Disabling and Hiding Dialog Box Controls

About Disabling and Hiding Controls

The Simulink product includes a customization API that allows you to disable and hide controls (also referred to as widgets), such as text fields and buttons, on most of its dialog boxes. The customization API allows you to disable or hide controls on an entire class of dialog boxes, for example, parameter dialog boxes via a single method call.

Before attempting to customize a Simulink dialog box or class of dialog boxes, you must first ensure that the dialog box or class of dialog boxes is customizable. Any dialog box that appears in the dialog pane of Model Explorer is customizable. In addition, any dialog box that has dialog and widget IDs is customizable. To determine whether a standalone dialog box (i.e., one that does not appear in Model Explorer) is customizable, open the dialog box, enable dialog and widget ID display (see Dialog Box and Widget IDs), and position the mouse over a widget. If a widget ID appears, the dialog box is customizable.

Once you have determined that a dialog box or class of dialog boxes is customizable, you must write MATLAB code to customize the dialog boxes. This entails writing callback functions that disable or hide controls for a specific dialog box or class of dialog boxes (see Writing Control Customization Callback Functions) and registering the callback functions via an object called the customization manager (see Registering Control Customization Callback Functions). Simulink then invokes the callback functions to disable or hide the controls whenever a user opens the dialog boxes.

For more information on Dialog Box controls, see:

Back to Top

Example: Disabling a Button on a Simulink Dialog Box

The following sl_customization.m file disables the Build button on the Code Generation pane of the Configuration Parameters dialog box for any model whose name contains "engine."

function sl_customization(cm)

% Disable for standalone Configuration Parameters dialog box.
cm.addDlgPreOpenFcn('Simulink.ConfigSet',@disableRTWBuildButton)
% Disable for Configuration Parameters dialog box that appears in
% the Model Explorer.
cm.addDlgPreOpenFcn('Simulink.RTWCC',@disableRTWBuildButton)

end

function disableRTWBuildButton(dialogH)
  hSrc   = dialogH.getSource;  % Simulink.RTWCC
  hModel = hSrc.getModel;
  modelName   = get_param(hModel, 'Name');

  if ~isempty(strfind(modelName, 'engine'))
    % Takes a cell array of widget Factory ID.
    dialogH.disableWidgets({'Simulink.RTWCC.Build'})
  end

end

To test this customization:

1. Put the preceding sl_customization.m file on the path.

2. Register the customization by entering sl_refresh_customizations at the command line or by restarting the MATLAB software (see Registering Customizations).

3. Open the sldemo_engine demo model, for example, by entering the command sldemo_engine at the command line.

Back to Top

Writing Control Customization Callback Functions

A callback function for disabling or hiding controls on a dialog box should accept one argument: a handle to the dialog box object that contains the controls you want to disable or hide. The dialog box object provides methods that the callback function can use to disable or hide the controls that the dialog box contains.

The dialog box object also provides access to objects containing information about the current model. Your callback function can use these objects to determine whether to disable or hide controls. For example, the following callback function uses these objects to disable the Build button on the Code Generation pane of the Configuration Parameters dialog box displayed in Model Explorer for any model whose name contains "engine."

function disableRTWBuildButton(dialogH)

  hSrc   = dialogH.getSource;  % Simulink.RTWCC
  hModel = hSrc.getModel;
  modelName   = get_param(hModel, 'Name');

  if ~isempty(strfind(modelName, 'engine'))
     % Takes a cell array of widget Factory ID.
     dialogH.disableWidgets({'Simulink.RTWCC.Build'})
  end

Back to Top

Dialog Box Methods

Dialog box objects provide the following methods for enabling, disabling, and hiding controls:

• disableWidgets(widgetIDs)

• hideWidgets(widgetIDs)

where widgetIDs is a cell array of widget identifiers (see Dialog Box and Widget IDs) that specify the widgets to be disabled or hidden.

Back to Top

Dialog Box and Widget IDs

Dialog box and widget IDs are strings that identify a control on a Simulink dialog box. To determine the dialog box and widget ID for a particular control, execute the following code at the command line:

cm = sl_customization_manager;
cm.showWidgetIdAsToolTip = true

Then, open the dialog box that contains the control and move the mouse cursor over the control to display a tooltip listing the dialog box and the widget IDs for the control. For example, moving the cursor over the Start time field on the Solver pane of the Configuration Parameters dialog box reveals that the dialog box ID for the Solver pane is Simulink.SolverCC and the widget ID for the Start time field is Simulink.SolverCC.StartTime.

Note   The tooltip displays "not customizable" for controls that are not customizable.

Back to Top

Registering Control Customization Callback Functions

To register control customization callback functions for a particular installation of the Simulink product, include code in the installation's sl_customization.m file (see Registering Customizations) that invokes the customization manager's addDlgPreOpenFcn on the callbacks.

The addDlgPreOpenFcn takes two arguments. The first argument is a dialog box ID (see Dialog Box and Widget IDs) and the second is a pointer to the callback function to be registered. Invoking this method causes the registered function to be invoked for each dialog box of the type specified by the dialog box ID. The function is invoked before the dialog box is opened, allowing the function to perform the customizations before they become visible to the user.

The following example registers a callback that disables the Build button on the Code Generation pane of the Configuration Parameters dialog box (see Writing Control Customization Callback Functions).

function sl_customization(cm)  

  % Disable for standalone Configuration Parameters dialog box. 
  cm.addDlgPreOpenFcn('Simulink.ConfigSet',@disableRTWBuildButton)

  % Disable for Configuration Parameters dialog box that appears in 
  % the Model Explorer 
  cm.addDlgPreOpenFcn('Simulink.RTWCC',@disableRTWBuildButton)

end

Note   Registering a customization callback causes the Simulink software to invoke the callback for every instance of the class of dialog boxes specified by the method's dialog box ID argument. This allows you to use a single callback to disable or hide a control for an entire class of dialog boxes. In particular, you can use a single callback to disable or hide the control for a parameter that is common to most built-in blocks. This is because most built-in block dialog boxes are instances of the same dialog box super class.

Back to Top

Disabling and Hiding Model Editor Menu Items

Customizing the Library Browser

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