Uibuttongroup Properties

Control uibuttongroup appearance and behavior

Uibuttongroups are containers for grouping together and managing the exclusive selection of radio buttons and toggle buttons. The uibuttongroup function creates a button group and sets any required properties. By changing uibuttongroup property values, you can modify certain aspects of its appearance and behavior.

Starting in R2014b, you can use dot notation to refer to a particular object and property:

b = uibuttongroup;
bgcolor = b.BackgroundColor;
b.BackgroundColor = [.5 .5 .5];

If you are using an earlier release, use the get and set functions to query and set properties.

Appearance

expand all

VisibleUibuttongroup visibility'on' (default) | 'off'

Uibuttongroup visibility, specified as 'on' or 'off'. The Visible property determines whether the uibuttongroup displays on the screen. If the Visible property of a uibuttongroup is set to 'off', the entire uibuttongroup is invisible, but you can still specify and access its properties.

Changing the size of an invisible uibuttongroup triggers the SizeChangedFcn callback when the uibuttongroup becomes visible.

    Note   Changing the Visible property of a uibuttongroup does not change the Visible property of its child components even though hiding the uibuttongroup prevents its children from displaying.

BackgroundColorUibuttongroup background color[.94 .94 .94] (default) | RGB triplet | short name | long name

Uibuttongroup background color, specified as an RGB triplet, short name, or long name. The color you specify fills the area bounded by the uibuttongroup.

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]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

    Note:   Some operating systems override the BackgroundColor value.

Data Types: double | char

ForegroundColorUibuttongroup title color[0 0 0] (default) | RGB triplet | short name | long name

Uibuttongroup title color, specified as an RGB triplet, short name, or long name.

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]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

Example: [0 0 1]

Example: 'b'

Example: 'blue'

BorderTypeBorder of the uibuttongroup'etchedin' (default) | 'etchedout' | 'beveledin' | 'beveledout' | 'line' | 'none'

Border of the uibuttongroup area, specified as 'etchedin', 'none', 'etchedout', 'beveledin', 'beveledout', or 'line'.

  • For a 3-D look, use etched or beveled borders.

    Use the HighlightColor and ShadowColor properties to specify the color of 3-D borders.

  • For a 2-D look, use a line border.

    Use the ForegroundColor property to specify the line border color.

BorderWidthWidth of uibuttongroup border1 (default) | positive integer value

Width of the uibuttongroup border, specified as a positive integer value. The unit of measurement is pixels. Etched and beveled borders wider than three pixels might not appear correctly at the corners.

HighlightColorUibuttongroup 3-D frame highlight colorRGB triplet | short name | long name

Uibuttongroup 3-D frame highlight color, specified as an RGB triplet, short name, or long name.

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]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

ShadowColorUibuttongroup border shadow colorRGB triplet | short name | long name

Uibuttongroup border shadow color, specified as an RGB triplet, short name, or long name.

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]. This table lists RGB triplet values that have equivalent color strings.

Long NameShort NameRGB Triplet
'yellow''y'[1 1 0]
'magenta''m'[1 0 1]
'cyan''c'[0 1 1]
'red''r'[1 0 0]
'green''g'[0 1 0]
'blue''b'[0 0 1]
'white''w'[1 1 1]
'black'k'[0 0 0]

ClippingClipping of child components to uibuttongroup'on' (default) | 'off'

    Note:   The behavior of the Clipping property has changed. It no longer has any effect on uibuttongroups. Child objects are now clipped to the uibuttongroup boundary regardless of the value of this property. This property might be removed in a future release.

Location and Size

expand all

PositionLocation and size of uibuttongroup relative to parent[left bottom width height]

