Learn more about MATLAB

Adding Components to the GUI

On this page…
Available Components A Working GUI with Many Components Adding Components to the GUIDE Layout Area Defining User Interface Controls Defining Panels and Button Groups Defining Axes Defining Tables Adding ActiveX Controls Working with Components in the Layout Area Locating and Moving Components Resizing Components

Other topics that may be of interest:

• Aligning Components

• Setting Tab Order

Available Components

The component palette at the left side of the Layout Editor contains the components that you can add to your GUI. You can display it with or without names.

When you first open the Layout Editor, the component palette contains only icons. To display the names of the GUI components, select Preferences from the File menu, check the box next to Show names in component palette, and click OK.

See Creating Menus for information about adding menus to a GUI.

Note   This section provides information about using components to lay out a GUI. For information about programming these components see Programming a GUIDE GUI.

Component	Icon	Description
Push Button		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.
Slider		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.
Radio Button		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.
Check Box		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		Edit text components are fields that enable users to enter or modify text strings. Use edit text when you want text as input. Users can enter numbers but you must convert them to their numeric equivalents.
Static Text		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.
Pop-Up Menu		Pop-up menus open to display a list of choices when users click the arrow.
List Box		List boxes display a list of items and enable users to select one or more items.
Toggle Button		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 toggle buttons.
Table		Use the table button to create a table component. Refer to the uitable function for more information on using this component.
Axes		Axes enable your GUI to display graphics such as graphs and images. Like all graphics objects, axes have properties that you can set to control many aspects of its behavior and appearance. See Axes Properties in the MATLAB Graphics documentation and commands such as the following for more information on axes objects: plot, surf, line, bar, polar, pie, contour, and mesh. See Functions — By Category in the MATLAB Function Reference documentation for a complete list.
Panel		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.
Button Group		Button groups are like panels but are used to manage exclusive selection behavior for radio buttons and toggle buttons.
Toolbar		You can create toolbars containing push buttons and toggle buttons. Use the GUIDE Toolbar Editor to create toolbar buttons. Choose between predefined buttons, such as Save and Print, and buttons which you customize with your own icons and callbacks.
ActiveX® Component		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 ActiveX Control in this document for an example. See Creating COM Objects in the MATLAB External Interfaces documentation to learn more about ActiveX controls.

Back to Top

A Working GUI with Many Components

To see what GUI components look like and how they work, you can open in GUIDE and run an example GUI that demonstrates more than a dozen of them. When you run the GUI, all its component callbacks tell your actions using the GUI and some also update the plot it displays. The GUI, called controlsuite, includes all the components listed in the table in the previous section, Available Components, except for ActiveX controls. It consists of a FIG-file (controlsuite.fig) that opens in GUIDE, and an M-file (controlsuite.m) that opens in the MATLAB Editor.

Viewing the controlsuite Layout and GUI M-File

If you are reading this in the MATLAB Help browser, click the following links to display the GUIDE Layout Editor and the MATLAB Editor with a completed version of the controlsuite example.

• Click here to display the controlsuite GUI in the GUIDE Layout Editor.

• Click here to display the controlsuite GUI M-file in the MATLAB Editor.

• Click here to run the controlsuite GUI.

Note   If you want to experiment with the controlsuite GUI, first save a copy of the FIG-file and the M-file in a writable folder on your MATLAB path and work with those copies.

When you open controlsuite.fig in GUIDE, it looks like this in the Layout Editor. Click any control outlined in yellow in the following figure to read about how that type of component is programmed, as described in the section Examples: Programming GUIDE GUI Components. Several of the controls are also discussed later in this section.

The GUI contains 15 controls organized within seven panels. The Action Panel contains a static text component that changes to describe the actions a user makes when manipulating the controls. For example, selecting Charlie in the Listbox panel places the word Charlie in the Action Panel. The Membrane data table and plot panel on the right side displays a 3-D surface plot (generated by the membrane function) in an axes at its bottom, and the data for that plot in the table above it. The user can control the view azimuth and the colormap using the two controls in the Plot Controls panel at the bottom center.

Running the controlsuite GUI

When you click the Run Figure button in the Layout Editor, the GUI opens, initializes, and displays itself as shown in the following figure.

The following sections describe several controls and the code they execute (their callbacks). Study the sections of code and click the links to the callbacks below to learn the how the controlsuite M-file controls the GUI.

The Push Button.   When the user clicks the Push Button button, the result show up in the Action Panel as

The M-code that generates the message is part of the pushbutton1_Callback, shown below:

function pushbutton1_Callback(hObject, eventdata, handles)
% hObject    handle to pushbutton1 (see GCBO)
% eventdata  reserved - to be defined in a future version of MATLAB
% handles    structure with handles and user data (see GUIDATA)

set(handles.textStatus, 'String', 'Push button pushed')

This callback is activated when pushbutton1 is clicked. It places the string 'Push button pushed' in the static text field named textStatus using the set function. All the controls in controlsuite perform this action, but some of them do other things as well.

The Toggle Button.   When the user clicks the Toggle Button button, this is the result.

The callback for this button, togglebutton1, contains this M-code:

