uiselectiongroup

R2026b

Create selection group for radio buttons and toggle buttons

Since R2026b. Recommended over uibuttongroup.

collapse all in page

Syntax

sg = uiselectiongroup
sg = uiselectiongroup(members)
sg = uiselectiongroup(___,Name=Value)

Description

sg = uiselectiongroup creates an empty single selection group and returns a SingleSelectionGroup object.

sg = uiselectiongroup(members) creates a single selection group with the specified radio buttons or toggle buttons.

example

sg = uiselectiongroup(___,Name=Value) sets SingleSelectionGroup properties using one or more name-value arguments. Use this option with any of the input argument combinations in the previous syntaxes. For example, uiselectiongroup(members,SelectedObject=button1) creates a single selection group with button1 selected.

Examples

collapse all

Open Live Script

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

fig = uifigure(Position=[100 100 200 200]);
gl = uigridlayout(fig,[3 1]);
rb1 = uiradiobutton(gl,Text="English");
rb2 = uiradiobutton(gl,Text="French");
rb3 = uiradiobutton(gl,Text="German");
sg = uiselectiongroup([rb1 rb2 rb3]);

Figure contains an object of type uigridlayout.

Change the radio button selection to French.

rb2.Value = true;

Figure contains an object of type uigridlayout.

Open Live Script

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]);

Figure containing three toggle buttons labeled English, French, and German. The first button labeled English is selected.

Change the toggle button selection to French.

tb2.Value = true;

Figure contains an object of type uigridlayout.

Input Arguments

collapse all

Buttons to manage in the selection group, specified as an array of RadioButton objects or an array of ToggleButton objects. The specified buttons must be the same type and in the same figure.

Name-Value Arguments

collapse all

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: uiselectiongroup(rb,SelectionChangedFcn=@myCallback) assigns a callback function that executes when the selected button changes.

Note

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

Currently selected radio button or toggle button, specified as a RadioButton or ToggleButton object.

If the group contains radio buttons or toggle buttons, then SelectedObject must be specified as one of those buttons. If you do not specify this name-value argument, the first button in the group is selected by default. Use this name-value argument to specify the currently selected button. MATLAB® adjusts the Value property for the buttons in the selection group accordingly.

For example, suppose that you create a selection group that contains three radio buttons and you specify the SelectedObject name-value argument as radiobutton3. MATLAB sets the Value property for each child RadioButton object as follows:

  • radiobutton1.Value = false;

  • radiobutton2.Value = false;

  • radiobutton3.Value = true;

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

Selection changed callback, specified as one of these values:

  • Function handle

  • Cell array in which the first element is a function handle and subsequent elements are the arguments to pass to the callback function

  • String scalar or character vector containing a valid MATLAB command or function, which is evaluated in the base workspace (not recommended)

This callback executes when a user selects a different button in the selection group in the app. It does not execute if the selection is changed programmatically, either using the Value property of a radio button or toggle button or the SelectedObject property of the selection group.

This callback function can access specific information about the selection change. MATLAB passes this information in a SelectedObjectChangedData object as the second argument to your callback function. In App Designer, the argument is named event. You can query the object properties using dot notation. For example, event.SelectedObject returns the currently selected button. The SelectedObjectChangedData object is not available to callback functions specified as character vectors.

This table lists the properties of the SelectedObjectChangedData object.

Property

Description

SelectedObject

Currently selected button

PreviousSelectedObject

Previously selected button

Source

Component that executes the callback

EventName

'SelectionChanged'

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

Output Arguments

collapse all

Selection group, returned as a SingleSelectionGroup object. You can use sg to set properties of the SingleSelectionGroup object after you create it.

Tips

  • Buttons managed by a selection group can be in any container within the same figure.

  • To add or remove buttons after creating the group, use the addMember and removeMember functions.

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

  • To determine which button is currently selected, query the SelectedObject property of the selection group.

Version History

Introduced in R2026b

See Also

Functions

Objects