Quantcast

Documentation Center

  • Trial Software
  • Product Updates

uicontrol

Create user interface control object

Syntax

handle = uicontrol('Name',Value,...)
handle = uicontrol(parent,'Name',Value,...)
handle = uicontrol
uicontrol(uich)

Description

handle = uicontrol('Name',Value,...) creates a uicontrol and assigns the specified properties and values to it. It assigns the default values to any properties you do not specify. The default uicontrol style is pushbutton. The default parent is the current figure. See the Uicontrol Properties reference page for more information.

handle = uicontrol(parent,'Name',Value,...) creates a uicontrol in the object specified by the handle, parent. If you also specify a different value for the Parent property, the value of the Parent property takes precedence. parent can be the handle of a figure, uipanel, or uibuttongroup.

handle = uicontrol creates a push button in the current figure. The uicontrol function assigns all properties their default values.

uicontrol(uich) gives focus to the uicontrol specified by the handle, uich.

uicontrol creates a uicontrol graphics objects (user interface controls), which you use to implement graphical user interfaces.

Specifying the Uicontrol Style

When selected, most uicontrol objects perform a predefined action. To create a specific type of uicontrol, set the Style property as one of the strings that follow. You can specify a partial string if it is unique among all the styles. For example, instead of 'radiobutton', you can specify 'radio'.

  • 'checkbox' – A check box generates an action when you select it. Use check boxes to provide a number of independent choices. To activate a check box, click the mouse button on the object. The check box updates its appearance when its state changes.

  • 'edit' – Editable text fields enable you to enter or modify text values. Use editable text when you want free text as input. To enable multiple lines of text, set Max-Min>1. Multiline edit boxes provide a vertical scroll bar for scrolling. The arrow keys also provide a way to scroll. Obtain the current text by getting the String property. The String property does not update as you type in an edit box. To execute the callback routine for an edit text control, type in the desired text and then do one of the following:

    • Click another component, the menu bar, or the background of the GUI.

    • For a single line editable text box, press Enter.

    • For a multiline editable text box, press Ctl+Enter.

  • 'frame'

      Note   MathWorks® recommends you use uipanel or uibuttongroup instead of frames.

      GUIDE continues to support frames in those GUIs that contain them, but the frame component does not appear in the GUIDE Layout Editor component palette.

  • 'listbox' – List boxes display a list of items, from which you can select one or more items. Unlike pop-up menus, list boxes do not expand when clicked. The Min and Max properties control the selection mode:

    • To enable multiple selection of items, set Max-Min > 1.

    • To enable selection of only one item at a time, set Max-Min <= 1

    The Value property stores the row indexes of currently selected list box items, and is a vector value when you select multiple items. After any mouse button up event that changes the Value property, MATLAB® evaluates the list box's callback routine. To delay action when multiple items can be selected, you can associate a "Done" push button with the list box. Use the callback for that button to evaluate the list box Value property.

    List boxes with the Enable property set to on differentiate between single and double left clicks. MATLAB sets the figure SelectionType property to normal or open accordingly before evaluating the list box Callback property. For enabled list boxes, Ctrl-left click and Shift-left click also set the figure SelectionType property to normal or open, respectively indicating a single or double click.

  • 'popupmenu' – Pop-up menus (also known as drop-down menus or combo boxes) display a list of choices when you open them with a button-press. When closed, a pop-up menu indicates the current choice. Pop-up menus are useful when you want to provide a number of mutually exclusive choices, but do not want to take up the amount of space that a group of radio buttons requires.

  • 'pushbutton' – Push buttons generate an action when activated. Left-click a push button to activate it. The button appears to depress until you release the mouse button. The callback activates when you release the mouse button while still pointing within the push button.

  • 'radiobutton' – Radio buttons are similar to check boxes, but are intended to be mutually exclusive within a group of related radio buttons. When used this way, you can only select one radio button at any given time). To activate a radio button, click and release the mouse button over it. The easiest way to implement mutually exclusive behavior for a set of radio buttons is to place them within a uibuttongroup.

  • 'slider' – Sliders accept numeric input within a specific range when you move the "thumb" button along a bar. The location of the thumb indicates a numeric value, assigned to the Value property when you release the mouse button. You can set the minimum, maximum, and current values, and step sizes of a slider.

    Move the thumb by doing any one of the following:

    • Press the mouse button on the thumb, and drag it along the bar.

    • Click in the bar or on arrow buttons located at both ends of the bar.

    • Click the keyboard arrow keys when the slider is in focus.

  • 'text' – Static text boxes display lines of text. You typically use static text to label other controls, provide information to the user, or indicate values associated with a slider. Users cannot change static text interactively. Static text controls do not activate callback routines when clicked.

  • 'togglebutton' – Toggle buttons are similar in appearance to push buttons, but they visually indicate their state, either on (pressed down) or off (up). Clicking a toggle button changes its state, and switches its Value property between Min and Max.

Examples

Create a figure and an axes to contain a 3-D surface plot.

    figure
    hax = axes('Units','pixels');
    surf(peaks)

Place a uicontrol object to let users change the colormap with a pop-up menu. Supply a function handle as the object's Callback property.

