event.listener Class

Namespace: event

Class defining listener objects

Description

The event.listener class defines listener objects. Listener objects respond to a specific event by executing a callback function when the event is triggered. You can use the event.listener class to construct a listener object. Also, you can create listeners using the handle addlistener and listener methods.

Use the handle notify method to trigger an event.

The event.listener class is a handle class.

Class Attributes

`ConstructOnLoad`	`true`
`HandleCompatible`	`true`

For information on class attributes, see Class Attributes.

Creation

Description

eListener = event.listener(eventSource,eventName,callbackFcn) creates a listener for the specified event name on the specified source objects and identifies a function handle to the callback function.

If eventSource is an array of object handles, the listener responds to the named event on any of the objects in the array.

example

Input Arguments

expand all

`eventSource` — Event source
handle object | cell array of handle objects

Event source, specified as a handle object array or a cell array of object handles. Use a cell array when the source objects cannot form an array because their classes differ. All source objects must define the specified event.

`eventName` — Event name
character vector | string scalar

Event name, specified as the literal name of the event.

`callbackFcn` — Callback function
function handle

Callback function, specified by a function handle. For more information, see Listener Callback Syntax

Properties

expand all

`Source` — Event source objects
handle object array or a cell array of handle objects.

Event source objects, specified as the handles of the objects that this listener responds to when the event is triggered.

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`
`GetObservable`	`true`
`SetObservable`	`true`

Data Types: handle object | cell array

`EventName` — Name of event
character vector | string scalar

Name of the event that the listener responds to when triggered on the specified source objects.

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`
`GetObservable`	`true`
`SetObservable`	`true`

Data Types: char | string

`Callback` — Event callback
function handle

Event callback, specified as a function handle. The function executes when the event is triggered.

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`
`GetObservable`	`true`
`SetObservable`	`true`

Data Types: function_handle

`Enabled` — Enable or disable listener
true (default) | false

If Enabled is set to true (the default), the callback executes when the event occurs. To disable callback execution for this listener, set Enabled to false.

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`
`GetObservable`	`true`
`SetObservable`	`true`

Data Types: logical

`Recursive` — Execute callback recursively
false (default) | true

When false (the default), the listener does not execute its callback recursively. Therefore, if the callback triggers its own event, the listener does not respond again.

When true, the listener callback can cause the same event that triggered the callback. This scheme can lead to infinite recursion, which ends when the MATLAB^® recursion limit eventually throws an error.

Attributes:

`GetAccess`	`public`
`SetAccess`	`public`
`GetObservable`	`true`
`SetObservable`	`true`

Data Types: logical

Examples

collapse all

Define Listener

Define a listener for an event named EOL with a callback function named EOLCallback that is triggered on an object in the array textReader.

listenerHandle = event.listener(textReader,"EOL",@EOLCallback);

More About

expand all

Listener Callback Signature

The listener callback function must accept at least two input arguments.

function CallbackFunction(source,eventData)
   ...
end

source is the object that is the source of the event.
eventData is an event.EventData object or an instance of a subclass of event.EventData.

For more information about listener callbacks, see Listener Callback Syntax, Callback Execution, and Define Custom Event Data.

Limiting Listener Lifecycle

You can create listener object using the event.listener class constructor, or using the handle class addlistener or listener method.

When you create a listener using addlistener, the event source object holds a reference to the listener. When the source is destroyed, MATLAB also destroys the listener. You do not need to store a reference to the listener object to manage its lifecycle.

When you create a listener using event.listener or the listener method, the listener's lifecycle is not coupled to the event source. Because the event source object does not hold a reference to the listener, you have more control over the listener lifecycle. However, if the listener object goes out of scope, the listener no longer exists.

For more information on listener lifecycle, see Listener Lifecycle.

Removing a Listener

If you call delete(lh) on the listener object, the listener ceases to exist, which means the event no longer causes the listener callback function to execute.

Disabling a Listener

You can enable or disable a listener by setting the value of the listener Enabled property.

Version History

Introduced in R2008a

event.listener Class

Description

Class Attributes

Creation

Description

Input Arguments

`eventSource` — Event source
handle object | cell array of handle objects

`eventName` — Event name
character vector | string scalar

`callbackFcn` — Callback function
function handle

Properties

`Source` — Event source objects
handle object array or a cell array of handle objects.

Attributes:

`EventName` — Name of event
character vector | string scalar

Attributes:

`Callback` — Event callback
function handle

Attributes:

`Enabled` — Enable or disable listener
true (default) | false

Attributes:

`Recursive` — Execute callback recursively
false (default) | true

Attributes:

Examples

Define Listener

More About

Listener Callback Signature

Limiting Listener Lifecycle

Removing a Listener

Disabling a Listener

Version History

See Also

Topics

event.listener Class

Description

Class Attributes

Creation

Description

Input Arguments

eventSource — Event source handle object | cell array of handle objects

eventName — Event name character vector | string scalar

callbackFcn — Callback function function handle

Properties

Source — Event source objects handle object array or a cell array of handle objects.

Attributes:

EventName — Name of event character vector | string scalar

Attributes:

Callback — Event callback function handle

Attributes:

Enabled — Enable or disable listener true (default) | false

Attributes:

Recursive — Execute callback recursively false (default) | true

Attributes:

Examples

Define Listener

More About

Listener Callback Signature

Limiting Listener Lifecycle

Removing a Listener

Disabling a Listener

Version History

See Also

Topics

`eventSource` — Event source
handle object | cell array of handle objects

`eventName` — Event name
character vector | string scalar

`callbackFcn` — Callback function
function handle

`Source` — Event source objects
handle object array or a cell array of handle objects.

`EventName` — Name of event
character vector | string scalar

`Callback` — Event callback
function handle

`Enabled` — Enable or disable listener
true (default) | false

`Recursive` — Execute callback recursively
false (default) | true