Toggle Button (App Designer) Properties

Control toggle button appearance

expand all in page

Valid for toggle buttons created with App Designer or the uitogglebutton function. For buttons created with GUIDE or the uicontrol function, see Uicontrol Properties.

Toggle buttons are app components that appear in a button group, as a set of mutually exclusive options. Typically, the button group to which the toggle button belongs generates an action when the selection changes. Properties control the appearance and behavior of a particular instance of a toggle button. To modify aspects of a toggle button, change property values. Use dot notation to refer to a particular object and property:

f = uifigure;
bg = uibuttongroup(f)
togbutton = uitogglebutton(bg);
txt = togbutton.Text;
togbutton.Text = 'Celsius';

    Note:   To specify how you want your app to respond when the app user changes a toggle button selection, code the SelectionChangedFcn callback for the Button Group to which the toggle buttons are parented.

Value

expand all

State of the toggle button specified as 0 (unpressed) or 1 (depressed). Within a given button group, only one toggle button can be selected (depressed) at a time. When the Value property is set to 1, the toggle button appears depressed. The state of the first button added to a button group is 1, by default. Subsequent buttons added to the same button group have a default state of 0.

When the Value property for one toggle button changes to 1, the Value property of the previously selected toggle button in the same button group changes to 0. In addition, the SelectedObject property value of the button group is updated to reflect the selected toggle button.

If you programmatically change the toggle button value to 0, then MATLAB® sets the value for the first toggle button added to the button group to 1. If the first toggle button added is the one that you set the value to 0, then MATLAB sets the value of the second toggle button added to the button group to 1.

    Note:   The first toggle button added to a button group is not necessarily the first toggle button listed when you get the button group children.

Appearance

expand all

Text for toggle button, specified as a character vector or a cell array of character vectors.

Example: 'Steady state'

Example: {'Steady','state'}

Horizontal alignment of the text and the icon on the button, specified as 'center', 'left', or 'right'.

This image shows the three horizontal alignment options, center, left, and right, when the VerticalAlignment and IconAlignment properties are set to their default values ('center' and 'left', respectively).

Vertical alignment of the icon and the text on the button, specified as 'center', 'top', or 'bottom'.

These images show the three vertical alignment options when the value of HorizontalAlignment is 'center' and the value of IconAlignment is 'left'.

    Note:   Vertical alignment values appear to have no effect when the button is the default height.

File name of the button icon, specified as a character vector.

The file name can be an image file name on the MATLAB path or a full path to an image file. If you plan to share an app with others, put the image file on the MATLAB path to facilitate app packaging.

The image file type must be JPEG, GIF, or PNG.

  • If the button text takes up all the space specified by the Position property value, then MATLAB does not display the icon.

  • If some room is available for the icon, then MATLAB scales down the image to fit, if necessary.

Example: 'icon.png'

Example: 'C:\Documents\icon.png'

Location of the button icon relative to the button text (if any), specified as one of the values in this table.

    Note:   The table images reflect the icon location when HorizontalAlignment and VerticalAlignment are each set to their default value, 'center'.

ValueResult
'left'
'right'
'top'
'bottom'
'center'

If you specify an empty character vector('') for the Text property, then the icon aligns as though it is text, according to the values set for HorizontalAlignment and VerticalAlignment. The IconAlignment property value has no effect in this case.

Background color of the button, specified as an RGB triplet, short name, or long name. The color you specify fills the area bounded by the button.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7]. This table lists the long and short color name options and the equivalent RGB triplet values.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black''k'[0 0 0]

Example: [0 0 1]

Example: 'b'

Example: 'blue'

Visibility of the button, specified as 'on' or 'off'. The Visible property determines whether the button is displayed on the screen. If the Visible property of a button is set to 'off', the entire button is hidden, but you can still specify and access its properties.

To make your app start faster, set the Visible property of all components that do not need to appear at startup to 'off'.

Location and Size

expand all

Location and size of the button relative to the button group containing it, specified as the vector [left bottom width height]. This table describes each element in the vector.

