Tutorial: Create a GUI with UI Designer to Interact with a Simulation

Learn how to generate code from the UI Designer and use it to run a simulation.

Files for This Tutorial

Original gui code.ui; Original gui code.oml; Gui for simulation.scm

A finished version of the model you build in this tutorial along with any files required to complete the tutorials are available from the Demo Browser: Tutorial Models > Modeling and Simulation > Create a GUI with UI Designer or at this location: <installation_directory>\Tutorial Models\Modeling and Simulation\Create a GUI with UI Designer.

Overview

After you generate OML code from the UI Designer, include it in the Twin Activate environment to change some block parameters and run a simulation.

The model in this tutorial has an Include block. You will use the GUI to select the gain that will multiply the input parameter, that is, a Step signal.

Generate the Twin Activate Model

From the Palette Browser, select Activate > SignalGenerators > Step Generator.
From the Palette Browser, select Activate > CustomBlocks > IncludeDiagram, and then modify the block's Includes tab:
- Number of possible diagrams: 2
- Diagram choice: Gain
- Diagram path: 'Gain1' and 'Gain2'
Select Activate > SignalViewers > Scope.
Connect them following the setup below:
Create two different super blocks with a gain inside each of them and put Input and Output ports.

The setup outside of the super blocks should match the following:

Note: The names of the super block are the same as used on the Include Diagram block.
Right-click each super block, and then select Status > Off.
From the ribbon, open Simulation > Setup, and then set Final Time to "simtime."

Create the GUI

From the ribbon, select Tools > UI Designer.

The UI Designer opens in a new window.
Drag objects from the Widget box into the Dialog to create your GUI design.
The following example shows a simple GUI with a main panel, push button, slider, radio buttons, push button, and labels.
Modify the location, name, and properties of each object as required for your design.
To adjust location, select the object and move it with your mouse or arrow keys.

To modify properties, select an object, then modify the desired properties in the Property Editor.

You can also right-click an object and define a number of properties through the context menu. The Gain selection, its values, and simulation time parameters are manipulated on the main code on Twin Activate. Therefore, it is good practice to set ‘tag’ values on each of them. Example on the Gain RadioButton:
From the UI Designer ribbon, click the Preview button.

A preview of your GUI design is shown. Review your design, and then close the Preview window.
Save your design and specify your prefered file format:
- *.UI: Saves your design as a UI Designer file. Use this file format when you want to continue working on your design through UI Designer.
- *.OML: Use this format to generate a code skeleton.
Note: After you save your design as code, you cannot load it back into the UI Designer. If you want to keep a working version of your design that you can open through the UI Designer, save a version in .UI format before saving as code.

When the design example from above is saved as an .OML file, the following code is produced:

% Auto-generated code [UI Designer]
% Altair Twin Activate 2023
% Last update: Fri Jan 19 09:11:07 2024

%------------------------------------------------------------
% % Callback functions: 
%------------------------------------------------------------
function gain1_button_callback(handle, data, varargin)
  % Add implementation: [callback]
end

function gain2_button_callback(handle, data, varargin)
  % Add implementation: [callback]
end

function gain1_value_callback(handle, data, varargin)
  % Add implementation: [callback]
end

function gain2_value_callback(handle, data, varargin)
  % Add implementation: [callback]
end

function simtime_slider_callback(handle, data, varargin)
  % Add implementation: [callback]
end

function runsim_button_callback(handle, data, varargin)
  % Add implementation: [callback]
end

%------------------------------------------------------------
% % GUI objects:
%------------------------------------------------------------
Dialog = figure('units', 'pixels', 'position', [0 0 167 346] ...
    , 'name','Dialog', 'windowicon','', 'windowstyle','undocked' ...
    , 'tag','Dialog', 'handlevisibility','on', 'numbertitle','off', 'visible','on');

