Main Content

uibuttongroup

Create button group to manage radio buttons and toggle buttons

Description

bg = uibuttongroup creates a button group in the current figure and returns the ButtonGroup object. If there is no figure available, MATLAB® calls the figure function to create one.

bg = uibuttongroup(parent) creates the button group in the specified parent container. The parent container can be a figure created with either the figure or uifigure function, or a child container such as a panel.

example

bg = uibuttongroup(___,Name,Value) specifies ButtonGroup properties using one or more name-value arguments. Use this option with any of the input argument combinations in the previous syntaxes. Button group property values vary slightly depending on whether the app is created with the figure or uifigure function. For more information, see Name-Value Arguments.

Examples

collapse all

Create a button group in a UI figure. Add three toggle buttons to the button group. By default, the first button is selected.

fig = uifigure;
bg = uibuttongroup(fig,"Position",[137 113 123 85]);
b1 = uitogglebutton(bg,"Text","Button 1","Position",[10 50 100 22]);
b2 = uitogglebutton(bg,"Text","Button 2","Position",[10 28 100 22]);
b3 = uitogglebutton(bg,"Text","Button 3","Position",[10 6 100 22]);

Figure contains an object of type uibuttongroup.

Click Button 3. The button group manages the toggle button selection by showing the first button as deselected and the third button as selected.

Button group in a UI figure window. There are three toggle buttons and the third button is selected.

Create a button group in a UI figure. Add three radio buttons to the button group. By default, the first button is selected.

fig = uifigure;
bg = uibuttongroup(fig,"Position",[137 113 123 85]);
b1 = uiradiobutton(bg,"Text","Button 1","Position",[10 50 100 22]);
b2 = uiradiobutton(bg,"Text","Button 2","Position",[10 28 100 22]);
b3 = uiradiobutton(bg,"Text","Button 3","Position",[10 6 100 22]);

Figure contains an object of type uibuttongroup.

Click Button 3. The button group manages the radio button selection by showing the first button as deselected and the third button as selected.

Button group in a UI figure window. There are three toggle buttons and the third button is selected.

Use the Scrollable property to enable within a button group that has components outside its borders. Scrolling is only possible when the button group is in a figure created with the uifigure function. App Designer uses this type of figure for creating apps.

Create a button group in a UI figure. Add six toggle buttons, with the first three lying outside the upper border of the button group.

fig = uifigure;
bg = uibuttongroup(fig,"Position",[20 20 196 135]);
tb1 = uitogglebutton(bg,"Position",[11 165 140 22],"Text","One");
tb2 = uitogglebutton(bg,"Position",[11 140 140 22],"Text","Two");
tb3 = uitogglebutton(bg,"Position",[11 115 140 22],"Text","Three");
tb4 = uitogglebutton(bg,"Position",[11 90 140 22],"Text","Four");
tb5 = uitogglebutton(bg,"Position",[11 65 140 22],"Text","Five");
tb6 = uitogglebutton(bg,"Position",[11 40 140 22],"Text","Six");

Figure contains an object of type uibuttongroup.

Enable scrolling by setting the Scrollable property of the button group to 'on'. By default, the scroll box displays at the top.

bg.Scrollable = 'on';

Figure contains an object of type uibuttongroup.

Create an app that shows the previous and current button selections in the MATLAB Command Window when the user selects a different radio button in a button group.

In a file named buttonGroupApp.m, write a function that implements the app:

  • Create a UI figure with a button group that contains three radio buttons.

  • Write a callback function named displaySelection for the button group that displays the text of the previously and currently selected radio buttons, and assign the function to the SelectionChangedFcn callback property. For more information about callbacks, see Create Callbacks for Apps Created Programmatically.

function buttonGroupApp
fig = uifigure;
bg = uibuttongroup(fig, ...
    "SelectionChangedFcn",@displaySelection, ...
    "Position",[137 113 123 85]);
r1 = uiradiobutton(bg, ...
    "Text","Option 1", ...
    "Position",[10 50 100 22]);
r2 = uiradiobutton(bg, ...
    "Text","Option 2", ...
    "Position",[10 28 100 22]);
r3 = uiradiobutton(bg, ...
    "Text","Option 3", ...
    "Position",[10 6 100 22]);

function displaySelection(src,event)
disp("Previous: " + event.OldValue.Text);
disp("Current: " + event.NewValue.Text);
end
end

Run the buttonGroupApp function. Change the button selection. The previous and current selection displays in the Command Window.

buttonGroupApp

Figure contains an object of type uibuttongroup.

Input Arguments

collapse all

Parent container, specified as a figure created with either the figure or uifigure function, or a child container:

  • Panels, tabs, and button groups can be containers in either type of figure.

  • Grid layouts can be containers only in figures created with the uifigure function.

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: uibuttongroup(Title="Options") specifies that the button group title is Options.

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

Example: uibuttongroup("Title","Options") specifies that the button group title is Options.

Note

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

Title, specified as a character vector, string scalar, or categorical array. If you specify this property as a categorical array, MATLAB displays only the first element in the array.

MATLAB does not interpret a vertical slash ('|') character as a line break, it displays as a vertical slash in the title.

If you want to specify a Unicode® character, pass the Unicode decimal code to the char function. For example, ['Multiples of ' char(960)] displays as Multiples of π.

Background color, specified as an RGB triplet, a hexadecimal color code, or one of the color options listed in the table.

