GUI Features

Characters Value for Units Property

If you write user interfaces intended to be used on more than one computer platform, you may find that you need to adjust the size of controls to accommodate the differences in the size of the fonts used to label the controls.

For example, this figure shows the same check box defined on three platforms. Because the size of the font differs, the size of the control on one platform isn't suitable for use on another.

All check boxes were created 115 pixels wide and 25 pixels high. As you can see, the width of the check box is suitable for the font used by Microsoft Windows computers. However, the default font used by the UNIX computer is wider and the string does not fit within the control's borders.

To implement consistent user interfaces across platforms, use the characters value for the Units property for uicontrol, root, figure, and axes objects. Using this property value enables you to define the location and size of objects in units that are based on the size of the default system font:

The width of one character unit is the width of the letter x.
The height of one unit is the distance between the baselines of two successive lines of text.

This figure illustrates the width and height of a single character:

In the example above, defining the width of the check box to be 23 (16 characters for the string, seven characters for spacing around the label and for the check box) and the height to be 1.7 (to provide padding between the label and the top and bottom of the check box), generates these controls, arranged to show the difference in size (see below for a discussion of padding).

The command used to create this check box is:

h = uicontrol('Style','checkbox','String','Impulse Response',...
              'Units','characters','Position',[5 5 23 1.7]);

If you use Guide to create the check box, specify the Units and Position properties as in the code above.

The width of a control includes its border, the area required for the string, and, for check boxes and radio buttons, additional space for the selection graphic. As a result, you need to add padding characters to provide enough space to display the string and make it readable. The table below provides guidelines for the number of padding characters for different types of controls. You may need to adjust the padding depending on the width of the characters in the String property value.


Control	Padding of Width	Padding of Height
Check box	7	.7
Edit text	5	.7
List box	5	.7
Popup menu	7	.7
Push button	4	.7
Radio button	7	.7
Static text	4	0

For a static text control, the string appears at the top of the control, so adding space to the height does not affect the placement of the string.

A good graphical user interface design uses controls that have consistent sizes. These statements show how to combine this principle with the use of the characters property value:

pblabel1 = 'Apply';
pblabel2 = 'Revert';
pblabel3 = 'Close';
lenlabel = max(length(pblabel1, pblabel2, pblabel3)) + 7;

Then, when you define the three push buttons, use lenlabel as the third element (the width) in each position vector.

You can also define the position of axes and figure objects in character units to define the layout of the entire GUI based on the size of the default system font.

Tooltips

A tooltip is a small rectangle that contains textual information. A tooltip is associated with a uicontrol and appears below the control when the cursor is held over the control for a certain amount of time (determined by system settings).

Defining a Tooltip

To associate a tooltip with a control, define a text value for the TooltipString property:

In Guide, select the control, then modify its TooltipString property.
In an M-file or in the Command Window, define a value for the TooltipString property.

You can clear the tooltip for a control by assigning an empty string value to the TooltipString property.

Displaying a Tooltip

To display a tooltip, position the mouse pointer over a control and leave it there. If a tooltip is defined for the object, it appears after a short amount of time (the exact amount of time is determined by system settings).

For example, this figure shows a tooltip for a Close push button:

This statement created the tooltip:

cb = uicontrol('Style','pushbutton','String','Close',...
     'TooltipString','Close window');

Toggle Buttons

Toggle buttons have two states, down (selected) and up (unselected). When you click on a toggle button, its state changes and its callback is executed.

Toggle buttons are similar to push buttons except that they retain their state until changed. When you click on a toggle button, these things occur:

The toggle button's state changes, which causes its Value property to change. If the state goes from unselected to selected, Value changes from Min to Max. If the state goes from selected to unselected, Value changes from Max to Min.
The toggle button's callback executes.

Toggle buttons are useful when creating toolbars. Each button on a toolbar can execute a different callback, which can display its own dialog box and menus.

The Max property specifies the value when the state is down, or selected; its default value is 1. The Min property specifies the value when the state is up, or unselected; its default value is 0. The current state is stored in the Value property; its default value is 0, so the starting state of a toggle button is unselected.

These statements create a toggle button and define its callback, which displays a message that indicates the toggle button state.

% Define the toggle button callback
cb = ['if get(tb,''Value'') == 1, disp(''Selected''),',...
      'elseif get(tb,''Value'') == 0, disp (''Unselected''),',...
      'end'];
% Define the toggle button
tb = uicontrol('Style','togglebutton','Callback',cb);

This example changes the selection state of the control:

% This statement makes the toggle button appear selected
% It also causes the callback to execute
set(tb, 'Value', get(tb, 'Max'))

Displaying Truecolor Images on Controls

You can display images on push buttons and toggle buttons using the CData property.

To create a push button with an image, set the CData property to be a truecolor image, an m-by-n-by-3 array containing RGB values. Each value must be within the range 0.0 to 1.0.

For example, this command creates a push button on which is displayed the image defined by the array my_image:

uicontrol('Style', 'pushbutton', 'Position', [100 100 75 30],...
   'CData', my_image);

Context Menus

A context menu is a menu that is attached to an object and is activated by a right-button click. This action is called an extend-click.

For example, this figure shows a simple plotted line. When you right-click anywhere on the line, a context menu appears, providing three choices. Selecting a menu item from the context menu executes a callback that changes the line style.

Implementing a context menu involves these steps:

1.: Creating the context menu object.

2.: Defining the context menu items and their callbacks.

3.: Associating the context menu with one or more objects.

Creating the Context Menu

Each context menu is an object and is created using the uicontextmenu function. For example, this statement creates a context menu and assigns its handle to cm:

cm = uicontextmenu;

You can specify the Callback and Visible properties.

The Callback property specifies the callback routine for the context menu (not for the individual menu items). The callback routine is called immediately after the right-click but before the context menu becomes visible. Defining a callback routine for a context menu gives you the opportunity to modify the menu's contents before it appears. A callback routine for a context menu might be useful when the context menu items depend on the state of the application when the context menu is invoked. The default value for the Callback property is ''.

The Visible property determines or indicates whether the context menu is posted. The property is normally controlled automatically, returning 'on' when the menu is posted as a result of a right-click and 'off' after a menu item has been selected and the context menu is withdrawn. You can use the property to force the context menu to be posted without a menu click or to be withdrawn before an item is selected.

The uicontextmenu object is a child of the figure and the parent of the uimenu objects that define its contents.

Defining Context Menu Items

You define context menu items using the uimenu function:

uimenu(handle, 'Label', 'string', 'Callback', value)

Each uimenu statement adds one menu item to the context menu identified by handle. The order of the menu items is the same as the order of the uimenu statements. These statements add menu items to the context menu shown in the example above and define their callbacks:

% Define context menu
cm = uicontextmenu;
% Define context menu item callbacks
cb1 = ['set(hline,''LineStyle'',''--'')'];
cb2 = ['set(hline,''LineStyle'','':'')'];
cb3 = ['set(hline,''LineStyle'',''-'')'];
% Define context menu items
item1 = uimenu(cm, 'Label', 'dashed', 'Callback', cb1);
item2 = uimenu(cm, 'Label', 'dotted', 'Callback', cb2);
item3 = uimenu(cm, 'Label', 'solid', 'Callback', cb3);

Associating the Context Menu with an Object

To associate a context menu with an object, the statement that creates the object must reference the context menu using the UIContextMenu property. The form of the property name/property value pair is

'UIContextMenu', object_handle

In the example above, these statements create the line object and associate it with a context menu, whose handle is cm:

hline = plot(1:10);
set(hline, 'UIContextMenu', cm)

Callback Execution Order

When you extend-click in a figure, these steps are performed:

1.: A hit test is performed to determine the object clicked on.

2.: The CurrentPoint is set to the point on which the button down action occurred.

3.: The SelectionType is set to alt.

4.: The CurrentObject is set to the object found during the hit test (step 1).

5.: The figure's WindowButtonDownFcn callback is executed, then the current object's ButtonDownFcn is executed. (Note that the WindowButtonDownFcn can redefine the CurrentObject property.)

6.: The figure's WindowButtonUpFcn callback is executed.

7.: If the current object is associated with an enabled context menu,

Executing the figure's WindowButtonUpFcn callback before posting the context menu enables applications to display a context menu depending on the results of the WindowButtonUpFcn and WindowButtonMotionFcn callbacks, if defined.

When the context menu is removed (when you select a menu item and that menu item's callback is executed), all variables associated with the callbacks are cleared.

[ Release 11 New Features | Help Desk ]