Documentation

This is machine translation

Translated by Microsoft
Mouse over text to see original. Click the button below to return to the English verison of the page.

Overview Events and Listeners

Why Use Events and Listeners

Events are notices that objects broadcast in response to something that happens, such as a property value changing or a user interaction with an application program. Listeners execute functions when notified that the event of interest occurs. Use events to communicate changes to objects. Listeners respond by executing the callback function.

For more information, see Event and Listener Concepts.

Events and Listeners Basics

When using events and listeners:

  • Only handle classes can define events and listeners.

  • Define event names in the events block of a class definition (Events and Listeners Syntax).

  • Use event attributes to specify access to the event (Event Attributes).

  • Call the handle notify method to trigger the event. The event notification broadcasts the named event to all listeners registered for this event.

  • Use the handle addlistener method to couple a listener to the event source object. MATLAB® destroys the listener when the source of the event is destroyed.

  • Use the event.listener class constructor to create listeners that are not coupled to the lifecycle of the event source object. This approach is useful when the event source and the listeners are defined in different components that you want to be able to add, remove, or modify independently of each other. Your application code controls the listener object lifecycle.

  • Listener callback functions must define at least two input arguments — the event source object handle and the event data (See Listener Callback Syntax for more information).

  • Modify the data passed to each listener callback by subclassing the event.EventData class.

Predefined Events

MATLAB Defines events for listening to property sets and queries. For more information, see Listen for Changes to Property Values.

All handle objects define an event named ObjectBeingDestroyed. MATLAB triggers this event before calling the class destructor.

Events and Listeners Syntax

Define an event name in the events code block:

classdef ClassName < handle
   ...
   events
      EventName
   end
   ...
end

For example, MyClass defines an event named StateChange:

classdef MyClass < handle
   events
      StateChange
   end
end

Trigger an event using the handle class notify method:

classdef ClassName < handle
   ...
   events
      EventName
   end
   ...
   methods
      function anyMethod(obj)
         ...
         notify(obj,'EventName');
      end
end

Any function or method can trigger the event for a specific instance of the class defining the event. For example, the triggerEvent method calls notify to trigger the StateChange event:

classdef MyClass < handle
   events
      StateChange
   end
   methods
      function triggerEvent(obj)
         notify(obj,'StateChange')
      end
   end
end

Trigger the StateChange event with the triggerEvent method:

obj = MyClass;
obj.triggerEvent

Create Listener

Define a listener using the handle class addlistener method. Pass a function handle for the listener callback function using a syntax like these:

  • addlistener(eventObject,'EventName',@functionName) — for an ordinary function.

  • addlistener(eventObject,'EventName',@Obj.methodName) — for a method of Obj.

  • addlistener(eventObject,'EventName',@ClassName.methodName) — for a static method of the class ClassName.

ListenerObject = addlistener(SourceOfEvent,'EventName',@listenerCallback);

addlistener returns the listener object. The input arguments are:

  • SourceOfEvent — An object of the class defining the event on which the event occurred.

  • EventName — The name of the event defined in the class events code block.

  • @listenerCallback — a function handle referencing the function that executes in response to the event.

For example, create a listener object for the StateChange event:

function lh = createListener(src)
   lh = addlistener(src,'StateChange',@handleStateChange)
end

Define the callback function for the listener. The callback function must accept as the first two arguments the event source object and an event data object:

function handleStateChange(src,eventData)
   ...
end

Related Examples

Was this topic helpful?