Push Button

Change parameter or variable value using button

• 

Libraries:
Simulink / Dashboard

Description

Use the Push Button block to change the value of the connected variable or parameter before or during simulation. You can configure the button to change the value only while you press the button or to latch the value change until you click the button again. Use the Push Button block with other Dashboard blocks to create an interactive dashboard to control your model.

Double-clicking the Push Button block does not open its dialog box during simulation or when the block is selected. To edit the block parameters, you can use the Property Inspector or open the block dialog box by:

• Double-clicking the block when the block is not selected and the model is not simulating.

• Right-clicking the block and selecting Block Parameters from the context menu.

Push Button Icons

You can add an icon to the Push Button block that is displayed alongside the button text. You can choose an icon from a predefined set that includes basic shapes, automotive indicators, and wireless icons, or you can upload your own custom icon. For more information, including a complete list of the built-in icons, see Icon.

When you add an icon to the Push Button block, you can configure an on color and an off color for the icon so its color changes with the state of the block and specify the alignment of the icon relative to the button text. For example, this Push Button block is configured to use a circle icon with the on color specified as bright green, aligned to the left of the button text.

The icon settings for the Push Button block allow you to configure the appearance of the block in your model. When you want to customize the appearance of the block further, consider using the Push Button block in the Customizable Blocks library. The Push Button block in the Customizable Blocks library supports adding a custom icon but does not include any built-in icons.

Connect Dashboard Blocks

Dashboard blocks do not use ports to connect to model elements. To connect dashboard blocks to variables and block parameters, use connect mode. Connect mode facilitates the process of connecting dashboard blocks in your model, especially when you want to connect multiple blocks at once. To connect a single dashboard block, you can also use the Connection table in the block dialog box.

Tip

You can modify dashboard block connections in your model during normal and accelerator mode simulations.

Note

Dashboard blocks cannot connect to variables until you update the model diagram. To connect dashboard blocks to variables or modify variable values between opening your model and running a simulation, update the model diagram using Ctrl+D.

To enter connect mode, in the canvas, select the dashboard block to connect. On the Simulink^® Toolstrip, a tab named after the type of the selected block appears. On the block tab, click Connect. In connect mode, when you select one or more blocks, a list of parameters and variables available for connection appears. Select a variable or parameter from the list to connect to the selected dashboard block.

When the value of the selected variable or block parameter is nonscalar, use the text box at the bottom of the Connection table to specify the element you want to connect to the dashboard block. To connect to an element of a vector, matrix, or array, specify the element index, for example, 3 or (1,3). To connect to an element in a bus or structure, specify the element in the context of the bus or structure hierarchy by using dots to indicate different levels in the hierarchy, and omit the top level. For example, specify a.b to connect to scalar element b of the structure or bus a nested inside the selected composite variable or parameter.

To connect another dashboard block, pause on another dashboard block and click the Connect button above it. Then, make a selection of signals and blocks in your model and choose a model element to connect.

When you finish connecting the dashboard blocks in your model, on the block tab, click Done Connecting.

Tip

You can hide the message shown on unconnected blocks using the set_param function with the ShowInitialText block parameter. The message also disappears when you connect the block.

Parameter Logging

Tunable parameters connected to dashboard blocks are logged to the Simulation Data Inspector, where you can view the parameter values along with logged signal data. You can access logged parameter data in the MATLAB^® workspace by exporting the parameter data from the Simulation Data Inspector by using the UI or the Simulink.sdi.exportRun function. For more information about exporting data using the Simulation Data Inspector UI, see Export Data to Workspace or File. The parameter data is stored in a Simulink.SimulationData.Parameter object, accessible as an element in the exported Simulink.SimulationData.Dataset.

Examples

Control Merging Signals with the Push Button Block

Use the Push Button block to control the mergedemo model.

Open Model

Limitations

• Except for the Dashboard Scope block and the Display block, dashboard blocks can only connect to real scalar signals.

• The toolstrip does not support blocks that are inside a panel.

• You cannot use the Connection table in the block dialog to connect a dashboard block to a block that is commented out. When you connect a dashboard block to a commented block using connect mode, the dashboard block does not display the connected value until the you uncomment the block.

• Dashboard blocks cannot connect to model elements inside referenced models.

• When you simulate a model hierarchy, dashboard blocks inside referenced models do not update.

• Dashboard blocks do not support rapid accelerator simulation.

• When you connect a dashboard block to a variable or parameter during simulation, the data for that variable or parameter is not logged to the Simulation Data Inspector. To log variable and parameter data to the Simulation Data Inspector, connect the dashboard block to the variable or parameter prior to simulation.