function togglebutton1_Callback(hObject, eventdata, handles)
% hObject    handle to togglebutton1 (see GCBO)
% eventdata  reserved - to be defined in a future version of MATLAB
% handles    structure with handles and user data (see GUIDATA)

% Hint: get(hObject,'Value') returns toggle state of togglebutton1

isDown = get(hObject,'Value');

if isDown
    set(handles.textStatus, 'string', 'Toggle down')
else
    set(handles.textStatus, 'string', 'Toggle up')
end

The if block tests the variable isDown, which has been set to the Value property of the toggle button, and writes a different message depending on whether the value is true or false.

The Plot Controls.   The two components of the Plot Controls panel affect the plot of the peaks function as well as rewrite the text in the Action Panel.

• A popup menu to select a built-in colormap by name

• A slider to rotate the view around the z-axis

The popup, named popupmenu1, contains a list of seven colormap names in its String property, which you can set in the Property Inspector by clicking its Edit icon . Typing the strings into the edit dialog and clicking OK sets all seven colormap names at once.

The popup's callback controls its behavior. GUIDE generates this much of the callback.

function popupmenu1_Callback(hObject, eventdata, handles)
% hObject    handle to popupmenu1 (see GCBO)
% eventdata  reserved - to be defined in a future version of MATLAB
% handles    structure with handles and user data (see GUIDATA)

% Hints: contents = get(hObject,'String') returns popupmenu1
%        contents as cell array
%        contents{get(hObject,'Value')} returns selected item
%        from popupmenu1

The callbacks's code adds these statements.

contents       = get(hObject,'String'); 
selectedText   = contents{get(hObject,'Value')};
colormapStatus = [selectedText ' colormap'];
set(handles.textStatus, 'string', colormapStatus);
colormap(selectedText)

The String data is retrieved as a cell array and assigned to contents. The Value property indexes the member of contents that the user just selected to retrieve the name of the colormap That name, selectedText, is composed into a message and placed in the textStatus static text field, and used by the colormap function to reset the colormap. For example, if the user selects autumn from the popup, the surface changes to shades of yellow, orange, and red, as shown in the following cutout from the GUI.

The slider control sets the viewing azimuth, causing the plot to rotate when the user moves its "thumb" or clicks its arrows. Its name is slider1 and its callback is slider1_Callback.

The Data Table.   The table in the upper right corner is a uitable component. When the GUI is created, the table's CreateFcn loads the same membrane data into the table that the plot in the axes below it displays.

The table is by default not editable, but by clicking the small Edit toggle button in its upper left corner the user can edit table values, one at a time. This button is placed on top of the table, but is not actually part of it. The table's CellEditCallback responds to each table cell edit by updating the surface plot and displaying the result of the edit in the Action Panel. Clicking the Edit button again makes the table not editable. See togglebutton2_Callback in the controlsuite M-file for details on how this works.

For another example describing how to couple uitables with graphics, see GUI to Interactively Explore Data in a Table.

Find more about how to work with the GUI components used in controlsuite in Examples: Programming GUIDE GUI Components and in the following sections:

• Defining User Interface Controls

• Defining Panels and Button Groups

• Defining Axes

• Defining Tables

Back to Top

Adding Components to the GUIDE Layout Area

This topic tells you how to place components in the GUIDE layout area and give each component a unique identifier.

Note   See Creating Menus for information about adding menus to a GUI. See Creating Toolbars for information about working with the toolbar.

1. Place components in the layout area according to your design.

   • Drag a component from the palette and drop it in the layout area.

   • Click a component in the palette and move the cursor over the layout area. The cursor changes to a cross. Click again to add the component in its default size, or click and drag to size the component as you add it.

   Once you have defined a GUI component in the layout area, selecting it automatically shows it in the Property Inspector. If the Property Inspector is not open or is not visible, double-clicking a component raises the inspector and focuses it on that component.

   The components listed in the following table have additional considerations; read more about them in the sections described there.

   If You Are Adding...	Then...
   Panels or button groups	See Adding a Component to a Panel or Button Group.
   Menus	See Creating Menus
   Toolbars	See Creating Toolbars
   ActiveX controls	See Adding ActiveX Controls.

   See Grid and Rulers for information about using the grid.

2. Assign a unique identifier to each component. Do this by setting the value of the component Tag properties. SeeAssigning an Identifier to Each Component for more information.

3. Specify the look and feel of each component by setting the appropriate properties. The following topics contain specific information.

   • Defining User Interface Controls

   • Defining Panels and Button Groups

   • Defining Axes

   • Defining Tables

   • Adding ActiveX Controls

This is an example of a GUI in the Layout Editor. Components in the Layout Editor are not active. Saving and Running a GUIDE GUI describes how to generate a functioning GUI.

Using Coordinates to Place Components

The status bar at the bottom of the GUIDE Layout Editor displays:

• Current Point — The current location of the mouse relative to the lower left corner of the grid area in the Layout Editor.

• Position — The Position property of the selected component, a 4-element vector: [distance from left, distance from bottom, width, height], where distances are relative to the parent figure, panel, or button group. All values are given in pixels. Rulers also display pixels.

