Documentation

Add Components to a Programmatic UI

User interface controls are common UI components, such as buttons, check boxes, and sliders. Tables present data in rows and columns. Panels and button groups are containers in which you can group together related elements in your UI. ActiveX® components enable you to display ActiveX controls.

User Interface Controls

Push Button

This code creates a push button:

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

The first uicontrol argument, f, specifies the parent container. In this case, the parent is a figure, but you can also specify the parent to be any container, such as a panel or button group.

The name-value pair arguments, 'Style','pushbutton', the uicontrol to be a push button.

'String','Button 1' add the label, Button 1 to the push button.

'Position',[50 20 60 40] 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.

Displaying an Icon on a Push Button.  To add an icon to a push button, assign the button's CData property to be an m-by-n-by-3 array of RGB values that define a truecolor image.

Radio Button

This code creates a radio button:

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

The first uicontrol argument, f, specifies the parent container. In this case, the parent is a figure, but you can also specify the parent to be any container, such as a panel or button group. If you have multiple radio buttons, you can manage their selection by specifying the parent to be a button group. See Button Groups for more information.

The name-value pair arguments, 'Style','radiobutton' specifies the uicontrol to a radio button.

'String','Indent nested functions.' specifies a label for the radio button.

'Value',1 selects the radio button by default. Set the Value property to be the value of the Max property to select the radio button. Set the value to be the value of the Min property to deselect the radio button. The default values of Max and Min are 1 and 0, respectively.

'Position',[30 20 150 20] 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.

Toggle Button

This code creates a toggle button:

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

The first uicontrol argument, f, specifies the parent container. In this case, the parent is a figure, but you can also specify the parent to be any container, such as a panel or button group.

The name-value pair arguments, 'Style','togglebutton', specify the uicontrol to be a toggle button.

'String','Left/Right Tile' puts a text label on the toggle button.

The 'Value',0 deselects the toggle button by default. To select (raise) the toggle button, set Value equal to the Max property. To deselect the toggle button, set Value equal to the Min property. By default, Min = 0 and Max = 1.

'Position',[30 20 100 30] specifies the location and size of the toggle button. In this example, the toggle button is 100 pixels wide and 30 pixels high. It is positioned 30 pixels from the left of the figure and 20 pixels from the bottom.

Check Box

This code creates a check box:

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

The first uicontrol argument, f, specifies the parent container. In this case, the parent is a figure, but you can also specify the parent to be any container, such as a panel or button group.

The name-value pair arguments, 'Style','checkbox', specify the uicontrol to be a check box.

The next pair, 'String','Display file extension' puts a text label on the check box.

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® 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 check box. In this example, the check 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.

Slider

This code creates a slider:

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

The first uicontrol argument, f, specifies the parent container. In this case, the parent is a figure, but you can also specify the parent to be any container, such as a panel or button group.

The name-value pair arguments, 'Style','slider' specifies the uicontrol to be a slider.

'Min',0 and 'Max',100 specify the range of the slider to be [0, 100]. The Min property must be less than Max.

'Value',25 sets the default slider position to 25. The number you specify for this property must be within the range, [Min, Max].

'SliderStep',[0.05 0.2] specifies the fractional amount that the thumb moves when the user clicks the arrow buttons or the slider trough (also called the channel). In this case, the slider's thumb position changes by the smaller amount (5 percent) when the user clicks an arrow button. It changes by the larger amount (20 percent) when the user clicks the trough.

Specify SliderStep to be a two-element vector, [minor_step major_step]. The value of minor_step must be less than or equal to major_step. To ensure the best results, do not specify either value to be less than 1e-6. Setting major_step 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.

'Position',[30 20 150 30] 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.

    Note:   On Mac platforms, the height of a horizontal slider is constrained. If the height you set in the Position property exceeds this constraint, the displayed height of the slider is the maximum allowed by the system. However, the value of the Position property does not change to reflect this constraint.

Static Text

This code creates a static text component:

f = figure;
t = uicontrol(f,'Style','text',...
                'String','Select a data set.',...
                'Position',[30 50 130 30]);

The first uicontrol argument, f, specifies the parent container. In this case, the parent is a figure, but you can also specify the parent to be any container, such as a panel or button group.