ElementDescription
leftDistance from the inner left edge of the button group to the outer left edge of the button
bottomDistance from the inner bottom edge of the button group to the outer bottom edge of the button
widthDistance between the right and left outer edges of the button
heightDistance between the top and bottom outer edges of the button

All measurements are in pixel units.

Example: [100 100 100 22]

Inner location and size of the button, specified as [left bottom width height]. Position values are relative to the button group containing the button. All measurements are in pixel units. This property value is identical to Position for toggle buttons.

This property is read only.

Outer location and size of the button, returned as [left bottom width height]. Position values are relative to the button group containing the button. All measurements are in pixel units. This property value is identical to Position for toggle buttons.

Font Style

expand all

Font in which to display the Text property value, specified as a system supported font name. The default font depends on the specific operating system and locale.

If the specified font is not available, then MATLAB uses the best match among the fonts available on the system where the app is running.

Example: 'Arial'

Color of the Text property value, specified as an RGB triplet, long name, or short name.

An RGB triplet is a three-element row vector whose elements specify the intensities of the red, green, and blue components of the color. The intensities must be in the range [0,1]; for example, [0.4 0.6 0.7]. This table lists the long and short color name options and the equivalent RGB triplet values.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black''k'[0 0 0]

Example: [0.4 0.6 0.7]

Font size of the Text property value, specified as a positive number. The units of measurement are pixels.

Example: 14

Thickness of the Text property value, specified as one of these values:

  • 'normal' — Default weight as defined by the particular font

  • 'bold' — Thicker character outlines than 'normal'

Not all fonts have a bold font weight. Therefore, specifying a bold font weight can result in the normal font weight.

Character slant of the text, specified as 'normal' or 'italic'. Setting this property to italic selects a slanted version of the font, if it is available on the app user's system.

Interactive Control

expand all

Operational state of the button, specified as 'on' or 'off'.

  • If you set this property to 'on', then the appearance of the button indicates that the app user can interact with it.

  • If you set this property to 'off', then the appearance of the button appears dimmed, indicating that the app user cannot interact with it.

Callback Execution Control

expand all

Callback interruptibility status, specified as 'on' or 'off'. The Interruptible property determines if a running callback can be interrupted.

There are two callback states to consider:

  • The running callback is the currently executing callback.

  • The interrupting callback is a callback that tries to interrupt the running callback.

Whenever MATLAB invokes a callback, that callback attempts to interrupt the running callback. The Interruptible property of the object owning the running callback determines if interruption is allowed. If interruption is not allowed, then the BusyAction property of the object owning the interrupting callback determines if it is discarded or put into a queue.

If a callback is the running callback, then the Interruptible property determines if it can be interrupted by another callback. The Interruptible property has two possible values:

  • 'off' — A callback cannot interrupt the running callback. MATLAB finishes executing the running callback without any interruptions. This is the default behavior.

  • 'on' — A callback can interrupt the running callback. The interruption occurs at the next point where MATLAB processes the queue, such as when there is a drawnow, uifigure, getframe, waitfor, or pause command.

    • If the running callback contains one of the commands, then MATLAB stops the execution of the callback at this point and executes the interrupting callback. MATLAB resumes executing the running callback when the interrupting callback completes.

    • If the running callback does not contain one of these commands, then MATLAB finishes executing the callback without interruption.

    Note:   Callback interruption and execution behave differently in these situations:

    • If the interrupting callback is a DeleteFcn, CloseRequestFcn or SizeChangedFcn callback, then the interruption occurs regardless of the Interruptible property value.

    • If the running callback is currently executing the waitfor function, then the interruption occurs regardless of the Interruptible property value.

    • Timer objects execute according to schedule regardless of the Interruptible property value.

    When an interruption occurs, MATLAB does not save the state of properties or the display . For example, the handle returned by the gca or gcf command might change when another callback executes.

Callback queuing, specified as 'queue' or 'cancel'. The BusyAction property determines how MATLAB handles the execution of interrupting callbacks. There are two callback states to consider:

  • The running callback is the currently executing callback.

  • The interrupting callback is a callback that tries to interrupt the running callback.

