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

# Qtopia Style Guide: Application Design

- Two Basic Styles
  - Document based applications
    - List of Lists
    - List of Items
    - Viewing a single item
    - Editing a single item
    - Deleting a single item
    - Navigational flow
    - Form layout
  - Task based applications
- D-Pointers
- Code Formatting
  - Do's and Don'ts

## Two Basic Styles

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:

- List of Lists (if necessary).
- List of Items.
- View of a Single Item.
- Edit Single Item.
- 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 Qtopia Messaging 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.

Highlighting a list and pressing Select displays the List of Items. Pressing Back or Done 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.

Highlighting an item and pressing Select should display a more detailed view of the highlighted item. Pressing Back or Done 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.

The context menu must contain entries that act only on the viewed item. If the application can edit the document, it should contain an Edit menu entry.

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 or Back option and nothing has been altered the button acts as the Cancel option 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.

The context menu must be limited to those entries that act on the item being edited. Phones that do not offer a No button may automatically have a Cancel entry added to the end of the menu.

Pressing Back or Done must accept the changes and return to the view. Pressing Cancel must discard the changes and return to the view.

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

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 Back or Done), 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 Back 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.
- The select button is also used to move through tabs when the tab has focus.

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.

## D-Pointers

Always give an exported Class a d-pointer. For example:

    --- exampleclass.h ---

    #ifndef EXAMPLE_CLASS_H

    #define EXAMPLE_CLASS_H

    class ExampleClassPrivate;

    class ExampleClass {

        public:

     // Some member functions

        private:

     ExampleClassPrivate *d; // The d-pointer.

    };

    #endif

    ------------------------

    --- exampleclass.cpp ---

    class ExampleClassPrivate {

        public:

     int variable;

     int anotherVariable;

    };

    ExampleClass::ExampleClass()

    {

        d = new ExampleClassPrivate;

    }

    ExampleClass::~ExampleClass()

    {

        delete d;

    }

    ------------------------

## Code Formatting

Indenting: is always 4 characters with tab spaces set to 8 characters.

Other prefered code formatting is as follows:

    class MyExampleClass {

    };

    void MyExampleFunction()

    {

        int someVariable;

        if (TRUE) {

     // Something

        } else {

     // Something else

        }

    }

### Do's and Don'ts

- Do not use goto.
- Do not use callback functions.
- Avoid passing pointers, try to use reference passing instead.
- Avoid using the preprocessor in application code, instead find a way for Qt/Qtopia to abstract the platform/compiler differences.
- For screen resizing also avoid the preprocessor, dynamically resize based on the widget's size.
- Use const where applicable for member functions and argument passing.