Documentation Center

  • Trial Software
  • Product Updates

Uibuttongroup Properties

Describe button group properties

Modifying Properties

You can set and query graphics object properties in two ways:

  • The Property Inspector is an interactive tool that enables you to see and change object property values. The Property inspector is available from the GUIDE Layout Editor View menu, or use the inspect function at the command line.

  • The set and get functions enable you to set and query the values of properties.

Uibuttongroup takes its default property values from uipanel. To set a uibuttongroup default property value, set the default for the corresponding uipanel property. Note that you can set no default values for the uibuttongroup SelectedObject and SelectionChangeFcn properties.

For more information about changing the default value of a property see Setting Default Property Values. For an example, see the CreateFcn property.

Uibuttongroup Properties

This section describes all properties useful to uibuttongroup objects and lists valid values. Curly braces { } enclose default values.

Property Name

Description

BackgroundColor

Color of the button group background

BeingDeleted

This object is being deleted

BorderType

Type of border around the button group

BorderWidth

Width of the button group border in pixels

BusyAction

Interruption of other callback routines

ButtonDownFcn

Button-press callback routine

Children

All children of the button group

Clipping

Clipping of child axes, panels, and button groups to the button group. Does not affect child user interface controls (uicontrol)

CreateFcn

Callback routine executed during object creation

DeleteFcn

Callback routine executed during object deletion

FontAngle

Title font angle

FontName

Title font name

FontSize

Title font size

FontUnits

Title font units

FontWeight

Title font weight

ForegroundColor

Title font color and color of 2-D border line

HandleVisibility

Handle accessibility from command line and GUIs

HighlightColor

3-D frame highlight color

Interruptible

Callback routine interruption mode

Parent

uibuttongroup object's parent

Position

Button group position relative to parent figure, panel, or button group

ResizeFcn

User-specified resize routine

SelectedObject

Currently selected uicontrol of style radiobutton or togglebutton

SelectionChangeFcn

Callback routine executed when the selected radio button or toggle button changes

ShadowColor

3-D frame shadow color

Tag

User-specified object identifier

Title

Title string

TitlePosition

Location of title string in relation to the button group

Type

Object class

UIContextMenu

Associate context menu with the button group

Units

Units used to interpret the position vector

UserData

User-specified data

Visible

Button group visibility

    Note:   Controls the visibility of a uibuttongroup and of its child axes, uibuttongroups. uipanels, and child uicontrols. Setting it does not change their Visible property.

BackgroundColor

ColorSpec

Color of the uibuttongroup background. A three-element RGB vector or one of the MATLAB® predefined names, specifying the background color. See the ColorSpec reference page for more information on specifying color.

BeingDeleted

on | {off} (read-only)

This object is being deleted. Mechanism to determine if objects are in the process of being deleted. MATLAB sets the BeingDeleted property to on when the object's delete function callback is called (see the DeleteFcn property). It remains set to on while the delete function executes, after which the object no longer exists.

For example, an object's delete function calls other functions that act on a number of different objects. If a function does not need to perform an action on an about-be-deleted object, it can check the object's BeingDeleted property before acting.

BorderType

none | {etchedin} | etchedout |
beveledin | beveledout | line

Border of the uibuttongroup area. Used to define the button group area graphically. Etched and beveled borders provide a 3-D look. Use the HighlightColor and ShadowColor properties to specify the border color of etched and beveled borders. A line border is 2-D. Use the ForegroundColor property to specify its color.

BorderWidth

integer

Width of the button group border. The width of the button group borders in pixels. The default border width is 1 pixel. 3-D borders wider than 3 may not appear correctly at the corners.

BusyAction

cancel | {queue}

Callback queuing

Determines how MATLAB handles the execution of interrupting callbacks.

A running callback is the currently executing callback. The interrupting callback is the callback that tries to interrupt the running callback. The BusyAction property of the interrupting callback determines how MATLAB handles its execution. When the BusyAction property is set to:

  • 'queue' — Puts the interrupting callback in a queue to be processed after the running callback finishes execution.

  • 'cancel' — Discards the interrupting callback as MATLAB finishes execution.

For information about how the Interruptible property of the callback controls whether other callbacks can interrupt the running callback, see the Interruptible property description.

ButtonDownFcn

string or function handle

Button-press callback routine. A callback routine that executes when you press a mouse button while the pointer is in a 5-pixel wide border around the uibuttongroup. This is useful for implementing actions to interactively modify object properties, such as size and position, when they are clicked on (using the selectmoveresize function, for example).

If you define this routine as a string, the string can be a valid MATLAB expression or the name of a code file. The expression executes in the MATLAB workspace.

Children

vector of handles

Children of the uibuttongroup. A vector containing the handles of all children of the uibuttongroup. Although a uibuttongroup manages only uicontrols of style radiobutton and togglebutton, its children can be axes, uipanels, uibuttongroups, and other uicontrols. You can use this property to reorder the children.

