OpieStyleGuide

= Opie Style and Application Guide =

= Introduction = This document describes the rules to be followed when designing an application for Opie. The focus is on consistency, think very carefully before departing from the preferred style.

Why follow guidelines?
( From http://www.palmos.com/dev/support/docs/ui/UI_Intro.html#918034 )

Designing a proper user interface may feel at first like you are "wasting" a lot of time agonizing over the user interface rather than focusing on the nuts and bolts of your application. While most developers acknowledge the importance of user interface design, it's easy to let design take a back seat until the application is working properly. If you do take the time to get the interface right, however, you'll achieve greater success in the long run.

Consider as a case study the success the Palm Powered handheld has had compared to its major competitor, the Pocket PC handheld. The Palm Powered handheld was not the first handheld on the market, but it was the first one to be successful because it focused on giving users what they wanted. Palm OS was designed from the ground up with users in mind. Designers focused on what users would want to do with a handheld and provided just that functionality (emphasis added.) More features are added only when doing so does not diminish the overall user experience.

In contrast, the first versions of the Windows Pocket PC operating system were designed by stuffing as many features of a desktop Windows system as possible into a pocket-sized form factor. (emphasis added.) The resulting user experience has been so negative that it has forced the designers back to the drawing board more than once.

Windows Pocket PC handhelds have been on the market for more than three years. Only recently have those devices begun to gain acceptance. In the meantime, 17.5 million Palm Powered handhelds have been sold compared to 2 million Pocket PC handhelds

= Design principles =

( The following design principles have been quoted and adapted from http://www.palmos.com/dev/support/docs/ui/UI_Design.html )

Focus of your design
Priorities include the ability to:


 * Execute key commands quickly
 * Navigate to key screens quickly
 * Find key data quickly (for example, phone numbers)

Less Is More
To save space, sacrifice features that don't belong on a handheld. On a desktop system, users use 20% of an application's features 80% of the time. Your application should provide only that top 20% of features. Save any other functionality for the desktop application.

On a desktop system, it's easy to just add another button to the button toolbar or add another menu. For a Opie application, you'll have to resist that temptation. Otherwise, your screen becomes too cluttered, and your application becomes too complicated to use.

Perceived Speed Is Important
On a desktop, users don't mind waiting a few seconds while an application loads because they plan to use the application for an extended amount of time. On a handheld, users want to quickly look something up and then go on about their lives, and they do this several times a day

Optimize your application to these short bursts of user activity. Remember that requiring a user to spend an extra 30 seconds to find necessary information is excusable when they are sitting down for 3 hours at a desktop computer but cumbersome on a handheld when that is the only thing they are going to do before they turn it off.

As a rule of thumb, the user should be able to keep up with someone on the telephone when setting up appointments, looking up phone numbers, and so on.

Be Consistent
Consistency reduces the time needed to learn an application by limiting the number of things that people need to keep in their heads at once. The user should not have to memorize an entire set of rules to use the handheld easily. For example, the up arrow key should not do different things on different screens.

Minimize Required Steps
Minimize the number of steps a user must perform to see vital information. Display the most essential information on the first screen of the application.

Reduce clutter so that users will find the information they need quickly. Strive for a balance between providing enough information and overcrowding the screen.

Place command buttons on the first screen that perform the tasks the user will want to perform most often. Accomplishing common tasks should be fast and easy.

Choose the number of buttons on the screen carefully:


 * The fewer buttons on the screen, the less time it takes to learn how to use the product. If there are too many buttons, users are forced to hunt and peck to find what they need until they eventually learn the placement of each button.
 * On the other hand, keeping a few frequently used buttons on screen helps reduce the time spent learning basic functionality.

Minimize Taps
Most information about that data should be accessible in a minimal number of taps of the stylus ? one or two.

Desktop user interfaces are typically designed to display commands as if they were used equally. In reality, some commands are used very frequently while most are used only rarely. Similarly, some settings are more likely to be used than others. On Palm Powered handhelds, more frequently used commands and settings should be easier to find and faster to execute.


 * Frequently executed software commands should be accessible by one tap.
 * Infrequently used or dangerous commands may require more user action.

This table shows how the frequency of an action maps to its accessibility in the Date Book application.

Frequency of actions

||Frequency||Example||Accessibility|| ||Several times per day||Checking today's schedule or to-do items||One tap|| ||Several times per week||Scheduling a one hour meeting starting at the top of the hour||One tap, write in place|| ||A few times a month||Setting a weekly meeting (repeating event)||Several taps, second dialog box||

This goal of minimizing taps can be taken too far. It must be balanced with other guidelines. For example, using a command button generally minimizes the taps to perform a command, but if you have too many buttons, you overcrowd the screen and introduce confusion into the interface.

Some designers break the behavior guidelines for a particular element for the sole purpose of minimizing taps. User interface elements should behave the way users expect them to behave unless the

= Naming conventions =

All words should start with a capital letter with the exception of words that are usually excluded from acronyms such as "of", "and", or "to". These extremely common words are referred to as stop words.

Once a certain name is used for a specific item it should be re-used in each and every application. For example: if Contacts and Calendar both have a "company" info field they should use the same label. This means both applications use either "Company", "Cmpny", or "Comp.". Please see the used label names table for reference.

String styles (from KDE)
There are two major styles for capitalizing labels, book title and sentence style. Some people argue back and forth how one style is more readable than the other, but what plays the deciding role here is information hierarchy and consistency.

Book title capitalization
Book title capitalization capitalizes the first letter of a single-word item. Capitalization of a multi-word item should be based on title capitalization in the native language. Thus, in English the first letter of the first and last words should always be capitalized and the first letter of all intervening words should all be capitalized except for (i) prepositions having less than five letters, except "From", which should be capitalized (e.g. "for", "in", "with" or "to", but "From" or "Under"), (ii) conjunctions ("and", "or" and "but") and (ii) articles ("the", "a" and "an"). In short titles (buttons, menus) articles are usually dropped and "and" is replaced with "&".

Sentence style capitalization
Follow spelling and grammar of the native language.

Widget that should use Book title capitalization

 * window and dialog box titles
 * group box / group line labels
 * button labels
 * tab labels
 * listview column headers
 * menu titles / menu items
 * combobox items
 * listbox items
 * tree list items
 * other heading/title text

Widget that should use Sentence style capitalization

 * edit box labels
 * list box labels
 * combo box labels
 * spin box labels
 * check box labels
 * option button labels
 * spin box labels
 * slider labels
 * pop-up hint text
 * other non heading/title text

Tree list and listbox items that are representative of items found elsewhere in the system, like folders for example, should utilize the capitalization of the represented items.

Example of both

 * Example of Book Title Capitalization
 * Example of sentence style capitalization

Abbreviations
The rules listed below should be followed when using abbreviations:


 * Abbreviations are meant to be self explanatory.
 * An abbreviation point should occur at the end of a word. For example: etc.
 * Abbreviations consisting of initial letters are written as un-spaced and undivided sequences with abbreviation points after each letter. For example:"e.g."
 * Abbreviations should not consist of any characters except a-z A-Z.

NOTE: No abbreviation point is required if the last letter of the word is displayed such as "cmpny".

Acronyms
Acronyms basically follow the same set of rules as those found in the abbreviations section. Always check existing acronyms before creating a new one.

Using the "..." label
The following rules define the use of the ... in association with menu items.


 * if the command has to be refined before a user can initiate an action then yes, use ...
 * if the command does not need to be refined before a user can initiate an action then do not use ...
 * if in doubt, do not apply ... to the menu

Examples of when to use "..."
Use ... only when the menu is followed by another dialog that is a direct and integral continuation of the command.


 * Send All... is appropriate since the next dialog requires the user to select one of Email/Infrared/SMS before anything is sent.
 * View Category... is appropriate since the next dialog requires the user to select which category they want to view.

Examples of when not to use "..."
Do not use "..." when the menu is followed by another dialog that is related to but not a continuation of the command.


 * Edit (without ...) is appropriate if the user is immediately shown the entire record and is free to edit any aspect of it.
 * Delete (without ...) is appropriate since the user does not have to refine the delete command in order for it to work. A please confirm dialog does not specify additional parameters; it is associated with the command but does not refine its functionality.
 * Settings (without ...) should be used when a user is immediately given access to all the features that can be set, such as in the Calendar application.

Group Boxes
Group Boxes should NOT have a ':' at the end of the string.

Labels associated with Buttons
A Label in front of an Option (Button,LineEdit,ComboBox) should have a ':' at the End

= Delayed code execution = ( Much of this section is quoted from http://doc.trolltech.com/qtopia2.0/html/quicklaunch.html )

Application startup time is critical on consumer devices. This document describes techniques for making Qtopia applications startup as quickly as possible.

Making an application startup quickly is closely related to how much code is executed during the startup process. Some of the common operations that can affect startup time are:


 * Loading/parsing configuration files.
 * Ceating user interface components (dialogs, etc.)
 * Reading data files.

The simplest way to improve startup time is to defer some of these operations until after the UI is visible. If possible, perform the operation on demand, for example, do not create a dialog until it is actually needed:

MainWidget::MainWidget( QWidget *parent, const char *name, WFlags f ) : QMainWindow( parent, name, f ), settingsDialog(0) { }

void MainWidget::showSettings {   // If settingsDialog has not yet been created, create it now. if ( !settingsDialog ) settingsDialog = new SettingsDialog( this ); settingsDialog-&gt;exec; }

If the operation is required immediately after the application is visible, a single shot timer may be used to start the processing after the main widget is visible:

MainWidget::MainWidget( QWidget *parent, const char *name, WFlags f ) : QMainWindow( parent, name, f ), settingsDialog(0) {   // After the event queue has been processed and the mainwindow is    // visible, load the data. QTimer::singleShot(0, this, SLOT(loadData)); }

void MainWidget::loadData {   // Open data file and populate data view. }

= Context menus =

Personally, I go back and forth between trying to decide if context menus are even needed. I've come to the conclusion that they certainly are nice, but they should NOT be required to use all application functionality. E.g. any action available on a context menu should be available via other means, be it a menubar, QPushButton, or other.

When implemented on touchscreen devices, context menus should be implemented with low-level notification of the availability of a context menu. Consider the implementation in the latest version of PocketPC: In context-enabled applications (e.g. filebrowser), as soon as the stylus touches the screen, dots begin in a circular pattern. If the stylus is held until pattern completion, the menu appears. If the stylus is removed before completion, no action taken. This is both visible and obvious to the user that the device acknowledges his/her input and is acting upon it.

In the application design comments below, any references to context menu assume that the functionality is also provided by alternate methods discussed above.

= Device-specific design rules = Opie runs on a wide variety of devices. Therefore, it is impossible to create one style guide that will apply across all platforms. Granted, there will be every attempt to maintain consistency in design, yet there will be some elements which will change across platforms, such as menubars, toolbars, and such. For more information about which devices Opie runs on, see the Hardware link at the left.

All devices are assumed have a touchscreen.

This document will handle these differences by grouping devices into the following broad categories:

--

PDA
This device is typically used in "Portrait" orientation (e.g. height greater than width.) Primary method of input is the touch screen, agumented with hardware buttons.

Example devices include:
 * HP iPAQ: 31xx, 36xx, 37xx, 38xx, 39xx, 54xx, 55xx, 22xx
 * Sharp Zaurus: SL 5x00
 * M&N Ramses

(Note: The frame of the window does have a Minimize button - which should NOT be included on a PDA)

Characteristics

 * Screen: 240x320/320x240
 * Buttons: Four-way direction pad (or Five way - arrows + center select), Two function buttons (Ok and Cancel)
 * Pointer: Touchscreen
 * Additional Input: Possibly one to five Shortcut buttons (e.g. Calendar, Contacts, etc.)

Windows
( Non-modal forms )
 * Main GUI area of application

Size

 * All windows should be automatically "maximized," e.g. resized to use the maximum avialable screen space.
 * There is no facility for resizing a window.

Titlebar

 * Title bar contains name of application and a "Close" button
 * At no time will the title bar contain an "Ok" or "Cancel" button (ASIDE: This is open to discussion...Thoughs?)

Menubar/toolbar

 * Dual-function menu bar below title bar will contain up to three menus and up to three tool buttons (icons, no text.)
 * Should NOT contain individual menu bar and tool bar, they should be combined with only the most frequently used actions available as a tool button, limited to three.

Dialogs
( Model forms )
 * Reserved for use where a user must acknowledge a certain state before continuing
 * Should NOT be used for lengthly data entry

Size/position

 * Must be shorter than the screen height
 * Should not take up more than 60% of the screen space
 * Vertically aligned with the bottom of the screen

Titlebar

 * The title bar should not contain ANY buttons, only a Title string ("caption").
 * Ok/Cancel buttons MUST be included as QPushButton or similar control in the body of the dialog

--

Clamshell
This device is typically used in able to be used in either "Portrait" or "Landscape" orientation (e.g. width greater than height.) Primary method of input is the touch screen, agumented with hardware buttons when in "Portrait" orientation (clamshell closed), and keyboard agumented with touchscreen when in "Landscape" orientation (clamshell open.) Typically this device will be able to fold open to reveal a keyboard recessed under the display. Often the device is usable both closed (keyboard hidden) and open (keyboard visible). Often in the "closed" mode, the display is used in "portrait" orientation, when in "open" mode the display is rotated into "landscape" orientation.

Example devices:
 * Sharp Zaurus C7x0, C8x0, C9x0
 * GMate YopY

(This snapshot is the same for both clamshell and webpad right now. I plan on making more details screenshots very soon...)

Characteristics

 * Screen: 640x480/480x640
 * Buttons: Four-way direction pad (or Five way - arrows + center select), Two function buttons (Ok and Cancel)
 * Pointer: Touchscreen
 * Additional Input: Possibly one to five Shortcut buttons (e.g. Calendar, Contacts, etc.) and full QWERTY keyboard

Windows
( Non-modal forms )
 * Main GUI area of application

Size

 * Windows may be resized.
 * Note: The following should be user-configurable behaviours:
 * Preferred: In "portrait" mode, all windows should be automatically maximized.
 * Preferred: In "landscape" mode, windows should be intelligently tiled.

Titlebar

 * Title bar contains name of application, a Maximize/Restore/Minimize button, and a Close button
 * At no time will the title bar contain an "Ok" or "Cancel" button (ASIDE: This is open to discussion...Thoughs?)

Menubar/Toolbar

 * Dual-function menu bar below title bar will contain up to four menus and up to five tool buttons (icons, no text.)
 * May contain individual menu bar and tool bars
 * Tool bars should be docked, not movable.

Dialogs
( Model forms )
 * Should NOT be used for lengthly data entry
 * Reserved for use where a user must acknowledge a certain state before continuing

Size/Position

 * Must not be maximized
 * Should be of a fixed size
 * If in portrait mode, should be vertically aligned with the bottom of the screen, apply size rules from PDA Design, above.
 * If in landscape mode, should be centered over main window, should only take up 60% of screen space.

Titlebar

 * Should NOT display Ok/Canel buttons in the title bar
 * Ok/Cancel buttons MUST be included as QPushButton or similar control in the body of the dialog

--

Webpad
This device typically consists of a large touchscreen (often 5"x5" or greater) as the dominate input device, possibly agumented by several small buttons. This device is often primarly used for viewing content, as opposed to detailed content editing,

Example devices: SIEMENS Simpad: CL4, SL4, SLC, T-Sinus

(This snapshot is the same for both clamshell and webpad right now. I plan on making more details screenshots very soon...)

Characteristics

 * Screen: 640x480/480x460 or 800x600/600x800
 * Primary Input: Touchscreen
 * Additional Input: Possibly four way direction pad, maybe additional user-defined buttons.

Windows
( Non-modal forms )
 * Main GUI area of application

Size/Position

 * Windows may be resized.
 * Windows should be automatically and intellignetly positioned so as to minimize overlap to the greatest extent possible (when automatically positioning, that is.)
 * Windows should be resized to take up the minimum allowed size (according to QSizeHints)

Titlebar

 * IMPORTANT: Titlebar buttons should be designed with screen resolution to screen size considered. E.g. should be large enough target for a stylus to activate easily even with a greater pixel-per-inch resolution.
 * Title bar contains name of application, a Maximize/Restore/Minimize button, and a Close button
 * At no time will the title bar contain an "Ok" or "Cancel" button (ASIDE: This is open to discussion...Thoughs?)

Menubar/Toolbar

 * Menu bars should limit the total number of top-level menus to the most frequently used and general categories.
 * Toolbar buttons should take note of above comments re: screen resoltion and size.
 * May contain individual menu bar and tool bars
 * Toolbars may be movable and dockable and undefined locations.

Dialogs
( Model forms )
 * Reserved for use where a user must acknowledge a certain state before continuing
 * Should NOT be used for lengthly data entry

Size/Position

 * May be maximized
 * Should be of a fixed size
 * Should be centered over main window, should only take up 60% of screen space.
 * If an open dialog already exists, should be intelligently positioned.

Titlebar

 * Should NOT display Ok/Canel buttons in the title bar
 * Ok/Cancel buttons must be included as QPushButton or similar control in the body of the dialog

--

PC
Opie also runs on a wide variety of x86 desktops and laptops. These systems all generally contain NO touch screen and rely on the mouse as the primary pointing device, augmented by a keyboard. Typically the primary display has a user-defined resolution. These systems sometimes have the capibility of displaying on more than one physical display.

Characteristics

 * Screen: User definable resolution, almost always in "landscape" orientation.
 * Primary Input: Mouse
 * Additional Input: Full QWERTY keyboard, direction keys, Enter and Escape keys
 * NO touchscreen (usually.)

GUI design notes
As a whole, the design should optimize for minimum-clicks, while maintaining ease of keyboard navigation.

Windows
( Non-modal forms )
 * Main GUI area of application

Size/Position
( See related section under Webpad, above )
 * Window frame should indicate a resize handle (??)

Titlebar
Title bar contains name of application, a Maximize/Restore/Minimize button, and a Close button

Menubar/Toolbar

 * May contain individual menu bar and tool bars
 * Toolbars may be movable and dockable and undefined locations.

Dialogs
( Model forms ) See same section under Webpad, above.

--

= Application design = ( Much of this section is quoted and adapted from http://doc.trolltech.com/qtopia2.0/html/styleguide.html )

There are two basic styles of application:


 * Document based - Document based applications are used to view and possibly edit a specific document type. Applications such as the "Contacts" or "Tasks" are considered to be document based applications.
 * Task based - A task based application allows a specific task to be performed such as view the time in the case of the Clock application.

Document based applications
The main window of a document based application will present a list of items, or in some cases a list of sub-lists.

Note: The documents are not necessarily individual files. The entries in an address book for instance may be considered documents.

Document based applications should follow a standard navigational flow:


 * 1) List of Lists (if necessary).
 * 2) List of Items.
 * 3) View of a Single Item.
 * 4) Edit Single Item.
 * 5) Deleting a Single Item.

List of Lists
This is rarely needed. It is used when there are a number of lists that behave differently or have some incompatible properties. An example application is the Opie Mail application. This application shows folders that have specific functions. The Outbox, Trash, Inbox, etc. all have particular properties that preclude grouping their items into one list.

The context menu must contain entries that act on all of the lists, and optionally a New entry.

For PDA: The form should contain a Details or an Edit button. The form should also contain a "New" button.

For Clamshell and Webpad usage: The Details/Edit and New button may be optionally moved to a toolbar button and excluded from inclusion in the main form.

Highlighting a list and pressing Select (on five-way direction pads) or Ok displays the List of Items. Pressing Cancel must close the application.

List of items
This is the screen most applications will display when started via the launcher. It lists the documents that the application may view and/or edit. It is recommended that the menu contains a View Category... option to display only the items in the selected category.

The context menu should contain entries that act on all of the items, and optionally a New entry.

For PDA: The form should contain a Details or an Edit button. The form should also contain a "New" button.

For Clamshell and Webpad usage: The Details/Edit and New button may be optionally moved to a toolbar button and excluded from inclusion in the main form.

Highlighting an item and pressing Select or Ok should display a more detailed view of the highlighted item. Pressing Cancel must return to the previous list of items or lists (if present), otherwise close the application.

When an item in the list is used to group or store information; selecting that list item should present the information about that item.

Viewing a single item
This screen displays a single item, and may allow navigation and activation of data within the view.

No context menu should generally be available.

Individual widgets may contain a context menu. See "Widgets" section, below.

The form should contain an Edit (if the item can be edited), Ok, and Cancel QPushButton.

If the view contains elements that can be activated, then the Select key must activate the highlighted element. Pressing Back or Done must return to the list of items.

Editing a single item
This screen allows a single item to be modified. Edit screens must be able to be canceled via the Cancel option found in the context menu.

Note: When a user selects the Done button or hits the Close button on the window and nothing has been altered the button acts as the Cancel button otherwise the item will be stored. More information on this can be found in the ... section.

When creating or editing an item, the first tab must be displayed with the first input widget focused.

There is no context menu available on the form.

Individual widgets may contain a context menu. See "Widgets" section, below.

The form must contain an Ok and a Cancel button.

The form should contain a Delete button.

Pressing Ok button must accept the changes and return to the view. Pressing the Close button on the window must prompt to save if the item has changed. Pressing the Cancel button must discard the changes and return to the view without prompting.

Deleting a single item
An application that can create or edit an item should provide the ability to remove an item of the same type.

The form must contain an Ok and Cancel button.

Items are only able to be deleted when viewing there details hence only one at a time.

Navigational flow
In order to maintain a consistent navigational flow, the following rules must be adhered to:


 * When moving forward (e.g. by pressing Select or selecting Edit from the menu), the displayed screen must be in its initial state. For example, in a list of items the top-most item must be highlighted.
 * When moving back (e.g. by pressing Cancel or selecting the Close widget on the window frame), the previously viewed screen must be displayed in the same state that it was in when left. For example, if item D was highlighted then viewed, pressing Cancel in the view must return to the list with item D still highlighted.
 * The left and right buttons are used for moving between tabs in a tabbed dialog although in some cases they may be used to select widgets that are horizontally aligned.
 * The up and down buttons are used for moving between fields in a dialog.

To edit a field you first have to focus it using the up/down buttons then select it by pressing select.

Note: In case there is no tabbed dialog it is very tempting to give the left and right buttons the same functionality as up and down. We have explicitly chosen NOT to do so in order to keep the user interface as consistent as possible, i.e. maintaining one way of doing things.

Form layout
An input form should provide a simple and familiar way for the user to input data. The basic layout of an input form is a 2 columned table: the first column provides a label for the field found in the same row; the second is the input field.

The basic layout of an input form should remain consistent between all applications. It is also recommended that the same input form is used when creating and editing an item.

Task based applications
These applications allow a specific task to be performed. They do not operate on documents, though they may generate documents. Examples of task based applications are Clock and Calculator.

= Interprocess actions =

When an application is activated via a QCop message in order to view a document, pressing Back or Done must close the application. For example viewing a picture from the Documents launcher will open the picture in the Pictures application, Closing the image viewed in the application will close the application and return to the Documents launcher.

= References =


 * Palm: http://www.palmos.com/dev/support/docs/ui/UI_Intro.html#918034
 * KDE HIG: http://developer.kde.org/documentation/standards/kde/style/basics/index.html
 * KDE String Style: http://developer.kde.org/documentation/standards/kde/style/basics/labels.html

= Comments =

zecke: Should Menus have Accelerators? josiah: Yes, I believe so. That way keyboard-enabled devices can take advantage of shortcuts such things. Probably the best way would be to use a custom OAction. Possibly extend OAction to support action typesuch as Hint_PDA, Hint_Clamshell, and Hint_Webpad. Then Qtoolbar could selectivly display according to device type, and Qpopupmenu could do selective display and orginization of actions. Thoughts?

zecke: instead of dialog->exec one should use QPEApplication::execDialog josiah: not a bad idea. Not familiar with execDialog myself, tho - and I dont have the source on my laptop to read. What does execDialog to different?

LewisJardine : Clamshell/PDAs Despite opening and closing, the Gmate YopY is not really a clamshell: its screen is much smaller, and cannot really be used in landscape mode. The yopy is more like a PDA than a clamshell, as defined by this document, except that it has a keyboard. The Yopy, and newer Zauruses, have a full keyboard that is comfortable to use. Possibly the yopy, zauruses, etc. deserve a category of their own: 'keyboard PDA', or something?

KeyboardPDA
This device is typically used in "Portrait" orientation (e.g. height greater than width.) Primary method of input is the touch screen, agumented with hardware buttons.

Example devices include:
 * Sharp Zaurus: SL 5500, 5600, 6000
 * GMate YopY

Characteristics

 * Screen: 240x320
 * Buttons: Four-way direction pad (or Five way - arrows + center select), Two function buttons (Ok and Cancel)
 * Pointer: Touchscreen
 * Additional Input: Full QWERTY keyboard, direction keys, Enter and Escape keys