• When you simulate a model in external mode with the Default parameter behavior set to Inlined, dashboard blocks can appear to change parameter and variable values. However, the change does not propagate to the simulation. For example, Gain blocks display changes made to the Gain parameter using the dashboard blocks, but the Gain value used in the simulation does not change.

Parameters

Connection

Connection — Select a variable or block parameter to connect

variable and parameter connection options

Select the variable or block parameter to control using the Connection table. To connect the block to a signal:

1. Make a selection in the model that includes one or more blocks.

2. Select the variable or parameter you want to connect.

   When the value of the selected variable or block parameter is nonscalar, use the text box at the bottom of the Connection table to specify the element you want to connect to the dashboard block. To connect to an element of a vector, matrix, or array, specify the element index, for example, 3 or (1,3). To connect to an element in a bus or structure, specify the element in the context of the bus or structure hierarchy by using dots to indicate different levels in the hierarchy, and omit the top level. For example, specify a.b to connect to scalar element b of the structure or bus a nested inside the selected composite variable or parameter.

3. Click Apply.

To facilitate understanding and debugging your model, you can connect Dashboard blocks to variables and parameters in your model during simulation.

Note

To see workspace variables in the connection table, update the model diagram using Ctrl+D.

Programmatic Use

To programmatically connect a dashboard block to a tunable parameter or a variable, use a Simulink.HMI.ParamSourceInfo object. The Simulink.HMI.ParamSourceInfo object contains four properties. Some of the properties apply to connecting dashboard blocks to parameters, and some apply to connecting dashboard blocks to variables. Not all fields have a value for a connection because a given dashboard block connects to either a parameter or a variable.

Block Parameter: Binding

Type: Simulink.HMI.ParamSourceInfo

Default: []

Main

Button Text — Text label for button

Button (default) | string | character vector

The text displayed on the Push Button block in your model.

Tips

To design a button that displays different text depending on the state of the block, use the Push Button block in the Customizable Blocks library.

Programmatic Use

Block Parameter: ButtonText

Type: string or character array

Default: 'Button'

On Value — Value assigned to connected parameter when button is pressed or latched

1 (default) | scalar

The value assigned to the connected block parameter when the button is pressed or latched.

Tips

Use the Block Type parameter to configure how the block responds to a click:

• Momentary — The button applies the On Value only while you press it.

• Latch — The button latches the state change when you click it and applies the On value until you click it again.

Programmatic Use

Block Parameter: OnValue

Type: string or character array

Default: '1'

Button Type — Button response to click

Momentary (default) | Latch

Specify how the button responds to a click.

• Momentary — The button applies the On Value only while you press it.

• Latch — The button latches the state change when you click it and applies the On value until you click it again.

Programmatic Use

Block Parameter: ButtonType

Type: string or character array

Value: 'Momentary' | 'Latch'

Label — Block label position

Hide (default) | Bottom | Top

Position of the block label. When the block is connected to an element in the model, the label is the name of the connected element.

Programmatic Use

Block Parameter: LabelPosition

Type: character vector

Values: 'Hide' | 'Bottom' | 'Top'

Default: 'Hide'

Format

Opacity — Block background opacity

1 (default) | scalar

Block background opacity, specified as a scalar value between 0 and 1.

Example: 0.5

Programmatic Use

Block Parameter: Opacity

Type: scalar

Default: 1

Foreground Color — Block foreground color

[r g b] vector

Block foreground color, including the text. You can select a color from a palette of standard colors or specify a custom color.

Programmatic Use

Specify the ForegroundColor parameter for the block as a string or a character vector that defines a 1-by-3 [r g b] vector with values between 0 and 1.

Block Parameter: ForegroundColor

Type: character vector | string

Values: [r g b] vector

Background Color — Block background color

[r g b] vector

Block background color. You can select a color from a palette of standard colors or specify a custom color.

Programmatic Use

Specify the BackgroundColor parameter for the block as a string or a character vector that defines a 1-by-3 [r g b] vector with values between 0 and 1.

Block Parameter: BackgroundColor

Type: character vector | string

Values: [r g b] vector

Icon

Icon — Icon to display on button

SVG file | PNG file | JPEG file

You can add an icon to the Push Button block to display alongside or instead of the button text. You can choose from built-in shape, automotive, and wireless icons, or you can upload your own custom SVG, PNG, or JPEG file to use as the icon.

To view icon options, on the Icon tab of the block dialog box, select an Icon Type. To use your own custom icon, select Custom as the Icon Type and upload the image file.

When you add an icon, you can configure the icon appearance using these parameters:

• Icon Alignment — Alignment of icon relative to button text

• On Color — Icon color when block is pressed or latched and applying the On value to the connected parameter

• Off Color — Icon color when the block is not pressed or latched and is not applying the On value to the connected parameter

