uicontrol

Create user interface control object

Syntax

c = uicontrol
c = uicontrol(Name,Value,...)
c = uicontrol(parent)
c = uicontrol(parent,Name,Value,...)
uicontrol(c)

Description

c = uicontrol creates a uicontrol (push button) in the current figure and returns the uicontrol object, c. If there is no figure available, then MATLAB® creates a new figure to serve as the parent.

c = uicontrol(Name,Value,...) creates a uicontrol and specifies one or more uicontrol property names and corresponding values. Use this syntax to override the default uicontrol properties. The default uicontrol style is 'pushbutton'.

c = uicontrol(parent) creates a uicontrol and designates a specific parent object. The parent argument can be a figure, uipanel, uibuttongroup, or uitab object.

c = uicontrol(parent,Name,Value,...) creates a uicontrol with a specific parent and one or more uicontrol properties.

uicontrol(c) gives focus to a specific uicontrol object, c.

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) 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. If you assign the Callback property of a static text object to a function (or a string of commands), the static text will not respond when users try to interact with the text. However, you can code the ButtonDownFcn callback to respond to mouse clicks on the static text. See Tips for more information.

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

Examples

This code creates a GUI that displays a surface plot with three uicontrols that affect the characteristics of the plot. Copy and paste this code into the Editor and run it to see how it works.

 function mygui
    % Create a figure and axes
    f = figure('Visible','off');
    ax = axes('Units','pixels');
    surf(peaks)
    
    % Create pop-up menu
    popup = uicontrol('Style', 'popup',...
           'String', {'parula','jet','hsv','hot','cool','gray'},...
           'Position', [20 340 100 50],...
           'Callback', @setmap);    
    
   % Create push button
    btn = uicontrol('Style', 'pushbutton', 'String', 'Clear',...
        'Position', [20 20 50 20],...
        'Callback', 'cla');       

   % Create slider
    sld = uicontrol('Style', 'slider',...
        'Min',1,'Max',50,'Value',41,...
        'Position', [400 20 120 20],...
        'Callback', @surfzlim); 
					
    % Add a text uicontrol to label the slider.
    txt = uicontrol('Style','text',...
        'Position',[400 45 120 20],...
        'String','Vertical Exaggeration');
    
    % Make figure visble after adding all components
    f.Visible = 'on';
    
    function setmap(source,callbackdata)
        val = source.Value;
        maps = source.String;
        newmap = maps{val};
        colormap(newmap);
    end

    function surfzlim(source,callbackdata)
       val = 51 - source.Value;
       zlim(ax,[-val val]);
    end
end

The code creates a figure and an axes containing the surface plot. The figure also contains four uicontrols:

  • popup — A uicontrol (pop-up menu) that lists the different color maps the user can select. The Callback property of this object is the function handle, @setmap. When the user selects an item in the pop-up menu, MATLAB calls the setmap function to reset the colormap.

  • btn — A uicontrol (push button) that clears the axes when the user clicks it. The Callback property of this object is the command, cla, which clears the current axes.

  • sld — A uicontrol (slider) that changes the vertical scaling of the surface plot. The Callback property of this object is the function handle, @surfzlim. When the user moves the slider, MATLAB calls the surfzlim function to adjust the vertical scaling of the plot.

  • txt — A uicontrol (static text) that is a label for the slider.

More About

expand all

Tips

  • To make static text respond to mouse clicks, set the text object's Enable property to 'Inactive'. Then, define a ButtonDownFcn callback that responds when the user clicks on the text. For example, the following code displays 'Text was clicked' in the Command Window when the user clicks on the text in the GUI.

    mytxt = uicontrol('Style','text','String','Click Me!');
    mytxt.Enable = 'Inactive';
    mytxt.ButtonDownFcn = 'disp(''Text was clicked'')';
Was this topic helpful?