Motif and Common Desktop Environment: Style Guide Reference Migration Version

Motif and CDE 2.1 Style Guide Reference

Controls, Groups, and Models (CDE)

Reference

Description

Controls and groups are components that the user interacts with in CDE. Models are guidelines for the layout and functionality of controls.

Guidelines

Required

Check buttons should only select settings that are not mutually exclusive. A check button graphically indicates its state with the presence or absence of a check mark.

Required

When the user presses the SELECT button in a check button, display the check button with armed emphasis. If the check button was previously unset, show it in the set state. If the check button was previously set, show it in the unset state.

Pressing the SELECT button arms a check button; releasing the SELECT button shows the result of activating it.

Required

When the user releases the SELECT button in the same check button in which the press occurred:

If the check button was previously unset, set it.

If the check button was previously set, unset it.

In all cases, disarm the check button and, if the check button is in a menu, unpost the menu. When the user releases the SELECT button, activate the check button.

Required

When the user presses Enter or Return in a check button, if the check button is in a window with a default action, activate the default action. If the check button is in a menu:

If the check button was previously unset, set it.

If the check button was previously set, unset it.

In both cases, disarm the check button and unpost the menu.

Required

When the user presses Select or Spacebar in a check button, if the check button was previously unset, set it. If the check button was previously set, unset it. In both cases, disarm the check button and, if the check button is in a menu, unpost the menu.

Required

In a list that can be scrolled, such as a scrollable list box, do not allow the cursor to wrap.

Required

Provide vertical scroll bars when some of the data is not visible in the combination box.

Recommended

Provide horizontal scroll bars when elements are wider than the list box.

Recommended

Display the elements in an order that is meaningful to the user.

Recommended

Display an initial value from the list in the text-entry field. Display selected emphasis on the initial value so that typed text will replace the value.

Recommended

Make the combination box large enough to display a minimum of six list items at a time.

Recommended

When a user increases the size of the window in which the combination box is displayed, increase the number of items displayed in the combination box.

Recommended

When a user decreases the size of the window in which the combination box is displayed, decrease the number of items displayed in the combination box. As a minimum, reduce the combination box to the text-entry field and a list box with one entry displayed. If the window is sized so that two list items cannot be displayed, clip the combination box.

Required

If your application uses a command box, include a text component with a command-line prompt for text input and a list component for a command history area. Use either the single selection or browse selection model.

Required

When an element of a command box list is selected, place its contents in the text area.

Required

Make the list navigation actions ^, V, Ctrl Begin, and Ctrl End available from the text component so the user can move the cursored element within the list and thus change the contents of the text.

Required

The default action of the command box should pass the command in the text area to the application for execution and add the command to the end of the list.

Required

If your application uses a file selection dialog box, it should contain the following components:

A directory text component that shows the current directory path. The user can edit the directory text component and press Return or Enter to change the current directory.

For applications that allow saving to different formats, an option button that allows users to specify the format when saving a file.

A file name text component for displaying and editing a file name. This component is optional when the file selection box is used to choose an existing file or directory.

A group of push buttons, including a command button, and Update, Cancel, and Help buttons. The command button is typically labeled Open or Save, but if there is another label that better describes the resulting action (such as Include), use that label. Activating the command button carries out the corresponding action and dismisses the file selection box.

Recommended

When the file selection box is used to specify an existing file (for example, to open a document), the command button is normally labeled Open and it should be the default action.

Recommended

If the Update button is activated while a directory is selected in the contents list, open the directory, display its contents in the contents list, and update the directory text.

Required

If the Open button is activated while the appropriate file is selected in the contents list, the file should be utilized by the application and the file selection box dismissed.

Recommended

When the file selection dialog box is used to choose an existing directory (for example, to install a set of files into the chosen directory) or to specify a new directory, the command button should be given an appropriate label, such as Install, Choose, Create, or OK. If this button is activated while the appropriate directory is selected in the contents list, the directory should be utilized by the application and the file selection box dismissed.

Required

When the file selection dialog box is used to choose an existing directory, there must also be an additional button, labeled Update, that is enabled whenever a directory is selected in the contents list and that opens the directory. Make this Update button the default action.

Recommended

When the file selection dialog box is used to specify a new file name (for example, a Save As dialog box), label the command button Save and make it the default action.

Optional

When the file selection dialog box is used to choose an existing file, show files in the contents list but disable them. Double-clicking the SELECT button on a disabled file name should have no effect.

Required

Make the normal text navigation and editing functions available in the text components for moving the cursor within each text component and changing the contents of the text. These actions provide a convenient way to choose a directory or file name from the corresponding list while focus remains in the text component.

Required

When the user double-clicks the SELECT button on an item in the contents list, select that item and activate the default action. In all cases, double-clicking the SELECT button on a directory in the contents list should open that directory and display its contents in the contents list (the default action is Open).

When the file selection box is used to choose an existing file and the user double-clicks the SELECT button on an appropriate file in the contents list, choose that file and dismiss the file selection box (the default action is Open).

When the file selection box is used to choose an existing directory or to specify a new directory or file, the files list should not appear.

Required

Make the normal text navigation and editing functions available in the text components for moving the cursor within each text component and for changing the contents of the text.

Optional

Allow the user to select a file by scrolling through the list of file names and selecting the desired file or by entering the file name directly into the file selection text component. Selecting a file from the list should cause that file name to appear in the file selection text area.

This method of selecting a file needs to be consistent across applications.

Required

Make use of a selection when one of the following occurs:

The user activates the command push button while an appropriate item is selected in the contents list

The user double-clicks the SELECT button on an appropriate file in the contents list

The user presses Return or Enter while the file name text component has keyboard focus and contains an appropriate item

Required

Make the file selection box display the contents of a directory in the contents list when the file selection box is initialized, when the user presses Enter or Return in the directory text component, and when the user opens a directory in the contents list. Update the contents list each time the contents of the directory changes.

Recommended

If the user has opened the application without supplying a file name argument, the Open dialog box should use the user's home directory as the default directory.

An exception to this rule might be made if a clearly more useful directory can be identified; for example, the icon editor might default to HomeDirectory/.dt/icons. For applications that allow editing, never default to a directory in which the user does not have read and write permission, such as /usr/dt/bin.

Required

If the user has opened the application with a file name argument, the Open dialog box should default to the directory in which that file resides.

Optional

When using the file selection dialog box in Save As capacity, provide a default name of Untitled, place the location cursor in the file name field and highlight the file name text to create a "delete pending type-in" mode. If the current directory already has a file of that name, create a name Untitled2, and so forth.

Optional

When using the file selection dialog box in a Save As capacity, add a file name extension if the application supports file typing by extension, and make this extension visible in the file name field. Do not highlight the extension to create a "delete pending type-in" mode, but allow the user to modify the extension or to delete it explicitly.

Optional

The file selection dialog box should come up in a directory that makes sense for the task. For example, when saving a new file from an editor, the file selection box should come up in the user's home directory. If the user navigates to some other directory within the file selection box, the application should remember that directory the next time it is brought up.

Optional

Never allow the user to overwrite an existing file through the file selection box without providing a warning dialog box prompt.

Optional

Place keyboard focus in the file name field each time the user brings up a file selection dialog box.

Optional

Present directory and file name lists alphabetically, case insensitive. The first item on the directory list should be the parent directory and it should be labeled "..".

Optional

Create clear labels. In the English language, use the labels in Table 10 for the file selection dialog box fields and lists.

Table 10. File Selection Dialog Box Labels

Component	Label
Directory text field	Enter Path or Folder Name:
Filter text field	Filter:
Directory list	Folders:
Contents list	Files:
File text field	Enter File Name:*

Application developers can make this label more instructive and specific, such as Enter File to Open for Open dialog boxes.

These labels should be the default labels. If they are not set by default, you need to set them through resources in your application's app-defaults file.

Required

Within a list component, pressing ^ moves the location cursor to the previous item in the list, and pressing V moves the location cursor to the next item in the list. In a scrollable list, pressing < scrolls the list one character to the left, and pressing > scrolls the list one character to the right.

Required

Within a list component, pressing Ctrl Begin moves the location cursor to the first item in the list, and pressing Ctrl End moves the location cursor to the last item in the list. In a scrollable list, pressing Begin moves the horizontal scroll region so that the leftmost edge of the list is visible, and pressing End moves the horizontal scroll region so that the rightmost edge of the list is visible.

Required

Within a scrollable list, pressing Page Up moves the location cursor to the item one page up in the list, and pressing Page Down moves the location cursor to the item one page down in the list. In a scrollable list, pressing Page Left (or Ctrl Page Up) scrolls the list one page to the left, and pressing Page Right (or Ctrl Page Down) scrolls the list one page to the right.

Required

Within a list component, clicking the SELECT button selects the item that was double-clicked and then initiates any default action for the window.

Required

If your application uses option buttons, make the label for the button the last selection made from the option button.

Required

When the user presses the SELECT button or the MENU button on an option button, post the associated option menu.

Required

When the user releases the SELECT button or the MENU button within the same option button that the press occurred in, post the associated option menu if it was not posted at the time of the press. When the user releases the SELECT button or the MENU button outside of the option button, unpost the associated option menu.

Required

When the user presses Select or Spacebar in an option button, post the associated option menu.

Required

If your application uses paned windows, they should be composed of any number of groups of components, called panes, each separated by a sash and a separator. Group the panes, sashes, and separators linearly, either horizontally or vertically. A sash is the handle on a separator between two panes that is used to adjust the position of the separator.

Required

The ^, V, >, and < directional keys navigate among components in a panel.

A panel group organizes a collection of basic controls in a horizontal, vertical, or two-dimensional layout. The directional keys are used to navigate among the controls.

Required

When the user presses the SELECT button in a push button, arm the push button. When the user releases the SELECT button in the same push button where the press occurred, disarm and activate the push button. When the user releases the SELECT button outside the push button, disarm but do not deactivate the push button.

Required

When the user presses Enter or Return in a push button that is in a window with a default action, activate the push button. When the user presses Enter or Return in a push button in a menu, activate the push button and unpost the menu.

Required

When the user presses Select or Spacebar in a push button, activate the push button. If the push button is in a menu, unpost the menu.

Required

If your application uses radio buttons, graphically indicate each button's state.

Required

When the user presses the SELECT button in a radio button, the radio button is armed. If the radio button was previously unset, show it in the set state.

Required

When the user releases the SELECT button in the same radio button where the press occurred, and the radio button was previously unset, set it and unset any other radio button in the same panel that was previously set. Disarm the radio button and, if the radio button is in a menu, unpost the menu.

Required

When the user presses Enter or Return in a radio button, if the radio button is in a window with a default action, activate the default action. If the radio button is in a menu:

If the radio button was previously unset, set it and unset any other radio button in the same panel that was previously set.

Disarm the radio button and unpost the menu.

Required

When the user presses Select or Spacebar in a radio button, if the radio button was previously unset, set it and unset any other radio button in the same panel that was previously set. Disarm the radio button and, if the radio button is in a menu, unpost the menu.

Required

Within a paned window, a sash adjusts the position of a separator, which adjusts the sizes of the panes next to it. As a sash is moved, make the pane in the direction of the sash movement get smaller and the opposite pane get larger by an equal amount.

Required

Within a sash, pressing the SELECT button or the TRANSFER button and moving the pointer causes the sash to track the movement of the pointer. In a vertically oriented paned window, the sash tracks the vertical position of the pointer. In a horizontally oriented paned window, the pane tracks the horizontal position of the pointer.

Required

Pressing ^ or V (for a sash that can move vertically) and < or > (for a sash that can move horizontally) moves the sash one increment in the specified direction.

Required

Pressing Ctrl ^ or Ctrl V (for a sash that can move vertically) and Ctrl < or Ctrl > (for a sash that can move horizontally) moves the sash one large increment in the specified direction.

Required

If a scale has arrow buttons, pressing the SELECT button on an arrow button moves the slider one increment in the direction of the side of the slider on which the button was pressed and autorepeats until the button is released.

Required

In a scale trough, if the scale has tick marks, pressing the SELECT button moves the slider one major tick mark in the direction of the side of the slider on which the trough was pressed and autorepeats until the button is released. If the scale does not have tick marks, pressing the SELECT button in the trough moves the slider one large increment in the direction of the side of the slider on which the trough was pressed and autorepeats until the button is released.

Required

Within a scale slider, pressing the SELECT button and moving the pointer causes the slider to track the position of the pointer. In a vertical scale, the slider tracks the vertical position of the pointer. In a horizontal scale, the slider tracks the horizontal position of the pointer.

Required

Within a scale slider or trough, pressing the TRANSFER button and moving the pointer positions the slider to the point of the button press and then causes the slider to track the position of the pointer. In a vertical scale, the slider tracks the vertical position of the pointer. In a horizontal scale, the slider tracks the horizontal position of the pointer.

Required

If a mouse-based sliding action is in progress, pressing Cancel cancels the sliding action and returns the slider to its position prior to the start of the sliding operation.

Required

In a vertical scale, pressing ^ or V moves the slider one increment in the specified direction. In a horizontal scale, pressing > or < moves the slider one increment in the specified direction.

Required

In a vertical scale, pressing Ctrl ^ or Ctrl V moves the slider one large increment in the specified direction. In a horizontal scale, pressing Ctrl < or Ctrl > moves the slider one large increment in the specified direction.

Required

Pressing Begin or Ctrl Begin moves the slider to its minimum value. Pressing End or Ctrl End moves the slider to its maximum value.

Required

Within a scroll bar, pressing the SELECT button in an arrow button moves the slider one increment in the direction of the side of the slider on which the button was pressed and autorepeats until the button is released.

Required

In the trough of a scroll bar, pressing the SELECT button moves the slider one page in the direction of the side of the slider on which the trough was pressed and autorepeats until the button is released.

Required

Within a scroll bar slider, pressing the SELECT button and moving the pointer causes the slider to track the position of the pointer. In a vertical scroll bar, the slider tracks the vertical position of the pointer. In a horizontal scroll bar, the slider tracks the horizontal position of the pointer.

Required

Within a scroll bar slider or trough, pressing the TRANSFER button and moving the pointer positions the slider to the point of the button press and then causes the slider to track the position of the pointer. In a vertical scroll bar, the slider tracks the vertical position of the pointer. In a horizontal scroll bar, the slider tracks the horizontal position of the pointer.

Required

If a mouse-based scrolling action is in progress, pressing the Cancel key cancels the scrolling action and returns the slider to its position prior to the start of the scrolling operation.

Required

In a vertical scroll bar, pressing ^ or V moves the slider one increment in the specified direction. In a horizontal scroll bar, pressing < or > moves the slider one increment in the specified direction.

Required

In a vertical scroll bar, pressing Ctrl ^ or Ctrl V moves the slider one large increment in the specified direction. Pressing Ctrl < or Ctrl > moves the slider one large increment in the specified direction.

Required

Pressing Page Up or Page Down moves the slider in a vertical scroll bar one page in the specified direction. Pressing Page Left (or Ctrl Page Up) or Page Right (or Ctrl Page Down) moves the slider in a horizontal scroll bar one page in the specified direction.

Required

Pressing Begin or Ctrl Begin moves the slider to the minimum value. Pressing End or Ctrl End moves the slider to the maximum value.

Required

If your application uses a selection box, include at least a text component for the selected alternative and a list component above the text component for presenting alternatives. Use either the single selection or browse selection model. Selecting an element from the list should place the selected element in the text component.

Required

Make the list navigation actions ^, V Ctrl Begin, and Ctrl End available from the text component so the user can move the cursored element within the list and thus change the contents of the text.

Required

Present the items as a ring of items that wrap. For example, if a user is at the largest number and presses the up arrow, display the smallest number and vice versa so that the user can spin through all the items by pressing the same arrow.

Required

Move through the items in a spin box as shown in Table 11.

Table 11. Navigation in a Spin Box

Movement	Keys	Example
Toward the beginning of the list	<, V	Chronology: If Tuesday is displayed, move to Monday when the user presses < or V .
		Magnitude: If 15 is displayed, move to 14 when the user presses < or V .
Toward the end of the list	>, ^	Chronology: If Tuesday is displayed, move to Wednesday when the user presses > or ^ .
		Magnitude: If 15 is displayed, move to 16 when the user presses > or ^ .

Recommended

Allow the user to set values with the arrow buttons or through keyboard input. Values should be evaluated immediately upon entry. If a value is entered that is already in the list, scroll to the position of that entry in the list.

Recommended

If entry of nonlisted items is permitted, use the following behavior: when a new value is entered, scroll the list to the position appropriate for the new entry; if the user scrolls off the new entry, scroll to the next appropriate value in the list and dismiss the keyboard-entered value.

Recommended

On entry of an invalid value, provide an auditory warning and error message.

Required

In a multiline text component, pressing ^ moves the location cursor up one line and pressing V moves the location cursor down one line. In a single-line text component, pressing ^ navigates upward to the previous component and pressing V navigates downward to the next component, if the text component is designed to act like a basic control.

Required

Pressing < moves the location cursor left one character and pressing > moves the location cursor right one character.

Required

In a text component generally used to hold multiple words, pressing Ctrl > moves the location cursor to the right by a word and pressing Ctrl < moves the location cursor to the left by a word.

Required

In a text component generally used to hold multiple words, pressing Begin moves the location cursor to the beginning of the line and pressing End moves the location cursor to the end of the line.

Required

In a multiline text component, pressing Ctrl Begin moves the location cursor to the beginning of the file and pressing Ctrl End moves the location cursor to the end of the file.

Required

Pressing Spacebar or Shift Spacebar inserts a space in a text component. Modifying these keys with Ctrl invokes the normal selection function.

Required

Pressing Return in a multiline text component inserts a carriage return. Pressing Enter or Ctrl Return invokes the default action.

Required

In a multiline text component, Tab is used for tabbing. In a single-line text component, Tab is used either for tabbing or to move to the next field.

Required

If a text component supports replace mode, insert toggles between insert mode and replace mode.

By default, the component should start in insert mode, where the location cursor is between two characters. In insert mode, typing a character inserts the character at the position of the location cursor.

In replace mode, place the location cursor on a character. Typing a character replaces the current character with the newly entered character and moves the location cursor to the next character, selecting it.

Required

Double-clicking the SELECT button selects text a word at a time.

Required

A gauge is a display-only device and should have no user interactions. The appearance of a gauge is similar to a scale, but the gauge lacks a scale slider.

Optional

Despite being a display-only device, a gauge should get keyboard focus so that the user can access Help or settings for that control.

Essential Related Topics

For more information, see the Control and Selection Models reference pages.

Supplemental Related Topics

For more information, see the Data Transfer and Selection reference pages.