If you select a single component and move it, the first two elements of the position vector (distance from left, distance from bottom) are updated as you move the component. If you resize the component, the last two elements of the position vector (width, height) are updated as you change the size. The first two elements may also change if you resize the component such that the position of its lower left corner changes. If no components are selected, the position vector is that of the figure.

For more information, see Using Coordinate Readouts.

Adding a Component to a Panel or Button Group

To add a component to a panel or button group, select the component in the component palette then move the cursor over the desired panel or button group. The position of the cursor determines the component's parent.

GUIDE highlights the potential parent as shown in the following figure. The highlight indicates that if you drop the component or click the cursor, the component will be a child of the highlighted panel, button group, or figure.

Note   Assign a unique identifier to each component in your panel or button group by setting the value of its Tag property. See Assigning an Identifier to Each Component for more information.

Including Existing Components in Panels and Button Groups.   When you add a new component or drag an existing component to a panel or button group, it will become a member, or child, of the panel or button group automatically, whether fully or partially enclosed by it. However, if the component is not entirely contained in the panel or button group, it appears to be clipped in the Layout Editor. When you run the GUI, the entire component is displayed and straddles the panel or button group border. The component is nevertheless a child of the panel and behaves accordingly. You can use the Object Browser to determine the child objects of a panel or button group. Viewing the Object Hierarchy tells you how.

You can add a new panel or button group to a GUI in order to group any of its existing controls. In order to include such controls in a new panel or button group, do the following. The instructions refer to panels, but you do the same for components inside button groups.

1. Select the New Panel or New Button Group tool and drag out a rectangle to have the size and position you want.

   The panel will not obscure any controls within its boundary unless they are axes, tables, or other panels or button groups. Only overlap panels you want to nest, and then make sure the overlap is complete.

2. You can use Send Backward or Send to Back on the Layout menu to layer the new panel behind components you do not want it to obscure, if your layout has this problem. As you add components to it or drag components into it, the panel will automatically layer itself behind them.

   Now is a good time to set the panel's Tag and String properties to whatever you want them to be, using the Property Inspector.

3. Open the Object Browser from the View menu and find the panel you just added. Use this tool to verify that it contains all the controls you intend it to group together. If any are missing, perform the following steps.

4. Drag controls that you want to include but don't fit within the panel inside it to positions you want them to have. Also, slightly move controls that are already in their correct positions to group them with the panel.

   The panel highlights when you move a control, indicating it now contains the control. The Object Browser updates to confirm the relationship. If you now move the panel, its child controls move with it.

   Tip   You need to move controls with the mouse to register them with the surrounding panel or button group, even if only by a pixel or two. Selecting them and using arrow keys to move them does not accomplish this. Use the Object Browser to verify that controls are properly nested.

See Defining Panels and Button Groups for more information on how to incorporate panels and button groups into a GUI.

Assigning an Identifier to Each Component

Use the Tag property to assign each component a unique meaningful string identifier.

When you place a component in the layout area, GUIDE assigns a default value to the Tag property. Before saving the GUI, replace this value with a string that reflects the role of the component in the GUI.

The string value you assign Tag is used in the M-file code to identify the component and must be unique in the GUI. To set Tag:

1. Select Property Inspector from the View menu or click the Property Inspector button .

2. In the layout area, select the component for which you want to set Tag.

3. In the Property Inspector, select Tag and then replace the value with the string you want to use as the identifier. In the following figure, Tag is set to mybutton.

   

Back to Top

Defining User Interface Controls

User interface controls include push buttons, toggle buttons, sliders, radio buttons, edit text controls, static text controls, pop-up menus, check boxes, and list boxes.

To define user interface controls, you must set certain properties. To do this:

1. Use the Property Inspector to modify the appropriate properties. Open the Property Inspector by selecting Property Inspector from the View menu or by clicking the Property Inspector button .

2. In the layout area, select the component you are defining.

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

• Commonly Used Properties

• Push Button

• Slider

• Radio Button

• Check Box

• Edit Text

• Static Text

• Pop-Up Menu

• List Box

• Toggle Button

Note   See Available Components for descriptions of these components. See Examples: Programming GUIDE GUI Components for basic examples of programming these components.

Commonly Used Properties

The most commonly used properties needed to describe a user interface control are shown in the following table. Instructions for a particular control may also list properties that are specific to that control.

Property	Value	Description
Enable	on, inactive, off. Default is on.	Determines whether the control is available to the user
Max	Scalar. Default is 1.	Maximum value. Interpretation depends on the type of component.
Min	Scalar. Default is 0.	Minimum value. Interpretation depends on the type of component.
Position	4-element vector: [distance from left, distance from bottom, width, height].	Size of the component and its location relative to its parent.
String	String. Can also be a cell array or character array of strings.	Component label. For list boxes and pop-up menus it is a list of the items.
Units	characters, centimeters, inches, normalized, pixels, points. Default is characters.	Units of measurement used to interpret the Position property vector
Value	Scalar or vector	Value of the component. Interpretation depends on the type of component.

For a complete list of properties and for more information about the properties listed in the table, see Uicontrol Properties in the MATLAB documentation. Properties needed to control GUI behavior are discussed in Programming a GUIDE GUI

Push Button

To create a push button with label Button 1, as shown in this figure:

