Tune Mask Enumeration Parameters - Popup and Radio Button

Open Script

You can observe the behavior of a Simulink® model under different conditions by tuning block parameter values. The Type options dialog box in Mask Editor helps you to associate custom values to each option of popup or radio button parameter.

Achieve tunability for mask popup and radio buttons in these ways:

Options with custom values — Select the option for the popup or radio button parameter from the mask dialog box. The corresponding value is used in simulation and code generation. Using options with custom values allows for tunability in simulation but not in generated code.

Provide external enumeration file — Populate the options for the popup or radio button parameter from an external enumeration file. Select the option from the mask dialog box. The corresponding value from the enumeration file is used in simulation and code generation. You can achieve tunability in both simulation and code generation with this method.

Create enumeration class — Provide data to create an enumeration class that defines the parameter options and their values. Select the option for the popup or radio button parameter. The corresponding value from the enumeration class is used in simulation and code generation. You can achieve tunability in both simulation and code generation with this method.

Note: You can create options and achieve tunability for a radio button using the above methods, but you cannot achieve tunability by associating a workspace variable to a radio button.

Explore the Model

This example model contains four Subsystems that associate values to popup parameters to achieve tunability.

The Subsystem block Options with custom values uses options with custom values for the popup parameter.

The Subsystem block EnumClass uses an enumeration class with the provided data and associates it with the popup parameter.

The Subsystem block ExternalEnum references an external enumeration file and associates the values to the popup parameter.

The Subsystem block Associate Variable associates a variable with the popup parameter. The parameter values and display strings are populated from external enumeration file XFactor.m. The popup parameter is associated with model workspace variable workspaceVar.

open_system("slexMaskTunablePopupExample.slx");

Associate Values to Popup Parameter Using Options with Custom Values

To create and associate options for the popup parameter using custom values:

1. Create a Subsystem block Options with custom values and create a mask for the block. Connect the Subsystem block to a Display block.

2. In Parameters & Dialogs tab of the Mask Editor, create a popup parameter XFactorParam.

3. In the Property Editor pane, double-click Type options field. In the dialog box that opens, select Options with custom values.

4. Click the plus sign to add new row to the table of custom values. In the Description column, enter alpha(0.001) and in the Value column, enter 0.001. Similarly, add two new options with beta(0.0001) and gamma(0.00001) in the Description column, enter 0.0001 and 0.00001 in the Value column, respectively.

You can associate string values to the popup options. To enter string values as options to the popup parameter, enter string values enclosed in quotes in the Values column.

5. Click Save, and then click Save Mask to save the options and the mask.

6. Reference the popup parameter in a child block of the subsystem. Create a Constant block inside the Subsystem block and connect it to the output. Set the Constant value parameter in the Constant block to XFactorParam.

7. Double-click the block Options with custom values and select the value for XFactorParam and simulate the model. Observe that the selected value appears in the Display block.

Note: Using options with custom values allows for tunability in simulation but not in generated code.

Reference an External Enumeration File for Popup Options

An external enumeration file can have multiple members with different display names and values. When the enumeration file is associated with a popup parameter:

The display name of the enumeration member becomes the popup parameter option.
The enumeration member value becomes the value assigned to the popup parameter option.

To create and associate options for the popup parameter using an enumeration file:

1. Create a Subsystem block ExternalEnum and create a mask for the block.

2. In Parameters & Dialog tab of the Mask Editor, create a popup parameter XFactorParam with prompt XFactorParam options.

3. In the Property Editor pane, double-click the Type options field. In the dialog box that opens, select Use enumeration, and then select Reference Enumeration file.

4. Enter the name of the enumeration file as XFactor (without the .m file extension).

The contents of the file appear in the Name, Description, and Value columns. Observe that the contents are read-only and cannot be edited from the interface.

Numeric values are associated with popup options from the enumeration file Xfactor.m. The enumeration class of the file Xfactor, is derived from Simulink.Mask.EnumerationBase. The class has three enumeration members, alpha, beta, and gamma. These enumerated members have numeric values 0.001, 0.0001, and 0.00001, respectively.

classdef  XFactor < Simulink.Mask.EnumerationBase
   enumeration
      alpha(.001,  'alpha (.001)')
      beta (.0001, 'beta (.0001)')
      gamma(.00001,'gamma (.00001)')
   end
 end

In the generated code, the default data type for the enumeration member is double. Alternatively, you can specify a different data type for the enumeration members. For example, use alpha(int32(0.001),'alpha(0.001)') in the enumeration class file. All members of the enumeration class must be of the same data type.

5. Click Save and then Save Mask.

6. Reference the popup parameter in a child block of the subsystem. Create a Constant block inside the Subsystem block. Set the Cosntant value parameter of the Constant block to XFactorParam.

7. Simulate the model and generate code.

The parameter value is evaluated as the value associated with the enumeration member corresponding to the display name you select. For example, if you select alpha(0.001) from the XFactorParam options drop-down list, the value of XFactorParam is set to 0.001.