Clipping

{on} | off

Clipping mode. By default, MATLAB clips a uibuttongroup's child axes, uipanels, and uibuttongroups to the uibuttongroup rectangle. If you set Clipping to off, the axis, uipanel, or uibuttongroup display outside the button group rectangle. This property does not affect child uicontrols which, by default, can display outside the button group rectangle.

CreateFcn

string or function handle

Callback routine executed during object creation. The specified function executes when MATLAB creates a uibuttongroup object. MATLAB sets all property values for the uibuttongroup before executing the CreateFcn callback so these values are available to the callback. Within the function, use gcbo to get the handle of the uibuttongroup being created.

Setting this property on an existing uibuttongroup object has no effect.

To define a default CreateFcn callback for all new uibuttongroups you must define the same default for all uipanels. This default applies unless you override it by specifying a different CreateFcn callback when you call uibuttongroup. For example, the code

set(0,'DefaultUipanelCreateFcn','set(gcbo,...
    ''FontName'',''arial'',''FontSize'',12)')

creates a default CreateFcn callback that runs whenever you create a new panel or button group. It sets the default font name and font size of the uipanel or uibuttongroup title.

To override this default and create a button group whose FontName and FontSize properties are set to different values, call uibuttongroup with code similar to

hpt = uibuttongroup(...,'CreateFcn','set(gcbo,...
''FontName'',''times'',''FontSize'',14)')

    Note   To override a default CreateFcn callback you must provide a new callback and not just provide different values for the specified properties. This is because the CreateFcn callback runs after the property values are set, and can override property values you have set explicitly in the uibuttongroup call. In the example above, if instead of redefining the CreateFcn property for this uibuttongroup, you had explicitly set FontSize to 14, the default CreateFcn callback would have set FontSize back to the system dependent default.

Do not call copyobj or textwrap (which calls copyobj) inside a CreateFcn. The act of copying the uicontrol object fires the CreateFcn repeatedly, which raises a series of error messages after exceeding the root object's RecursionLimit property.

See Function Handle Callbacks for information on how to use function handles to define a callback function.

DeleteFcn

string or function handle

Callback routine executed during object deletion. A callback routine that executes when you delete the uibuttongroup object (e.g., when you issue a delete command or clear the figure containing the uibuttongroup). MATLAB executes the routine before destroying the object's properties so these values are available to the callback routine. The handle of the object whose DeleteFcn is being executed is accessible only through the root CallbackObject property, which you can query using gcbo.

FontAngle

{normal} | italic | oblique

Character slant used in the Title. MATLAB uses this property to select a font from those available on your particular system. Setting this property to italic or oblique selects a slanted version of the font, when it is available on your system.

FontName

string

Font family used in the Title. The name of the font in which to display the Title. To display and print properly, this must be a font that your system supports. The default font is system dependent. To eliminate the need to hard code the name of a fixed-width font, which may not display text properly on systems that do not use ASCII character encoding (such as in Japan), set FontName to the string FixedWidth. This string value is case insensitive.

set(uicontrol_handle,'FontName','FixedWidth')

This then uses the value of the root FixedWidthFontName property, which can be set to the appropriate value for a locale from startup.m in the end user's environment. Setting the root FixedWidthFontName property causes an immediate update of the display to use the new font.

FontSize

integer

Title font size. A number specifying the size of the font in which to display the Title, in units determined by the FontUnits property. The default size is system dependent.

FontUnits

inches | centimeters | normalized |
{points} |pixels

Title font size units. Normalized units interpret FontSize as a fraction of the height of the uibuttongroup. When you resize the uibuttongroup, MATLAB modifies the screen FontSize accordingly. pixels, inches, centimeters, and points are absolute units (1 point = 1/72 inch).

FontWeight

light | {normal} | demi | bold

Weight of characters in the title. MATLAB uses this property to select a font from those available on your particular system. Setting this property to bold causes MATLAB to use a bold version of the font, when it is available on your system.

ForegroundColor

ColorSpec

Color used for title font and 2-D border line. A three-element RGB vector or one of the MATLAB predefined names, specifying the font or line color. See the ColorSpec reference page for more information on specifying color.

HandleVisibility

{on} | callback | off

