Quantcast

Documentation Center

  • Trial Software
  • Product Updates

Add Components to a Programmatic GUI

Add User Interface Controls to a Programmatic GUI

Use the uicontrol function to create user interface controls. These include push buttons, toggle buttons, sliders, radio buttons, edit text controls, static text controls, pop-up menus, check boxes, and list boxes.

A syntax for the uicontrol function is

uich = uicontrol(parent,'PropertyName',PropertyValue,...)

where uich is the handle of the resulting user interface control. If you do not specify parent, the component parent is the current figure as specified by the root CurrentFigure property. See the uicontrol reference page for other valid syntaxes.

Subsequent topics describe commonly used properties of user interface controls and offer a simple example for each kind of control:

Commonly Used Properties

The most commonly used properties needed to describe a user interface control are shown in the following table:

Property

Values

Description

Max

Scalar. Default is 1.

Maximum value. Interpretation depends on the Style property.

Min

Scalar. Default is 0.

Minimum value. Interpretation depends on the Style property.

Position

4-element vector: [distance from left, distance from bottom, width, height]. Default is [20, 20, 60, 20].

Size of the component and its location relative to its parent.

String

String. Can be a cell array or character array or strings.

Component label. For list boxes and pop-up menus it is a list of the items. To display the & character in a label, use two & characters in the string. The words remove, default, and factory (case sensitive) are reserved. To use one of these as a label, prepend a backslash (\) to the string. For example, \remove yields remove.

Style

pushbutton, togglebutton, radiobutton, checkbox, edit, text, slider, listbox, popupmenu. Default is pushbutton.

Type of user interface control object.

TooltipString

String

Text of the tooltip associated with the push tool or toggle tool.

Units

pixels, centimeters, characters, inches, normalized, points, Default is pixels.

Units of measurement used to interpret position vector

Value

Scalar or vector

Value of the component. Interpretation depends on the Style property.

For a complete list of properties and for more information about the properties listed in the table, see Uicontrol Properties documentation.

Check Box

The following statement creates a check box with handle cbh.

cbh = uicontrol(fh,'Style','checkbox',...
                'String','Display file extension',...
                'Value',1,'Position',[30 20 130 20]);

The first argument, fh, specifies the handle of the parent figure. You can also specify the parent as a panel or button group. See Panel and Button Group for more information.

The Style property, checkbox, specifies the user interface control as a check box.

The String property labels the check box as Display file extension. The check box accommodates only a single line of text. If you specify a component width that is too small to accommodate the specified String, MATLAB® software truncates the string with an ellipsis.

The Value property specifies whether the box is checked. Set Value to the value of the Max property (default is 1) to create the component with the box checked. Set Value to Min (default is 0) to leave the box unchecked. Correspondingly, when the user clicks the check box, MATLAB software sets Value to Max when the user checks the box and to Min when the user unchecks it.

The Position property specifies the location and size of the list box. In this example, the list box is 130 pixels wide and 20 high. It is positioned 30 pixels from the left of the figure and 20 pixels from the bottom. The statement assumes the default value of the Units property, which is pixels.

Edit Text

The following statement creates an edit text component with handle eth:

eth = uicontrol(fh,'Style','edit',...
                'String','Enter your name here.',...
                'Position',[30 50 130 20]);

The first argument, fh, specifies the handle of the parent figure. You can also specify the parent as a panel or button group. See Panel and Button Group for more information.

The Style property, edit, specifies the user interface control as an edit text component.

The String property defines the text that appears in the component.

To enable multiple-line input, Max - Min must be greater than 1, as in the following statement. MATLAB software wraps the string if necessary.

eth = uicontrol(fh,'Style','edit',...
                'String','Enter your name and address here.',...
                'Max',2,'Min',0,...
                'Position',[30 20 130 80]);

If Max-Min is less than or equal to 1, the edit text component admits only a single line of input. If you specify a component width that is too small to accommodate the specified string, MATLAB software displays only part of the string. The user can use the arrow keys to move the cursor over the entire string.

The Position property specifies the location and size of the edit text component. In this example, the edit text is 130 pixels wide and 20 high. It is positioned 30 pixels from the left of the figure and 50 pixels from the bottom. The statement assumes the default value of the Units property, which is pixels.

