Seth on Simulink

August 13th, 2008

When configuring a Simulink block, you usually use a graphical user interface (GUI).  In this post I’m going to investigate the basics of programming a dynamic GUI using the mask editor.

The Saturation block features

In my last post, I introduced the example of a Saturation block that can use fixed limits set in the mask dialog or dynamic limits set via input signals.  Here is an animation of the mask GUI that configures the block for these different modes.

When the Upper and Lower Limit Sources are internal, the block has a single input port.  When the Upper/Lower Limit Source is set to external, the block grows additional ports to accept signals that provide those limits.

Mask dialogs can associate actions with its components.  Most Simulink block GUIs have a standard row of buttons along the bottom. These four buttons provide a consistent interface for Simulink blocks, and when you use the mask editor, you get them free.

• OK – apply changes and dismiss the GUI
• Cancel – abandon changes made in the GUI and do not change the block
• Help – display documentation for the block
• Apply – apply changes made in the GUI

I added the other elements of the Saturation GUI through the parameters tab of the mask editor:

Each parameter of the mask has a row in the Dialog Parameters table.  The Prompt (1) is the text displayed next to the widget that sets the value.  The Variable (2) is the name of the variable set in the mask workspace when the GUI is applied.  The Type (3) controls the widget used for the parameter.  You can choose edit, checkbox or popup.  I picked popup for the parameters Upper Limit Source and Lower Limit Source parameters.  I set the popups (4) to display internal or external.  The Upper Limit and Lower Limit parameters use the edit type.

Each of the parameters also has an Evaluate (5) and Tunable (6) setting.  I want uplim and lowlim to have the values that are entered into the dialog.  If a MATLAB expression (like 'sin(x)+1') is used to set the value of the Upper Limit, I want that to be evaluated.  I don’t want the variable to hold the string that was typed into the edit field.  Tunable means the value of the parameter can change during the simulation.  Upper and Lower Limits will be tunable through the dialog if internal limits are used.  The Limit Source parameters are not tunable because they change the configuration of the block.  It is not possible to reconfigure the model structurally in mid simulation.

Dialog Callbacks

Dialog callbacks (7) are called when the parameter is changed in the mask.  Use dialog callback for error checking and controlling the visibility and enabled/disabled setting of other parameters in the mask dialog.  In the Saturation mask dialog, the Upper Limit Source and Lower Limit Source parameters fire a Dialog callback when you click on them.  This is the mechanism for enabling and disabling the Upper Limit and Lower Limit Edit fields in the GUI.

Key Point: Just like a handle graphics GUI, the Dialog callbacks run in the MATLAB base workspace. Program the callback as if you are running it from the MATLAB command line.

Here is the uplimsrc_cb called when the uplimsrc parameter changes:

% uplimsrc_cb Dialog Callback

function uplimsrc_cb(blk)

en = get_param(blk,'MaskEnables');

switch get_param(blk,'uplimsrc')

    case 'external'

        en{2} = 'off';

    case 'internal'

        en{2} = 'on';

    otherwise

        disp('Should never get here')

end

set_param(blk,'MaskEnables',en)

When you click on the uplimsrc popup and change it, this callback fires.  The callback:

• Gets the MaskEnables, which is a cell array of on/off values, one for each parameter
• Assigns the second element (corresponding to uplim) to off if uplimsrc is external, on if uplimsrc is internal
• Sets the MaskEnables to use the updated on/off values

If the block uses an external limit source, the corresponding fixed limit is disabled.

Mask Dialog Callback Confusion

I have found callbacks that modify the block contents are a major source of problems.

Key Point: The mask dialog callback is for modifying the mask dialog, not the system.

The documentation on mask callbacks also discusses this subject.  If you need to modify the contents of your system, do that in the Mask Initialization, which runs when you click the Apply or OK button.  That will be the topic of my next post.

Now it’s your turn

Do you have dynamic masks? Leave a comment here.

16:45 UTC | Posted in Masking | Permalink |

You can follow any responses to this entry through the RSS 2.0 feed. You can skip to the end and leave a response. Pinging is currently not allowed.

10 Responses to “Dynamic Mask Dialogs”

1. Waqas Mahmood replied on August 13th, 2008 at 21:48 UTC :
   

   In video stabilization demo provided with video and image processing blockset, the ‘Stabilization’ block has a mask that takes parameters as:
   pos.template_orig = template_orig;
   pos.template_size = template_size;
   pos.search_border = search_border;
   Initial inputs are acquied via user dialog. My question is how can i make it dynamic? i.e. pass these parameters to the block in runtime rather than specifying them before running the simulation.

   Thanks

