|On this page…|
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).
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
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).
Class Metadata provides more information about the meta.property class.
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
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:
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:
See function_handle for more information on passing functions as arguments.
The following two classes show how to create PostSet property listeners for two properties — PropOne and PropTwo.
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
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) 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
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.
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.
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:
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 get.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 no 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 a = 9
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
Calls the property get method again to determine if the result of calling the set method changed the value.
>> ats.PropOne = 11; get.PropOne called Pre-set event triggered set.PropOne called get.PropOne called
Because 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.