The name-value pair arguments, 'Style','text' specify the uicontrol to be static text.

'String','Select a set' specifys the text that displays. If you specify a component width that is too small to accommodate the specified String, MATLAB wraps the string.

'Position',[30 50 130 30] specifies the location and size of the static text. 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.

Editable Text Field

This code creates an editable text field, txtbox:

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

The first uicontrol argument, f, specifies the parent container. In this case, the parent is a figure, but you can also specify the parent to be any container, such as a panel or button group.

The name-value pair arguments, 'Style','edit', specify the style of the uicontrol to be an editable text field.

'String','Enter your name here', specifies the default text to display.

The next pair, 'Position',[30 50 130 20] specifies the location and size of the text field. In this example, the text field is 130 pixels wide and 20 pixels high. It is positioned 30 pixels from the left of the figure and 50 pixels from the bottom.

To enable multiple-line input, the value of Max - Min must be greater than 1, as in the following statement.

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

If the value of Max - Min is less than or equal to 1, the editable text field allows only a single line of input. If the width of the text field is too narrow for the string, MATLAB displays only part of the string. The user can use the arrow keys to move the cursor over the entire string.

Pop-Up Menu

This code creates a pop-up menu:

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

The first uicontrol argument, f, specifies the parent container. In this case, the parent is a figure, but you can also specify the parent to be any container, such as a panel or button group.

The name-value pair arguments, Style,'popupmenu', specify the uicontrol to be a pop-up menu.

'String',{'one','two','three','four'} defines the menu items.

'Value',1 sets the index of the item that is selected by default. Set Value to a scalar that indicates the index of the selected item. A value of 1 selects the first item.

'Position',[30 80 130 20] 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.

List Box

This code creates a list box:

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

The first uicontrol argument, f, specifies the parent container. In this case, the parent is a figure, but you can also specify the parent to be any container, such as a panel or button group.

The name-value pair arguments, 'Style','listbox', specify the uicontrol to be a list box.

'String',{'one','two','three','four'} defines the list items.

'Position',[30 20 130 80] 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 final pair of arguments, Value,1 sets the list selection to the first item in the list. To select a single item, set the Value property to be a scalar that indicates the position of the item in the list.

To select more than one item, set the Value property to be a vector of values. To enable your users to select multiple items, set the values of the Min and Max properties such that Max - Min is greater than 1. Here is a list box that allows multiple selections and has two items selected initially:

lb = uicontrol(f,'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, set these property values:

  • Set the Max and Min properties such that Max - Min is greater than 1.

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

Tables

This code creates a table and populates it with the values returned by magic(5).

f = figure;
tb = uitable(f,'Data',magic(5));

The first uitable argument, f, specifies the parent container. In this case, the parent is a figure, but you can also specify the parent to be any container, such as a panel or button group.

The name-value pair arguments, 'Data',magic(5), specifies the table data. In this case, the data is the 5-by-5 matrix returned by the magic(5) command.

You can adjust the width and height of the table to accommodate the extent of the data. The uitable's Position property controls the outer bounds of the table, and the Extent property indicates the extent of the data. Set the last two values in the Position property to the corresponding values in the Extent property:

tb.Position(3) = tb.Extent(3);
tb.Position(4) = tb.Extent(4);

You can change several other characteristics of the table by setting certain properties:

  • To control the user's ability to edit the table cells, set the ColumnEditable property.

  • To make your application respond when the user edits a cell, define a CellEditCallback function.

  • To add or change row striping, set the RowStriping property.

  • To specify row and column names, set the RowName and ColumnName properties.

  • To format the data in the table, set the ColumnFormat property.

See Uitable Properties for the entire list of properties.

If you are building a UI using GUIDE, you can set many of the uitable properties using the Table Property Editor. For more information, see Create a Table.

Panels

This code creates a panel:

f = figure;
p = uipanel(f,'Title','My Panel',...
             'Position',[.25 .1 .5 .8]);

The first argument passed to uipanel, f, specifies the parent container. In this case, the parent is a figure, but you can also specify the parent to be any container, such as another panel or a button group.

'Title','My Panel' specifies a title to display on the panel.

'Position',[.25 .1 .5 .8] specifies the location and size of the panel as a fraction of the parent container. In this case, the panel is 50 percent of the width of the figure and 80 percent of its height. The left edge of the panel is located at 25 percent of the figure's width from the left. The bottom of the panel is located 10 percent of the figure's height from the bottom. If the figure is resized, the panel retains its original proportions.

The following commands add two push buttons to the panel. Setting the Units property to 'normalized' causes the Position values to be interpreted as fractions of the parent panel. Normalized units allow the buttons to retain their original proportions when the panel is resized.

b1 = uicontrol(p,'Style','pushbutton','String','Button 1',...
                'Units','normalized',...
                'Position',[.1 .55 .8 .3]);
b2 = uicontrol(p,'Style','pushbutton','String','Button 2',...
                'Units','normalized',...
                'Position',[.1 .15 .8 .3]);

Button Groups

This code creates a button group:

f = figure;
bg = uibuttongroup(f,'Title','My Button Group',...
            'Position',[.1 .2 .8 .6]);

The first argument passed to uibuttongroup, f, specifies the parent container. In this case, the parent is a figure, but you can also specify the parent to be any container, such as a panel or another button group.

'Title','My Button Group' specifies a title to display on the button group.

'Position',[.1 .2 .8 .6] specifies the location and size of the button group as a fraction of the parent container. In this case, the button group is 80 percent of the width of the figure and 60 percent of its height. The left edge of the button group is located at 10 percent of the figure's width from the left. The bottom of the button group is located 20 percent of the figure's height from the bottom. If the figure is resized, the button group retains its original proportions.

The following commands add two radio buttons to the button group. Setting the Units property to 'normalized' causes the Position values to be interpreted as fractions of the parent panel. Normalized units allow the buttons to retain their original relative positions when the button group is resized.

rb1 = uicontrol(bg,'Style','radiobutton','String','Red',...
                'Units','normalized',...
                'Position',[.1 .6 .3 .2]);
rb2 = uicontrol(bg,'Style','radiobutton','String','Blue',...
                'Units','normalized',...
                'Position',[.1 .2 .3 .2]);

By default, the first radio button added to the uibuttongroup is selected. To override this default, set any other radio button's Value property to its Max property value.

Button groups manage the selection of radio buttons and toggle buttons by allowing only one button to be selected within the group. You can determine the currently selected button by querying the uibuttongroup's SelectedObject property.

Axes

This code creates an axes in a figure:

f = figure;
ax = axes('Parent',f,'Position',[.15 .15 .7 .7]);

The first two arguments passed to the axes function, 'Parent',f specify the parent container. In this case, the parent is a figure, but you can also specify the parent to be any container, such as a panel or button group.

'Position',[.15 .15 .7 .7] specifies the location and size of the axes as a fraction of the parent figure. In this case, the axes is 70 percent of the width of the figure and 70 percent of its height. The left edge of the axes is located at 15 percent of the figure's width from the left. The bottom of the axes is located 15 percent of the figure's height from the bottom. If the figure is resized, the axes retains its original proportions.

Prevent Customized Axes Properties from Being Reset

Data graphing functions, such as plot, image, and scatter, reset axes properties before they draw into an axes. This can be a problem when you want to maintain consistency of axes limits, ticks, colors, and font characteristics in a UI.

The default value of the NextPlot axes property, 'replace' allows the graphing functions to reset many property values. In addition, the 'replace' property value allows MATLAB to remove all callbacks from the axes whenever a graph is plotted. If you create an axes in a UI window, consider setting the NextPlot property to 'replacechildren'. You might need to set this property prior to changing the contents of an axes:

ax.NextPlot = 'replacechildren';

ActiveX Controls

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

An ActiveX control can be the child only of a figure. 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.

How to Set Font Characteristics

Use the FontName property to specify a particular font for a user interface control, panel, button group, table, or axes.

Use the uisetfont function to display a dialog that allows you to choose a font, style, and size all at once:

myfont = uisetfont

uisetfont returns the selections as a structure array:

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

You can use this information to set font characteristics of a component in the UI:

btn = uicontrol;
btn.FontName = myfont.FontName;
btn.FontSize = myfont.FontSize;

Alternatively, you can set all the font characteristics at once:

set(btn,myfont); 

Related Examples

Was this topic helpful?