Setting Font Characteristics.  You specify the text font to display in the edit box with the FontName property. On Microsoft® Windows® platforms, the default is MS Sans Serif; on Macintosh and UNIX® platforms, the default is Helvetica. You can use any system font except Symbol and Marlett.

You can chose a text font for the edit box and set all font characteristics at once with output from the uisetfont GUI, which lists and previews available fonts. When you select one of them and click OK, its name and other characteristics are returned in a MATLAB structure, which you can use to set the font characteristic for the edit box. For example, to use the Century Schoolbook font with a normal style and 9 point size, do the following:

font = uisetfont

font = 
      FontName: 'Century Schoolbook'
    FontWeight: 'normal'
     FontAngle: 'normal'
      FontSize: 9
     FontUnits: 'points'

.

    Note:   Not all fonts listed may be available to users of your GUI on their systems.

You can then insert as much of the struct's data as you need into a statement in your code file. For example:

set(eth,'FontName','Century Schoolbook','FontSize',9)

Instead of designating a font yourself, you could provide a push button or context menu in your GUI that allows users to select fonts themselves via the uisetfont GUI. The callback for the feature could be

font = uisetfont;
set(eth, font) 

where eth is the handle for the edit box whose font the user is setting. You can store the handle in the figure's AppData and retrieve it with getappdata.

List Box

The following statement creates a list box with handle lbh:

lbh = uicontrol(fh,'Style','listbox',...
                'String',{'one','two','three','four'},...
                'Value',1,'Position',[30 20 130 80]);

The first argument, fh, specifies the handle of the parent figure. You can also specify the parent as a panel or button group. See Panel and Button Group for more information.

The Style property, listbox, specifies the user interface control as a list box.

The String property defines the list items. You can specify the items in any of the formats shown in the following table.

String Property FormatExample
Cell array of strings{'one' 'two' 'three'}
Padded string matrix['one ';'two ';'three']
String vector separated by vertical slash (|) characters['one|two|three']

If you specify a component width that is too small to accommodate one or more of the specified strings, MATLAB software truncates those strings with an ellipsis.

The Value property specifies the item or items that are selected when the component is created. To select a single item, set Value to a scalar that indicates the index of the selected list item, where 1 corresponds to the first item in the list.

To select more than one item, set Value to a vector of indices of the selected items. To enable selection of more than one item, Max - Min must be greater than 1, as in the following statement:

lbh = uicontrol(fh,'Style','listbox',...
                'String',{'one','two','three','four'},...
                'Max',2,'Min',0,'Value',[1 3],...
                'Position',[30 20 130 80]);

If you want no initial selection:

  1. Set the Max and Min properties to enable multiple selection

  2. Set the Value property to an empty matrix [].

If the list box is not large enough to display all list entries, you can set the ListBoxTop property to the index of the item you want to appear at the top when the component is created.

The Position property specifies the location and size of the list box. In this example, the list box is 130 pixels wide and 80 high. It is positioned 30 pixels from the left of the figure and 20 pixels from the bottom. The statement assumes the default value of the Units property, which is pixels.

The list box does not provide for a label. Use a static text component to label the list box.

Pop-Up Menu

The following statement creates a pop-up menu (also known as a drop-down menu or combo box) with handle pmh:

pmh = uicontrol(fh,'Style','popupmenu',...
                'String',{'one','two','three','four'},...
                'Value',1,'Position',[30 80 130 20]);

The first argument, fh, specifies the handle of the parent figure. You can also specify the parent as a panel or button group. See Panel and Button Group for more information.

The Style property, popupmenu, specifies the user interface control as a pop-up menu.

The String property defines the menu items. You can specify the items in any of the formats shown in the following table.

String Property FormatExample
Cell array of strings{'one' 'two' 'three'}
Padded string matrix['one ';'two ';'three']
String vector separated by vertical slash (|) characters['one|two|three']

If you specify a component width that is too small to accommodate one or more of the specified strings, MATLAB software truncates those strings with an ellipsis.

The Value property specifies the index of the item that is selected when the component is created. Set Value to a scalar that indicates the index of the selected menu item, where 1 corresponds to the first item in the list. In the statement, if Value is 2, the menu looks like this when it is created:

The Position property specifies the location and size of the pop-up menu. In this example, the pop-up menu is 130 pixels wide. It is positioned 30 pixels from the left of the figure and 80 pixels from the bottom. The height of a pop-up menu is determined by the font size; the height you set in the position vector is ignored. The statement assumes the default value of the Units property, which is pixels.

The pop up menu does not provide for a label. Use a static text component to label the pop-up menu.

Table

The following code creates a table with handle th. It populates it with the matrix magic(5), and then adjusts its size by setting the width and height of its Position property to that of its Extent property:

th      = uitable(fh,'Data',magic(5));
tpos= get(th,'Position')

tpos =
    20    20   300   300

texn= get(th,'Extent')

texn =
     0     0   407   100

tpos(3) = texn(3);
tpos(4) = texn(4);
set(th, 'Position', tpos)

By default, the size of a uitable is 300-by-300 pixels, and pixels is the default Units for uitable Position and Extent. The table's Extent is calculated to include its scrollbars, which obscure the last row and column of data when setting the table's Position as above.

Table cells can be edited by users if the ColumnEditable property enables it. The CellEditCallback fires whenever a table cell is edited. By default, cells are not editable.

A uitable has no Style property, but you can change its appearance in several ways by setting

  • Foreground and background colors.

  • Row striping.

  • Row labels/numbers.

  • Column labels/numbers.

  • Column formats and widths.

  • Font characteristics.

Also, uitables have six callback functions that you can program.

You can set most uitable properties using the Table Property Editor that you open from the Property Inspector instead of using the set command. This GUI lets you set properties for table rows, columns, colors, and data.

See uitable and uitable properties for complete documentation. For an example of a GUI containing a uitable, see Synchronized Data Presentations in a Programmatic GUI.

Push Button

The following statement creates a push button with handle pbh:

pbh = uicontrol(fh,'Style','pushbutton','String','Button 1',...
                'Position',[50 20 60 40]);

The first argument, fh, specifies the handle of the parent figure. You can also specify the parent as a panel or button group. See Panel and Button Group for more information.

The Style property, pushbutton, specifies the user interface control as a push button. Because pushbutton is the default style, you can omit the 'Style' property from the statement.

The String property labels the push button as Button 1. The push button allows only a single line of text. If you specify more than one line, only the first line is shown. If you specify a component width that is too small to accommodate the specified String, MATLAB software truncates the string with an ellipsis.

The Position property specifies the location and size of the push button. In this example, the push button is 60 pixels wide and 40 high. It is positioned 50 pixels from the left of the figure and 20 pixels from the bottom. This statement assumes the default value of the Units property, which is pixels.

Add an Image to a Push Button.  To add an image to a push button, assign the button's CData property an m-by-n-by-3 array of RGB values that defines a truecolor image. For example, the array img defines 16-by-64 truecolor image using random values between 0 and 1 (generated by rand).

img(:,:,1) = rand(16,64);
img(:,:,2) = rand(16,64);
img(:,:,3) = rand(16,64);
pbh = uicontrol(fh,'Style','pushbutton',...
                'Position',[50 20 100 45],...
                'CData',img);

    Note   See ind2rgb for information on converting a matrix X and corresponding colormap, i.e., an (X, MAP) image, to RGB (truecolor) format.

Radio Button

The following statement creates a radio button with handle rbh:

rbh = uicontrol(fh,'Style','radiobutton',...
                'String','Indent nested functions.',...
                'Value',1,'Position',[30 20 150 20]);

The first argument, fh, specifies the handle of the parent figure. You can also specify the parent as a panel or button group. Use a button group to manage exclusive selection of radio buttons and toggle buttons. See Panel and Button Group for more information.

The Style property, radiobutton, specifies the user interface control as a radio button.

The String property labels the radio button as Indent nested functions. The radio button allows only a single line of text. If you specify more than one line, only the first line is shown. If you specify a component width that is too small to accommodate the specified String, MATLAB software truncates the string with an ellipsis.

The Value property specifies whether the radio button is selected when the component is created. Set Value to the value of the Max property (default is 1) to create the component with the radio button selected. Set Value to Min (default is 0) to leave the radio button unselected.

The Position property specifies the location and size of the radio button. In this example, the radio button is 150 pixels wide and 20 high. It is positioned 30 pixels from the left of the figure and 20 pixels from the bottom. The statement assumes the default value of the Units property, which is pixels.