uicontrol('Style', 'popup',...
           'String', 'jet|hsv|hot|cool|gray',...
           'Position', [20 340 100 50],...
           'Callback', @setmap);   
            % The popup function handle callback
            % is implemented as a local function

Add a different uicontrol. Create a push button that clears the current axes when pressed. Position the button inside the axes at the lower left. All uicontrols have default units of pixels. In this example, the axes has units of pixels, as well.

uicontrol('Style', 'pushbutton', 'String', 'Clear',...
        'Position', [20 20 50 20],...
        'Callback', 'cla');        
% The pushbutton string callback
% calls a MATLAB function

Add a slider uicontrol to control the vertical scaling of the surface object. Position it at the bottom right corner of the figure. Then add a text uicontrol as a label for the slider.

uicontrol('Style', 'slider',...
        'Min',1,'Max',50,'Value',41,...
        'Position', [400 20 120 20],...
        'Callback', {@surfzlim,hax});   
% Uses cell array function handle callback
% Implemented as a local function with an argument

uicontrol('Style','text',...
        'Position',[400 45 120 20],...
        'String','Vertical Exaggeration')

To operate the controls, you need callback functions. The callback for the pop-up menu is a local function called setmap that contains the following code.

    function setmap(hObj,event) %#ok<INUSD>
        % Called when user activates popup menu 
        val = get(hObj,'Value');
        if val ==1
            colormap(jet)
        elseif val == 2
            colormap(hsv)
        elseif val == 3
            colormap(hot)
        elseif val == 4
            colormap(cool)
        elseif val == 5
            colormap(gray)
        end
    end

The callback for the slider is also a local function in the same file, and contains the following code.

function surfzlim(hObj,event,ax) %#ok<INUSL>
    % Called to set zlim of surface in figure axes
    % when user moves the slider control
    val = 51 - get(hObj,'Value');
    zlim(ax,[-val val]);
end

To use the uicontrols in the example, you need to put all the functions in a MATLAB code file. Copy the following code and paste it into a new file. Save the file as ex_uicontrol.m on your search path, and then run it.

function ex_uicontrol
    % Example code for uicontrol reference page

    % Create a figure and an axes to 
    % contain a 3-D surface plot.
    figure
    hax = axes('Units','pixels');
    surf(peaks)
    % Create a uicontrol object to let users 
    % change the colormap with a pop-up menu. 
    % Supply a function handle as the object's 
    % Callback:
    uicontrol('Style', 'popup',...
           'String', 'hsv|hot|cool|gray',...
           'Position', [20 340 100 50],...
           'Callback', @setmap);    
    
    % Add a different uicontrol. Create a push button 
    % that clears the current axes when pressed. 
    % Position the button insidethe axes at the lower 
    % left. All uicontrols have default units of pixels. 
    % In this example, the axes does as well.
    uicontrol('Style', 'pushbutton', 'String', 'Clear',...
        'Position', [20 20 50 20],...
        'Callback', 'cla');       

    % Add a slider uicontrol to control the vertical 
    % scaling of the surface object. Position it 
    % under the Clear button.
    uicontrol('Style', 'slider',...
        'Min',1,'Max',50,'Value',41,...
        'Position', [400 20 120 20],...
        'Callback', {@surfzlim,hax}); 
					% Slider function handle callback
          % Implemented as a local function
   
    % Add a text uicontrol to label the slider.
    uicontrol('Style','text',...
        'Position',[400 45 120 20],...
        'String','Vertical Exaggeration')
end


function setmap(hObj,event) %#ok<INUSD>
    % Called when user activates popup menu 
    val = get(hObj,'Value');
    if val ==1
        colormap(jet)
    elseif val == 2
        colormap(hsv)
    elseif val == 3
        colormap(hot)
    elseif val == 4
        colormap(cool)
    elseif val == 5
        colormap(gray)
    end
end

function surfzlim(hObj,event,ax) %#ok<INUSL>
    % Called to set zlim of surface in figure axes
    % when user moves the slider control 
    val = 51 - get(hObj,'Value');
    zlim(ax,[-val val]);
end

More About

expand all

Tips

  • To simulate activation on static text by a mouse click, set the text object's Enable property to Inactive, and set its ButtonDownFcn callback to perform an action. For example, the following code displays ‘Text was clicked' in the Command Window when you click on the Click Me! text in the running GUI. (Without the set command, it would do nothing.)

    h = uicontrol('Style','text','String','Click Me!');
    set(h,'Enable','Inactive','ButtonDownFcn',...
       'disp(''Text was clicked'')') 
  • Adding a uicontrol to a figure removes the figure toolbar when the figure Toolbar property is 'auto' (which is the default). To prevent this from happening, set the Toolbar property to 'figure'. You can restore the toolbar by selecting Figure Toolbar from the View menu regardless of this property setting.

  • 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 use the set and get functions to set and query property values after creating the control.

  • A uicontrol object is a child of a figure, uipanel, or uibuttongroup. Therefore, the uicontrol object does not require an axes to exist when placed in a figure window, uipanel, or uibuttongroup.

  • When you pause MATLAB and a uicontrol has focus, pressing a keyboard key does not cause MATLAB to resume. Click anywhere outside a uicontrol and then press any key. For more information, see the pause function.

See Also

| | | | | |

Was this topic helpful?