You can generate code using Simulink Coder™ or Embedded Coder™. In the generated code:

The value array XFactorValues is generated in the | _modelname.c_ | file.

const real_T XFactorValues[3] = { 0.001, 0.0001, 1.0E-5 } ;

The enumeration is generated in the code according to the referenced enumeration file.

typedef enum {
XFactor_alpha = 1,                   /* Default value */
XFactor_beta,
XFactor_gamma
} XFactor;

The mask parameter XFactorParam appears in the parameter structure.

/* Parameters (default storage) */
struct P_slexMaskTunablePopupExample_T_ {
XFactor ExternalEnum_XFactorParam;/* Mask Parameter: ExternalEnum_XFactorParam
                                   * Referenced by: '<S1>/Constant'
                                   */
};

Tunable variable XFactorParam is referenced while generating the output. You can specify different values to XFactorParam and thus XFactorParam is tunable.

/* Model step function */
void slexMaskTunablePopupExample_step(void)
{
    /* Outport: '<Root>/Out3' incorporates:
    *  Constant: '<S1>/Constant'
    */
    slexMaskTunablePopupExample_Y.Out3 = XFactorValues[(int32_T)
    slexMaskTunablePopupExample_P.ExternalEnum_XFactorParam - 1];
}

Create and Associate Enumeration Class to Popup Parameter

An enumeration class can be created with the user data and associated with the popup parameter. To create an enumeration class:

1. Create a Subsystem block EnumClass and create a mask for the block.

2. In Parameters & Dialogs tab of the Mask Editor, create a popup parameter XFactorParam with prompt XFactorParam options.

3. In the Property Editor pane, double-click the Type options field. In the dialog box that opens, select Use enumeration and then select Create new Enumeration.

4. Enter the name of the enumeration class as XFactorInternal and enter the values for Name, Description, and Value.

5. Click Save and then click Save Mask to save the enumeration class and the mask.

6. Reference the popup parameter in a child block of the subsystem. Create a Constant block inside the Subsystem block. Set the Cosntant value parameter of the Constant block to XFactorParam.

If the values of the enumeration members are all integers, then the value of the mask parameter when used in the child block is the enumeration member, (for example, XFactorInternal.beta). However, if any enumeration member has a noninteger value such as 100.1, then the value of the mask parameter when used in the child block is its numeric value and not the enumeration member XFactorInternal.beta.

7. Simulate the model and generate the code. The mask parameter (XFactorParam) appears in the parameter structure.

/* Parameters (default storage) */
struct P_slexMaskTunablePopupExample_T_ {
XFactorInternal EnumClass_XFactorParam;/* Mask Parameter: EnumClass_XFactorParam
                                        * Referenced by: '<S1>/Constant'
                                        */
};

The tunable parameter XFactorParam is referenced while generating the output. You can specify different values to XFactorParam and thus XFactorParam is tunable.

/* Model step function */
void slexMaskTunablePopupExample_step(void)
{
    /* Outport: '<Root>/Out2' incorporates:
     *  Constant: '<S1>/Constant'
    */
    slexMaskTunablePopupExample_Y.Out2 = XFactorInternalValues[(int32_T)
    slexMaskTunablePopupExample_P.EnumClass_XFactorParam - 1];
}

Create and Associate Variables Using the Mask Dialog Box

By default, the parameter behavior in Model Settings is Tunable for all parameters in the generated code. However, if the Default parameter behavior is set to Inlined in the Model Settings and if you want to tune a specific parameter then create a variable of type Simulink.Parameter with a specific storage class (other than Auto) in the desired workspace and associate it with the mask popup parameter. You cannot associate a workspace variable to a radio button parameter.

1. Create a Subsystem block ExternalEnum and create a mask for the block.

2. In Parameters & Dialogs tab of the Mask Editor, create a popup parameter XFactorParam with prompt XFactorParam options.

3. In the Property Editor pane, double-click the Type options field. In the dialog box that opens, select the option Use enumeration, then select Reference Enumeration file.

4. Enter the name of the enumeration file as XFactor (without the file extension .m).

5. Click Save and then Save Mask.

6. Reference the popup parameter in a child block of the subsystem. Create a Constant block inside the Subsystem block. Set the Cosntant value parameter of the Constant block to XFactorParam.

7. Open the mask dialog box of the Subsystem block. Click the action widget.

8. Select Associate Variable. Specify Variable name as worspaceVar to associate the variable workspaceVar with the popup parameter. You can also create a new variable of type Simulink.Parameter or MATLAB Variable in one of the available locations in the Locations list and associate it with the popup parameter.

Click Create to create and associate the variable with the popup parameter. The variable appears next to the popup option in the mask dialog box.

The value of the associated variable and the popup value are always synchronized. For example, if you change the popup option from alpha (0.001) to beta (0.0001), the value of workspaceVar is updated to XFactor.beta. Similarly, when you change the value of the variable workspaceVar, the value of the parameter reflects the change in the mask dialog box.