• Specify the push button label by setting the String property to the desired label, in this case, Button 1.

  

  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.

  The push button accommodates only a single line of text. If you specify more than one line, only the first line is shown. If you create a push button that is too narrow to accommodate the specified String, MATLAB software truncates the string with an ellipsis.

  

• If you want to set the position or size of the component to an exact value, then modify its Position property. See Locating and Moving Components and Resizing Components for details.

• 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. You must do this programmatically in the opening function of the GUI M-file. For example, the array img defines a 16-by-64-by-3 truecolor image using random values between 0 and 1 (generated by rand).

  img = rand(16,64,3);
  set(handles.pushbutton1,'CData',img);
  

  where pushbutton1 is the push button's Tag property.

  

  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.

Slider

To create a slider as shown in this figure:

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

• Control 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 by setting the SliderStep property. Specify SliderStep as a two-element vector, [min_step,max_step], where each value is in the range [0, 1] to indicate a percentage of the range.

  

• If you want to set the position or size of the component to an exact value, then modify its Position property. See Locating and Moving Components and Resizing Components for details.

  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.

  Note   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 provide a value for the slider.

Radio Button

To create a radio button with label Indent nested functions, as shown in this figure:

• Specify the radio button label by setting the String property to the desired label, in this case, Indent nested functions.

  

  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.

  The radio button accommodates only a single line of text. If you specify more than one line, only the first line is shown. If you create a radio button that is too narrow to accommodate the specified String, MATLAB software truncates the string with an ellipsis.

  

• Create the radio button with the button selected by setting its Value property to the value of its Max property (default is 1). Set Value to Min (default is 0) to leave the radio button unselected. Correspondingly, when the user selects the radio button, the software sets Value to Max, and to Min when the user deselects it.

• If you want to set the position or size of the component to an exact value, then modify its Position property. See Locating and Moving Components and Resizing Components for details.

• To add an image to a radio button, assign the button's CData property an m-by-n-by-3 array of RGB values that defines a truecolor image. You must do this programmatically in the opening function of the GUI M-file. For example, the array img defines a 16-by-24-by-3 truecolor image using random values between 0 and 1 (generated by rand).

  img = rand(16,24,3);
  set(handles.radiobutton1,'CData',img);
  

  Note   To manage exclusive selection of radio buttons and toggle buttons, put them in a button group. See Button Group for more information.

Check Box

To create a check box with label Display file extension that is initially checked, as shown in this figure:

• Specify the check box label by setting the String property to the desired label, in this case, Display file extension.

  

  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.

  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.

  

• Create the check box with the box checked by setting the Value property to the value of the Max property (default is 1). Set Value to Min (default is 0) to leave the box unchecked. Correspondingly, when the user clicks the check box, the software sets Value to Max when the user checks the box and to Min when the user clears it.

• If you want to set the position or size of the component to an exact value, then modify its Position property. See Locating and Moving Components and Resizing Components for details.

Edit Text

To create an edit text component that displays the initial text Enter your name here, as shown in this figure:

• Specify the text to be displayed when the edit text component is created by setting the String property to the desired string, in this case, Enter your name here.

  

  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.

• To enable multiple-line input, specify the Max and Min properties so that their difference is greater than 1. For example, Max = 2, Min = 0. Max default is 1, Min default is 0. MATLAB software wraps the string and adds a scroll bar if necessary. On all platforms, when the user enters a multiline text box via the Tab key, the editing cursor is placed at its previous location and no text highlights.

  

  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 through the entire string. On all platforms, when the user enters a single-line text box via the Tab key, the entire contents is highlighted and the editing cursor is at the end (right side) of the string.

  

• If you want to set the position or size of the component to an exact value, then modify its Position property. See Locating and Moving Components and Resizing Components for details.

• You specify the text font to display in the edit box by typing the name of a font residing on your system into the FontName entry in the Property Inspector. On Microsoft Windows platforms, the default is MS Sans Serif; on Macintosh^® and UNIX^® platforms, the default is Helvetica.

  Tip   To find out what fonts are available, type uisetfont at the MATLAB prompt; a dialog displays containing a list box from which you can select and preview available fonts. When you select a font, its name and other characteristics are returned in a structure, from which you can copy the FontName string and paste it into the Property Inspector. Not all fonts listed may be available to users of your GUI on their systems.

Static Text

To create a static text component with text Select a data set, as shown in this figure:

• Specify the text that appears in the component by setting the component String property to the desired text, in this case Select a data set.

  

  To display the & character in a list item, 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.

  If your component is not wide enough to accommodate the specified String, MATLAB software wraps the string.

  

• If you want to set the position or size of the component to an exact value, then modify its Position property. See Locating and Moving Components and Resizing Components for details.

• You can specify a text font, including its FontName, FontWeight, FontAngle, FontSize, and FontUnits properties. For details, see the previous topic, Edit Text, and for a programmatic approach, the section Setting Font Characteristics.

Pop-Up Menu

To create a pop-up menu (also known as a drop-down menu or combo box) with items one, two, three, and four, as shown in this figure:

• Specify the pop-up menu items to be displayed by setting the String property to the desired items. Click the

  

  button to the right of the property name to open the Property Inspector editor.

  

  To display the & character in a menu item, 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.

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

