Subclassing Simulink Data Classes

About Packages and Data Classes

Simulink packages and data classes are introduced in About Data Object Classes and Defining Data Representation and Storage for Code Generation . Simulink resources include several built-in packages and data classes. You can add user-defined packages and data classes with the Simulink Data Class Designer, which can:

• Create and delete user-defined packages that can hold user-defined subclasses.

• Create, change, and delete user-defined subclasses of some Simulink classes.

• Add and delete user-defined subclasses contained within user-defined packages.

• Define enumerated property types (not data types) for use by classes in a package.

• Enable defining custom storage classes for classes that have an appropriate parent class.

Simulink stores all package and data class definitions as P-files. You can view any package or data class in the Data Class Designer, but you cannot use the Designer to change a built-in package or data class. If you create or change user-defined packages and data classes, do so only in the Data Class Designer. Do not try to circumvent the Data Class Designer and directly modify any package or data class definition. An unrecoverable error could result.

Appropriately configured packages and data classes can define custom storage classes, which specify how data is declared, stored, and represented in generated code. Some built-in packages and data classes define built-in custom storage classes. You can use the Data Class Designer to enable a user-defined package and data class to have custom storage classes, as described in Enabling Custom Storage Classes.

Custom storage classes are defined and stored in different files than packages and data classes use, and different rules apply to changing them. See Creating and Using Custom Storage Classes in the Real-Time Workshop Embedded Coder documentation for complete information about custom storage classes.

Back to Top

Working with Packages

You can use the Simulink Data Class Designer to create and manage user-defined packages. To view the Data Class Designer, choose Tools > Data Class Designer from the Simulink menu. When opened, the designer first scans the MATLAB path and loads any packages that it finds. The Data Class Designer looks like this when no package is currently selected:

You can use the fields and buttons at the top and bottom of the Data Class Designer, and a few other designer capabilities, to select an existing package, create a new package, and copy, rename, or delete a package, as described in this section. The rest of the designer manages classes, as described in Working with Classes.

Selecting a Package

To select an existing user-defined package, select that package in the Package Name field of the Simulink Data Class Designer. The designer then displays the location of the package and the classes that it contains, plus class initialization and other information.

Creating a Package

To create a new package to contain your classes:

1. Click the New button next to the Package name field of the Data Class Designer.

   

   A default package name is displayed in the Package name field.

   

2. Edit the Package name field to contain the package name that you want.

   

3. Click OK to create the new package in memory.

4. In the package Parent directory field, enter the path of the directory where you want Simulink to create the new package.

   Note   Do not create class package directories under matlabroot. Packages in these directories are treated as built-in and will not be visible in the Data Class Designer.

   

   The Simulink software creates the specified directory, if it does not already exist, when you save the package to your file system in the succeeding steps.

5. Click the Confirm changes button on the Data Class Designer.

   The Packages to write panel is displayed.

   

6. To enable use of this package in the current and future sessions, ensure that the Add parent directory to MATLAB path option is set to Yes - permanently. The default is Yes - for this session only.

   This adds the path of the new package's parent directory to the MATLAB path.

7. Click Write all or select the new package and click Write selected to save the new package.

Copying a package

To copy a package, select the package and click the Copy button next to the Package name field. The Simulink software creates a copy of the package under a slightly different name. Edit the new name, if desired, and click OK to create the package in memory. Then save the package to make it permanent.

Renaming a package

To rename a package, select the package and click the Rename button next to the Package name field. The field becomes editable. Edit the field to reflect the new name. Save the renamed package.

Removing a package

To remove a package, select the package and click the Remove button next to the Package name field to remove the package from memory. Click the Confirm changes button to display the Packages to remove panel. Select the package and click Remove selected to remove the package from your file system or click Remove all to remove all packages that you have removed from memory from your file system as well.

Back to Top

Working with Classes

You can use the Simulink Data Class Designer to create and manage user-defined classes. To view the Data Class Designer, choose Tools > Data Class Designer from the Simulink menu. When opened, the designer first scans the MATLAB path and loads any packages that it finds. The Data Class Designer looks like this when no package is currently selected:

You can use the three tabs in the Data Class Designer, and a few other designer capabilities, to select an existing class, create a new class, copy, rename, or delete a class, and specify various class properties, as described in this section. The rest of the designer manages packages, as described in Working with Classes.

Creating a Data Object Class

To create a class within the currently selected package:

1. Select Data Class Designer from the Simulink Tools menu.

   The Data Class Designer dialog box appears.

   The designer initially scans the MATLAB path and loads any packages that it finds.

2. Select the name of the package in which you want to create the class from the Package name list.

   Do not create a class in any of the Simulink built-in packages, i.e., packages in matlabroot/toolbox/simulink, or any directory under matlabroot. See Working with Packages for information on creating your own class packages.

3. Click the New button on the Classes pane of the Data Class Designer dialog box.

4. Enter the name of the new class in the Class name field on the Classes pane.

   Note   The name of the new class must be unique in the package to which the new class belongs. Class names are case sensitive. For example, Signal and signal is considered to be names of different classes.

5. Press Enter or click OK on the Classes pane to create the specified class in memory.

6. Select a parent class for the new class (see Specifying a Parent for a Class).

7. Optionally enable custom storage classes for the class (see Enabling Custom Storage Classes).

8. Define the properties of the new class (see Defining Class Properties).

9. If necessary, create initialization code for the new class (see Creating Initialization Code).

10. Click Confirm Changes.

    Simulink displays the Confirm Changes pane.

    

11. Click Write All or select the package containing the new class definition and click Write Selected to save the new class definition.

Copying a class

To copy a class, select the class in the Classes pane and click Copy. The Simulink software creates a copy of the class under a slightly different name. Edit the name, if desired, click Confirm Changes, and click Write All or, after selecting the appropriate package, Write Selected to save the new class.

Renaming a class

To rename a class, select the class in the Classes pane and click Rename. The Class name field becomes editable. Edit the field to reflect the new name. Save the package containing the renamed class, using the Confirm changes pane.

Note   You cannot modify an instantiated Simulink data class. If you try to modify a class that has already been instantiated during the current MATLAB session, an error message informs you that you need to restart MATLAB if you want to modify this package.

Removing a class from a package

To remove a class definition from the currently selected package, select the class in the Classes pane and click Remove. The class is removed from the in-memory definition of the class. Save the package that formerly contained the class.

Specifying a Parent for a Class

To specify a parent for a class:

1. Select the name of the class from the Class name field on the Classes pane.

2. Select the package name of the parent class from the left-hand Derived from list box.

   

3. Select the parent class from the right-hand Derived from list.

   

   The properties of the selected class derived from the parent class are displayed in the Properties of this class field.

   

   The inherited properties are grayed to indicate that they cannot be redefined by the child class.

4. Save the package containing the class.

Defining Class Properties

To add a property to a class:

1. Select the name of the class from the Class name field on the Classes pane.

   Note   You cannot modify an instantiated Simulink data class. If you try to modify a class that has already been instantiated during the current MATLAB session, an error message informs you that you need to restart MATLAB if you want to modify this package.

2. Click the New button next to the Properties of this class field on the Classes pane.

   A property is created with a default name and value and displays the property in the Properties of this class field.

   

3. Enter a name for the new property in the Property Name column.

   Note   The property name must be unique to the class. Unlike class names, property names are not case sensitive. For example, Value and value are treated as referring to the same property.

4. Select the data type of the property from the Property Type list.

   The list includes built-in property types and any enumerated property types that you have defined (see Enumerated Property Types).

5. If you want the property to have a default value, enter the default value in the Factory Value column.

   The default value is the value the property has when an instance of the associated class is created. The initialization code for the class can override this value (see Creating Initialization Code for more information).

   The following rules apply to entering factory values for properties:

   • Do not use quotation marks when entering the value of a string property. The value that you enter is treated as a literal string.

   • The value of a MATLAB array property can be any expression that evaluates to an array, cell array, structure, or object. Enter the expression exactly as you would enter the value on the command line, for example, [0 1; 1 0]. The expression that you enter is evaluated to check its validity. A warning is displayed if evaluating the expression results in an error. Regardless of whether an evaluation error occurs, Simulink stores the expression as the factory value of the property. This is because an expression that is invalid at define time might be valid at run-time.

   • You can enter any expression that evaluates to a numeric value as the value of a double or int32 property. The expression is evaluated and the result stored as the property's factory value.

