MATLAB Function Reference | Search  Help Desk |
uicontrol | Examples See Also |
Create user interface control object
handle = uicontrol(parent) handle = uicontrol(...,'PropertyName',PropertyValue,...)
uicontrol
creates Uicontrol graphics objects (user interface controls). You implement graphical user interfaces using Uicontrols. When selected, most Uicontrol objects perform a predefined action. MATLAB supports numerous styles of Uicontrols, each suited for a different purpose:
get(edit_handle,'String')does not return the current contents of the edit box on Microsoft Windows and Macintosh systems because MATLAB must execute the callback routine to update the
String
property (even though the text string has changed on the screen). This behavior is consistent with the respective platform conventions.
Frames are boxes that visually enclose regions of a figure window. Frames can make a user interface easier to understand by visually grouping related controls. Frames have no callback routines associated with them. Only Uicontrols can appear within frames.
Frames are opaque, not transparent, so the order you define Uicontrols is important in determining whether Uicontrols within a frame are covered by the frame or are visible. Stacking order determines the order objects are drawn: objects defined first are drawn first; objects defined later are drawn over existing objects. If you use frames to enclose objects, you must define the frames before you define the objects.
List boxes display a list of items and enable users to select one or more items. The Min
and Max
properties control the selection mode. The Value
property indicates selected entries and contains the indices into the list of strings; a vector value indicates multiple selections. MATLAB evaluates the list box's callback routine after any mouse button up event that changes the Value
property. Therefore, you may need to add a "Done" button to delay action caused by multiple clicks on list items. List boxes differentiate between single and double clicks and set the Figure SelectionType
property to normal
or open
accordingly before evaluating the list box's Callback
property.
Pop-up menus open when pressed to display a list of choices. When not activated, they display a single button with text indicating the current setting. Pop-up menus are useful when you want to provide users with a number of mutually exclusive choices, but do not want to take up the amount of space that a series of radio buttons requires. You must specify a value for the String
property.
Push buttons generate an action with each press, but do not remain in a pressed state. To activate a push button, click the mouse button on the object. Push buttons are useful when the action you want to perform is not related to any other action executable by the user interface (for example, an "OK" button).
Radio buttons are similar to check boxes, but are intended to be mutually exclusive within a group of related radio buttons (i.e., only one is in a pressed state at any given time). To activate a radio button, click the mouse button on the object. The state of the device is indicated on the display. Note that your code can implement the mutually exclusive behavior of radio buttons.
Sliders accept numeric input within a specific range by enabling the user to move a sliding bar. Users move the bar by pressing the mouse button and dragging the pointer over the bar, or by clicking in the trough or on an arrow. The location of the bar indicates a numeric value, which is selected by releasing the mouse button. You can set the minimum, maximum, and current values of the slider.
Static text boxes display lines of text. Static text is typically used to label other controls, provide directions to the user, or indicate values associated with a slider. Users cannot change static text interactively and there is no way to invoke the callback routine associated with it.
Toggle buttons are controls that execute callbacks when clicked on and indicate their state, either on or off. Toggle buttons are useful for building toolbars. More information about toggle buttons.
The uicontrol
function accepts property name/property value pairs, structures, and cell arrays as input arguments and optionally returns the handle of the created object. You can also set and query property values after creating the object using the set
and get
functions.
Uicontrol objects are children of Figures and therefore do not require an Axes to exist when placed in a Figure window.
This table lists all uicontrol
properties, grouping them by function. Each property name acts as a link to a description of the property.Property Name |
Property Description |
Property Value |
Controlling Style and Appearance | ||
BackgroundColor |
Object background color |
Value: ColorSpec Default: [0.8 0.8 0.8] |
CData |
Truecolor image displayed on the control |
Value: matrix |
Clipping |
This property has no effect on Uicontrol objects |
|
ForegroundColor |
Color of text |
Value: ColorSpec Default: [0 0 0] |
SelectionHighlight |
Object highlighted when selected |
Value: on , off Default: on |
String |
Uicontrol label |
Value: string |
Visible |
Uicontrol visibility |
Value: on , off Default: on |
General Information About the Object | ||
Children |
Uicontrol objects have no children |
|
Enable |
Enable or disable the Uicontrol |
Value: on , inactive , off Default: on |
Parent |
Uicontrol object's parent |
Value: scalar Figure handle |
Selected |
Whether object is selected |
Value: on , off Default: off |
SliderStep |
Slider step size |
Value: two-element vector Default: [0.01 0.1] |
Style |
Type of Uicontrol object |
Value: pushbutton , togglebutton , radiobutton , checkbox , edit , text , slider , frame , listbox , popupmenu Default: pushbutton |
Tag |
User-specified object identifier |
Value: string |
TooltipString |
Content of object's tooltip |
Value: string |
Type |
Class of graphics object |
Value: string (read-only) Default: uicontrol |
UserData |
User-specified data |
Value: matrix |
Controlling the Object Position | ||
Position |
Size and location of Uicontrol object |
Value: position rectangle Default: [20 20 60 20] |
Units |
Units to interpret position vector |
Value: pixels , normalized , inches , centimeters , points , characters Default: pixels |
Controlling Fonts and Labels | ||
FontAngle |
Character slant |
Value: normal , italic , oblique Default: normal |
FontName |
Font family |
Value: string Default: system dependent |
FontSize |
Font size |
Value: size in FontUnits Default: system dependent |
FontUnits |
Font size units |
Value: points , normalized , inches , centimeters , pixels Default: points |
FontWeight |
Weight of text characters |
Value: light , normal , demi , bold Default: normal |
HorizontalAlignment |
Alignment of label string |
Value: left , center , right Default: depends on Uicontrol object |
String |
Uicontrol object label |
Value: string |
Controlling Callback Routine Execution | ||
BusyAction |
Callback routine interruption |
Value: cancel , queue Default: queue |
ButtonDownFcn |
Button press callback routine |
Value: string |
Callback |
Control action |
Value: string |
CreateFcn |
Callback routine executed during object creation |
Value: string |
DeleteFcn |
Callback routine executed during object deletion |
Value: string |
Interruptible |
Callback routine interruption mode |
Value: on , off Default: on |
UIContextMenu |
Uicontextmenu object associated with the Uicontrol |
Value: handle |
Information About the Current State | ||
ListboxTop |
Index of top-most string displayed in list box |
Value: scalar Default: [1] |
Max |
Maximum value (depends on Uicontrol object) |
Value: scalar Default: object dependent |
Min |
Minimum value (depends on Uicontrol object) |
Value: scalar Default: object dependent |
Value |
Current value of Uicontrol object |
Value: scalar or vector Default: object dependent |
Controlling Access to Objects | ||
HandleVisibility |
Whether handle is accessible from command line and GUIs |
Value: on, callback, off Default: on |
HitTest |
Whether selectable by mouse click |
Value: on, off Default: on |
h = uicontrol('Style', 'pushbutton', 'String', 'Clear',... 'Position', [20 150 100 70], 'Callback', 'cla');You can create a Uicontrol object that changes Figure colormaps by specifying a pop-up menu and supplying an M-file name as the object's
Callback
:
hpop = uicontrol('Style', 'popup',... 'String', 'hsv|hot|cool|gray',... 'Position', [20 320 100 50],... 'Callback', 'setmap');The above call to
uicontro
l defines four individual choices in the menu: hsv
, hot
, cool
, and gray
. You specify these choices with the String
property, separating the choices with the "|" character.
The Callback
, in this case setmap
, is the name of an M-file that defines a more complicated set of instructions than a single MATLAB command. setmap contains these statements:
val = get(hpop,'Value'); if val == 1 colormap(hsv) elseif val == 2 colormap(hot) elseif val == 3 colormap(cool) elseif val == 4 colormap(gray) endThe
Value
property contains a number that indicates the selected choice. The choices are numbered sequentially from one to four. The setmap
M-file can get and then test the contents of the Value
property to determine what action to take.
textwrap
, uimenu