uiPanel = uipanel('parent', Dialog, 'units','normalized', 'position',[0.00 0.03 0.96 0.96] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'backgroundcolor', [246 246 246] ...
    , 'bordertype','none', 'borderwidth', 1 , 'title','' ...
    , 'aspectratio','off', 'backgroundimage','', 'tag','uiPanel' ...
    , 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on');

gain1_button = uicontrol('parent', uiPanel, 'style','radiobutton' ...
    , 'callback','gain1_button_callback', 'units','normalized', 'position',[0.07 0.03 0.66 0.09] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'string','Gain 1', 'value', 1 , 'foregroundcolor', [20 20 20] ...
    , 'interruptible','off', 'tag','goption', 'userdata',[], 'tooltipstring','', 'visible','on');

gain2_button = uicontrol('parent', uiPanel, 'style','radiobutton' ...
    , 'callback','gain2_button_callback', 'units','normalized', 'position',[0.07 0.12 0.66 0.09] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'string','Gain 2', 'value', 0 , 'foregroundcolor', [20 20 20] ...
    , 'interruptible','off', 'tag','gain2_button', 'userdata',[], 'tooltipstring','', 'visible','on');

gain1_value = uicontrol('parent', uiPanel, 'style','edit' ...
    , 'callback','gain1_value_callback', 'units','normalized', 'position',[0.07 0.25 0.34 0.10] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'string','0' ...
    , 'horizontalalignment','left' ...
    , 'verticalalignment','middle', 'foregroundcolor', [20 20 20], 'backgroundcolor', [255 255 255] ...
    , 'interruptible','off', 'tag','g1v', 'userdata',[] ...
    , 'value',0, 'tooltipstring','', 'visible','on');

gain1_text = uicontrol('parent', uiPanel, 'style','text' ...
    , 'units','normalized', 'position',[0.46 0.25 0.47 0.09] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'string','Gain 1 Value' ...
    , 'horizontalalignment','left' ...
    , 'verticalalignment','middle', 'foregroundcolor', [20 20 20], 'backgroundcolor', [255 255 255] ...
    , 'tag','gain1_text', 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on');

gain2_text = uicontrol('parent', uiPanel, 'style','text' ...
    , 'units','normalized', 'position',[0.46 0.37 0.47 0.09] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'string','Gain 2 Value' ...
    , 'horizontalalignment','left' ...
    , 'verticalalignment','middle', 'foregroundcolor', [20 20 20], 'backgroundcolor', [255 255 255] ...
    , 'tag','gain2_text', 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on');

gain2_value = uicontrol('parent', uiPanel, 'style','edit' ...
    , 'callback','gain2_value_callback', 'units','normalized', 'position',[0.07 0.37 0.34 0.10] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'string','0' ...
    , 'horizontalalignment','left' ...
    , 'verticalalignment','middle', 'foregroundcolor', [20 20 20], 'backgroundcolor', [255 255 255] ...
    , 'interruptible','off', 'tag','g2v', 'userdata',[] ...
    , 'value',0, 'tooltipstring','', 'visible','on');

simtime_slider = uicontrol('parent', uiPanel, 'style','slider' ...
    , 'callback','simtime_slider_callback', 'units','normalized', 'position',[0.13 0.62 0.80 0.07] ...
    , 'enable','on', 'max', 30 , 'min', 1 , 'orient','horizontal', 'sliderstep', [1 10] ...
    , 'tracking', 'on', 'tickinterval', 1, 'tickmarks', 'nomarks' ...
    , 'callbackdelay',0.000000, 'interruptible','off', 'tag','simtimev' ...
    , 'userdata',[], 'tooltipstring','', 'visible','on');

simtime = uicontrol('parent', uiPanel, 'style','text' ...
    , 'units','normalized', 'position',[0.26 0.50 0.54 0.09] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'string','Simulation Time' ...
    , 'horizontalalignment','left' ...
    , 'verticalalignment','middle', 'foregroundcolor', [20 20 20], 'backgroundcolor', [255 255 255] ...
    , 'tag','simtime', 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on');

runsim_button = uicontrol('parent', uiPanel, 'style','pushbutton' ...
    , 'callback','runsim_button_callback', 'units','normalized', 'position',[0.20 0.84 0.66 0.09] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','bold', 'fontsize',8.00 , 'fontunits','pixels' ...
    , 'string','Run Simulation', 'horizontalalignment','center' ...
    , 'backgroundcolor', [255 255 255], 'foregroundcolor', [20 20 20] ...
    , 'backgroundimage','', 'aspectratio','on' ...
    , 'interruptible','off', 'tag','runsim_button', 'userdata',[] ...
    , 'value',0, 'tooltipstring','', 'visible','on');

min_simtime = uicontrol('parent', uiPanel, 'style','text' ...
    , 'units','normalized', 'position',[0.13 0.69 0.14 0.10] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.00 , 'fontunits','pixels' ...
    , 'string','1' ...
    , 'horizontalalignment','center' ...
    , 'verticalalignment','middle', 'foregroundcolor', [20 20 20], 'backgroundcolor', [246 246 246] ...
    , 'tag','min_simtime', 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on');

max_simtime = uicontrol('parent', uiPanel, 'style','text' ...
    , 'units','normalized', 'position',[0.79 0.69 0.14 0.10] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.00 , 'fontunits','pixels' ...
    , 'string','30' ...
    , 'horizontalalignment','center' ...
    , 'verticalalignment','middle', 'foregroundcolor', [20 20 20], 'backgroundcolor', [246 246 246] ...
    , 'tag','max_simtime', 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on');

Combine GUI and Model

As the blocks are set and the OML code was generated, it is time to bring the OML code to the Twin Activate environment.

Return to the Twin Activate window and select Activate > CustomBlocks > ExecOMLScript.

The original OML code must be slightly changed. First, it is good practice to clear the workspace at the beginning of the code, using the commands below on line 1:

clc, clear, close all

When a Twin Activate model is run from this block, some parameters and functions must be used. This GUI has a PushButton that will start the simulation, so the commands below must be used inside the callback function of this Widget:

model = bdeGetCurrentModel; %Get handle of current model

aux_g1v = findobj('tag', 'g1v'); %Auxiliar variable to the Gain1 value
ctx.g1 = str2num(get(aux_g1v, 'string')); %Getting Gain1 Value

aux_g2v = findobj('tag', 'g2v'); %Auxiliar variable to the Gain2 value
ctx.g2 = str2num(get(aux_g2v, 'string')); %Getting Gain2 Value

aux_rbut = findobj('tag', 'goption'); %Auxiliar variable to the RadioButton option
rbut = get(aux_rbut, 'value'); %Getting RadioButton Value - 1: 1st Gain, 0: 2nd Gain

if rbut == 1
  ctx.Gain = 1; %Select the first SuperBlock - Gain1
else
  ctx.Gain = 2; %Select the second SuperBlock - Gain2
end

aux_sliv = findobj('tag', 'simtimev'); %Auxiliar variable to the Slider value
ctx.simtime = get(aux_sliv, 'value'); %Getting Final Simulation Time
env = getnewenv; %Create a new environment variable to read/write the signals
vssRunSimulation(model,ctx,env); %Run Twin Activate simulation

Below is the final OML code to be used inside the ExecOmlScript:

clc, clear, close all

% Auto-generated code [UI Designer]
% Altair Twin Activate 2023
% Last update: Fri Jan 19 09:02:01 2024

%------------------------------------------------------------
% % Callback functions: 
%------------------------------------------------------------
function gain1_button_callback(handle, data, varargin)
  % Add implementation: [callback]
end

function gain2_button_callback(handle, data, varargin)
  % Add implementation: [callback]
end

function gain1_value_callback(handle, data, varargin)
  % Add implementation: [callback]
end

function gain2_value_callback(handle, data, varargin)
  % Add implementation: [callback]
end

function simtime_slider_callback(handle, data, varargin)
  % Add implementation: [callback]
end

function runsim_button_callback(handle, data, varargin)
  model = bdeGetCurrentModel; %Get handle of current model

  aux_g1v = findobj('tag', 'g1v'); %Auxiliar variable to the Gain1 value
  ctx.g1 = str2num(get(aux_g1v, 'string')); %Getting Gain1 Value

  aux_g2v = findobj('tag', 'g2v'); %Auxiliar variable to the Gain2 value
  ctx.g2 = str2num(get(aux_g2v, 'string')); %Getting Gain2 Value

  aux_rbut = findobj('tag', 'goption'); %Auxiliar variable to the RadioButton option
  rbut = get(aux_rbut, 'value'); %Getting RadioButton Value - 1: 1st Gain, 0: 2nd Gain

  if rbut == 1
    ctx.Gain = 1; %Select the first SuperBlock - Gain1
  else
    ctx.Gain = 2; %Select the second SuperBlock - Gain2
  end

  aux_sliv = findobj('tag', 'simtimev'); %Auxiliar variable to the Slider value
  ctx.simtime = get(aux_sliv, 'value'); %Getting Final Simulation Time
  env = getnewenv; %Create a new environment variable to read/write the signals
  vssRunSimulation(model,ctx,env); %Run Twin Activate simulation
end

%------------------------------------------------------------
% % GUI objects:
%------------------------------------------------------------
Dialog = figure('units', 'pixels', 'position', [0 0 167 346] ...
    , 'name','Dialog', 'windowicon','', 'windowstyle','undocked' ...
    , 'tag','Dialog', 'handlevisibility','on', 'numbertitle','off', 'visible','on');

uiPanel = uipanel('parent', Dialog, 'units','normalized', 'position',[0.00 0.03 0.96 0.96] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'backgroundcolor', [246 246 246] ...
    , 'bordertype','none', 'borderwidth', 1 , 'title','' ...
    , 'aspectratio','off', 'backgroundimage','', 'tag','uiPanel' ...
    , 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on');

gain1_button = uicontrol('parent', uiPanel, 'style','radiobutton' ...
    , 'callback','gain1_button_callback', 'units','normalized', 'position',[0.07 0.03 0.66 0.09] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'string','Gain 1', 'value', 1 , 'foregroundcolor', [20 20 20] ...
    , 'interruptible','off', 'tag','goption', 'userdata',[], 'tooltipstring','', 'visible','on');

gain2_button = uicontrol('parent', uiPanel, 'style','radiobutton' ...
    , 'callback','gain2_button_callback', 'units','normalized', 'position',[0.07 0.12 0.66 0.09] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'string','Gain 2', 'value', 0 , 'foregroundcolor', [20 20 20] ...
    , 'interruptible','off', 'tag','gain2_button', 'userdata',[], 'tooltipstring','', 'visible','on');

gain1_value = uicontrol('parent', uiPanel, 'style','edit' ...
    , 'callback','gain1_value_callback', 'units','normalized', 'position',[0.07 0.25 0.34 0.10] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'string','0' ...
    , 'horizontalalignment','left' ...
    , 'verticalalignment','middle', 'foregroundcolor', [20 20 20], 'backgroundcolor', [255 255 255] ...
    , 'interruptible','off', 'tag','g1v', 'userdata',[] ...
    , 'value',0, 'tooltipstring','', 'visible','on');

gain1_text = uicontrol('parent', uiPanel, 'style','text' ...
    , 'units','normalized', 'position',[0.46 0.25 0.47 0.09] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'string','Gain 1 Value' ...
    , 'horizontalalignment','left' ...
    , 'verticalalignment','middle', 'foregroundcolor', [20 20 20], 'backgroundcolor', [255 255 255] ...
    , 'tag','gain1_text', 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on');

gain2_text = uicontrol('parent', uiPanel, 'style','text' ...
    , 'units','normalized', 'position',[0.46 0.37 0.47 0.09] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'string','Gain 2 Value' ...
    , 'horizontalalignment','left' ...
    , 'verticalalignment','middle', 'foregroundcolor', [20 20 20], 'backgroundcolor', [255 255 255] ...
    , 'tag','gain2_text', 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on');

gain2_value = uicontrol('parent', uiPanel, 'style','edit' ...
    , 'callback','gain2_value_callback', 'units','normalized', 'position',[0.07 0.37 0.34 0.10] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'string','0' ...
    , 'horizontalalignment','left' ...
    , 'verticalalignment','middle', 'foregroundcolor', [20 20 20], 'backgroundcolor', [255 255 255] ...
    , 'interruptible','off', 'tag','g2v', 'userdata',[] ...
    , 'value',0, 'tooltipstring','', 'visible','on');

simtime_slider = uicontrol('parent', uiPanel, 'style','slider' ...
    , 'callback','simtime_slider_callback', 'units','normalized', 'position',[0.13 0.62 0.80 0.07] ...
    , 'enable','on', 'max', 30 , 'min', 1 , 'orient','horizontal', 'sliderstep', [1 10] ...
    , 'tracking', 'on', 'tickinterval', 1, 'tickmarks', 'nomarks' ...
    , 'callbackdelay',0.000000, 'interruptible','off', 'tag','simtimev' ...
    , 'userdata',[], 'tooltipstring','', 'visible','on');

simtime = uicontrol('parent', uiPanel, 'style','text' ...
    , 'units','normalized', 'position',[0.26 0.50 0.54 0.09] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.25 , 'fontunits','pixels' ...
    , 'string','Simulation Time' ...
    , 'horizontalalignment','left' ...
    , 'verticalalignment','middle', 'foregroundcolor', [20 20 20], 'backgroundcolor', [255 255 255] ...
    , 'tag','simtime', 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on');

runsim_button = uicontrol('parent', uiPanel, 'style','pushbutton' ...
    , 'callback','runsim_button_callback', 'units','normalized', 'position',[0.20 0.84 0.66 0.09] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','bold', 'fontsize',8.00 , 'fontunits','pixels' ...
    , 'string','Run Simulation', 'horizontalalignment','center' ...
    , 'backgroundcolor', [255 255 255], 'foregroundcolor', [20 20 20] ...
    , 'backgroundimage','', 'aspectratio','on' ...
    , 'interruptible','off', 'tag','runsim_button', 'userdata',[] ...
    , 'value',0, 'tooltipstring','', 'visible','on');

min_simtime = uicontrol('parent', uiPanel, 'style','text' ...
    , 'units','normalized', 'position',[0.13 0.69 0.14 0.10] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.00 , 'fontunits','pixels' ...
    , 'string','1' ...
    , 'horizontalalignment','center' ...
    , 'verticalalignment','middle', 'foregroundcolor', [20 20 20], 'backgroundcolor', [246 246 246] ...
    , 'tag','min_simtime', 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on');

max_simtime = uicontrol('parent', uiPanel, 'style','text' ...
    , 'units','normalized', 'position',[0.79 0.69 0.14 0.10] ...
    , 'enable','on', 'fontname','MS Shell Dlg', 'fontangle','regular', 'fontweight','normal', 'fontsize',8.00 , 'fontunits','pixels' ...
    , 'string','30' ...
    , 'horizontalalignment','center' ...
    , 'verticalalignment','middle', 'foregroundcolor', [20 20 20], 'backgroundcolor', [246 246 246] ...
    , 'tag','max_simtime', 'userdata',[], 'value',0, 'tooltipstring','', 'visible','on');

Apply, and then Push the script from the ExecOmlScript block.