6. Save the package containing the class with new or changed properties.

Creating Initialization Code

You can specify code to be executed when the Simulink software creates an instance of a data object class. To specify initialization code for a class, select the class from the Class name field of the Data Class Designer and enter the initialization code in the Class initialization field.

The Data Class Designer inserts the code that you enter in the Class initialization field in the class instantiation function of the corresponding class. This function is invoked when an instance of this class is created. The class instantiation function has the form

function h = ClassName(varargin)

where h is the handle to the object that is created and varargin is a cell array that contains the function's input arguments.

By entering the appropriate code in the Data Class Designer, you can cause the instantiation function to perform such initialization operations as

• Error checking

• Loading information from data files

• Overriding factory values

• Initializing properties to user-specified values

For example, suppose you want to let a user initialize the ParamName property of instances of a class named MyPackage.Parameter. The user does this by passing the initial value of the ParamName property to the class constructor:

Kp = MyPackage.Parameter('Kp');

The following code in the instantiation function would perform the required initialization:

switch nargin
	case 0
		% No input arguments - no action
	case 1
		% One input argument
		h.ParamName = varargin{1};
	otherwise
		warning('Invalid number of input arguments');
end

Back to Top

Enumerated Property Types

An enumerated property type is a property type whose value must be one of a specified set of values, for example, red, blue, or green. An enumerated property type is valid only in the package that defines it, but must be globally unique throughout all packages.

Note   Do not confuse an enumerated property type with an enumerated data type. For information on enumerated data types, see Using Enumerated Data in a Simulink Model. The Data Class Designer cannot be used for defining enumerated data types.

To create an enumerated property type:

1. Select the Enumerated Property Types tab of the Data Class Designer.

   

2. Click the New button next to the Property type name field.

   An enumerated property type is created with a default name.

   

3. Change the default name in the Property type name field to the desired name for the property.

   The currently selected package defines an enumerated property type and the type can be referenced only in the package that defines it. However, the name of the enumerated property type must be globally unique. There cannot be any other built-in or user-defined enumerated property type with the same name. An error is displayed if you enter the name of an existing built-in or user-defined enumerated property type.

4. Click the OK button.

   The new property is created in memory and the Enumerated strings field on the Enumerated Property Types pane is enabled .

5. Enter the permissible values for the enumerated property type Enumerated strings field, one per line.

   For example, the following Enumerated strings field shows the permissible values for an enumerated property type named Color.

   

6. Click Apply to save the changes in memory.

7. Click Confirm changes. Then click Write all to save this change.

You can also use the Enumerated Property Type pane to copy, rename, and remove enumerated property types.

• Click the Copy button to copy the currently selected property type. A new property that has a new name, but has the same value set as the original property is created.

• Click the Rename button to rename the currently selected property type. The Property name field becomes editable. Edit the field to reflect the new name.

• Click the Remove button to remove the currently selected property.

Always save the package containing the modified enumerated property type.

Note   You must restart the MATLAB software if you modify, add, or remove enumerated property types from a class you have already instantiated.

Back to Top

Enabling Custom Storage Classes

If you select Simulink.Signal or Simulink.Parameter as the parent of a user-defined class, the Simulink Data Class Designer displays a check box labeled Create your own custom storage classes for this class. You can ignore this option if you do not intend to use Real-Time Workshop Embedded Coder to generate code from models that reference this data object class.

Otherwise, select this check box to cause Simulink Data Class Designer to create custom storage classes for this data object class. See Creating Packages that Support CSC Definitions in the Real-Time Workshop Embedded Coder documentation for more information. The Data Class Designer also provides a tab labeled Custom Storage Classes, but this tab is now obsolete.

Back to Top

Working with Data Objects

Associating User Data with Blocks

Related Products & Applications

• Simulink
• Control Design
• Signal Processing & Communications
• Model-Based Design
• Physical Modeling
• Verification & Validation

Get Simulink trial software

Learn more about Simulink through this collection of videos, articles, technical literature and the Getting Started with Simulink Guide.

Get this Simulink Kit