To specify an On Color and Off Color for the icon, you must select Customize Icon Color.

Shape Icons

Icon	Basic Shapes Library Block Name	Programmatic Use Value
	Check1	Check1
	Check2	Check2
	Check3	Check3
	Check4	Check4
	Circle	Circle
	Ex1	Ex1
	Ex2	Ex2
	Ex3	Ex3
	Ex4	Ex4
	Face	Face
	Frown1	Frown1
	Frown2	Frown2
	Hexagon	Hexagon
	Pentagon	Pentagon
	Rectangle	Rectangle
	Smile1	Smile1
	Smile2	Smile2
	Solid Face	SolidFace
	Solid Frown1	SolidFrown1
	Solid Frown2	SolidFrown2
	Solid Smile1	SolidSmile1
	Solid Smile2	SolidSmile2
	Square	Square
	Triangle	Triangle

Automotive Icons

Icon	Automotive Indicator Lamps Library Block Name	Programmatic Use Value
	Adaptive Cruise Control	AdaptiveCruiseControl
	Adaptive Cruise Control Failure	AdaptiveCruiseControlFailure
	Antilock Brake System	AntilockBrakeSystem
	Battery	Battery
	Check Engine	CheckEngine
	Check Engine2	CheckEngine2
	Cruise Control	CruiseControl
	Eco Mode	EcoMode
	Electronic Stability	ElectronicStability
	Engine	Engine
	Engine Coolant Temp	EngineCoolantTemp
	Engine Failure	EngineFailure
	Engine Heating	EngineHeating
	Engine Oil	EngineOil
	Exterior Bulb Failure	ExteriorBulbFailure
	Front Fog Light	FrontFogLight
	Fuel	Fuel
	Hazards	Hazards
	Headlamp Leveling	HeadlampLeveling
	High Beams	HighBeams
	Hill Descent Control	HillDescentControl
	Lighting Switch	LightingSwitch
	Low Beams	LowBeams
	Parking Assistance	ParkingAssistance
	Rear Fog Light	RearFogLight
	Side Lights	SideLights
	Stability Control	StabilityControl
	Stability Control Off	StabilityControlOff
	Tire Monitor	TireMonitor
	Traction Control	TractionControl
	Traction Control Off	TractionControlOff
	Traction Control Failure	TractionControlFailure
	Turn Signal Left	TurnSignalLeft
	Turn Signal Right	TurnSignalRight

Wireless Icons

Icon	Icon Name	Programmatic Use Value
	Network	Network
	Network No Signal	NetworkNoSignal
	Network Transmission	NetworkTransmission
	Network3G	Network3G
	Network4G	Network4G
	Network5G	Network5G

Tips

• You can change the icon for a Push Button block using the Button tab in the toolstrip.

• If you want to customize the appearance of the Push Button block further, consider designing your own button using the Push Button block in the Customizable Blocks library.

  The Push Button block in the Customizable Blocks library supports adding a custom icon but does not include any built-in icons.

• The on and off colors for the icon can apply to these SVG elements:

  • altGlyph

  • circle

  • ellipse

  • path

  • polygon

  • rect

  • text

  • textPath

  • tref

  • tspan

Programmatic Use

Block Parameter: Icon

Type: string | character vector

Default: 'Default'

Icon Alignment — Icon alignment relative to button text

Left (default) | Right | Top | Bottom | Center

Alignment of the icon relative to the button text. When you do not specify button text, the icon is always in the center of the block.

Programmatic Use

Block Parameter: IconAlignment

Type: string | character vector

Value: 'Left' | 'Right' | 'Top' | 'Bottom' | 'Center'

Default: 'Left'

Customize Icon Color — Whether to use icon on and off colors

Off (default) | On

When you add an icon to the Push Button block, you can specify on and off colors so the icon color changes to reflect the state of the block. To use and specify the On Color and Off Color for an icon, select Customize Icon Color.

Programmatic Use

Block Parameter: IconColor

Type: string | character vector

Value: 'On' | 'Off'

Default: 'Off'

On Color — Icon color when block is pressed or latched

[r g b] vector

When you add an icon to the Push Button block, you can specify on and off colors so the icon color changes to reflect the state of the block. The On Color specifies the color of the icon when the block is pressed or latched and is applying the On value to the connected parameter. You can select a color from a palette of standard colors or specify a custom color.

Dependencies

To enable the On Color parameter, select Customize Icon Color.

Programmatic Use

Specify the IconOnColor parameter for the block as a 1-by-3 [r g b] vector with values between 0 and 1.

Block Parameter: IconOnColor

Type: [r g b] vector

Off Color — Icon color when block is not pressed or latched