Control access to object's handle. This property determines when an object's handle is visible in its parent's list of children. When a handle is not visible in its parent's list of children, it is not returned by functions that obtain handles by searching the object hierarchy or querying handle properties. This includes get, findobj, gca, gcf, gco, newplot, cla, clf, and close. Neither is the handle visible in the parent figure's CurrentObject property. Handles that are hidden are still valid. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.

  • Handles are always visible when HandleVisibility is on.

  • Setting HandleVisibility to callback causes handles to be visible from within callback routines or functions invoked by callback routines, but not from within functions invoked from the command line. This provides a means to protect GUIs from command-line users, while allowing callback routines to have complete access to object handles.

  • Setting HandleVisibility to off makes handles invisible at all times. This may be necessary when a callback routine invokes a function that might potentially damage the GUI (such as evaluating a user-typed string), and so temporarily hides its own handles during the execution of that function.

      Note   Uicontrols of style radiobutton and togglebutton that are managed by a uibuttongroup should not be accessed outside the button group. Set the HandleVisibility of such radio buttons and toggle buttons to off or callback to prevent inadvertent access.

You can set the root ShowHiddenHandles property to on to make all handles visible, regardless of their HandleVisibility settings. This does not affect the values of the HandleVisibility properties.

HighlightColor

ColorSpec

3-D frame highlight color. A three-element RGB vector or one of the MATLAB predefined names, specifying the highlight color. See the ColorSpec reference page for more information on specifying color.

Interruptible

off | {on}

Callback routine interruption

Controls whether MATLAB can interrupt an object's callback function when subsequent callbacks attempt to interrupt it.

For user interface objects, the Interruptible property affects the callbacks for these properties only:

  • ButtonDownFcn

  • KeyPressFcn

  • KeyReleaseFcn

  • WindowButtonDownFcn

  • WindowButtonMotionFcn

  • WindowButtonUpFcn

  • WindowKeyPressFcn

  • WindowKeyReleaseFcn

  • WindowScrollWheelFcn

A running callback is the currently executing callback. The interrupting callback is the callback that tries to interrupt the running callback. MATLAB handles both callbacks based on the Interruptible property of the object of the running callback.

When the Interruptible property is set to:

  • 'off', MATLAB finishes execution of the running callback without any interruptions

  • 'on', these conditions apply:

    • If there is a drawnow, figure, getframe, waitfor, or pause command in the running callback, then MATLAB executes the interrupting callbacks which are already in the queue and returns to finish execution of the current callback.

    • If one of the above functions is not in the running callback, then MATLAB finishes execution of the current callback without any interruption.

The BusyAction property of the object of interrupting callback determines whether the callback should be ignored or should be put in the queue.

Setting the Interruptible property to on (default), allows a callback from other user interface objects to interrupt callback functions originating from this object.

    Note:   MATLAB does not save the state of properties or the display when an interruption occurs. For example, the handle returned by the gca or gcf command may be changed as another callback is executed.

After the function that interrupts a callback completes, the callback resumes execution where it halted when interrupted. For more information, see Control Callback Execution and Interruption.

    Note:   If the interrupting callback is a DeleteFcnor CreateFcn callback, or a figure's CloseRequest or ResizeFcn callback, it interrupts an executing callback regardless of the value of that object's Interruptible property. The interrupting callback starts execution at the next drawnow, figure, getframe, pause, or waitfor statement. An object's ButtonDownFcn or Callback routine is processed according to the rules described previously in this section.

Parent

handle

Uibuttongroup parent. The handle of the uibuttongroup's parent figure, uipanel, or uibuttongroup. You can move a uibuttongroup object to another figure, uipanel, or uibuttongroup by setting this property to the handle of the new parent.

Position

position rectangle

Size and location of uibuttongroup relative to parent. The rectangle defined by this property specifies the size and location of the button group within the parent figure window, uipanel, or uibuttongroup. Specify Position as

[left bottom width height]

left and bottom are the distance from the lower-left corner of the parent object to the lower-left corner of the uibuttongroup object. width and height are the dimensions of the uibuttongroup rectangle, including the title. All measurements are in units specified by the Units property.

ResizeFcn

string or function handle

Resize callback routine. MATLAB executes this callback routine whenever a user resizes the uibuttongroup and the figure Resize property is set to on, or in GUIDE, the Resize behavior option is set to Other. You can query the uibuttongroup Position property to determine its new size and position. During execution of the callback routine, the handle to the figure being resized is accessible only through the root CallbackObject property, which you can query using gcbo.

You can use ResizeFcn to maintain a GUI layout that is not directly supported by the MATLAB Position/Units paradigm.

For example, consider a GUI layout that maintains an object at a constant height in pixels and attached to the top of the figure, but always matches the width of the figure. The following ResizeFcn accomplishes this; it keeps the uicontrol whose Tag is 'StatusBar' 20 pixels high, as wide as the figure, and attached to the top of the figure. Note the use of the Tag property to retrieve the uicontrol handle, and the gcbo function to retrieve the figure handle. Also note the defensive programming regarding figure Units, which the callback requires to be in pixels in order to work correctly, but which the callback also restores to their previous value afterwards.

u = findobj('Tag','StatusBar');
fig = gcbo;
old_units = get(fig,'Units');
set(fig,'Units','pixels');
figpos = get(fig,'Position');
upos = [0, figpos(4) - 20, figpos(3), 20];
set(u,'Position',upos);
set(fig,'Units',old_units);

