Learning to Use Events and Listeners

What You Can Do With 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. You can use events to communicate things that happen to objects, and respond to these events by executing the listener's callback function.

See Events and Listeners — Concepts for a more thorough discussion of the MATLAB event model.

Back to Top

What You Need to Know to Use Events

The following sections provide simple examples that show the basic techniques for using events and listeners. Subsequent sections provide more detailed descriptions and more complex examples.

Events and Listeners Basics

When using events and listeners:

• Only handle classes can define events and listeners (See Naming Events for syntax).

• Call the handle notify method to trigger the event (See Triggering Events, and Defining and Triggering an Event, for examples). The event notification broadcasts the named event to all listeners registered for this event.

• Use the handle addlistener method to associate a listener with an object that will be the source of the event (Listening to Events, Creating a Listener for the Overflow Event, and Property Event and Listener Classes).

• When adding a listener, pass a function handle for the listener callback function using a syntax such as the following:

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

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

• You can modify the data passed to each listener callback by subclassing the event.EventData class (See Defining Event-Specific Data) and Defining the Event Data for more information).

Back to Top

Customizing Event Data

Suppose you want to create a listener callback function that has access to specific information when the event occurs. This example shows how to do this by creating custom event data.

Events provide information to listener callback functions by passing an event data argument to the specified function. By default, MATLAB passes an event.EventData object to the listener callback. This object has two properties:

• EventName — Name of the event triggered by this object.

• Source — Handle of the object triggering the event.

Provide additional information to the listener callback by subclassing the event.EventData class.

• Define properties in the subclass to contain the additional data.

• Define a constructor that accepts the additional data as arguments.

• Use the subclass constructor as an argument to the notify method to trigger the event.

The Defining the Event Data section shows an implementation of this subclass.

See Defining Event-Specific Data for another example that subclasses event.EventData.

Defining and Triggering an Event

The SimpleEventClass defines a property set method (see Property Set Methods) from which it triggers an event if the property is set to a value exceeding a certain limit. The property set method performs these operations:

• Saves the original property value

• Sets the property to the specified value

• If the specified value is greater than 10, the set method triggers an Overflow event

• Passes the original property value, as well as other event data, in a SpecialEventDataClass object to the notify method (see Defining the Event Data )

classdef SimpleEventClass < handle
% Must be a subclass of handle
   properties
      Prop1 = 0;
   end
   events
      Overflow
   end
   methods
      function set.Prop1(obj,value)
         orgvalue = obj.Prop1;
         obj.Prop1 = value;
            if (obj.Prop1 > 10)
            % Trigger the event using custom event data
               notify(obj,'Overflow',SpecialEventDataClass(orgvalue));
            end
      end
   end
end

Defining the Event Data

Event data is always contained in an event.EventData object. The SpecialEventDataClass adds the original property value to the event data by subclassing event.EventData:

classdef SpecialEventDataClass < event.EventData
   properties
      OrgValue = 0;
   end
   methods
      function eventData = SpecialEventDataClass(value)
            eventData.OrgValue = value;
      end
   end
end

Creating a Listener for the Overflow Event

To listen for the Overflow event, attach a listener to an instance of the SimpleEventClass class. Use the addlistener method to create the listener. You also need to define a callback function for the listener to execute when the event is triggered.

The function setupSEC instantiates the SimpleEventClass class and adds a listener to the object. In this example, the listener callback function displays information that is contained in the eventData argument (which is a SpecialEventDataClass object).

function sec = setupSEC
   % Create an object and attach the listener
   sec = SimpleEventClass;
   addlistener(sec,'Overflow',@overflowHandler)
   % Define the listener callback function
   function overflowHandler(eventSrc,eventData)
      disp('The value of Prop1 is overflowing!')
      disp(['It''s value was: ' num2str(eventData.OrgValue)])
      disp(['It''s current value is: ' num2str(eventSrc.Prop1)])
   end
end

Create the SimpleEventClass object and add the listener:

>> sec = setupSEC;
>> sec.Prop1 = 5;
>> sec.Prop1 = 15; % listener triggers callback
The value of Prop1 is overflowing!
It's value was: 5
It's current value is: 15

Back to Top

Observe Property Changes

This example shows how to listen for changes to a property value. This examples uses:

• PostSet event predefined by MATLAB

• SetObservable property attribute to enable triggering the property PostSet event.

• addlistener handle class method to create the listener

classdef PropLis < handle
   % Define a property that is SetObservable
   properties (SetObservable)
      ObservedProp = 1;
   end
   methods
      function attachListener(obj)
         %Attach a listener to a PropListener object
         addlistener(obj,'ObservedProp','PostSet',@PropLis.propChange);
      end
   end
   methods (Static)
      function propChange(metaProp,eventData)
         % Callback for PostSet event
         % Inputs: meta.property object, event.PropertyEvent
         h = eventData.AffectedObject;
         propName = metaProp.Name;
         disp(['The ',propName,' property has changed.'])
         disp(['The new value is: ',num2str(h.ObservedProp)])
         disp(['It''s defaul value is: ',num2str(metaProp.DefaultValue)])
      end
   end
end

The PropLis class uses an ordinary method (attachListener) to add the listener for the ObservedProp property. If the PropLis classed defined a constructor, it could contain the call to addlistener.

The listener callback is a static method (propChange) to which MATLAB passes a meta.property object for ObservedProp, and an event.PropertyEvent object. These arguments provide information about the property and the event.

Use the PropLis class by creating an instance and calling its attachListener method:

plObj = PropLis;
plObj.ObservedProp

ans =

     1
plObj.attachListener
plObj.ObservedProp = 2;
The ObservedProp property has changed.
The new value is: 2
It's defaul value is: 1

See Creating Property Listeners for more information on property listeners.

Back to Top

Events — Sending and Responding to Messages

Example – Property Set Listener

Recommended Products

• MATLAB
• Signal Processing Toolbox
• Optimization Toolbox
• Statistics Toolbox
• Control System Toolbox

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit