Listen for Changes to Property Values

Create Property Listeners

For handle classes, you can define listeners for the predeclared property events (named: PreSet, PostSet, PreGet, and PostGet). To create listeners for those named events:

  • Specify the SetObservable and/or GetObservable property attributes.

  • Define callback functions

  • Create the property listener by including the name of the property and the event in the call to addlistener or event.proplistener.

  • If necessary, subclass event.EventData to create a specialized event data object to pass to the callback function.

  • Prevent execution of the callback if the new value is the same as the current value (see Assignment When Property Value Is Unchanged).

Set Property Attributes to Enable Property Events

In the properties block, enable the SetObservable attribute. You can define PreSet and PostSet listeners for the properties defined in this block:

properties (SetObservable) 
   PropOne
   PropTwo
end

Define Callback Function for Property Event

The listener executes the callback function when MATLAB® triggers the property event. Define the callback function to have two specific arguments, which are passed to the function automatically when called by the listener:

You can pass additional arguments if necessary. It is often simple to define this method as Static because these two arguments contain most necessary information in their properties.

For example, suppose the handlePropEvents function is a static method of the class creating listeners for two properties of an object of another class:

methods (Static)
   function handlePropEvents(src,evnt)
      switch src.Name 
         case 'PropOne'
            % PropOne has triggered an event
         case 'PropTwo'
            % PropTwo has triggered an event
      end
   end
end

Another possibility is to use the event.PropertyEvent object's EventName property in the switch statement to key off the event name (PreSet or PostSet in this case).

Class Metadata provides more information about the matlab.metadata.Property class.

Add Listener to Property

The addlistener handle class method enables you to attach a listener to a property without storing the listener object as a persistent variable. For a property event, use the four-argument version of addlistener.

Here is a call to addlistener:

addlistener(EventObject,'PropOne','PostSet',@ClassName.handlePropertyEvents);

The arguments are:

  • EventObject — handle of the object generating the event

  • PropOne — name of the property to which you want to listen

  • PostSet — name of the event for which you want to listen

  • @ClassName.handlePropertyEvents — function handle referencing a static method, which requires the use of the class name

If your listener callback is an ordinary method and not a static method, the syntax is:

addlistener(EventObject,'PropOne','PostSet',@obj.handlePropertyEvents);

where obj is the handle of the object defining the callback method.

If the listener callback is a function that is not a class method, you pass a function handle to that function. Suppose that the callback function is a namespace function:

addlistener(EventObject,'PropOne','PostSet',@namespace.handlePropertyEvents);

For more information on passing functions as arguments, see Create Function Handle.

Property Event and Listener Classes

The following two classes show how to create PostSet property listeners for two properties — PropOne and PropTwo.

Class Generating the Event

The PropEvent class enables property PreSet and PostSet event triggering by specifying the SetObservable property attribute. These properties also enable the AbortSet attribute, which prevents the triggering of the property events if the properties are set to a value that is the same as their current value (see Assignment When Property Value Is Unchanged).

classdef PropEvent < handle
   properties (SetObservable, AbortSet)
      PropOne
      PropTwo
   end
   methods
      function obj = PropEvent(p1,p2)
         if nargin > 0
            obj.PropOne = p1;
            obj.PropTwo = p2;
         end
      end
   end
end

Class Defining the Listeners

The PropListener class defines two listeners:

  • Property PropOne PostSet event

  • Property PropTwo PostSet event

You can define listeners for other events or other properties using a similar approach. It is not necessary to use the same callback function for each listener. See the matlab.metadata.Property and event.PropertyEvent reference pages for more on the information contained in the arguments passed to the listener callback function.

classdef PropListener < handle
   % Define property listeners
   methods
      function obj = PropListener(evtobj)
         if nargin > 0
            addlistener(evtobj,'PropOne','PostSet',@PropListener.handlePropEvents);
            addlistener(evtobj,'PropTwo','PostSet',@PropListener.handlePropEvents);
         end
      end
   end
   methods (Static)
      function handlePropEvents(src,evnt)
         switch src.Name
            case 'PropOne'
               sprintf('PropOne is %s\n',num2str(evnt.AffectedObject.PropOne))
            case 'PropTwo'
               sprintf('PropTwo is %s\n',num2str(evnt.AffectedObject.PropTwo))
         end
      end
   end
end

See Also

Topics