Slider

The following statement creates a slider with handle sh:

sh = uicontrol(fh,'Style','slider',...
                'Max',100,'Min',0,'Value',25,...
                'SliderStep',[0.05 0.2],...
                'Position',[30 20 150 30]);

  • The first argument, fh, specifies the handle of the parent figure. You can also specify the parent as a panel or button group. See Panel and Button Group for more information.

  • The Style property, slider, specifies the user interface control as a slider.

  • Specify the range of the slider by setting its Min property to the minimum value of the slider and its Max property to the maximum value. The Min property must be less than Max.

  • Specify the value indicated by the slider when it is created by setting the Value property to the appropriate number. This number must be less than or equal to Max and greater than or equal to Min. If you specify Value outside the specified range, the slider is not displayed.

  • The slider Value changes by a small amount when a user clicks the arrow button, and changes by a larger amount when the user clicks the trough (also called the channel). Control how the slider responds to these actions by setting the SliderStep property. Specify SliderStep as a two-element vector, [minor_step major_step], where minor_step is less than or equal to major_step. Because specifying very small values can cause unpredictable slider behavior, make both minor_step and major_step greater than 1e-6. Set major_step to the proportion of the range that clicking the trough moves the slider thumb. Setting it to 1 or higher causes the thumb to move to Max or Min when the trough is clicked.

    As major_step increases, the thumb grows longer. When major_step is 1, the thumb is half as long as the trough. When major_step is greater than 1, the thumb continues to grow, slowly approaching the full length of the trough. When a slider serves as a scroll bar, you can uses this behavior to indicate how much of the document is currently visible by changing the value of major_step.

  • If you want to set the location or size of the component to an exact value, then modify its Position property.

The example provides a 5 percent minor step and a 20 percent major step. The default major_step and minor_step, [0.01 0.10], provides a 1 percent minor step and a 10 percent major step.

The Position property specifies the location and size of the slider. In this example, the slider is 150 pixels wide and 30 high. It is positioned 30 pixels from the left of the figure and 20 pixels from the bottom. The statement assumes the default value of the Units property, which is pixels.

    Note:   On Mac platforms, the height of a horizontal slider is constrained. If the height you set in the position vector exceeds this constraint, the displayed height of the slider is the maximum allowed. The height element of the position vector is not changed.

The slider component provides no text description or data entry capability. Use a Static Text component to label the slider. Use an Edit Text component to enable a user to input a value to apply to the slider.

Static Text

The following statement creates a static text component with handle sth:

sth = uicontrol(fh,'Style','text',...
                'String','Select a data set.',...
                'Position',[30 50 130 20]);

The first argument, fh, specifies the handle of the parent figure. You can also specify the parent as a panel or button group. See Panel and Button Group for more information.

The Style property, text, specifies the user interface control as a static text component.

The String property defines the text that appears in the component. If you specify a component width that is too small to accommodate the specified String, MATLAB software wraps the string.

The Position property specifies the location and size of the static text component. In this example, the static text is 130 pixels wide and 20 high. It is positioned 30 pixels from the left of the figure and 50 pixels from the bottom. The statement assumes the default value of the Units property, which is pixels.

Toggle Button

The following statement creates a toggle button with handle tbh:

tbh = uicontrol(fh,'Style','togglebutton',...
                'String','Left/Right Tile',...
                'Value',0,'Position',[30 20 100 30]);

The first argument, fh, specifies the handle of the parent figure. You can also specify the parent as a panel or button group. Use a button group to manage exclusive selection of radio buttons and toggle buttons. See Panel and Button Group for more information.

The Style property, togglebutton, specifies the user interface control as a toggle button.

The String property labels the toggle button as Left/Right Tile. The toggle button allows only a single line of text. If you specify more than one line, only the first line is shown. If you specify a component width that is too small to accommodate the specified String, MATLAB software truncates the string with an ellipsis.

The Value property specifies whether the toggle button is selected when the component is created. Set Value to the value of the Max property (default is 1) to create the component with the toggle button selected (depressed). Set Value to Min (default is 0) to leave the toggle button unselected (raised). The following figure shows the toggle button in the depressed position.

