This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.


Class defining listener objects


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


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. Specify the event name as a character vector or a string scalar.

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)

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. The event.listener and the event.proplistener classes are part of the same heterogeneous hierarchy. Therefore, you can create arrays that contain objects of both classes. The class of an array containing both classes of objects is event.listener.

Limiting Listener Lifecycle

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

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

More Information on Events and Listeners

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


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).

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.

Introduced in R2008a

Was this topic helpful?