Quantcast

Documentation Center

  • Trial Software
  • Product Updates

uibuttongroup

Create container object to exclusively manage radio buttons and toggle buttons

Syntax

uibuttongroup('PropertyName1',Value1,'PropertyName2',Value2,...)
handle = uibuttongroup(...)

Description

A uibuttongroup groups components and manages exclusive selection behavior for radio buttons and toggle buttons that it contains. It can also contain other user interface controls, axes, uipanels, and uibuttongroups. It cannot contain ActiveX® controls.

uibuttongroup('PropertyName1',Value1,'PropertyName2',Value2,...) creates a visible container component in the current figure window. This component manages exclusive selection behavior for uicontrols of style radiobutton and togglebutton.

handle = uibuttongroup(...) creates a uibuttongroup object and returns a handle to it in handle.

A uibuttongroup object can have axes, uicontrol, uipanel, and uibuttongroup objects as children. However, only uicontrols of style radiobutton and togglebutton are managed by the component.

When programming a button group, you do not code callbacks for the individual buttons; instead, use its SelectionChangeFcn callback to manage responses to selections. The following example illustrates how you use uibuttongroup event data to do this.

For the children of a uibuttongroup object, the Position property is interpreted relative to the button group. If you move the button group, the children automatically move with it and maintain their positions in the button group.

If you have a button group that contains a set of radio buttons and toggle buttons and you want:

  • An immediate action to occur when a radio button or toggle button is selected, you must include the code to control the radio and toggle buttons in the button group's SelectionChangeFcn callback function, not in the individual toggle button Callback functions. See the SelectionChangeFcn property and the example on this reference page for more information.

  • Another component such as a push button to base its action on the selection, then that component's Callback callback can get the handle of the selected radio button or toggle button from the button group's SelectedObject property.

Use the Parent property to specify the parent as a figure, uipanel, or uibuttongroup. If you do not specify a parent, uibuttongroup adds the button group to the current figure. If no figure exists, one is created.

See the Uibuttongroup Properties reference page for more information.

After creating a uibuttongroup, you can set and query its property values using set and get. Run get(handle) to see a list of properties and their current values. Run set(handle) to see a list of object properties you can set and their legal values.

Examples

This example creates a uibuttongroup with three radio buttons. It manages the radio buttons with the SelectionChangeFcn callback, selcbk.

When you select a new radio button, selcbk displays the uibuttongroup handle on one line, the EventName, OldValue, and NewValue fields of the event data structure on a second line, and the value of the SelectedObject property on a third line.

% Create the button group.
h = uibuttongroup('visible','off','Position',[0 0 .2 1]);
% Create three radio buttons in the button group.
u0 = uicontrol('Style','radiobutton','String','Option 1',...
    'pos',[10 350 100 30],'parent',h,'HandleVisibility','off');
u1 = uicontrol('Style','radiobutton','String','Option 2',...
    'pos',[10 250 100 30],'parent',h,'HandleVisibility','off');
u2 = uicontrol('Style','radiobutton','String','Option 3',...
    'pos',[10 150 100 30],'parent',h,'HandleVisibility','off');
% Initialize some button group properties. 
set(h,'SelectionChangeFcn',@selcbk);
set(h,'SelectedObject',[]);  % No selection
set(h,'Visible','on');

For the SelectionChangeFcn callback, selcbk, the source and event data structure arguments are available only if selcbk is called using a function handle. See SelectionChangeFcn for more information.

function selcbk(source,eventdata)
disp(source);
disp([eventdata.EventName,'  ',... 
     get(eventdata.OldValue,'String'),'  ', ...
     get(eventdata.NewValue,'String')]);
disp(get(get(source,'SelectedObject'),'String'));

If you click Option 2 with no option selected, the SelectionChangeFcn callback, selcbk, displays:

    3.0011

SelectionChanged    Option 2
Option 2

If you then click Option 1, the SelectionChangeFcn callback, selcbk, displays:

    3.0011

SelectionChanged  Option 2  Option 1
Option 1

More About

expand all

Tips

If you set the Visible property of a uibuttongroup object to 'off', any child objects it contains (buttons, button groups, etc.) become invisible along with the uibuttongroup panel itself. However, doing this does not affect the settings of the Visible property of any of its child objects, even though all of them remain invisible until the button group's visibility is set to 'on'. uipanel components also behave in this manner.

Do not use the CreateFcn of a button group to create the buttons it contains. You can toggle buttons created in the button group CreateFcn on and off, but clicking them does not trigger the button group SelectionChangeCallback and the buttons do not display the expected mutually-exclusive behavior.

See Also

|

Was this topic helpful?