The Position property specifies the location and size of the toggle button. In this example, the toggle button is 100 pixels wide and 30 high. It is positioned 30 pixels from the left of the figure and 20 pixels from the bottom. The statement assumes the default value of the Units property, which is pixels.

Add Panels and Button Groups

Panels and button groups are containers that arrange GUI components into groups. If you move the panel or button group, its children move with it and maintain their positions relative to the panel or button group.

Use the uipanel and uibuttongroup functions to create these components.

A syntax for panels is

ph = uipanel(fh,'PropertyName',PropertyValue,...)

where ph is the handle of the resulting panel. The first argument, fh, specifies the handle of the parent figure. You can also specify the parent as a panel or button group. See the uipanel reference page for other valid syntaxes.

A syntax for button groups is

bgh = uibuttongroup('PropertyName',PropertyValue,...)

where bgh is the handle of the resulting button group. For button groups, you must use the Parent property to specify the component parent. See the uibuttongroup reference page for other valid syntaxes.

For both panels and button groups, if you do not specify a parent, the component parent is the current figure as specified by the root CurrentFigure property.

Subsequent topics describe commonly used properties of panels and button groups and offer a simple example for each component.

Commonly Used Properties

The most commonly used properties needed to describe a panel or button group are shown in the following table:

Property

Values

Description

Parent

Handle

Handle of the component's parent figure, panel, or button group.

Position

4-element vector: [distance from left, distance from bottom, width, height]. Default is [0, 0, 1, 1].

Size of the component and its location relative to its parent.

Title

String

Component label. To display the & character in a label, use two & characters in the string. The words remove, default, and factory (case sensitive) are reserved. To use one of these as a label, prepend a backslash (\) to the string. For example, \remove yields remove.

TitlePosition

lefttop, centertop, righttop, leftbottom, centerbottom, rightbottom. Default is lefttop.

Location of title string in relation to the panel or button group.

Units

normalized, centimeters, characters, inches, pixels, points. Default is normalized.

Units of measurement used to interpret position vector

For a complete list of properties and for more information about the properties listed in the table, see Uipanel Properties and Uibuttongroup Properties documentation. Properties needed to control GUI behavior are discussed in Write Callbacks Using the Programmatic Workflow.

Panel

The following statement creates a panel with handle ph. Use a panel to group components in the GUI.

ph = uipanel('Parent',fh,'Title','My Panel',...
             'Position',[.25 .1 .5 .8]);

The Parent property specifies the handle fh of the parent figure. You can also specify the parent as a panel or button group.

The Title property labels the panel as My Panel.

The statement assumes the default TitlePosition property, which is lefttop.

The Units property is used to interpret the Position property. This panel assumes the default Units property, normalized. This enables the panel to resize automatically if the figure is resized. See documentation for the figure ResizeFcn property for more information about resizing.

The Position property specifies the location and size of the panel. In this example, the panel is 50 percent of the width of the figure and 80 percent of its height. It is positioned 25 percent of the figure width from the left of the figure and 10 percent of the figure height from the bottom. As the figure is resized the panel retains these proportions.

The following statements add two push buttons to the panel with handle ph. The Position property of each component within a panel is interpreted relative to the panel.

pbh1 = uicontrol(ph,'Style','pushbutton','String','Button 1',...
                'Units','normalized',...
                'Position',[.1 .55 .8 .3]);
pbh2 = uicontrol(ph,'Style','pushbutton','String','Button 2',...
                'Units','normalized',...
                'Position',[.1 .15 .8 .3]);

See Push Button for more information about adding push buttons.

Button Group

The following statement creates a button group with handle bgh. Use a button group to exclusively manage radio buttons and toggle buttons.

bgh = uibuttongroup('Parent',fh,'Title','My Button Group',...
            'Position',[.1 .2 .8 .6]);

The Parent property specifies the handle fh of the parent figure. You can also specify the parent as a panel or button group.

The Title property labels the button group as My Button Group.

The statement assumes the default TitlePosition property, which is lefttop.

The Units property is used to interpret the Position property. This button group assumes the default Units property, normalized. This enables the button group to resize automatically if the figure is resized. See documentation for the figure property ResizeFcn for more information about resizing.

The Position property specifies the location and size of the button group. In this example, the button group is 80 percent of the width of the figure and 60 percent of its height. It is positioned 10 percent of the figure width from the left of the figure and 20 percent of the figure height from the bottom. As the figure is resized the button group retains these proportions.