Location and size of the uibuttongroup relative to the parent, specified as the vector, [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 uibuttongroup
bottomDistance from the inner bottom edge of the parent container to the outer bottom edge of the uibuttongroup
widthDistance between the right and left outer edges of the uibuttongroup
heightDistance between the top and bottom outer edges of the uibuttongroup

All measurements are in units specified by the Units property.

    Note:   If the parent of the uibuttongroup is a figure, then the Position values are relative to the figure's drawable area. The drawable area of a figure is the area inside the window borders, excluding the menu bar and tool bar.

Example: Modify One Value in the Position Vector

You can combine dot notation and array indexing when you want to change one value in the Postion vector. For example, this code sets the width of the Uibuttongroup to 0.5:

b = uibuttongroup;
b.Position(3) = 0.5;
b.Position
ans =

      0   0   0.5000  1.0000

UnitsUnits of measurement'normalized' (default) | 'inches' | 'centimeters' | 'pixels' | 'points' | 'characters'

Units of measurement, specified as 'normalized', 'inches', 'centimeters', 'pixels', 'points', or 'characters'.

MATLAB® uses these units to interpret the location and size values of the Position property:

  • Normalized units map the lower left corner of the parent container 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.

  • The size of a uibuttongroup specified in pixel units depends on the system display settings and resolution.

  • Characters units are determined by the default system font. Each character unit is the width of the letter x. The height of each character unit is the distance between the baselines of two lines of text.

MATLAB measures all units from the lower left corner of the parent object.

If you change the value of the Units property, it is good practice to return it to its default value after completing your computation to avoid affecting other functions that assume the Units property is set to the default value.

The order in which you specify the Units and Position properties has these effects:

  • If you specify the Units property before the Position property, then MATLAB sets Position using the units you specified.

  • If you specify the Units property after the Position property, MATLAB sets the position using the default Units. Then, MATLAB converts the Position values to the equivalent values in the units you specified.

SizeChangedFcnUibuttongroup resize callback function'' (default) | function handle | cell array | string

Uibuttongroup resize callback function, specified as one of these values:

  • Function handle

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

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

Define this callback function when you want to customize the layout of a GUI beyond what the Position and Units properties provide.

The SizeChangedFcn callback executes under these circumstances:

  • The uibuttongroup becomes visible for the first time.

  • The uibuttongroup is visible while its drawable area changes. The drawable area is the area inside the outer bounds of the uibuttongroup.

  • The uibuttongroup becomes visible for the first time after its drawable area changes. This situation occurs when the drawable area changes while the uibuttongroup is invisible, and then it becomes visible later.

These are some of the important characteristics of the SizeChangedFcn callback and some recommended best practices:

  • Consider delaying the display of the figure until after all the variables that the uibuttongroup's SizeChangedFcn uses are defined. This practice can prevent the uibuttongroup's SizeChangedFcn callback from returning an error. To delay the display of the figure, set its Visible property to 'off'. Then, set the Visible property to 'on' after you define the variables that your SizeChangedFcn callback uses.

  • Use the gcbo function in your SizeChangedFcn code to get the uibuttongroup object that the user is resizing. See the description of the figure SizeChangedFcn for an example that uses gcbo.

  • All visible Uibuttongroups that are specified in normalized units resize before the parent figure does. All visible, nested uibuttongroups resize from inside-out.

    Tip   As an easy alternative to specifying a SizeChangedFcn callback, you can set the Units property of all the objects you put inside the uibuttongroup to 'normalized'. Doing so makes those components scale proportionally with the uibuttongroup.

See Managing the Layout in Resizable GUIs for more information on controlling the resize behavior of a programmatic GUI.

See Resize Behavior for more information on controlling the resize behavior of a GUIDE GUI.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

ResizeFcnUibuttongroup resize callback function'' (default) | function handle | cell array | string

Callback function that executes when the uibuttongroup size changes, specified as one of these values:

  • Function handle

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

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

    Note:   Use of the ResizeFcn property is not recommended. It might be removed in a future release. Use SizeChangedFcn instead.

Data Types: function_handle | cell | char

Font Style

expand all

FontNameFont for displaying uibuttongroup titlestring

Font for displaying the uibuttongroup title, specified as a string. To display and print properly, the font name must refer to a font that the user's system supports. The default font is system dependent.

To use a fixed-width font, set the FontName property to the string, 'FixedWidth'. This setting instructs MATLAB to use the value of the root FixedWidthFontName property, which you can set in the startup.m file.

See Specifying Startup Options in MATLAB Startup File for more information about the startup.m file.

Example: 'Arial'

FontSizeFont size for uibuttongroup titlepositive number

Font size for the uibuttongroup title, specified as a positive number. The FontUnits property specifies the units. The default size is system-dependent.

Example: 12

Example: 12.5

Data Types: double

FontUnitsUnits of font size for uibuttongroup title'points' (default) | 'inches' | 'centimeters' | 'normalized' | 'pixels'

Units of font size for the uibuttongroup title, specified as 'points', 'inches', 'centimeters', 'normalized', or 'pixels'.

If you set this property to 'normalized', then MATLAB interprets the font size as a fraction of the uibuttongroup height. When you resize the uibuttongroup, MATLAB scales the displayed font to maintain that fraction.

The other FontUnits options (pixels, inches, centimeters, and points) are absolute units. 1 point = 1/72 inch.

FontWeightFont weight for the uibuttongroup title'normal' (default) | 'bold'

Font weight of uibuttongroup title, specified as a value from the following table.

FontWeight ValueDescription
'normal'Normal font weight
'bold'Heavy font weight

Not all fonts support all font weights. Therefore, if you specify an unsupported value for the FontWeight property, the result might appear the same as the default.

    Note:   The 'light' and 'demi' font weight values have been removed in R2014b. If you specify either of these values, the result is a normal font weight.

FontAngleCharacter slant of the uibuttongroup title'normal' (default) | 'italic'

Character slant of uibuttongroup title, specified as 'normal' or 'italic'. MATLAB uses this property to select a font from those available on your system. Setting this property to 'italic' selects a slanted version of the font, if it is available on your system.

    Note:   The 'oblique' value has been removed. Use 'italic' instead.

Text

expand all

TitleUibuttongroup titlestring

Uibuttongroup title, specified as a string.

MATLAB does not interpret a vertical slash ('|') character as a line break, it displays as a vertical slash in the uibuttongroup 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 π.

Example: 'Options'

Example: ['Multiples of ' char(960)]

TitlePositionLocation of uibuttongroup title'lefttop' (default) | 'centertop' | 'righttop' | 'leftbottom' | 'centerbottom' | 'righttbottom'

Location of the uibuttongroup title, specified as 'lefttop', 'centertop', 'righttop', 'leftbottom', 'centerbottom', or 'righttbottom'.

Interactive Control

expand all

ButtonDownFcnButton-press callback function'' (default) | function handle | cell array | string

Button-press callback function, specified as one of these values:

  • Function handle

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

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

The ButtonDownFcn callback is a function that executes when the user clicks a mouse button on the uibuttongroup.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

SelectionChangedFcnCallback that executes when user selects a different button'' (default) | function handle | cell array | string

Callback that executes when the user selects a different button, specified as one of these values:

  • Function handle

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

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This callback function executes when the user selects a different button within the uibuttongroup.

If you specify this property as a function handle (or cell array containing a function handle), MATLAB passes an object containing callback data as the second argument to the callback function. This object contains the properties described in this table. You can access these properties inside the callback function using dot notation.

Property

Description

OldValue

Previously selected button, or [] if none was selected

NewValue

Currently selected button

Source

The parent uibuttongroup object

EventName

'SelectionChanged'

Define a uibuttongroup SelectionChangedFcn callback to make your GUI respond when the user selects different buttons within the uibuttongroup. Do not code the response in the individual uicontrol Callback functions.

If you want another component to respond to the selection, then that component's callback function can access the selected radio button or toggle button from the uibuttongroup's SelectedObject property.

Example: @myfun

Example: {@myfun,x}

UIContextMenuUibuttongroup context menuempty GraphicsPlaceholder array (default) | uicontextmenu object

Uibuttongroup context menu, specified as a uicontextmenu object. Use this property to display a context menu when the user right-clicks on the uibuttongroup. Create the context menu using the uicontextmenu function.

SelectedSelection status of uibuttongroup'off' (default) | 'on'

    Note:   The behavior of the Selected property changed in R2014b, and it is not recommended. It no longer has any effect on uibuttongroups. This property might be removed in a future release.

SelectionHighlightAbility to highlight selection handles'on' (default) | 'off'

    Note:   The behavior of the SelectionHighlight property changed in R2014b, and it is not recommended. It no longer has any effect on uibuttongroups. This property might be removed in a future release.

Callback Execution Control

expand all

BusyActionCallback queuing'queue' (default) | 'cancel'

Callback queuing specified as 'queue' (default) or 'cancel'. The BusyAction property determines how MATLAB handles the execution of interrupting callbacks. There are two callback states to consider:

  • The running callback is the currently executing callback.

  • The interrupting callback is a callback that tries to interrupt the running callback.

The BusyAction property of the source of the interrupting callback determines how MATLAB handles its execution. The BusyAction property has these values:

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

  • 'cancel' — Do not execute the interrupting callback.

Whenever MATLAB invokes a callback, that callback always attempts to interrupt an executing callback. The Interruptible property of the object whose callback is running determines if interruption is allowed. If Interruptible is set to:

  • on — Interruption occurs at the next point where MATLAB processes the queue. This is the default.

  • off — The BusyAction property (of the object owning the executing callback) determines if MATLAB enqueues or ignores the interrupting callback.

InterruptibleCallback interruption'on' (default) | 'off'

Callback interruption, specified as 'on' or 'off'. The Interruptible property determines if a running callback can be interrupted.

There are two callback states to consider:

  • The running callback is the currently executing callback.

  • The interrupting callback is a callback that tries to interrupt the running callback.

Whenever MATLAB invokes a callback, that callback attempts to interrupt the running callback. The Interruptible property of the object owning the running callback determines if interruption is allowed. If interruption is not allowed, then the BusyAction property of the object owning the interrupting callback determines if it is discarded or put into a queue.

If a uibuttongroup callback is the running callback, then the Interruptible property determines if it can be interrupted by another callback. The Interruptible property has two possible values:

  • 'on' — A callback can interrupt the running callback. The interruption occurs at the next point where MATLAB processes the queue, such as when there is a drawnow, figure, getframe, waitfor, or pause.

    • If the running callback contains one of these commands, then MATLAB stops the execution of the callback at this point and executes the interrupting callback. MATLAB resumes executing the running callback when the interrupting callback completes.

    • If the running callback does not contain one of these commands, then MATLAB finishes executing the callback without interruption.

  • 'off' — A callback cannot interrupt the running callback. MATLAB finishes executing the running callback without any interruptions. This is the default behavior.

    Note:   Callback interruption and execution behave differently in these situations:

    • If the interrupting callback is a DeleteFcn, CloseRequestFcn, or SizeChangedFcn callback, then the interruption occurs regardless of the Interruptible property value.

    • If the running callback is currently executing the waitfor function, then the interruption occurs regardless of the Interruptible property value.

    • 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 might change when another callback executes.

HitTestAbility to become current object'on' (default) | 'off'

Ability to become current object, specified as 'on' or 'off':

  • Setting the value to 'on' allows the uibuttongroup to become the current object when the user clicks on it. A value of 'on' also allows the figure CurrentObject property and the gco function to report the uibuttongroup as the current object.

  • Setting the value to 'off' sets the figure CurrentObject property to an empty GraphicsPlaceholder array when the user clicks on the uibuttongroup.

Creation and Deletion Control

expand all

BeingDeletedDeletion status of uibuttongroup'off' (default) | 'on'

This property is read only.

Deletion status of uibuttongroup, returned as 'on' or 'off'. MATLAB sets the BeingDeleted property to 'on' when the delete function of the uibuttongroup begins execution (see the DeleteFcn property). The BeingDeleted property remains set to 'on' until the uibuttongroup no longer exists.

Check the value of the BeingDeleted property to verify that the uibuttongroup is not about to be deleted before querying or modifying it.

CreateFcnUibuttongroup creation functionfunction handle | cell array | string

Uibuttongroup creation function, specified as one of these values:

  • Function handle

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

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

This property specifies a callback function to execute when MATLAB creates the uibuttongroup. MATLAB initializes all uibuttongroup property values before executing the CreateFcn callback. If you do not specify the CreateFcn property, then MATLAB executes a default creation function.

Use the gcbo function in your CreateFcn code to get the handle to the uibuttongroup that is being created.

Setting the CreateFcn property on an existing uibuttongroup has no effect.

    Note:   Do not call copyobj or textwrap (which calls copyobj) inside a CreateFcn. Copying the uibuttongroup object causes the CreateFcn callback to execute repeatedly.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

DeleteFcnUibuttongroup deletion functionfunction handle | cell array | string

Uibuttongroup deletion function, specified as one of these values:

  • Function handle

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

  • String that is a valid MATLAB expression. MATLAB evaluates this expression in the base workspace.

For more information about specifying a callback property value as a function handle, cell array, or string, see How to Specify Callback Property Values.

The DeleteFcn property specifies a callback function to execute when MATLAB deletes the uibuttongroup (for example, when the end user deletes the figure). MATLAB executes the DeleteFcn callback before destroying the properties of the uibuttongroup. If you do not specify the DeleteFcn property, then MATLAB executes a default deletion function.

Use the gcbo function in your DeleteFcn code to get the handle to the uibuttongroup that is being deleted.

Example: @myfun

Example: {@myfun,x}

Data Types: function_handle | cell | char

Identifiers

expand all

TagUibuttongroup identifier'' (default) | string

Uibuttongroup identifier, specified as a string. You can specify a unique Tag value to serve as an identifier for the uibuttongroup. When you need access to the uibuttongroup elsewhere in your code, you can use the findobj function to search for the uibuttongroup based on the Tag value.

Example: 'buttongroup1'

Data Types: char

UserDataData to associate with the uibuttongroup objectempty array (default) | array

Data to associate with the uibuttongroup object, specified as any array. Specifying UserData can be useful for sharing data values within and across GUIs you create. See Share Data Among Callbacks for more information.

Example: [1 2 3]

Example: 'April 21'

Example: struct('value1',[1 2 3],'value2','April 21')

Example: {[1 2 3],'April 21'}

TypeType of graphics object'uibuttongroup'

This property is read only.

Type of graphics object, returned as 'uibuttongroup'.

SelectedObjectCurrently selected radio button or toggle buttonuicontrol object | []

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

Use this property to determine the currently selected button within a uibuttongroup. You can also use this property to initialize the GUI with a default button selection. If you want no selection, then set this property to [].

The default value of the SelectedObject property is the first uicontrol radio button or toggle button that you add to the uibuttongroup.

    Note:   The SelectionChangedFcn callback does not execute when you set the SelectedObject property programmatically..

Parent/Child

expand all

ParentUibuttongroup parentfigure | uipanel | uibuttongroup | uitab

Uibuttongroup parent, specified as a figure, uipanel, uibuttongroup, or uitab. You can move a uibuttongroup to a different figure, uipanel, uibuttongroup, or uitab by setting this property to the handle of the target figure, uipanel, uibuttgroup, or uitab.

ChildrenChildren of uibuttongroupempty GraphicsPlaceholder array (default) | 1-D array of component objects

Children of uibuttongroup, returned as an empty GraphicsPlaceholder or a 1-D array of component objects. Although a uibuttongroup manages only the user selection of radio buttons and toggle buttons, its children can be axes, uipanels, uibuttongroups, and any style of uicontrol.

You cannot add or remove children using the Children property of the uibuttongroup. Use this property to view the list of children or to reorder the children. The order of the children in this array reflects the front-to-back order (stacking order) of the components on the screen.

To add a child to this list, set the Parent property of the child component to the uibuttongroup handle.

Objects with the HandleVisibility property set to 'off' do not list in the uibuttongroup's Children property.

HandleVisibilityVisibility of uibuttongroup handle'on' (default) | 'callback' | 'off'

Visibility of Uibuttongroup handle, specified as 'on', 'callback', or 'off'.

This property controls the visibility of the uibuttongroup handle 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. These functions include get, findobj, gca, gcf, gco, newplot, cla, clf, and close. The HandleVisibility property also controls the visibility of the object's handle in the parent figure's CurrentObject property. Handles are still valid even if they are not visible. If you know an object's handle, you can set and get its properties, and pass it to any function that operates on handles.

HandleVisibility ValueDescription
'on'The uibuttongroup handle is always visible.
'callback'The uibuttongroup handle is visible from within callbacks or functions invoked by callbacks, but not from within functions invoked from the command line. This protects the GUI from command-line users, while allowing callback routines to have complete access.
'off'The uibuttongroup handle is invisible at all times. This option might be useful when a callback routine invokes a function that might potentially damage the GUI (such as a function that evaluates user-typed strings). You can set the HandleVisibility to 'off' to temporarily hide the handle during the execution of that function.

Set the graphics root ShowHiddenHandles property to 'on' to make all handles visible, regardless of their HandleVisibility value. This setting has no effect on their HandleVisibility values.

    Note:   Do not try to access radio buttons and toggle buttons that are managed by a uibuttongroup outside of the button group. Set the HandleVisibility of those radio buttons and toggle buttons to 'off' to prevent accidental access.

Was this topic helpful?