[r g b] vector

When you add an icon to the Push Button block, you can specify on and off colors so the icon color changes to reflect the state of the block. The Off Color specifies the color of the icon when the block is not pressed or latched and is not applying the On value to the connected parameter. You can select a color from a palette of standard colors or specify a custom color.

Dependencies

To enable the On Color parameter, select Customize Icon Color.

Programmatic Use

Specify the IconOffColor parameter for the block as a 1-by-3 [r g b] vector with values between 0 and 1.

Block Parameter: IconOffColor

Type: [r g b] vector

Block Characteristics

Data Types	double | half | integer | single
Direct Feedthrough	no
Multidimensional Signals	no
Variable-Size Signals	no
Zero-Crossing Detection	no

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using Simulink® Coder™.

Dashboard blocks are ignored for code generation.

Version History

Introduced in R2015a

R2023b: Open panel in new window

Starting in R2023b, you can open a dashboard panel in a new window. To do so, select the panel and pause on the ellipsis that appears. In the action menu that expands, click the Open In New Window button .

You can minimize and restore the new window containing the panel separately from the model window. From the panel window, you can run, pause, stop, and step through the simulation. In the panel window, you can edit the panel and the blocks it contains.

To return the panel to the model canvas, in the panel window toolstrip, click Open in canvas .

For more information about opening a panel in a new window, see Open Panel in New Window.

R2023a: Persistent panels tab in Simulink Toolstrip

When you add a dashboard panel to a model, the Panels tab appears in the Simulink Toolstrip and shows options for managing and editing panels.

Previously, the Panels tab was only visible when a panel was selected. Starting in R2023a, the Panels tab stays visible when no panel is selected.

The Panels tab also contains these new options:

• You can add an empty panel.

• You can rename the selected panel.

• You can hide the selected panel.

R2022b: Undo and redo support for customizable dashboard blocks in panel

Starting in R2022b, you can undo and redo the changes you make to customizable dashboard blocks that are in a panel.

To undo or redo a change:

1. Click the panel or a block in the panel.

2. Press Ctrl+Z to undo the change, or press Ctrl+Y to redo the change.

Note

The keyboard shortcuts are based on Windows^®. On a Mac, press command (⌘) instead of Ctrl.

R2022b: Toolstrip support for panels

Starting in R2022b, you can use the Simulink Toolstrip to manage and edit panels and the dashboard blocks that they contain.

When you click a dashboard block in a panel, the toolstrip tab for the block appears. For example, when you click a Circular Gauge block, the Gauge tab appears in the toolstrip.

When you click a panel, the Panel tab appears in the toolstrip. The tab provides these options:

• Manage the visibility of panels in the model.

• Fit all unhidden panels within the current view.

• Collapse the selected panel.

• Customize the size and the contents of the panel.

• Set a custom background image for the selected panel.

• Add a new tab to the selected panel.

R2021b: Push Button Block Can Apply Value After You Release Click

Starting in R2021b, you can configure the behavior of the Push Button block to latch or momentarily apply the On Value when you click the block.

R2021b: Push Button Block Can Display Icons

Starting in R2021b, you can add an icon to display on the Push Button block alongside or instead of the button text. Choose an icon for the block from a predefined set or upload your own custom icon using the block dialog box or the Button tab of the toolstrip.

You can also specify an on color and an off color so the icon color changes with the state of the block and specify the alignment of the icon relative to the button text.

R2021a: Tune matrix and structure elements using dashboard blocks

Starting in R2021a, you can connect a block from the Dashboard library to a scalar element of a matrix or structure that defines the value of a tunable block parameter. When you connect a dashboard block to a tunable parameter, you first select one or more blocks. Then, in a dialog box, you select the parameter to which you want to connect. When you select a parameter that has a nonscalar value, specify the element you want to tune using the text box in the dialog box.

R2020b: Background Color, Foreground Color, and Opacity properties added for several dashboard blocks

Starting in R2020b, you can specify a background color, a foreground color, and opacity for these blocks from the Dashboard library:

• Check Box

• Combo Box

• Edit

• Push Button

• Radio Button

R2020b: Simulink Toolstrip support for dashboard blocks

Starting in R2020b, the Block tab in the Simulink Toolstrip turns into a block-specific tab when you select a block in your model that is from the Dashboard library in the Simulink library or from the Flight Instruments library in the Aerospace Blockset™ Flight Control Analysis library. From the toolstrip, you can connect, disconnect, and modify connections for the selected block. You can jump to the model element connected to the selected block, and you can add the selected block to a panel.

R2019a: Programmatically add and configure dashboard blocks

Starting in R2019a, you can use functions such as add_block and set_param to create and configure blocks from the Dashboard library in your model.