Listening for Changes to Property Values

Creating Property Listeners

You can listen to the predeclared property events (named: PreSet, PostSet, PreGet, and PostGet) by creating a listener for those named events:

• Specify the SetObservable and/or GetObservable property attributes to add listeners for set or get events.

• Define a callback function

• Create a property listener by including the name of the property as well as the event in the call to addlistener (see Add a Listener to the Property.)

• Optionally subclass event.data 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 Aborting Set When Value Does Not Change).

Set Property Attributes to Enable Property Events

In the properties block, enable the SetObservable attribute:

properties (SetObservable) 
% Can define PreSet and PostSet property listeners
% for properties defined in this block
   PropOne
   PropTwo
   ...
end

Define a Callback Function for the Property Event

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

• Event source — a meta.property object describing the object that is the source of the property event

• Event data — a event.PropertyEvent object containing information about the event

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 % switch on the property 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).

Use Class Metadata provides more information about the meta.property class.

Add a Listener to the 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 events, use the four-argument version of addlistener.

If the call

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 the callback function is a package function:

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

See function_handle for more information on passing functions as arguments.

Back to Top

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 Aborting Set When Value Does Not Change)

classdef PropEvent < handle
   % enable property events with the SetObservable attribute
   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 could define listeners for other events or other properties using a similar approach and it is not necessary to use the same callback function for each listener. See the meta.property and event.PropertyEvent reference pages for more on the information contained in the arguments passed to the listener callback function.

classdef PropListener < handle
   methods
      function obj = PropListener(evtobj)
      % Pass the object generating the event to the constructor
      % Add the listeners from the constructor
         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'
               fprintf(1,'PropOne is %s\n',num2str(evnt.AffectedObject.PropOne))
            case 'PropTwo'
               fprintf(1,'PropTwo is %s\n',num2str(evnt.AffectedObject.PropTwo))
         end
      end
   end
end

Back to Top

Aborting Set When Value Does Not Change

By default, MATLAB triggers the property PreSet and PostSet events, invokes the property's set method (if defined), and sets the property value, even when the current value of the property is the same as the new value. You can prevent this behavior by setting the property's AbortSet attribute to true. When AbortSet is true, MATLAB does not:

• Set the property value

• Trigger the PreSet and PostSet events

• Call the property's set method, if one exists

When AbortSet is true, MATLAB gets the current property value to compare it to the value you are assigning to the property. This causes the property get method (get.Property) to execute, if one exists. However, MATLAB does not catch errors resulting from the execution of this method and these errors are visible to the user.

How AbortSet Works

The following example shows how the AbortSet attribute works. The AbortTheSet class defines a property, PropOne, that has listeners for the PreGet and PreSet events and enables the AbortSet attribute. The behavior of the post set/get events is equivalent so only the pre set/get events are used for simplicity:

Note   Save the AbortTheSet class in a file with the same name in a folder on your MATLAB path.

classdef AbortTheSet < handle
   properties (SetObservable, GetObservable, AbortSet)
      PropOne = 7
   end
   methods
      function obj = AbortTheSet(val)
         obj.PropOne = val;
         addlistener(obj,'PropOne','PreGet',@obj.getPropEvt);
         addlistener(obj,'PropOne','PreSet',@obj.setPropEvt);
      end
      function propval = get.PropOne(obj)
         disp('get.PropOne called')
         propval = obj.PropOne;
      end
      function set.PropOne(obj,val)
         disp('set.PropOne called')
         obj.PropOne = val;
      end
      function getPropEvt(obj,src,evnt)
         disp ('Pre-get event triggered')
      end
      function setPropEvt(obj,src,evnt)
         disp ('Pre-set event triggered')
      end
      function disp(obj)
      % Overload disp to avoid accessing property
         disp (class(obj))
      end
   end
end

The class specifies an initial value of 7 for the PropOne property. Therefore, if you create an object with the property value of 7, there is not need to trigger the PreSet event:

>> ats = AbortTheSet(7);
get.PropOne called

If you specify a value other than 7, then MATLAB triggers the PreSet event:

>> ats = AbortTheSet(9);
get.PropOne called
set.PropOne called

Similarly, if you set the PropOne property to the value 9, the AbortSet attribute prevents the property assignment and the triggering of the PreSet event. Notice also, that there is not PreGet event generated. Only the property get method is called:

>> ats.PropOne = 9;
get.PropOne called

If you query the property value, the PreGet event is triggered:

>> a = ats.PropOne
Pre-get event triggered
get.PropOne called

If you set the PropOne property to a different value, MATLAB:

• Calls the property get method to determine if the value is changing

• Triggers the PreSet event

• Calls the property set method to set the new value

>> ats.PropOne = 11;
get.PropOne called
Pre-set event triggered
set.PropOne called

Back to Top

Events and Listeners — Syntax and Techniques

Example — Using Events to Update Graphs

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