MATLAB®

Controlling Property Access

Property Access Methods

Property access methods enable you to execute code whenever properties values are referenced or assigned a new value. These methods enable you to:

• Execute code before an assignment is made to property values to impose range restrictions, check for proper types and dimensions, provide error handling, and so on.

• Execute code before returning the current value of properties to calculate the value of properties that do not store values, change the value of other properties, trigger events, and so on.

Property access methods automatically execute whenever object properties are queried or set. However, you can define property access only for concrete properties (i.e., properties that are not defined as abstract).

Note   Property set and get access methods are not equivalent to user-callable set and get methods used to access property values from an instance of the class. See Implementing a Set/Get Interface for Properties for information on user-callable set and get methods.

Access methods have special names that include the property's name. Therefore, get.PropertyName is executed whenever PropertyName is referenced and set.PropertyName is executed whenever PropertyName is assigned a new value.

You must define property access methods in a methods block that specifies no attributes. You cannot call these methods, but they are called when properties are accessed. Therefore, property access methods do not appear in the list of class methods returned by the methods command and are not included in the meta.class object's Methods property. However, the meta.property object's SetMethod property contains a function handle to the property's set method and the GetMethod property contains a function handle to the property's get method.

For example, if the class myClass defines a set function for its Text property, you can obtain a function handle to this method from the meta.class object:

m = ?myClass;
m.Properties{1}.SetMethod % Assuming Text is the first property in the cell array
ans = 
   @\mydir\@myClass\myClass.m>myClass.set.Text % This is a function handle

The meta.class object (m) contains meta.property objects corresponding to each class property in its Properties property. This example assumes that the Text property corresponds to the first meta.property object in the cell array of meta.property objects. The order of the class properties in the meta.class Properties property is the same as the order in which the properties are defined in the class definition.

Obtaining Information About Classes with Meta-Classes provides more information on using meta classes.

Function Handles discusses the use of function handles.

Back to Top

Property Set Methods

Property set methods have the following syntax, where PropertyName is the name of the property.

methods % No method attributes
   function obj = set.PropertyName(obj,value)
end

Here obj is the object whose property is being assigned a value and value is the new value that is to be assigned to the property.

Value class set functions must return the object with the new value for the property assigned. Value classes replace the object whose property is being assigned with the object returned by the set method. Handle classes do not need to return the modified object.

The property set method can perform actions like error checking on the input value before taking whatever action is necessary to store the new property value.

function obj = set.PropertyName(obj,value)
   if ~(value > 0)
      error('Property value must be positive')
   else
      obj.PropertyName = value;
   end
end

See Restricting Properties to Specific Values for an example of a property set method.

Set Method Behavior

MATLAB^® software calls a property set method whenever a property value is assigned, if a set method for that property exists. However, property set methods are NOT called in the following cases:

• Assigning a value to a property from within its own property set method, to prevent recursive calling of the set method

• Assigning a property to its default initial value

• Initial values specified in class definitions do not invoke the set method

• Copying a value object (i.e., not a handle object). Neither the set or get method is called when copying property values from one object to another.

It is possible for a set method from one property to assign values to other properties of the object. However, assignments made from property set methods cause the execution of any set methods defined for those properties.

When a property assignment takes place, modifications to the object that has been passed to the set method are reflected in the calling function's copy of the object. Therefore, an assignment to even a single property is able to affect the whole object. This enables set a method to change other properties in the object as well as its designated property. For example, a graphics window object might have a Units property and a Size property. Changing the Units property might also require a change to the values of the Size property to reflect the new units.

Back to Top

Property Get Methods

A property's get method is called whenever the property value is queried. For example, passing a property value in the following statement causes the method get.XYData to execute, if it exists.

plot(obj.XYData)

Property get methods have the following syntax, where PropertyName is the name of the property. Note that the function must return the property value.

methods % No method attributes
   function value = get.PropertyName(obj)
end

Dependent Properties — Values Not Stored

One application of a property get method is to determine the value of a property only when it is needed, and thereby avoid storing the value. To do this, set the property's Dependent attribute to true:

properties (Dependent = true)
   PropertyName
end

Now the get method for the PropertyName property determines the value of that property and assigns it to the object from within the method:

function value = get.PropertyName(obj)
   value = calculateValue;
   ...
end

This get method calls a function or static method calculateValue to calculate the property value and returns value to the code accessing the property. The property get method can take whatever action is necessary within the method to produce the output value.

Dependent Properties provide an example of a property get method.

Back to Top

Set and Get Method Execution and Property Events

MATLAB software generates events before and after set and get operations that can be used to inform listeners that property values have been referenced or assigned. The timing of event generation is as follows:

• PreGet — Before the property's get method is called

• PostGet — After the property's get method has returned its value

If a property value is computed (Dependent = true), then the behavior of its set events are similar to the get events:

• PreSet — Before the property's set method is called

• PostSet — After the property's set method is called

If a property is not computed (Dependent = false, the default), then the events are generated by the actual assignment statement within the set method:

• PropertyPreSet — Before the property's new value is assigned within the set method

• PropertyPostSet — After the property's new value is assigned within the set method

Events and Listeners — Concepts provides general information about events and listeners.

Creating Property Listeners provides information about using property events.

Implementing the PostSet Property Event and Listener shows an example of a property listener.

Back to Top

Access Methods and Subscripted Reference and Assignment

You can use subscripting as a way to reference or assign property values (e.g., a = obj.prop(6) or obj.prop(6) = a) without interfering with property set and get methods. In the case of subscripted reference, the get method returns the whole property value and MATLAB software then accesses the value referenced by subscripting on that object.

For subscripted assignment, the get method is invoked to get the property value, the subscripted assignment is carried out into the returned property, and then the new property value is passed to the set method.

MATLAB software always passes scalar objects to set and get methods. When reference or assignment occurs on an object array, the set and get methods are called in a loop.

Back to Top

Performing Additional Steps with Property Access Methods

Property access methods are useful in cases where you need to perform some additional steps before assigning or returning a property value. For example, the Testpoint class uses a property set method to check the range of a value, apply scaling if it is within a particular range, and set it to NaN if it is not.

The property get methods applies a scale factor before returning its current value:

classdef Testpoint
   properties
      expectedResult = [];
   end
   properties(Constant,SetAccess = private,GetAccess = private)
      scalingFactor = 0.001;
   end
   methods
      function obj = set.expectedResult(obj,erIn)
         if erIn >= 0 && erIn <= 100
            erIn = erIn.*obj.scalingFactor
            obj.expectedResult = erIn;
         else
            obj.expectedResult = NaN;
         end
      end
      function er = get.expectedResult(obj)
         er = obj.expectedResult/scalingFactor;
      end
   end
end

Back to Top

Property Attributes

Dynamic Properties — Adding Properties to an Instance