Listen for Changes to Property Values

On this page…

Creating Property Listeners

Property Event and Listener Classes

Aborting Set When Value Does Not Change

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 ...endDefine 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 endendAnother 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 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.

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 endendClass 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 % 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)%here, src=evtobj switch src.Name %here, Name='PropOne'or'PropTwo' which is an added prop %erties from the addlistener methods above case 'PropOne' sprintf('PropOne is %s\n',num2str(evnt.AffectedObject.PropOne)) case 'PropTwo' sprintf('PropTwo is %s\n',num2str(evnt.AffectedObject.PropTwo)) end end endend

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'sAbortSet 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.

When to Use AbortSet

Consider using AbortSet only when the cost of setting a property value is much greater than the cost of always comparing the current value of the property with the new value being assigned.

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 endendThe 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 calledIf you specify a value other than 7, then MATLAB triggers the PreSet event:

>> ats = AbortTheSet(9);get.PropOne calledset.PropOne calledget.PropOne calledSimilarly, if you set the PropOne property to the value 9, the AbortSet attribute prevents the property assignment and the triggering of thePreSet event. Notice also, that there is no PreGet event generated. Only the property get method is called:

>> ats.PropOne = 9;get.PropOne calledIf you query the property value, the PreGet event is triggered:

>> a = ats.PropOnePre-get event triggeredget.PropOne calleda = 9If 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

Calls the property get method again to determine if the result of calling the set method changed the value.

>> ats.PropOne = 11;get.PropOne calledPre-set event triggeredset.PropOne calledget.PropOne calledBecause a property set method might modify the value that is actually assigned to a property, MATLAB must query the property value that would result from an assignment after a call the property's set method. This results in multiple calls to a property get method, if one is defined for that property.