Define Custom Event Data

Class Event Data Requirements

Suppose that you want to create a listener callback function that has access to specific information when the event occurs. This example shows how 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.

  • Set the ConstructOnLoad class attribute.

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

Define and Trigger Event

The SimpleEventClass defines a property set method (see Property Get and 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, and other event data, in a SpecialEventDataClass object to the notify method.

classdef SimpleEventClass < 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

Define 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 (ConstructOnLoad) SpecialEventDataClass < event.EventData
   properties
      OrgValue = 0
   end
   methods
      function eventData = SpecialEventDataClass(value)
         eventData.OrgValue = value;
      end
   end
end

Create Listener for 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. Also, you must 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
   sec = SimpleEventClass;
   addlistener(sec,'Overflow',@overflowHandler)
   function overflowHandler(eventSrc,eventData)
      disp('The value of Prop1 is overflowing!')
      disp(['Its value was: ' num2str(eventData.OrgValue)])
      disp(['Its 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!
Its value was: 5
Its current value is: 15

See Also

Topics