uitogglebutton

R2026b

Create toggle button component

Syntax

tb = uitogglebutton

tb = uitogglebutton(parent)

tb = uitogglebutton(___,Name=Value)

Description

tb = uitogglebutton creates a toggle button in a new figure and returns the ToggleButton object. MATLAB^® calls the uifigure function to create the figure.

tb = uitogglebutton(parent) creates a toggle button in the specified parent container. The parent can be a Figure object or one of its child containers.

tb = uitogglebutton(___,Name=Value) specifies ToggleButton properties using one or more name-value arguments. Use this option with any of the input argument combinations in the previous syntaxes.

Examples

Manage Toggle Buttons in Grid Layout

Create a grid layout in a figure and add three toggle buttons. Then create a selection group to manage the three toggle buttons.

fig = uifigure(Position=[100 100 200 200]);
gl = uigridlayout(fig,[3 1]);
tb1 = uitogglebutton(gl,Text="English");
tb2 = uitogglebutton(gl,Text="French");
tb3 = uitogglebutton(gl,Text="German");
sg = uiselectiongroup([tb1 tb2 tb3]);

Change the toggle button selection to French.

tb2.Value = true;

Input Arguments

parent — Parent container

Figure object (default) | Tab object | Panel object | GridLayout object

Parent container, specified as a Figure object or one of its child containers: Tab, Panel, or GridLayout. If you do not specify a parent container, MATLAB calls the uifigure function to create a new Figure object that serves as the parent container.

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: uitogglebutton(fig,Text="French")

Note

The properties listed here are a subset of the available properties. For the full list, see ToggleButton.

Value — State of toggle button

true or 1 | false or 0

State of the toggle button, specified as a numerical or logical 1 (true) or 0 (false). When the Value property is set to 1, the toggle button appears depressed. If the toggle button is part of a selection group, only one button in the group can be selected (depressed) at a time. The state of the first toggle button added to a selection group is 1, by default. Subsequent buttons added to the same selection group have a default state of 0.

For buttons in a selection group, if the Value property of a toggle button changes to 1, the Value property of the previously selected toggle button changes to 0. In addition, the SelectedObject property value of the SingleSelectionGroup is updated.

If you programmatically change the Value property of a toggle button to 0, MATLAB sets the Value property of the first toggle button added to the selection group to 1. If the first toggle button added is the one for which you programmatically set the Value property to 0, then MATLAB sets the Value property for the second toggle button added to the selection group to 1.

Text — Button label

'Toggle Button' (default) | character vector | cell array of character vectors

Button label, specified as a character vector, cell array of character vectors, string scalar, string array, or 1-D categorical array. Specify a character vector or string scalar to label the button with a single line of text. Use a cell array or string array to label the button with multiple lines of text. Each element in the array represents a separate line of text. If you specify this property as a categorical array, MATLAB uses the values in the array, not the full set of categories.

Icon — Icon

'' (default) | predefined icon | custom icon

Icon, specified as a predefined icon or a custom icon.

Predefined Icon

This table lists the values to specify the predefined icons.

Value	Icon
'' (default)	No icon displays.
'question'
'info'
'success'
'warning'
'error'

Custom Icon

Specify a custom icon as one of these values:

• A character vector or string scalar that specifies the file name of an SVG, JPEG, GIF, or PNG image that is on the MATLAB path. Alternatively, you can specify a full path to the image file.

• An m-by-n-by-3 truecolor image array or an m-by-n grayscale image array. See Working with Image Types in MATLAB for more information.

If you plan to share an app with others, put the image file on the MATLAB path to facilitate app packaging.

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.

Position — Location and size of toggle button

[100 100 100 22] (default) | [left bottom width height]

Location and size of the toggle button, specified as a vector of the form [left bottom width height]. This table describes each element in the vector.

Element	Description
left	Distance from the inner left edge of the parent container to the outer left edge of the toggle button
bottom	Distance from the inner bottom edge of the parent container to the outer bottom edge of the toggle button
width	Distance between the right and left outer edges of the toggle button
height	Distance between the top and bottom outer edges of the button

The Position values are relative to the drawable area of the parent container. The drawable area is the area inside the borders of the container and does not include the area occupied by decorations such as a menu bar or title.

All measurements are in pixel units.

Tips

• To manage exclusive selection of radio buttons or toggle buttons, use the uiselectiongroup function to create a selection group. Buttons managed by a selection group can be in any container within the same figure.

• To make your program respond when a user selects a toggle button managed by a selection group, define a SelectionChangedFcn callback for the SingleSelectionGroup object. You cannot define callbacks for the individual buttons.

• To determine which toggle button is currently selected, query the SelectedObject property of the SingleSelectionGroup object. For example, sg.SelectedObject returns the currently selected button in the selection group sg. You can execute this query anywhere in your code.

• If you use a ButtonGroup object as the parent container for toggle buttons that are managed by a selection group, then only the selection group manages the selection of the buttons. (since R2026b)

Version History

Introduced in R2016a

R2026b: Manage layout and exclusive selection of radio buttons or toggle buttons

For improved layout control, you can now parent radio buttons (created using uiradiobutton) and toggle buttons (created using uitogglebutton) directly to figures, tabs, panels, and grid layouts. Previously, radio buttons and toggle buttons had to be parented to button groups.

To manage the exclusive selection of a set of radio buttons or toggle buttons, create a selection group using the new uiselectiongroup function. For more information about selection groups, see SingleSelectionGroup.

R2024b: Specify HTML markup and display equations in text

Enable text markup by setting the Interpreter property. Specify the interpreter as "html", "latex", "tex", or "none".

R2022b: Specify additional icon and icon alignment options

You can use these additional options when adding icons to a button:

• Specify the Icon property as a predefined icon, such as 'success'.

• Specify the IconAlignment property as 'leftmargin' or 'rightmargin' to display the icon on the far left or far right of the button, regardless of the button text location.

R2020b: Wrap button text

Use the WordWrap property to prevent text from getting clipped horizontally when the width of the UI component is smaller than the text you want to display. Setting the WordWrap property to 'on' breaks the text into new lines so that each line fits within the component. It avoids breaking words when possible. When the property is set to 'off', the text does not wrap.

For more information, see ToggleButton.