Main Content

Push Button

Change parameter or variable value using button

  • Library:
  • Simulink / Dashboard

  • Push Button block

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.

Push button block with a green circle icon 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, select the block. Then, 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 the Workspace or a File. The parameter data is stored in a Simulink.SimulationData.Parameter object, accessible as an element in the exported Simulink.SimulationData.Dataset.

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

expand all

Connection

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

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'

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'

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'

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

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

Example: 0.5

Programmatic Use

Block Parameter: Opacity
Type: scalar
Default: 1

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 1-by-3 [r g b] vector with values between 0 and 1.

Block Parameter: ForegroundColor
Type: [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 1-by-3 [r g b] vector with values between 0 and 1.

Block Parameter: BackgroundColor
Type: [r g b] vector

Icon

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

IconBasic Shapes Library Block NameProgrammatic Use Value

Check1Check1

Check2Check2

Check3Check3

Check4Check4

CircleCircle

Ex1Ex1

Ex2Ex2

Ex3Ex3

Ex4Ex4

FaceFace

Frown1Frown1

Frown2Frown2

HexagonHexagon

PentagonPentagon

RectangleRectangle

Smile1Smile1

Smile2Smile2

Solid FaceSolidFace

Solid Frown1SolidFrown1

Solid Frown2SolidFrown2

Solid Smile1SolidSmile1

Solid Smile2SolidSmile2

SquareSquare

TriangleTriangle

Automotive Icons

IconAutomotive Indicator Lamps Library Block NameProgrammatic Use Value

Adaptive Cruise ControlAdaptiveCruiseControl

Adaptive Cruise Control FailureAdaptiveCruiseControlFailure

Antilock Brake SystemAntilockBrakeSystem

BatteryBattery

Check EngineCheckEngine

Check Engine2CheckEngine2

Cruise ControlCruiseControl

Eco ModeEcoMode

Electronic StabilityElectronicStability

EngineEngine

Engine Coolant TempEngineCoolantTemp

Engine FailureEngineFailure

Engine HeatingEngineHeating

Engine OilEngineOil

Exterior Bulb FailureExteriorBulbFailure

Front Fog LightFrontFogLight

FuelFuel

HazardsHazards

Headlamp LevelingHeadlampLeveling

High BeamsHighBeams

Hill Descent ControlHillDescentControl

Lighting SwitchLightingSwitch

Low BeamsLowBeams

Parking AssistanceParkingAssistance

Rear Fog LightRearFogLight

Side LightsSideLights

Stability ControlStabilityControl

Stability Control OffStabilityControlOff

Tire MonitorTireMonitor

Traction ControlTractionControl

Traction Control OffTractionControlOff

Traction Control FailureTractionControlFailure

Turn Signal LeftTurnSignalLeft

Turn Signal RightTurnSignalRight

Wireless Icons

IconWireless Icons Library Block NameProgrammatic Use Value

NetworkNetwork

Network No SignalNetworkNoSignal

Network TransmissionNetworkTransmission

Network3GNetwork3G

Network4GNetwork4G

Network5GNetwork5G

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'

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'

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'

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

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

Introduced in R2015a