Tune Mask Enumeration Parameters - Popup and Radio Button

Open Script

You can visualize the behavior of a Simulink® model under different conditions by tuning block parameter values. You can assign numeric or string values to the popup and radio button parameters instead of indexes.

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

Select from list of option - 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 a list of options 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 and 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 internally. You can select the option for the popup or radio button parameter. The corresponding value 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 model workspace variable to a radio button.

Explore the Model

This example model contains four scenarios where you can associate values to the popup parameter to achieve tunability.

The Subsystem block ListofOptions uses a list of options 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. The popup parameter is associated with model workspace variable workspaceVar.

open_system("slexMaskTunablePopupExample.slx");

Associate Values to Popup Parameter Using List of Options

To create and associate a list of options for the popup parameter:

1. Create a Subsystem block ListofOptions and mask the block.

2. Create a popup parameter XFactorParam.

3. Double-click Type options and select List of options.

4. Enter the Description of each option as alpha(0.001), beta(0.0001), and gamma(0.00001), and their Values as 0.001, 0.0001, and 0.00001.

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

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

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

7. Double-click the block ListofOptions and select the value for XFactor and simulate the model. Observe that the selected value appears in the Display block.

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.

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

2. Create a popup parameter XFactorParam.

3. Double-click Type options select Use enumeration, then select Reference Enumeration file.

4. Enter the name of the enumeration file as XFactor without the 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 enumerated 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(0.001,  'alpha (0.001)')
      beta (0.0001, 'beta (0.0001)')
      gamma(0.00001,'gamma (0.00001)')
   end
 end

In the generated code, the default data type for the enumeration member is double. Alternatively, you can also specify a 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 Mask.

6. Reference the popup parameter in the child block. Create a Constant block inside the Subsystem block. The value of the Constant parameter inside the subsystem is set as XFactorValues(XFactorParam).

7. Simulate the model and generate code.

During model compilation, XFactorValues(XFactorParam) evaluates to XFactorValues(XFactor.alpha), thus setting the value of the Constant parameter. The parameter value is evaluated as the enumeration member corresponding to the display name you select. For example, if you select alpha(0.0001) from the Parameters drop-down, the value of XFactorParam is set to XFactor.alpha.

During model compilation, in order to get the numeric value corresponding to an option, Simulink creates an internal array that holds the value corresponding to each option. Therefore, when you select an option, the value corresponding to the option is selected from the array.

In this example, the array of values corresponding to parameter options is XFactorValues = {0.001, 0.0001, 0.00001}

Note: To get the value corresponding to the selected option, use this format:

| _enumerationClassName_ |Values| _ParameterName_ |

| _enumerationClassName_ | is the name of the enumeration class, and | _ParameterName_ | is the name of the popup parameter that you specified in the mask editor.

You can customize a name for the array in the enumeration file as the return value of the getValueArrayName() function.

classdef  XFactor < Simulink.Mask.EnumerationBase
 enumeration
     alpha(0.001,  'alpha (0.001)')
     beta (0.0001, 'beta (0.0001)')
     gamma(0.00001,'gamma (0.00001)')
 end
 methods(Static)
     function valueArrayName = getValueArrayName()
        valueArrayName = 'customValueArrayName';
     end
 end
end

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 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 mask the block.

2. Create a popup parameter XFactorParam.

3. Double-click Type options. 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.

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, optimization of code generation inlines all parameters in the the generated code. To achieve tunability for a specific parameter, create a variable of type Simulink.Parameter with a specific storage class (other than Auto) in the workspace and associate it with the mask popup parameter. You cannot associate a variable to the radio button parameter.

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

2. Create a popup parameter XFactorParam.

3. Double-click Type options. Select the option Use enumeration, then select Reference Enumeration file.

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

5. Click Save Mask.

6. Reference the popup parameter in the child block. Create a Constant block inside the Subsystem block. The value of the Constant parameter inside the subsystem is set as XFactorValues(XFactorParam).

7. Open the mask dialog box. Click the action widget.

8. Select Associate Variable. You can associate an existing variable with the popup parameter, or create a new variable in one of the available locations and associate it with the popup parameter.

After associating the variable with the popup parameter, the variable appears next to the popup option.

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, 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];
}

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);

/* TypeOptions defined using List of Options method */

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

     EnumerationMember with properties:

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

/* TypeOptions defined 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'

/* TypeOptions defined 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

3. Associate the list of options 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

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 will be populated with the enumeration members in the specified class prefixed by the enumeration class name.

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

Tune Mask Enumeration Parameters - Popup and Radio Button

Explore the Model

Associate Values to Popup Parameter Using List of Options

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