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(___,
specifies Name,Value
)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
Create Toggle Button Group
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]);
Click Button 3. The button group manages the toggle button selection by showing the first button as deselected and the third button as selected.
Create Radio Button Group
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]);
Click Button 3. The button group manages the radio button selection by showing the first button as deselected and the third button as selected.
Create Scrollable Button Group
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");
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';
Code Response to Radio Button Selection
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 theSelectionChangedFcn
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
Input Arguments
parent
— Parent container
Figure
object (default) | Panel
object | Tab
object | ButtonGroup
object | GridLayout
object
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
.
Title
— Title
character vector | string scalar | categorical array
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
π.
BackgroundColor
— Background color
[0.94 0.94 0.94]
(default) | RGB triplet | hexadecimal color code | 'r'
| 'g'
| 'b'
| ...
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 from0
toF
. 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 Name | Short Name | RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|---|---|
"red" | "r" | [1 0 0] | "#FF0000" | |
"green" | "g" | [0 1 0] | "#00FF00" | |
"blue" | "b" | [0 0 1] | "#0000FF" | |
"cyan"
| "c" | [0 1 1] | "#00FFFF" | |
"magenta" | "m" | [1 0 1] | "#FF00FF" | |
"yellow" | "y" | [1 1 0] | "#FFFF00" | |
"black" | "k" | [0 0 0] | "#000000" | |
"white" | "w" | [1 1 1] | "#FFFFFF" |
Here are the RGB triplets and hexadecimal color codes for the default colors MATLAB uses in many types of plots.
RGB Triplet | Hexadecimal Color Code | Appearance |
---|---|---|
[0 0.4470 0.7410] | "#0072BD" | |
[0.8500 0.3250 0.0980] | "#D95319" | |
[0.9290 0.6940 0.1250] | "#EDB120" | |
[0.4940 0.1840 0.5560] | "#7E2F8E" | |
[0.4660 0.6740 0.1880] | "#77AC30" | |
[0.3010 0.7450 0.9330] | "#4DBEEE" | |
[0.6350 0.0780 0.1840] | "#A2142F" |
SelectedObject
— Currently selected radio button or toggle button
first radio button or toggle button in button group (default)
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.
SelectionChangedFcn
— Selection changed callback
''
(default) | function handle | cell array | character vector
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 |
|
For more information about writing callbacks, see Callbacks in App Designer.
Position
— Location and size of button group, including borders and title
[left bottom width height]
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.
Element | Description |
---|---|
left | Distance from the inner left edge of the parent container to the outer left edge of the button group |
bottom | Distance from the inner bottom edge of the parent container to the outer bottom edge of the button group |
width | Distance between the right and left outer edges of the button group |
height | Distance 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
— Units of measurement
'pixels'
| 'normalized'
| 'inches'
| 'centimeters'
| 'points'
| 'characters'
Units of measurement, specified as one of the values in this table.
Units Value | Description |
---|---|
'pixels' (default in uifigure -based apps) | Distances in pixels are independent of your system resolution on Windows® and Macintosh systems:
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 |
'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:
To access the default uicontrol font, use |
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, theVisible
property value of each child object remains unaffected.
Version History
Introduced before R2006aR2023a: Change button group border color using BorderColor
property, not HighlightColor
You can change the border color of a button group in both
uifigure
-based and figure
-based apps by
using the BorderColor
property.
The BorderColor
property is recommended over the
HighlightColor
property, which is supported only in
figure
-based apps. However, there are no plans to remove support
for HighlightColor
.
R2022b: Change button group border width in uifigure
-based apps
In apps created in App Designer and using the uifigure
function,
use the BorderWidth
property to change the border width of the
button group.
R2020b: Turn interaction off and on
To control whether a button group responds to user interaction, use the
Enable
property. When the Enable
property
is set to 'on'
, you can interact with the button group and with UI
components within it as long as they are enabled. When the Enable
property is set to 'off'
, you cannot interact with the button group
or its content.
The Enable
property is supported only for button groups in App
Designer and uifigure
-based apps.
Comando MATLAB
Hai fatto clic su un collegamento che corrisponde a questo comando MATLAB:
Esegui il comando inserendolo nella finestra di comando MATLAB. I browser web non supportano i comandi MATLAB.
Select a Web Site
Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .
You can also select a web site from the following list:
How to Get Best Site Performance
Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.
Americas
- América Latina (Español)
- Canada (English)
- United States (English)
Europe
- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)
- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)