RGB triplets and hexadecimal color codes are useful for specifying custom colors.

  • 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].

  • A hexadecimal color code is a character vector or a string scalar that starts with a hash symbol (#) followed by three or six hexadecimal digits, which can range from 0 to F. The values are not case sensitive. Thus, the color codes "#FF8800", "#ff8800", "#F80", and "#f80" are equivalent.

Alternatively, you can specify some common colors by name. This table lists the named color options, the equivalent RGB triplets, and hexadecimal color codes.

Color NameShort NameRGB TripletHexadecimal Color CodeAppearance
"red""r"[1 0 0]"#FF0000"

Sample of the color red

"green""g"[0 1 0]"#00FF00"

Sample of the color green

"blue""b"[0 0 1]"#0000FF"

Sample of the color blue

"cyan" "c"[0 1 1]"#00FFFF"

Sample of the color cyan

"magenta""m"[1 0 1]"#FF00FF"

Sample of the color magenta

"yellow""y"[1 1 0]"#FFFF00"

Sample of the color yellow

"black""k"[0 0 0]"#000000"

Sample of the color black

"white""w"[1 1 1]"#FFFFFF"

Sample of the color white

Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.

RGB TripletHexadecimal Color CodeAppearance
[0 0.4470 0.7410]"#0072BD"

Sample of RGB triplet [0 0.4470 0.7410], which appears as dark blue

[0.8500 0.3250 0.0980]"#D95319"

Sample of RGB triplet [0.8500 0.3250 0.0980], which appears as dark orange

[0.9290 0.6940 0.1250]"#EDB120"

Sample of RGB triplet [0.9290 0.6940 0.1250], which appears as dark yellow

[0.4940 0.1840 0.5560]"#7E2F8E"

Sample of RGB triplet [0.4940 0.1840 0.5560], which appears as dark purple

[0.4660 0.6740 0.1880]"#77AC30"

Sample of RGB triplet [0.4660 0.6740 0.1880], which appears as medium green

[0.3010 0.7450 0.9330]"#4DBEEE"

Sample of RGB triplet [0.3010 0.7450 0.9330], which appears as light blue

[0.6350 0.0780 0.1840]"#A2142F"

Sample of RGB triplet [0.6350 0.0780 0.1840], which appears as dark red

Currently selected radio button or toggle button, specified as a RadioButton or a ToggleButton object in uifigure-based apps, or a UIControl object in figure-based apps.

Get the value of this property to determine which button is currently selected within the button group.

Set the value of this property to change the currently selected button. When you change the selection using this property, MATLAB adjusts the Value property for the other buttons within the button group accordingly.

For example, suppose that your button group contains three radio buttons and you set the SelectedObject property to radiobutton3. MATLAB sets the Value property for each child RadioButton as follows:

  • radiobutton1.Value = false;

  • radiobutton2.Value = false;

  • radiobutton3.Value = true;

In other words, setting the SelectedObject property has the same effect as setting the Value property of the buttons in the button group.

Selection changed callback, 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 (not recommended). MATLAB evaluates this expression in the base workspace.

This callback executes when the user selects a different button within the button group in the app. It does not execute if a radio or toggle button Value property changes programmatically.

This callback function can access specific information about the user’s interaction with the buttons. MATLAB passes this information in a SelectionChangedData object as the second argument to your callback function. In App Designer, the argument is called event. You can query the object properties using dot notation. For example, event.NewValue returns the currently selected button. The SelectionChangedData object is not available to callback functions specified as character vectors.

The following table lists the properties of the SelectionChangedData object.

Property

Description

OldValue

Previously selected button

NewValue

Currently selected button

Source

Component that executes the callback

EventName

'SelectionChanged'

For more information about writing callbacks, see Callbacks in App Designer.

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

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

All measurements are in units specified by the Units property.

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.

Note

If the button group is parented to a grid layout manager, the value of the Position property is not immediately updated. To use the Position value to resize the button group children relative to the button group size, use a SizeChangedFcn callback.

Units of measurement, specified as one of the values in this table.

Units ValueDescription
'pixels' (default in uifigure-based apps)

Distances in pixels are independent of your system resolution on Windows® and Macintosh systems:

  • On Windows systems, a pixel is 1/96th of an inch.

  • On Macintosh systems, a pixel is 1/72nd of an inch.

On Linux® systems, the size of a pixel is determined by your system resolution.

'normalized' (default in figure-based apps)

These units are normalized with respect to the parent container. The lower-left corner of the container maps to (0,0) and the upper-right corner maps to (1,1).

'inches'Inches.
'centimeters'Centimeters.
'points'Points. One point equals 1/72nd of an inch.
'characters'

These units are based on the default uicontrol font of the graphics root object:

  • Character width = width of the letter x.

  • Character height = distance between the baselines of two lines of text.

To access the default uicontrol font, use get(groot,'defaultuicontrolFontName') or set(groot,'defaultuicontrolFontName').

The recommended value is 'pixels', because most MATLAB app building functionality measures distances in pixels. You can create an object that rescales based on the size of the parent container by parenting the object to a grid layout manager created using the uigridlayout function. For more information, see Lay Out Apps Programmatically.

Tips

  • A button group can contain any UI component type, but it manages the selection of only 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 button group. You cannot define callbacks for the individual buttons.

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

  • If you set the Visible property of a button group object to 'off', then any child objects it contains (buttons, other button groups, and so on) become invisible along with the parent button group. However, the Visible property value of each child object remains unaffected.

Version History

Introduced before R2006a

expand all