• To select an item when the component is created, set Value to a scalar that indicates the index of the selected list item, where 1 corresponds to the first item in the list. If you set Value to 2, the menu looks like this when it is created:

  

• If you want to set the position and size of the component to exact values, then modify its Position property. See Locating and Moving Components and Resizing Components for details. The height of a pop-up menu is determined by the font size. The height you set in the position vector is ignored.

  Note   The pop-up menu does not provide for a label. Use a Static Text component to label the pop-up menu.

List Box

To create a list box with items one, two, three, and four, as shown in this figure:

• Specify the list of items to be displayed by setting the String property to the desired list. Use the Property Inspector editor to enter the list. You can open the editor by clicking the button to the right of the property name.

  

  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.

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

• Specify selection by using the Value property together with the Max and Min properties.

  • To select a single item when the component is created, 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 when the component is created, set Value to a vector of indices of the selected items. Value = [1,3] results in the following selection.

    

    To enable selection of more than one item, you must specify the Max and Min properties so that their difference is greater than 1. For example, Max = 2, Min = 0. Max default is 1, Min default is 0.

  • If you want no initial selection, set the Max and Min properties to enable multiple selection, i.e., Max - Min > 1, and then 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.

• If you want to set the position or size of the component to an exact value, then modify its Position property. See Locating and Moving Components and Resizing Components for details.

  Note   The list box does not provide for a label. Use a Static Text component to label the list box.

Toggle Button

To create a toggle button with label Left/Right Tile, as shown in this figure:

• Specify the toggle button label by setting its String property to the desired label, in this case, Left/Right Tile.

  

  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.

  The toggle button accommodates only a single line of text. If you specify more than one line, only the first line is shown. If you create a toggle button that is too narrow to accommodate the specified String, MATLAB software truncates the string with an ellipsis.

  

• Create the toggle button with the button selected (depressed) by setting its Value property to the value of its Max property (default is 1). Set Value to Min (default is 0) to leave the toggle button unselected (raised). Correspondingly, when the user selects the toggle button, MATLAB software sets Value to Max, and to Min when the user deselects it. The following figure shows the toggle button in the depressed position.

  

• If you want to set the position or size of the component to an exact value, then modify its Position property. See Locating and Moving Components and Resizing Components for details.

• To add an image to a toggle button, assign the button's CData property an m-by-n-by-3 array of RGB values that defines a truecolor image. You must do this programmatically in the opening function of the GUI M-file. For example, the array img defines a 16-by-64-by-3 truecolor image using random values between 0 and 1 (generated by rand).

  img = rand(16,64,3);
  set(handles.togglebutton1,'CData',img);
  

  where togglebutton1 is the toggle button's Tag property.

  

  Note   To manage exclusive selection of radio buttons and toggle buttons, put them in a button group. See Button Group for more information.

Back to Top

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

To define panels and button groups, you must set certain properties. To do this:

1. Use the Property Inspector to modify the appropriate properties. Open the Property Inspector by selecting Property Inspector from the View menu or by clicking the Property Inspector button .

2. In the layout area, select the component you are defining.

   Note   See Available Components for descriptions of these components. See Examples: Programming GUIDE GUI Components for basic examples of programming these components.

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

• Commonly Used Properties

• Panel

• Button Group

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
Position	4-element vector: [distance from left, distance from bottom, width, height].	Size of the component and its location relative to its parent.
Title	String	Component label.
TitlePosition	lefttop, centertop, righttop, leftbottom, centerbottom, rightbottom. Default is lefttop.	Location of title string in relation to the panel or button group.
Units	characters, centimeters, inches, normalized, pixels, points. Default is characters.	Units of measurement used to interpret the Position property vector

For a complete list of properties and for more information about the properties listed in the table, see the Uipanel Properties and Uibuttongroup Properties in the MATLAB reference documentation. Properties needed to control GUI behavior are discussed in theProgramming a GUIDE GUI.

Panel

To create a panel with title My Panel as shown in the following figure:

• Specify the panel title by setting the Title property to the desired string, in this case My Panel.

  

  To display the & character in the title, 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.

• Specify the location of the panel title by selecting one of the available TitlePosition property values from the pop-up menu, in this case lefttop. You can position the title at the left, middle, or right of the top or bottom of the panel.

  

• If you want to set the position or size of the panel to an exact value, then modify its Position property. See Locating and Moving Components and Resizing Components for details.

  Note   For more information and additional tips and techniques, see Adding a Component to a Panel or Button Group and the uipanel reference documentation.

Button Group

To create a button group with title My Button Group as shown in the following figure:

• Specify the button group title by setting the Title property to the desired string, in this case My Button Group.

  

  To display the & character in the title, 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.

• Specify the location of the button group title by selecting one of the available TitlePosition property values from the pop-up menu, in this case lefttop. You can position the title at the left, middle, or right of the top or bottom of the button group.

  

• If you want to set the position or size of the button group to an exact value, then modify its Position property. See Locating and Moving Components and Resizing Components for details.

  Note   For more information and additional tips and techniques, see Adding a Component to a Panel or Button Group and the uibuttongroup reference documentation.

Back to Top

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