The BusyAction property of the object that owns the interrupting callback determines how MATLAB handles the execution of the interrupting callback. The BusyAction property has two possible values:

  • 'queue' — Put the interrupting callback in a queue to be processed after the running callback finishes execution.

  • 'cancel' — Do not execute the interrupting callback.

Whenever MATLAB invokes a callback, that callback always attempts to interrupt an executing callback (if one exists). The Interruptible property of the object whose callback is executing determines if interruption is allowed. The Interruptible property has two possible values:

  • 'on' — Interruption occurs at the next point where MATLAB processes the queue. This is the default.

  • 'off' — BusyAction property (of the object owning the interrupting callback) determines if MATLAB enqueues or ignores the interrupting callback.

Creation and Deletion Control

expand all

This property is read only.

Deletion status of this component, returned as 'off' or 'on'. MATLAB sets the BeingDeleted property to 'on' when the DeleteFcn callback begins execution. The BeingDeleted property remains set to 'on' until the component object no longer exists.

Check the value of the BeingDeleted property to verify that the object is not about to be deleted before querying or modifying it.

Component creation function, specified as one of these values:

  • A function handle.

  • A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • A character vector containing a valid MATLAB expression. For example, 'disp(''hello world'')' calls the disp function. MATLAB evaluates this expression in the base workspace.

This property specifies a callback function to execute when MATLAB creates this component in the app. MATLAB initializes all property values before executing the CreateFcn callback. If you do not specify the CreateFcn property, then MATLAB executes a default creation function.

Use the gcbo function in your CreateFcn code to get the component that is being created.

Setting the CreateFcn property on an existing component has no effect.

    Note:   Do not call copyobj or textwrap (which calls copyobj) inside a CreateFcn. Copying the object causes the CreateFcn callback to execute repeatedly.

Component deletion function, specified as one of these values:

  • A function handle.

  • A cell array in which the first element is a function handle. Subsequent elements in the cell array are the arguments to pass to the callback function.

  • A character vector containing a valid MATLAB expression. For example, 'disp(''hello world'')' calls the disp function. MATLAB evaluates this expression in the base workspace.

The DeleteFcn property specifies a callback function to execute when MATLAB deletes a component in an app. MATLAB executes the DeleteFcn callback before destroying the properties of the object. If you do not specify the DeleteFcn property, then MATLAB executes a default deletion function.

Use the gcbo function in your DeleteFcn code to access the component that is being deleted.

Identifiers

expand all

This property is read only.

Type of graphics object, returned as 'uitogglebutton'.

Object identifier, specified as a character vector. You can specify a unique Tag value to serve as an identifier for any component object in your app. When you need access to the object elsewhere in your code, you can use the findobj function to search for the object based on the Tag value.

Example: 'mybutton'

Data to associate with this component, specified as any array. Specifying UserData can be useful for sharing data values within and across apps you create programmatically.

Example: [1 2 3]

Example: 'April 21'

Example: struct('value1',[1 2 3],'value2','April 21')

Example: {[1 2 3],'April 21'}

Parent/Child

expand all

Parent object of the button, specified as a button group object. The button group object must be a child of a figure created using uifigure.

Visibility of the button handle, specified as 'on', 'callback', or 'off'.

This property controls the visibility of the button handle in its button group parent's list of children. When a handle is not visible in its parent's list of children, it is not returned by functions that obtain handles by searching the object hierarchy or querying handle properties. These functions include get, findobj, clf, and close. Handles are valid even if they are not visible. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.

HandleVisibility ValueDescription
'on'The button handle is always visible.
'callback'The button handle is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This option blocks access to the button at the command line, but allows callback functions to access it.
'off'The button handle is invisible at all times. This option is useful for preventing unintended changes to the UI by another function. Set the HandleVisibility to 'off' to temporarily hide the handle during the execution of that function.

See Also

Functions

Introduced in R2016a

Was this topic helpful?
MATLAB Documentation
Other Documentation
Support