| MATLAB® | |
| On this page… |
|---|
Adding User Interface Controls |
Components include user interface controls such as push buttons and sliders, containers such as panels and button groups, axes, and ActiveX® controls. This topic tells you how to populate your GUI with these components.
Note MATLAB® software provides a selection of standard dialog boxes that you can create with a single function call. For information about these dialog boxes and the functions used to create them, see Predefined Dialog Boxes in the MATLAB Function Reference documentation. |
The following table describes the available components and the function used to create each. Subsequent topics provide specific information about adding the components.
Component | Function | Description |
|---|---|---|
ActiveX components enable you to display ActiveX controls in your GUI. They are available only on the Microsoft® Windows® platform. | ||
Axes enable your GUI to display graphics such as graphs and images. | ||
Button groups are like panels, but are used to manage exclusive selection behavior for radio buttons and toggle buttons. | ||
Check boxes can generate an action when checked and indicate their state as checked or not checked. Check boxes are useful when providing the user with a number of independent choices, for example, displaying a toolbar. | ||
Edit text components are fields that enable users to enter or modify text strings. Use an edit text when you want text as input. Users can enter numbers, but you must convert them to their numeric equivalents. | ||
List boxes display a list of items and enable users to select one or more items. | ||
Panels arrange GUI components into groups. By visually grouping related controls, panels can make the user interface easier to understand. A panel can have a title and various borders. Panel children can be user interface controls and axes, as well as button groups and other panels. The position of each component within a panel is interpreted relative to the panel. If you move the panel, its children move with it and maintain their positions on the panel. | ||
Pop-up menus open to display a list of choices when users click the arrow. | ||
Push buttons generate an action when clicked. For example, an OK button might apply settings and close a dialog box. When you click a push button, it appears depressed; when you release the mouse button, the push button appears raised. | ||
Radio buttons are similar to check boxes, but radio buttons are typically mutually exclusive within a group of related radio buttons. That is, when you select one button the previously selected button is deselected. To activate a radio button, click the mouse button on the object. The display indicates the state of the button. Use a button group to manage mutually exclusive radio buttons. | ||
Sliders accept numeric input within a specified range by enabling the user to move a sliding bar, which is called a slider or thumb. Users move the slider by clicking the slider and dragging it, by clicking in the trough, or by clicking an arrow. The location of the slider indicates the relative location within the specified range. | ||
Static text controls 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. | ||
Toggle buttons generate an action and indicate whether they are turned on or off. When you click a toggle button, it appears depressed, showing that it is on. When you release the mouse button, the toggle button remains depressed until you click it a second time. When you do so, the button returns to the raised state, showing that it is off. Use a button group to manage mutually exclusive radio buttons. |
Components are sometimes referred to by the name of the function used to create them. For example, a push button is created using the uicontrol function, and it is sometimes referred to as a uicontrol. A panel is created using the uipanel function and may be referred to as a uipanel.
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.
Note See Available Components for descriptions of these components. See Programming User Interface Controls for basic examples of programming these components. |
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:
The most commonly used properties needed to describe a user interface control are shown in the following table:
Property | Values | Description |
|---|---|---|
Scalar. Default is 1. | Maximum value. Interpretation depends on the Style property. | |
Scalar. Default is 0. | Minimum value. Interpretation depends on the Style property. | |
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. 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. | |
pushbutton, togglebutton, radiobutton, checkbox, edit, text, slider, listbox, popupmenu. Default is pushbutton. | Type of user interface control object. | |
pixels, centimeters, characters, inches, normalized, points, Default is pixels. | Units of measurement used to interpret position vector | |
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 in the MATLAB Function Reference documentation. Properties needed to control GUI behavior are discussed in Programming the GUI .
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.
Note You can also use an image as a label. See Adding an Image to a Push Button for more information. |
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.
The following statement creates a list box with handle lbh:
lbh = uicontrol(fh,'Style','listbox',...
'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, 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 Format | Example |
|---|---|
| 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:
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.
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 Format | Example |
|---|---|
| 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.
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.
Adding 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 Create your own icon with the icon editor described in Icon Editor. See ind2rgb for information on converting a matrix X and corresponding colormap, i.e., an (X, MAP) image, to RGB (truecolor) format. |
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.
Note You can also use an image as a label. See Adding an Image to a Push Button for more information. |
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.
The Max property is the maximum value of the slider. The Min property is the minimum value of the slider and must be less than Max.
The Value property specifies the value indicated by the slider when it is created. Set Value to a number that is 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 rendered.
The SliderStep property controls the amount the slider Value changes when a user clicks the arrow button to produce a minimum step or the slider trough to produce a maximum step. Specify SliderStep as a two-element vector, [min_step,max_step], where each value is in the range [0, 1].
The example provides a 5 percent minimum step and a 20 percent maximum step. The default, [0.01 0.10], provides a 1 percent minimum step and a 10 percent maximum 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. Use static text components to label the slider.
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.
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.
Note You can also use an image as a label. See Adding an Image to a Push Button for more information. |
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.
Note See Available Components for descriptions of these components. |
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.
The most commonly used properties needed to describe a panel or button group are shown in the following table:
Property | Values | Description |
|---|---|---|
Handle | Handle of the component's parent figure, panel, or button group. | |
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. | |
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. | |
lefttop, centertop, righttop, leftbottom, centerbottom, rightbottom. Default is lefttop. | Location of title string in relation to the panel or button group. | |
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 in the MATLAB Function Reference documentation. Properties needed to control GUI behavior are discussed in Programming the GUI.
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.
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.
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.
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.
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.
Note See Available Components for a description of this component. |
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.
The most commonly used properties needed to describe an axes are shown in the following table:
Property | Values | Description |
|---|---|---|
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. | |
Handle | Handle of the component's parent figure, panel, or button group. | |
4-element vector: [distance from left, distance from bottom, width, height]. | Size of the component and its location relative to its parent. | |
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 in the MATLAB Function Reference documentation. Properties needed to control GUI behavior are discussed in Programming the GUI.
See commands such as the following for more information on axes objects: plot, surf, line, bar, polar, pie, contour and mesh. See Function Reference in the MATLAB Function Reference documentation for a complete list.
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 is used to interpret the Position property. This axes assumes the default Units property, normalized. This enables the axes to resize automatically if the figure is resized.
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.
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 in the MATLAB External Interfaces documentation for information about adding an ActiveX control to a figure. See Creating COM Objects in the MATLAB External Interfaces documentation for general information about ActiveX controls.
| Creating the GUI Figure | Aligning Components | |
| © 1984-2008- The MathWorks, Inc. - Site Help - Patents - Trademarks - Privacy Policy - Preventing Piracy - RSS |