You can change the figure Position from within the ResizeFcn callback; however, the ResizeFcn is not called again as a result.

Note that the print command can cause the ResizeFcn to be called if the PaperPositionMode property is set to manual and you have defined a resize function. If you do not want your resize function called by print, set the PaperPositionMode to auto.

See Function Handle Callbacks for information on how to use function handles to define the callback function.

Selected

on | off (read only)

Is object selected? This property indicates whether the button group is selected. When this property is on, MATLAB displays selection handles if the SelectionHighlight property is also on. You can, for example, define the ButtonDownFcn function to set this property, allowing users to select the object with the mouse.

SelectedObject

scalar handle

Currently selected radio button or toggle button uicontrol in the managed group of components. Use this property to determine the currently selected component or to initialize selection of one of the radio buttons or toggle buttons. By default, SelectedObject is set to the first uicontrol radio button or toggle button that is added. Set it to [] if you want no selection. Note that SelectionChangeFcn does not execute when this property is set by the user.

SelectionChangeFcn

string or function handle

Callback routine executed when the selected radio button or toggle button changes. If this routine is called as a function handle, uibuttongroup passes it two arguments. The first argument, source, is the handle of the uibuttongroup. The second argument, eventdata, is an event data structure that contains the fields shown in the following table.

Event Data Structure Field

Description

EventName

'SelectionChanged'

OldValue

Handle of the object selected before this event. [] if none was selected.

NewValue

Handle of the currently selected object.

If you have a button group that contains a set of radio buttons and/or 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.

If you want 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.

SelectionHighlight

{on} | off

Object highlighted when selected. When the Selected property is on, MATLAB indicates the selected state by drawing four edge handles and four corner handles. When SelectionHighlight is off, MATLAB does not draw the handles.

ShadowColor

ColorSpec

3-D frame shadow color. ShadowColor is a three-element RGB vector or one of the MATLAB predefined names, specifying the shadow color. See the ColorSpec reference page for more information on specifying color.

Tag

string

User-specified object identifier. The Tag property provides a means to identify graphics objects with a user-specified label. You can define Tag as any string.

With the findobj function, you can locate an object with a given Tag property value. This saves you from defining object handles as global variables. For example, this function call returns the handles of all children (of the specified figures) that have the Tag value 'FormatTb'.

h = findobj(figurehandles,'Tag','FormatTb')
Title

string

Title string. The text displayed in the button group title. You can position the title using the TitlePosition property.

Vertical slash ('|') characters are not interpreted as line breaks and instead show up in the text displayed in the uibuttongroup title.

Setting a property value to default, remove, or factory produces the effect described in Defining Default Values. To set Title to one of these words, you must precede the word with the backslash character. For example,

hp = uibuttongroup('Title','\default');
TitlePosition

{lefttop} | centertop | righttop |
leftbottom | centerbottom | rightbottom

Location of the title. This property determines the location of the title string, in relation to the uibuttongroup.

Type

string (read-only)

Object class. This property identifies the kind of graphics object. For uibuttongroup objects, Type is always the string 'uipanel', because its default properties derive from uipanels.

UIContextMenu

handle

Associate a context menu with a uibuttongroup. Assign this property the handle of a Uicontextmenu object. MATLAB displays the context menu whenever you right-click the uibuttongroup. Use the uicontextmenu function to create the context menu.

Units

inches | centimeters | {normalized} |
points | pixels | characters

Units of measurement. MATLAB uses these units to interpret the Position property. For the button group itself, units are measured from the lower-left corner of its parent figure window, panel, or button group. For children of the button group, they are measured from the lower-left corner of the button group.

  • Normalized units map the lower-left corner of the button group or figure window to (0,0) and the upper-right corner to (1.0,1.0).

  • inches, centimeters, and points are absolute units (1 point = 1/72 inch).

  • Character units are characters using the default system font; the width of one character is the width of the letter x, the height of one character is the distance between the baselines of two lines of text.

If you change the value of Units, it is good practice to return it to its default value after completing your computation so as not to affect other functions that assume Units is set to the default value.

UserData

matrix

User-specified data. Any data you want to associate with the uibuttongroup object. MATLAB does not use this data, but you can access it using set and get.

Visible

{on} | off

Uibuttongroup visibility. By default, a uibuttongroup object is visible. When set to 'off', the uibuttongroup is not visible, as are all child objects of the button group. When a button group is hidden in this manner, you can still query and set its properties.

    Note   The value of a uibuttongroup's Visible property determines whether its child components, such as axes, buttons, uipanels, and other uibuttongroups, are visible. However, changing the Visible property of a button group does not change the settings of the Visible property of its child components even though hiding the button group causes them to be hidden.

Was this topic helpful?