event.listener

Class defining listener objects

Syntax

lh = event.listener(Hobj,'EventName',@CallbackFunction)

Description

The event.listener class defines listener objects. Listener objects respond to the specified event and identify the callback function to invoke when the event is triggered.

lh = event.listener(Hobj,'EventName',@CallbackFunction) creates an event.listener object, lh, for the event named in EventName, on the specified object, Hobj.

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

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

function CallbackFunction(source,eventData)
   ...
end

where source is the object that is the source of the event and eventData is an event.EventData object.

The event.listener class is a handle class.

Limiting Listener Lifecycle

Generally, you create a listener object using addlistener. However, you can call the event.listener constructor directly to create a listener. When you use the event.listener constructor, the listener's lifecycle is not tied to the object(s) being listened to—once the listener object goes out of scope, the listener no longer exists. See Ways to Create Listeners for more information on creating listener objects.

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's Enabled property (see Properties table below).

More Information on Events and Listeners

See Events for more information and examples of how to use events and listeners.

Properties

PropertyPurpose
SourceCell array of source objects
EventNameName of the event
CallbackFunction to execute when the event is triggered and the Enabled property is set to true
EnabledThe callback executes when the event occurs if and only if Enabled is set to true (the default).
Recursive

When false (the default), this listener does not execute recursively. Therefore, if the callback triggers its own event, the listener does not execute 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 triggers an error.

Was this topic helpful?