9. Simulate the model and generate code.

The associated variable value appears in the parameter structure corresponding to the tunable popup parameter.

/* Parameters (default storage) */
    struct P_slexMaskTunablePopupExample_T_ {
    XFactor workspaceVar;                /* Variable: workspaceVar
                                      * Referenced by: '<S1>/Constant'
                                      */
};

The associated variable is referenced in the step function to generate output.

/* Model step function */
void slexMaskTunablePopupExample_step(void)
{
    /* Outport: '<Root>/Out4' incorporates:
    *  Constant: '<S1>/Constant'
    */
    slexMaskTunablePopupExample_Y.Out4 = XFactorValues[(int32_T)
    slexMaskTunablePopupExample_P.workspaceVar - 1];
}

Note: You can also create and associate variables using mask dialog box for enumerations created using user provided data.

Tune Popup Parameter Programmatically

You can use a set of APIs to tune popup parameters programmatically.

1. Create an object of Simulink.Mask.EnumerationMember and define the number of options.

typeOptions = Simulink.Mask.EnumerationMember.empty(3,0)

2. Define options for the popup parameter.

typeOptions=Simulink.Mask.EnumerationMember.empty(3,0);
typeOptions(1) = Simulink.Mask.EnumerationMember('alpha','XFactorAlpha',0.001);
typeOptions(2) = Simulink.Mask.EnumerationMember('beta','XFactorBeta',0.0001);
typeOptions(3) = Simulink.Mask.EnumerationMember('gamma','XFactorGamma',0.00001);

3. Define TypeOptions using Options with custom values method

enumObj = Simulink.Mask.EnumerationTypeOptions('EnumerationMembers',typeOptions)
enumObj.EnumerationMembers(1)
ans =

     EnumerationMember with properties:

        MemberName: 'alpha'
   DescriptiveName: 'XFactorAlpha'
             Value: 1.0000e-03

4. Define TypeOptions by creating an enumeration class

enumObj =
Simulink.Mask.EnumerationTypeOptions('EnumerationMembers',typeOptions,'EnumNameInGeneratedCode','XFactor');
enumObj(1)
 ans =
   EnumerationTypeOptions with properties:

        EnumerationMembers: [1*3 Simulink.Mask.EnumerationMember]
   EnumNameInGeneratedCode: 'XFactor'

5. Define TypeOptions by referencing an external enumeration file

enumObj = Simulink.Mask.EnumerationTypeOptions('ExternalEnumerationClass', 'XFactor');
enumObj.EnumerationMembers(1)

ans =

EnumerationMember with properties:

        MemberName: 'alpha'
   DescriptiveName: 'XFactor.alpha'
             Value: 1

6. Associate the options with custom values to the mask popup parameter.

addParameter(maskobj,'Type','popup','TypeOptions',enumObj);
paramHandle = maskobj.getParameter('XFactorParam');
paramHandle =

MaskParameter with properties:

            Type: 'popup'
     TypeOptions: [1*1 Simulink.Mask.EnumerationTypeOptions]
            Name: 'XFactor'
          Prompt: ''
           Value: 'XFactorAlpha'
        Evaluate: 'on'
         Tunable: 'on'
       NeverSave: 'off'
          Hidden: 'off'
        ReadOnly: 'off'
         Enabled: 'on'
         Visible: 'on'
     ShowTooltip: 'on'
        Callback: ''
           Alias: ''
    VariableName: ''
   DialogControl: [1*1 Simulink.dialog.parameter.Popup]

Note: A new property VariableName is added to the mask parameter, which is used for associating tunable variable to the popup parameter.

Use this command to associate the workspace variable to the value of the parameter.

paramHandle.VariableName = 'workspaceVar'

Associate Enumeration File Derived from `Simulink.IntEnumType`

If you have an existing enumeration class derived from Simulink.IntEnumType, you can use the enumeration file to associate numeric values to the popup parameter instead of creating a new enumeration class derived from Simulink.Mask.EnumerationBase. To associate enumeration file derived from Simulink.IntEnumType, follow these steps.

1. Define the enumeration file Color.m

classdef Color < Simulink.IntEnumType
    enumeration
        red(1)
        green(100)
        blue(1000)
    end
    methods(Static)
        function aOut = addClassNameToEnumNames()
            aOut = false;
        end
    end
end

2. Specify the name of the enumeration class.

3. The popup options are populated with the enumeration members in the specified class prefixed by the enumeration class name.

4. Set the Constant value parameter to the popup parameter XFactorParam.

Tune Mask Enumeration Parameters - Popup and Radio Button

Explore the Model

Associate Values to Popup Parameter Using Options with Custom Values

Reference an External Enumeration File for Popup Options

Create and Associate Enumeration Class to Popup Parameter

Create and Associate Variables Using the Mask Dialog Box

Tune Popup Parameter Programmatically

Associate Enumeration File Derived from Simulink.IntEnumType

See Also

Associate Enumeration File Derived from `Simulink.IntEnumType`