To define an axes, you must set certain properties. To do this:

1. Use the Property Inspector to modify the appropriate properties. Open the Property Inspector by selecting Property Inspector from the View menu or by clicking the Property Inspector button .

2. In the layout area, select the component you are defining.

   Note   SeeAvailable Components for a description of this component.

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

• Commonly Used Properties

• Axes

Commonly Used Properties

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

Property	Values	Description
NextPlot	add, replace, replacechildren. Default is replace	Specifies whether plotting adds graphics, replaces graphics and resets axes properties to default, or replaces graphics only.
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 in the MATLAB documentation. Properties needed to control GUI behavior are discussed in Programming a GUIDE GUI.

See commands such as the following for more information on axes objects: plot, surf, line, bar, polar, pie, contour, imagesc, and mesh. See Function Reference in the MATLAB Function Reference documentation for a complete list.

Many of these graphing functions reset axes properties by default, according to the setting of its NextPlot property, which can cause unwanted behavior in a GUI, such as resetting axis limits and removing axes context menus and callbacks. See the next section and also Adding Axes in the Creating GUIs Programmatically section for information on details on setting the NextPlot axes property.

Axes

To create an axes as shown in the following figure:

• Allow for tick marks to be placed outside the box that appears in the Layout Editor. The axes above looks like this in the layout editor; placement allows space at the left and bottom of the axes for tick marks. Functions that draw in the axes update the tick marks appropriately.

  

• Use the title, xlabel, ylabel, zlabel, and text functions in the GUI M-file to label an axes component. For example,

  xlh = (axes_handle,'Years')
  

  labels the X-axis as Years. The handle of the X-axis label is xlh. See Callback Syntax and Arguments for information about determining the axes handle.

  The words remove, default, and factory (case sensitive) are reserved. To use one of these in component text, prepend a backslash (\) to the string. For example, \remove yields remove.

• If you want to set the position or size of the axes to an exact value, then modify its Position property. See Locating and Moving Components and Resizing Components for details.

• If you customize axes properties, some of them (or example, callbacks, font characteristics, and axis limits and ticks) may get reset to default every time you draw a graph into the axes when the NextPlot property has its default value of 'replace'. To keep customized properties as you want them, set NextPlot to 'replacechildren' in the Property Inspector, as shown here.

  

Back to Top

Defining Tables

Tables enable you to display data in a two dimensional table. You can use the Property Inspector to get and set the object property values.

Commonly Used Properties

The most commonly used properties of a table component are listed in the table below. These are grouped in the order they appear in the Table Property Editor. Please refer to uitable command documentation for detail of all the table properties:

Group	Property	Values	Description
Column	ColumnName	1-by-n cell array of strings | {'numbered'} | empty matrix ([])	The header label of the column.
	ColumnFormat	Cell array of strings	Determines display and editablility of columns
	ColumnWidth	1-by-n cell array or 'auto'	Width of each column in pixels; individual column widths can also be set to 'auto'
	ColumnEditable	logical 1-by-n matrix | scalar logical value | empty matrix ([])}	Determines data in a column as editable
Row	RowName	1-by-n cell array of strings	Row header label names
Color	BackgroundColor	n-by-3 matrix of RGB triples	Background color of cells
	RowStriping	{on} | off	Color striping of table rows
Data	Data	Matrix or cell array of numeric, logical, or character data	Table data.

Creating a Table

To create a GUI with a table in GUIDE as shown, do the following:

Drag the table icon on to the Layout Editor and right click in the table. Select Table Property Editor from its pop-up context menu. You can also select Table Property Editor from the Tools menu when you select a table by itself.

Using the Table Property Editor.   When you open it this way, the Table Property Editor displays theColumn pane. You can also open it from the Property Inspector by clicking one of its Table Property Editor icons , in which case the Table Property Editor opens to display the pane appropriate for the property you clicked.

Clicking items in the list on the left hand side of the Table Property Editor changes the contents of the pane to the right . Use the items to activate controls for specifying the table's Columns, Rows, Data, and Color options.

The Columns and Rows panes each have a data entry area where you can type names and set properties. on a per-column or per-row basis. You can edit only one row or column definition at a time. These panes contain a vertical group of five buttons for editing and navigating:

Button	Purpose	Accelerator Keys
		Windows	Macintosh
Insert	Inserts a new column or row definition entry below the current one	Insert	Insert
Delete	Deletes the current column or row definition entry (no undo)	Ctrl+D	Cmd+D
Copy	Inserts a Copy of the selected entry in a new row below it	Ctrl+P	Cmd+P
Up	Moves selected entry up one row	Ctrl+ uparrow	Cmd+ uparrow
Down	Moves selected entry down one row	Ctrl+ downarrow	Cmd+ downarrow

Keyboard equivalents only operate when the cursor is in the data entry area. In addition to those listed above, typing Ctrl+T or Cmd+T selects the entire field containing the cursor for editing (if the field contains text).

To save changes to the table you make in the Table Property Editor, click OK, or click Apply commit changes and keep on using the Table Property Editor.

Set Column Properties.   Click Insert to add two more columns.

