uitogglebutton

Create toggle button component

Syntax

tb = uitogglebutton

tb = uitogglebutton(parent)

tb = uitogglebutton(___,Name,Value)

Description

tb = uitogglebutton creates toggle button within a button group and returns the ToggleButton object. MATLAB^® calls the uifigure function to create the parent figure of the button group.

tb = uitogglebutton(parent) creates the toggle button within the specified button group. The button group must be the child of a Figure object or must be parented to a child container of the figure: Tab, Panel, ButtonGroup, or GridLayout.

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

Examples

Create Toggle Buttons, Set and Access Property Values

Create toggle buttons by first creating a figure window and a button group to contain the buttons.

fig = uifigure('Position',[680 678 398 271]);
bg = uibuttongroup(fig,'Position',[137 113 123 85]);

Create three toggle buttons and specify the location of each.

tb1 = uitogglebutton(bg,'Position',[10 50 100 22]);
tb2 = uitogglebutton(bg,'Position',[10 28 100 22]);
tb3 = uitogglebutton(bg,'Position',[10 6 100 22]);

Change the text associated with each toggle button.

tb1.Text = 'English';
tb2.Text = 'French';
tb3.Text = 'German';

Change the toggle button selection to German programmatically.

tb3.Value = true;

Determine the font name of the German toggle button text.

font = tb3.FontName

font =

Helvetica

Input Arguments

parent — Parent container

ButtonGroup object

Parent container, specified as a ButtonGroup object. The ButtonGroup must be parented to a Figure object or to a child container of a figure, such as: Tab, Panel, ButtonGroup, or GridLayout.

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.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: 'Text', 'French' specifies that the text “French” displays on the toggle button.

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

Value — State of toggle button

1 | 0

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 of a ToggleButton changes to 1, the Value property of the previously selected ToggleButton changes to 0. In addition, the SelectedObject property value of the ButtonGroup is updated.

If you programmatically change the Value property of a ToggleButton to 0, MATLAB sets the Value property of the first ToggleButton added to the ButtonGroup to 1. If the first ToggleButton added is the one for which you programmatically set the Value property to 0, then MATLAB sets the Value property for the ToggleButton added to the ButtonGroup to 1.

Note

The first ToggleButton added to a ButtonGroup is not necessarily the first ToggleButton listed in the Children property of the ButtonGroup.

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 — Predefined or custom icon

'' (default) | character vector | string scalar | m-by-n-by-3 truecolor image array

Predefined or custom icon, specified as a character vector, string scalar, or m-by-n-by-3 truecolor image array.

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. 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 button

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

Location and size 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 button group to the outer left edge of the button
bottom	Distance from the inner bottom edge of the button group to the outer bottom edge of the button
width	Distance between the right and left outer edges of the button
height	Distance between the top and bottom outer edges of the button

The Position values are relative to the drawable area of the button group. The drawable area is the area inside the borders of the button group and does not include the area occupied by the title.

All measurements are in pixel units.

Tips

• Button groups can contain any UI component type, but can only manage the selection of radio buttons and toggle buttons.

• To make your program respond when the app user selects a radio button or toggle button that is inside a button group. define a SelectionChangedFcn callback function for the ButtonGroup object. You cannot define callbacks for the individual buttons.

• To determine which radio button or toggle button is selected, query the SelectedObject property of the ButtonGroup object. You can execute this query anywhere in your code.

• If you set the Visible property of a ButtonGroup object to 'off', then any child objects it contains become invisible along with the parent ButtonGroup. However, the Visible property value of each child object remains unaffected.

Version History

Introduced in R2016a

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.