Write Property Set Methods for Custom UI Components in App Designer

When you create a public property for a custom UI component, one step involves writing code to update the underlying components and graphics objects within your custom component whenever the value of the public property changes. In general, perform this step by writing code in the component update function. MATLAB^® calls the update function only when necessary, which can result in performance improvements over writing custom code to perform a similar purpose. For more information about updating properties using the update function, see Create Public Properties for Custom UI Components in App Designer.

However, you might want to perform certain tasks when one specific property is updated but not when other properties are updated. Because the update function executes whenever the value of any public property changes, you can instead write code to perform these tasks when a specific property changes by defining a set method for that property.

Consider writing a property set method when you want to:

• Perform custom property validation.

• Throw a custom error when the property is set incorrectly.

• Process the property value before storing it.

This example shows how to validate a public property of a custom IP address UI component by writing a set method.

IP Address Component Overview

This example IP address component accepts input formatted using either the IPv4 or IPv6 protocol. The protocol determines how the component is displayed:

• IPv4 — The component contains four numeric edit fields, each with a value between 0 and 255.

• IPv6 — The component contains eight text edit fields, each with four characters representing hexadecimal digits.

The IP address component interface consists of:

• A public property named Address to store the value of the IP address

• A public property named Protocol to specify the IP address protocol

• A public callback named AddressChangedFcn that executes when an app user changes the IP address by typing in an edit field

Because the Address property can store either a four-element numeric vector (when the protocol is IPv4) or an eight-element cell array (when the protocol is IPv6), use custom validation logic in a property set method to check whether the Address value is valid.

To view the full IPAddress component code in App Designer, enter this command in the MATLAB® Command Window:

openExample('matlab/IPAddressCustomComponentExample');

Create a Property Set Method

To create a new property set method for the Address property of the IP address component, use these steps:

1. Create a new public function. In Code View, in the Editor tab, select Function > Public Function.

2. In the methods block that contains the new function, delete the text (Access = public). Property set methods must be added in a methods block with no attributes. This deletion does not change the functionality of the methods block because the default value of the Access attribute is public. For more information, see Property Get and Set Methods.

3. Replace the function definition that App Designer creates with this code:

   function set.Address(comp,val)
   % Write property validation code here
   end

   The set.Address function executes whenever an app creator sets the value of the Address public property.

For more information about

Perform Custom Property Validation

Write code in the set.Address function to verify that the new property value follows the expected format:

• If the protocol is IPv4, check that the app creator set the property to a vector of four integers between 0 and 255.

• If the protocol is IPv6, check that the app creator set the property to a cell array of eight character vectors, where each character vector represents four hexadecimal digits.

In each case, if the new value is not in the expected format, throw a helpful error to inform the app creator what value the property expects. Finally, set the Address property of the component to the new property value.

Add this code to the body of the set.Address function:

switch comp.Protocol
    % Validate IPv4 address
    case "IPv4"
        if length(val) ~= 4
            error("IPv4 address must have four fields.")
        end
        mustBeInRange(val,0,255)

    % Validate IPv6 address
    case "IPv6"
        if length(val) ~= 8
            error("IPv6 address must have eight fields.")
        end

        if ~isequal(cellfun('length',val),repmat(4,1,8))
            error("Specify IPv6 field as a four-digit hexadecimal number.")
        end
        
        try 
            hex2dec(val);
        catch
            error("Specify IPv6 field as a four-digit hexadecimal number.")
        end
end
comp.Address = val;

Verify Property Validation Behavior

After you have finished developing the IPAddress component, verify the property validation behavior by creating a component object and setting the Address property from the MATLAB Command Window.

Navigate to the folder where the IPAddress.mlapp file is saved. Create an IP address component, specify its position, and return the component object as comp. By default, the component is created using the IPv4 protocol.

comp = IPAddress(Position=[50 100 420 31]);

Try to set the Address property to a scalar value. An error displays.

comp.Address = 10;

Error using IPAddress/set.Address
IPv4 address must have four fields.

Change the component to an IPv6 address component.

comp.Protocol = "IPv6";

Try to set one field of the IP address to a value that does not represent a four-digit hexadecimal number.

comp.Address{1} = '123h';

Error using IPAddress/set.Address
Specify IPv6 field as a four-digit hexadecimal number.