MATLAB Function Reference Previous page   Next Page
Uipanel Properties

Modifying Properties

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

You can set default uipanel properties by typing:

Where h can be the root handle (0), a figure handle, or a uipanel handle. PropertyName is the name of the uipanel property and PropertyValue is the value you specify as the default for that property.

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

Uipanel Properties

This section lists all properties useful to uipanel objects along with valid values and a descriptions of their use. Curly braces { } enclose default values.

Property Name
Description
BackgroundColor
Color of the uipanel background
BorderType
Type of border around the uipanel area.
BorderWidth
Width of the panel border.
BusyAction
Interruption of other callback routines
ButtonDownFcn
Button-press callback routine
Children
All children of the uipanel
Clipping
Clipping of child axes, uipanels, and uibuttongroups to the uipanel. 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/or color of 2-D border line
HandleVisibility
Handle accessibility from commandline and GUIs
HighlightColor
3-D frame highlight color
HitTest
Selectable by mouse click
Interruptible
Callback routine interruption mode
Parent
Uipanel object's parent
Position
Panel position relative to parent figure or uipanel
ResizeFcn
User-specified resize routine
Selected
Whether object is selected
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 panel
UIContextMenu
Associates uicontext menu with the uipanel
Units
Units used to interpret the position vector
UserData
User-specified data
Visible
Uipanel visibility.
Note: Controls the Visible property of child axes, uibuttongroups. and uipanels. Does not affect child uicontrols.

BackgroundColor              ColorSpec

Color of the uipanel 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 uipanel area. Used to define the panel 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 panel border. The width of the panel 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.

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 uipanel. This is useful for implementing actions to interactively modify control 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 uipanel. A vector containing the handles of all children of the uipanel. A uipanel object's children are axes, uipanels, uibuttongroups, and uicontrols. You can use this property to reorder the children.

Clipping                     {on} | off

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

CreateFcn                    string or function handle

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

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

You can define a default CreateFcn callback for all new uipanels. This default applies unless you override it by specifying a different CreateFcn callback when you call uipanel. For example, the code

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

To override this default and create a panel whose FontName and FontSize properties are set to different values, call uipanel 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 uipanel object (e.g., when you issue a delete command or clear the figure containing the uipanel). 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 uipanel. When you resize the uipanel, 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.

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:

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

Parent                       handle

Uipanel parent. The handle of the uipanel's parent figure, uipanel, or uibuttongroup. You can move a uipanel 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 uipanel relative to parent. The rectangle defined by this property specifies the size and location of the panel 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 uipanel object. width and height are the dimensions of the uipanel 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 uipanel and the figure Resize property is set to on, or in GUIDE, the Resize behavior option is set to Other. You can query the uipanel 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 panel 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.

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. 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 panel 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 uipanel 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 uipanel.

UIContextMenu                handle

Associate a context menu with a uipanel. Assign this property the handle of a Uicontextmenu object. MATLAB displays the context menu whenever you right-click the uipanel. 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.

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 uipanel object. MATLAB does not use this data, but you can access it using set and get.

Visible                      {on} | off

Uipanel visibility. By default, a uipanel object is visible. When set to off, the uipanel is not visible, but still exists and you can query and set its properties.


Previous page  uipanel uipushtool Next page

© 1994-2005 The MathWorks, Inc.