MATLAB Function Reference |
You can set and query graphics object properties in two ways:
inspect
function at the command line.
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 uibuttongroup background |
BorderType |
Type of border around the uibuttongroup area. |
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 uibuttongroup |
Clipping |
Clipping of child axes, uipanels, and uibuttongroups to the uibuttongroup. Does not affect child uicontrols. |
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 |
HitTest |
Selectable by mouse click |
Interruptible |
Callback routine interruption mode |
Parent |
uibuttongroup object's parent |
Position |
Uibuttongroup position relative to parent figure, uipanel, or uibuttongroup |
ResizeFcn |
User-specified resize routine |
Selected |
Whether object is selected |
SelectedObject |
Currently selected uicontrol of style radiobutton or togglebutton |
SelectionChangeFcn |
Callback routine executed when the selected radio button or toggle button changes. |
SelectionHighlight |
Object highlighted when selected |
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 |
UIContextMenu |
Associates uicontext menu with the uibuttongroup |
Units |
Units used to interpret the position vector |
UserData |
User-specified data |
Visible |
Uibuttongroup visibility. Note: Controls the Visible property of child axes, uipanels, and uibuttongroups. Does not affect child uicontrols. |
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.
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 routine interruption. If a callback is executing and the user triggers an event (such as a mouse click) on an object for which a callback is defined, the callback associated with the new event uses the value of BusyAction
to decide whether or not to attempt to interrupt the executing callback.
cancel
, the event is discarded and the second callback does not execute.
queue
, and the Interruptible
property of the first callback is on
, the second callback is added to the event queue and executes in its turn after the first callback finishes execution.
Note
If the interrupting callback is a DeleteFcn or 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. See the Interruptible property for information about controlling a callback's interruptibility.
|
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 an M-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 is displayed 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
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
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.
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.
HandleVisibility
is on
.
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.
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.
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.
HitTest
{on} | off
Selectable by mouse click. HitTest
determines if the figure can become the current object (as returned by the gco
command and the figure CurrentObject
property) as a result of a mouse click on the figure. If HitTest
is off
, clicking the figure sets the CurrentObject
to the empty matrix.
Interruptible
{on} | off
Callback routine interruption mode. If a callback is executing and the user triggers an event (such as a mouse click) on an object for which a callback is defined, that callback attempts to interrupt the first callback. MATLAB processes the callbacks according to these factors:
Interruptible
property of the object whose callback is executing
drawnow
, figure
, getframe
, pause
, or waitfor
statements
BusyAction
property of the object whose callback is waiting to execute
If the Interruptible
property of the object whose callback is executing is on
(the default), the callback can be interrupted. Whenever the callback calls one of the drawnow
, figure
, getframe
, pause
, or waitfor
functions, the function processes any events in the event queue, including the waiting callback, before performing its defined task.
If the Interruptible
property of the object whose callback is executing is off
, the callback cannot be interrupted (except by certain callbacks; see the note below). The BusyAction
property of the object whose callback is waiting to execute determines what happens to the waiting callback.
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
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.
See Function Handle Callbacks for information on how to use function handles to define the callback function.
See Resize Behavior for information on creating resize functions using GUIDE.
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
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 is the handle of the uibuttongroup. The second argument is an event data structure that contains the fields shown in the following table.
Include code for uicontrol radio buttons and toggle buttons that are managed by a uibuttongroup in the SelectionChangeFcn
callback function, not in the individual uicontrol Callback
functions. uibuttongroup
overwrites the Callback properties of radio buttons and toggle buttons that it manages.
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'
.
Title
string
Title string. The text displayed in the button group title. You can position the title using the TitlePosition
property.
If the string value is specified as a cell array of strings or padded string matrix, only the first string of a cell array or of a padded string matrix is displayed; the rest are ignored. 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 Setting Default Values. To set Title
to one of these words, you must precede the word with the backslash character. For example,
TitlePosition
{lefttop} | centertop | righttop |
leftbottom | centerbottom | rightbottom
Location ofthe title. This property determines the location of the title string, in relation to the uibuttongroup.
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. All units are measured from the lower-left corner of the figure window.
Normalized
units map the lower-left corner of the figure window to (0,0) and the upper-right corner to (1.0,1.0).
pixels
, 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, but still exists and you can query and set its properties.
uibuttongroup | uicontextmenu |
© 1994-2005 The MathWorks, Inc.