Select Show names entered below as the column headers and set the ColumnName by entering Rate, Amount, Available, and Fixed/Adj in Name group. for the Available and Fixed/Adj columns set the ColumnEditable property to on. Lastly set the ColumnFormat for the four columns

For the Rate column, select Numeric. For the Amount Column select Custom and in the Custom Format Editor, choose Bank.

Leave the Available column at the default value. This allows MATLAB to chose based on the value of the Data property of the table. For the Fixed/Adj column select Choice List to create a pop-up menu. In the Choice List Editor, click Insert to add a second choice and type Fixed and Adjustable as the 2 choices.

Note   The In order for a user to select items from a choice list, the ColumnEditable property of the column the list occupies must be set to 'true'. The pop-up control only appears when the column is editable.

Set Row Properties.   In the Row tab, leave the default RowName, Show numbered row headers.

Set Data Properties.   Specify the value of the Data you want in the table. You need create Data in the MATLAB command window before you specify it in GUIDE. For this example, type:

dat =  {6.125, 456.3457, true,  'Fixed';...
6.75,  510.2342, false, 'Adjustable';...
7,     658.2,    false, 'Fixed';};

In the Table Property Editor, select the data that you defined and select Change data value to the selected workspace variable below.

Set Color Properties.   Specify the BackgroundColor and RowStriping for your table in the Color tab.

You can change other uitable properties to the table via the Property Inspector.

Back to Top

Adding ActiveX Controls

When you drag an ActiveX component from the component palette into the layout area, GUIDE opens a dialog box, similar to the following, that lists the registered ActiveX controls on your system.

Note   If MATLAB software is not installed locally on your computer — for example, if you are running the software over a network — you might not find the ActiveX control described in this example. To register the control, see Registering Controls and Servers in the MATLAB External Interfaces documentation.

1. Select the desired ActiveX control. The right panel shows a preview of the selected control.

2. Click Create. The control appears as a small box in the Layout Editor.

3. Resize the control to approximately the size of the square shown in the preview pane. You can do this by clicking and dragging a corner of the control, as shown in the following figure.

   

When you select an ActiveX control, you can open the ActiveX Property Editor by right-clicking and selecting ActiveX Property Editor from the context menu or clicking the Tools menu and selecting it from there.

Note   What an ActiveX Property Editor contains and looks like is dependent on what user controls that the authors of the particular ActiveX object have created and stored in the GUI for the object. In some cases, a GUI without controls or no GUI at all appears when you select this menu item.

See ActiveX Control for information about programming a sample ActiveX control and an example.

Back to Top

Working with Components in the Layout Area

This topic provides basic information about selecting, copying, pasting, and deleting components in the layout area.

• Selecting Components

• Copying, Cutting, and Clearing Components

• Pasting and Duplicating Components

• Front-to-Back Positioning

Other topics that may be of interest are

• Locating and Moving Components

• Resizing Components

• Aligning Components

• Setting Tab Order

Selecting Components

You can select components in the layout area in the following ways:

• Click a single component to select it.

• Press Ctrl+A to select all child objects of the figure. This does not select components that are child objects of panels or button groups.

• Click and drag the cursor to create a rectangle that encloses the components you want to select. If the rectangle encloses a panel or button group, only the panel or button group is selected, not its children. If the rectangle encloses part of a panel or button group, only the components within the rectangle that are child objects of the panel or button group are selected.

• Select multiple components using the Shift and Ctrl keys.

In some cases, a component may lie outside its parent's boundary. Such a component is not visible in the Layout Editor but can be selected by dragging a rectangle that encloses it or by selecting it in the Object Browser. Such a component is visible in the active GUI.

See Viewing the Object Hierarchy for information about the Object Browser.

Note   You can select multiple components only if they have the same parent. To determine the child objects of a figure, panel, or button group, use the Object Browser.

Copying, Cutting, and Clearing Components

Use standard menu and pop-up menu commands, toolbar icons, keyboard keys, and shortcut keys to copy, cut, and clear components.

Copying.   Copying places a copy of the selected components on the clipboard. A copy of a panel or button group includes its children.

Cutting.   Cutting places a copy of the selected components on the clipboard and deletes them from the layout area. If you cut a panel or button group, you also cut its children.

Clearing.   Clearing deletes the selected components from the layout area. It does not place a copy of the components on the clipboard. If you clear a panel or button group, you also clear its children.

Pasting and Duplicating Components

Pasting.   Use standard menu and pop-up menu commands, toolbar icons, and shortcut keys to paste components. GUIDE pastes the contents of the clipboard to the location of the last mouse click. It positions the upper-left corner of the contents at the mouse click.

Consecutive pastes place each copy to the lower right of the last one.

Duplicating.   Select one or more components that you want to duplicate, then do one of the following:

• Copy and paste the selected components as described above.

• Select Duplicate from the Edit menu or the pop-up menu. Duplicate places the copy to the lower right of the original.

• Right-click and drag the component to the desired location. The position of the cursor when you drop the components determines the parent of all the selected components. Look for the highlight as described in Adding a Component to a Panel or Button Group.

Front-to-Back Positioning

MATLAB figures maintain separate stacks that control the front-to-back positioning for different kinds of components:

• User interface controls such as buttons, sliders, and pop-up menus

