Define Level-1 Data Classes Using Data Class Designer

Support for level-1 data class infrastructure will be removed in a future release. Use level-2 data classes instead. See Define Level-2 Data Classes Using MATLAB Class Syntax.

Note   The Data Class Designer, which is used to define level-1 data classes, is disabled by default. To use the Data Class Designer, run the following commands to enable level-1 data class infrastructure. sldataclasssetup (1) savepath

On this page…
About Packages and Data Classes Define Level-1 Data Classes Working with Classes Enumerated Property Types Enabling Custom Storage Classes

About Packages and Data Classes

Simulink packages and data classes are introduced in About Data Object Classes and Data, Function, and File Definition . 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 Custom Storage Classes in the Embedded Coder documentation for complete information about custom storage classes.

Back to Top

Define Level-1 Data Classes

This example shows how to use level-1 data class infrastructure to create subclasses of Simulink data classes.

Note   The Data Class Designer is disabled by default. To use the Data Class Designer, run the following commands to enable level-1 data class infrastructure. sldataclasssetup (1) savepath

Use the Data Class Designer to create a data class in a package, and, optionally, define custom storage classes.

Create a package

1. Open the Simulink Data Class Designer.

   sldataclassdesigner

   The Data Class Designer loads all packages that exist on the MATLAB path.

2. Click New next to the Package name field, name your package, and click OK.

3. In the Parent directory field, enter the path to the directory for storing 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.

4. Add the parent directory to the MATLAB path.

Define a data class

1. In the Classes tab, click New next to the Class name field, name your class, and click OK.

2. Specify the parent class using the Derived from menus. Select Simulink.Signal or Simulink.Parameter.

3. Select the option to Create your own custom storage classes for this class.

   At least one class in your package must have this option selected.

   Note   If you do not select this option, your new class inherits the CSCs of the parent class.

   

   In the figure above, a new package mypkg contains a new class called sig derived from Simulink.Signal. The option to Create your own custom storage classes for this class is selected.

4. Add other derived classes to your package and associate CSCs with them.

Register the package

1. Click Confirm Changes.

2. In the Confirm changes pane, select the package you created.

   Note   User-defined packages that you plan to add to the Data Object Wizard must contain a Simulink.Signal subclass named Signal and a Simulink.Parameter subclass named Parameter.

3. Click Write Selected.

   The package directories and files, including the CSC registration file, are written out to the parent directory.

4. Click Close.

Optional: Define custom storage classes

Define custom storage classes. See Use the Custom Storage Class Designer.

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 folder under matlabroot.

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.

Note   Do not include function definitions of the form shown below in the initialization code. The following example only illustrates how the Data Class Designer considers a class instantiation function. 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 enumeration. For information on enumerations, see Using Enumerated Data in Simulink Models. The Data Class Designer cannot be used for defining enumerations.

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 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. The Data Class Designer also provides a tab labeled Custom Storage Classes, but this tab is now obsolete.

Back to Top

New Infrastructure for Extending Simulink Data Classes

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