2. Ashish Sadanandan replied on August 14th, 2008 at 00:20 UTC :
   

   I wanted to add another tip. When referring to the mask parameters within your callback it’s very useful to create a C-style enumeration instead of calling them explicitly by numbers. In the above example, change the callback M file to:

   % uplimsrc_cb Dialog Callback
   function uplimsrc_cb(blk)

   UPPER_LIM_SRC = 1;
   UPPER_LIM = UPPER_LIM_SRC + 1;
   LOWER_LIM_SRC = UPPER_LIM + 1;
   LOWER_LIM = LOWER_LIM_SRC + 1;

   en = get_param(blk,’MaskEnables’);

   switch get_param(blk,’uplimsrc’)
   case ‘external’
   en{UPPER_LIM} = ‘off’;
   case ‘internal’
   en{UPPER_LIM} = ‘on’;
   otherwise
   disp(’Should never get here’)
   end

   set_param(blk,’MaskEnables’,en);

   This comes in very handy for masks with a large number of parameters and also if you need to add / remove a parameter from the mask.

   Ashish.

3. Hans-Werner replied on August 14th, 2008 at 05:38 UTC :
   

   What if I want to have a parameter that is only visible if another parameter gets a certain value ? For example a popup that is hidden and only visible when I select a checkbox. What if the values of a popup are subject to another popup ? Think of countries and states.

4. Witek Jachimczyk (team lead for the Video Blockset) replied on August 14th, 2008 at 15:18 UTC :
   

   Mahmood,

   >> pos.template_orig = template_orig;
   >> pos.template_size = template_size;
   >> pos.search_border = search_border;

   Both template_size and search_border affect the size of Simulink connections (wires). Simulink requires fixed size connections during runtime, therefore this information must be gathered prior to running the model.

   template_orig provides location information. It does not affect wire size, therefore it can be set dynamically during runtime. Although the Stabilization demo doesn’t show you how to do it, it’s possible to turn the mask input into a port to the Stabilize subsystem.

   Witek

5. Seth replied on August 17th, 2008 at 21:18 UTC :
   

   @Mahmood - thanks for the good question. I’m glad Witek was able to respond. (Thanks Witek!)

   @Ashish - This is an excellent tip and a very clear example. I’m sure I will be using that in the future.

   @Hans-Werner - The hidden/visible state of a mask widget is controlled by the MaskVisibilities parameter. It uses a cell array of ‘on’/'off’ values to control your mask. Try:

   get_param(blk,’MaskVisibilities’)

   The method I have used to set values of one popup based on another also involves MaskVisibilities. This only works if you have a small number of groups to switch between. Create a separate popup for each group and make the appropriate popup that corresponds to that group visible, and all the alternatives invisible. The programming gets very complicated to do it this way. The other option is to build your GUI using GUIDE and replace the OpenFcn for the block.

6. Waqas Mahmood replied on August 18th, 2008 at 11:15 UTC :
   

   Thanks for the respsonse. My other question is, Tracking with zoom-in/out requires to change the template size from frame to frame, in this particular case, how the template size can be varied dynamically during simulation? If not, what alternate method can I try from within Simulink?

   Thanks and Regards
   Mahmood

7. Alex replied on August 27th, 2008 at 07:03 UTC :
   

   Is it possible to dynamically change the MaskStyle, i.e. change the text entries of a popup parameter?

   For example, I would like to have a popup, whichs offers the choice between different parameter files I can load for the block. Now, I don’t want to alter the popup manually everytime I add a parameter-file to the list in the library block but rather scan a folder containing the files and create the popup list accordingly. Whenever I try something like this in the dialog callback with
   set_param(blk,’MaskStyles’,list)
   the dialog is closed automatically with a warning that a mask parameter has been changed.

   Any suggestions/ideas on how to solve this problem?

   Thanks

8. Tom replied on March 2nd, 2009 at 20:42 UTC :
   

   In the Simulink “discontinuities” library, the “Saturation Dynamic” block has a button in it’s dialog, and appears to be a masked subsystem. The mask uses callbacks and initialization code. I’d like to do something similar in my own custom dialogs. Can you explain how this is done?

9. Guy Rouleau replied on March 3rd, 2009 at 00:31 UTC :
   

   @Tom,

   You should have a look at previous posts from Seth, there is an example that exactly address this question:

   http://blogs.mathworks.com/seth/2008/08/13/dynamic-mask-dialogs/

10. Seth replied on March 3rd, 2009 at 02:13 UTC :
    

    @Tom - Buttons can not be added to user written masks using the Mask Editor. If the mask editor doesn’t provide the flexibility you need, make a GUI using M-code or GUIDE and set the OpenFcn for the block to launch your GUI.

Leave a Reply

<pre class="code">
a = magic(3);
sum(a)
</pre>

These postings are the author's and don't necessarily represent the opinions of The MathWorks.