The following statements add two radio buttons to the button group with handle bgh.

rbh1 = uicontrol(bgh,'Style','radiobutton','String','Red',...
                'Units','normalized',...
                'Position',[.1 .6 .3 .2]);
rbh2 = uicontrol(bgh,'Style','radiobutton','String','Blue',...
                'Units','normalized',...
                'Position',[.1 .2 .3 .2]);

By default, the software automatically selects the first radio button added to a button group. You can use the radio button Value property to explicitly specify the initial selection. See Radio Button for information.

Add Axes

Axes enable your GUI to display graphics such as graphs and images using commands such as: plot, surf, line, bar, polar, pie, contour, and mesh.

Use the axes function to create an axes. A syntax for this function is

ah = axes('PropertyName',PropertyValue,...)

where ah is the handle of the resulting axes. You must use the Parent property to specify the axes parent. If you do not specify Parent, the parent is the current figure as specified by the root CurrentFigure property. See the axes reference page for other valid syntaxes.

Subsequent topics describe commonly used properties of axes and offer a simple example.

Commonly Used Properties

The most commonly used properties needed to describe an axes are shown in the following table:

Property

Values

Description

HandleVisibility

on, callback, off. Default is on.

Determines if an object's handle is visible in its parent's list of children. For axes, set HandleVisibility to callback to protect them from command line operations.

NextPlot

add, replace, replacechildren. Default is replace

Specifies whether plotting adds graphics, replaces graphics and resets axes properties to default, or replaces graphics only.

Parent

Handle

Handle of the component's parent figure, panel, or button group.

Position

4-element vector: [distance from left, distance from bottom, width, height].

Size of the component and its location relative to its parent.

Units

normalized, centimeters, characters, inches, pixels, points. Default is normalized.

Units of measurement used to interpret position vector

For a complete list of properties and for more information about the properties listed in the table, see Axes Properties.

See commands such as the following for more information on axes objects: plot, surf, line, bar, polar, pie, contour, imagesc, and mesh.

Axes

The following statement creates an axes with handle ah:

ah = axes('Parent',fh,'Position',[.15 .15 .7 .7]);

The Parent property specifies the handle fh of the parent figure. You can also specify the parent as a panel or button group.

The Units property interprets the Position property. This axes assumes the default Units property, normalized. This enables the axes to resize automatically if the figure is resized. For more information about resizing, see the documentation for or the ResizeFcn property on the Figure Properties reference page.

The Position property specifies the location and size of the axes. In this example, the axes is 70 percent of the width of the figure and 70 percent of its height. It is positioned 15 percent of the figure width from the left of the figure and 15 percent of the figure height from the bottom. As the figure is resized the axes retains these proportions.

The software automatically adds the tick marks. Most functions that draw in the axes update the tick marks appropriately.

Prevent Customized Axes Properties from Being Reset.  Data graphing functions, such as plot, image, scatter, and many others by default reset axes properties before they draw into an axes. This can be a problem in a GUI where you might need to maintain consistency of axes limits, ticks, axis colors, and font characteristics from one plot to another.

The default value of the NextPlot axes property, 'replace' causes this behavior, and can further interfere with a GUI that generates plots by removing all callbacks from the axes whenever a graph is plotted or replotted. For a GUI, the appropriate value is often 'replacechildren'. Consequently, in callbacks that generate graphics, you might need to include code such as

set(ah,'NextPlot','replacechildren')

prior to changing the contents of an axes by drawing a graph; this will plot the graph without resetting existing property values of an axes that the GUI might require, such as its colors, fonts, context menu or ButtonDownFcn.

To see this in the context of a full example, set the NextPlot property of axes1 and axes2 to ReplaceChildrenin the Synchronized Data Presentations in a GUIDE GUI example.

Add ActiveX Controls

ActiveX® components enable you to display ActiveX controls in your GUI. They are available only on the Microsoft Windows platform.

An ActiveX control can be the child only of a figure; i.e., of the GUI itself. It cannot be the child of a panel or button group.

See Creating an ActiveX Control about adding an ActiveX control to a figure. See Creating COM Objects for general information about ActiveX controls.

Was this topic helpful?