Class defining listener objects
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
Use the handle
notify method to trigger an event.
event.listener class is a
For information on class attributes, see Class Attributes.
eListener = event.listener(
creates a listener for the specified event name on the specified source objects
and identifies a function handle to the callback function.
eventSource is an array of object handles, the listener
responds to the named event on any of the objects in the array.
eventSource— Event source
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
Event name, specified as the literal name of the event.
Source— Event source objects
Event source objects, specified as the handles of the objects that this listener responds to when the event is triggered.
handle object |
EventName— Name of event
Name of the event that the listener responds to when triggered on the specified source objects.
Callback— Event callback
Event callback, specified as a function handle. The function executes when the event is triggered.
Enabled— Enable or disable listener
Enabled is set to
default), the callback executes when the event occurs. To disable callback
execution for this listener, set
Recursive— Execute callback recursively
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.
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.
Define a listener for an event named
with a callback function named
EOLCallback that is triggered
on an object in the array
listenerHandle = event.listener(textReader,"EOL",@EOLCallback);
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
eventData is an
object or an instance of a subclass of
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.
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.
You can enable or disable a listener by setting the value of the listener