• Panels, button groups, and axes

• ActiveX controls

You can control the front-to-back positioning of components that overlap only if those components are in the same stack. For overlapping components that are in different stacks:

• User interface controls always appear on top of panels, button groups, and axes that they overlap.

• ActiveX controls appear on top of everything they overlap.

The Layout Editor provides four operations that enable you to control front-to-back positioning. All are available from the Layout menu, which is shown in the following figure.

• Bring to Front — Move the selected object(s) in front of nonselected objects (available from the right-click context menu, the Layout menu, or the Ctrl+F shortcut).

• Send to Back — Move the selected object(s) behind nonselected objects (available from the right-click context menu, the Layout menu, or the Ctrl+B shortcut).

• Bring Forward — Move the selected object(s) forward by one level, i.e., in front of the object directly forward of it, but not in front of all objects that overlay it (available from the Layout menu).

• Send Backward — Move the selected object(s) back by one level, i.e., behind the object directly in back of it, but not behind all objects that are behind it (available from the Layout menu).

Note   Changing front-to-back positioning of components also changes their tab order. See Setting Tab Order for more information.

Back to Top

Locating and Moving Components

You can locate or move components in one of the following ways:

• Using Coordinate Readouts

• Dragging Components

• Using Arrow Keys to Move Components

• Setting the Component's Position Property

Another topic that may be of interest is

• Aligning Components

Using Coordinate Readouts

Coordinate readouts indicate where a component is placed and where the mouse pointer is located. Use these readouts to position and align components manually. The coordinate readout in the lower right corner of the Layout Editor shows the position of a selected component or components as [xleft ybottom width height]. These values are displayed in units of pixels, regardless of the coordinate units you select for components.

If you drag or resize the component, the readout updates accordingly. The readout to the left of the component position readout displays the current mouse position, also in pixels. The following readout example shows a selected component that has a position of [35, 30, 180, 180], a 180-by-180 pixel object with a lower left corner at x=35 and y=30, and locates the mouse position at [200, 30].

When you select multiple objects, the Position readout displays numbers for x, y, width and height only if the objects have the same respective values; in all other cases it displays 'MULTI'. For example, if you select two check boxes, one with Position [250, 140, 76, 20] pixels and the other with position [250, 190, 68, 20] pixels, the Position readout indicates [250, MULTI, MULTI, 20].

Dragging Components

Select one or more components that you want to move, then drag them to the desired position and drop them. You can move components from the figure into a panel or button group. You can move components from a panel or button group into the figure or into another panel or button group.

The position of the cursor when you drop the components also determines the parent of all the selected components. Look for the highlight as described in Adding a Component to a Panel or Button Group.

In some cases, one or more of the selected components may lie outside its parent's boundary. Such a component is not visible in the Layout Editor but can be selected by dragging a rectangle that encloses it or by selecting it in the Object Browser. Such a component is visible in the active GUI.

See Viewing the Object Hierarchy for information about the Object Browser.

Note   To select multiple components, they must have the same parent. That is, they must be contained in the same figure, panel, or button group.

Using Arrow Keys to Move Components

Select one or more components that you want to move, then press and hold the arrow keys until the components have moved to the desired position. Note that the components remain children of the figure, panel, or button group from which you move them, even if they move outside its boundaries.

Setting the Component's Position Property

Select one or more components that you want to move. Then open the Property Inspector from the View menu or by clicking the Property Inspector button .

1. In the Property Inspector, scroll to the Units property and note whether the current setting is characters or normalized. Click the button next to Units and then change the setting to inches from the pop-up menu.

   

2. Click the + sign next to Position. The Property Inspector displays the elements of the Position property.

   

3. If you have selected

   • Only one component, type the x and y coordinates of the point where you want the lower-left corner of the component to appear.

   • More than one component, type either the x or the y coordinate to align the components along that dimension.

4. Reset the Units property to its previous setting, either characters or normalized.

Note   Setting the Units property to characters (nonresizable GUIs) or normalized (resizable GUIs) gives the GUI a more consistent appearance across platforms. See Cross-Platform Compatible Units for more information.

Back to Top

Resizing Components

You can resize components in one of the following ways:

• Dragging a Corner of the Component

• Setting the Component's Position Property

Dragging a Corner of the Component

Select the component you want to resize. Click one of the corner handles and drag it until the component is the desired size.

Setting the Component's Position Property

Select one or more components that you want to resize. Then open the Property Inspector from the View menu or by clicking the Property Inspector button .

1. In the Property Inspector, scroll to the Units property and note whether the current setting is characters or normalized. Click the button next to Units and then change the setting to inches from the pop-up menu.

   

2. Click the + sign next to Position. The Property Inspector displays the elements of the Position property.

   

3. Type the width and height you want the components to be.

4. Reset the Units property to its previous setting, either characters or normalized.

Note   To select multiple components, they must have the same parent. That is, they must be contained in the same figure, panel, or button group. See Selecting Components for more information. Setting the Units property to characters (nonresizable GUIs) or normalized (resizable GUIs) gives the GUI a more consistent appearance across platforms. See Cross-Platform Compatible Units for more information.

Back to Top

Setting the GUI Size

Aligning Components

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS