Qtopia Home - Classes - Hierachy - Annotated - Functions - Qt Embedded |

# Qtopia Style Guide: Widgets

- - Labels
  - Buttons
  - Input fields
    - Text fields
    - Number fields
  - Tabs
  - Lists
  - Menus
    - Menu names
    - Menu-like dialogs
  - Dialogs
  - Custom widgets

### Labels

The rules listed below should be followed when creating a label:

- No labels should have ":" appended.
- There should never be a blank label listed in or for any widget.
- All labels should conform to the Naming conventions.
- Text labels should be left aligned (non-semitic languages).

Please utilize the Currently used label names table to keep labels consistent across applications.

### Buttons

Button labels should follow the same labeling scheme described in Labels section.

For some applications it is desirable to associate keypad keys to buttons displayed in the applications (as is done in the the stopwatch/clock application) this is not recommended but if it must be done the label should include the associated keys label.

### Input fields

The Copy and Paste options should be available in all text input fields unless there is sufficient reason not to have these options listed.

When the using the multitap input method pressing the 1 button should display a number of extended characters that are specific to the currently selected dialog.

Note: When using the singletap input method and the field should always start with a capital letter, the first character should automatically be capitalized.

#### Text fields

Input fields should only remember the input type for that specific field (not all widgets of that type).

By default singletap should be enabled in any text input field.

#### Number fields

No characters other than numbers should be allowed in this field. Letters should be appended as labels or combo-boxes where appropriate. For example, "10 mins" should only display "10" and have mins appended as a label.

### Tabs

Tab widgets should be able to gain focus from the user pressing either of the up or down directional pad buttons. When a user has the tab selected pressing the select button should allow the them to proceed to the next available tab. Pressing the up or down directional pad buttons again will return the focus to the dialog, selecting the first or last element in the dialog.

If the user presses either of the left or right directional pad buttons while in a tabbed dialog, the user should be able to change the tab with the focus shifting to the tab's label/icon.

### Lists

A list may be displayed as an icon while it is not selected but when the list is opened the icon and label should be displayed with the icon displayed.

The default focus when opening a list should be on the item that the list was set to prior to opening.

If the list allows the user to select a blank item then the blank item should be listed as blank ie. not use a label such as "blank" or <none>. List items that display additional dialogs when they are selected should simple list a "..." option.

### Menus

The ordering of items in a menu must be based of the following ordering:

- New
- Edit
- Modify commands, e.g. Crop
- Delete
- Action commands, e.g. Beam, Duplicate, Copy, Paste
- View commands, e.g. Today, View Category...
- Options commands, e.g. Settings
- (separator)
- Help (added by system)
- Cancel

When the selection of a menu item leads to a new dialog, the menu item label should only be suffixed with "..." if the command is being further refined. In other words, the "..." extension should only be placed on the end of menu names when a selection of items is going to be offered or additional commands have to be specified. No space should be left between the first '.' and the last character of the menu name. Please refer to Using the "..." label for a full explanation.

Note: Application menu labels should not be appended with the type of item on which they are performing the action. For example, only "Edit" is required on the menu label, not "Edit Event".

- Menu options should be hidden when unavailable.
- A menu should have the top-most item selected by default.
- A menu separator should be used to group options that perform associated functionality such as New, Edit and Delete.
- Menus with predefined names such as Cancel should use the appropriate icon.

Where an application is structured as a list of items and selecting an item shows its details, the menu for the list should not include any actions that are directly related to a single item. Actions that are applied to an individual item (and never to a list) should be placed in the menu that becomes available when the details of an item are shown. (Menu, Down-past-New, Select-Edit is just as many steps as Select-Item, Menu, Select-Edit).

When particular widgets are selected the context menu may change its option list. Promoting this functionality is not recommended.

#### Menu names

Menu names should follow all conventions found in the Naming conventions.

An acronym or abbreviation for a menu item should only be used if the label doesn't fit on the screen OR if an acronym or abbreviation already exists for the current label (promotes consistency in the use of text labels).

#### Menu-like dialogs

Some dialogs consist of a list of items, only one of which the user needs to select in order to complete an operation. In a small number of cases the user may wish to do more with the item, such as edit it via the menu.

Such list dialogs are Menu-like Dialogs, and should behave like menus:

- Highlighting an item should have no long-term effect.
- Selecting an item should close the window and return to the previous view (even if that means closing the application).
- The ContextBar icon for Key_Back should be Cancel, not the usual Back.

To assist in creating Menu-like dialogs you can call the function

QPEApplication::setMenuLike();

which will map the context bar and menu correctly for the dialog.

If the dialog has a menu, consider having 'Activate', or 'Select' in the menu, but make sure that this command does not close the dialog.

Examples: Profile selection, Speed dial action selection.

### Dialogs

A Dialogs title should describe the process that is currently taking place in the dialog. For example, "Editing event", "Creating event". A dialog title should not have its text appended with "...".

Message dialogs that allow a positive or negative response should be phrased such that the user can answer "Yes" or "No", rather than "OK" or "Cancel".

Informative Message dialogs should only allow the Back/ Done context bar option.

### Custom widgets

Well defined widgets (ie. those defined in qt) should always be used where possible. If a custom widget must be used, make sure that such a widget doesn't already exist. Ie. Time input widgets.