Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference

Qtopia Style Guide: General

Introduction

This document describes the rules to be followed when designing a Qtopia application. The focus is on consistency, think very carefully before departing from the preferred style.

For ease of use the Qtopia Style Guide has been divided into several files:

Chapter Content
General (this document) Key binding, icons and their usage, Qtopia Desktop and formatting online help.
Application Design Outlines the styles that should be followed when creating a new Qtopia application including navigational flow, lists, and viewing items.
Naming Conventions Outlines the conventions for the use of capitals, abbreviations, acronyms and the formatting of labels. See Also styleguide-widgets.html
Widgets Outlines the styles that should be followed when creating or modifying widgets. See Also styleguide-naming.html
Online Help Outlines the styles that should be followed when creating or modifying online help files.

Qtopia Phone Keys

Qtopia requires the following keys:

Name Alternative representations Usual binding
Previous Left, Up, or Down Arrow* Previous item or value.
Next Right, Down, or Up Arrow* Next item or value.
Select Yes, OK Activate item or confirm changes.
Back No, Cancel Delete text or close window.
1 1 or space
2..9 Digits with phone key lettering.
0 0 or Function 1
* * or Function 2
# # or Function 3

Qtopia supports the following additional keys:

Name Alternative representations Usual binding
Menu Invoke context menu.
Up Up Arrow Item physically above
Down Down Arrow Item physically below.
Left Left Arrow Item physically to the left.
Right Right Arrow Item physically to the right.
Delete Cancel, Clear Delete item.
Jog Wheel up/down Scroll view or values.
F\ex Function keys Invoke global operation.

* on some phones, two keys represent both vertical and horizontal directions of suggested motion. Sometimes these are a Left/Up button and a Right/Down button, at other times they are a Left/Down button and a Right/Up button.

Standard Icons and Usage

Icon Component Filename Description of Use
Context Bar back.png Done: Finished using the current screen and wish to return to previous window.
Context Bar backspace.png Delete text: Deletes (backspace) 1 character.
Context Bar cancel.png Cancel: Removes all changes performed on the current item (transaction).
Context Bar ok.png Accept: Accepts and disengages the current information/data in the currently selected widget.
Context Bar options.png Open/Close Menu: Displays the current window's context menu.
Context Bar select.png Engage/Select: Selects the current item, widget or grouping.
Context Bar view.png More Information: Selects and displays information about the currently focused item.
Context Menu beam.png Beam: Sends the currently viewed item via IR.
Context Menu edit.png Edit: Edits the currently viewed item.
Context Menu find.png Find/Search: Locates an item.
Context Menu help_icon.png Help: Displays the help documentation for the current window.
Context Menu new.png New: Creates a new item.
Context Menu trash.png Delete item: Deletes the currently viewed item.

Help File Content

An application can have one or more help pages that can be viewed by either:

The help files are found in the current help path as specified by: Global::helpPath().

Each help file is encoded in UTF-8 and translation files are provided if required.(See also: Qtopia Internationalization).

The format of a help file can be modified by the user to present device-specific help content using:

Valid HTML Tags

For a list of the tags used to format help content see the Structuring tags section in the QStyleSheet class documentation.

Device-specific Help

Device-specific help content is delineated via special tags that are supported by the Help Browser Preprocessor.

Using Images Optimized for the Device

Like all Qtopia applications the HelpBrowser uses of the Resource class to determine the best image or icon to use at runtime.

For example: The following code in $QPEDIR/examples/application/help/html/example.html displays:

Code Image Displayed
<img width=12 height=12 src=Example> 
$QPEDIR/pics/Example.png

For example: The following code in $QPEDIR/help/html/qtmail-write-mail.html displays on a PDA device:

Code Image Displayed
<img src="qtmail/reply">
$QPEDIR/pics/qtmail/icons/14x14/reply.png

Specifying the Help to Install

The application .pro file has a help project that defines which help file to install. For example in $QPEDIR/example/application/application.pro:

     help.files=example.html
     help.path=/help/html
     INSTALLS+=help

Note: The name of the help file must be prefixed by the executable name of the application.

Context Sensitive Help

Context sensitive help is help associated with a specific widget. Creating context sensitive help for a widget requires the following:

  1. create a help file with a name comprising both the application name and the widget name as follows:
            <application exec name>-<widget name>.html
        
  2. set the name of the widget using QObject::setName()

For example the addressbook application has the AbEditor class which has in its constructor

    setName("edit");
So for the edit widget of addressbook, the help file is named:
    $QPEDIR/help/html/addressbook-edit.html

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.

Qtopia Desktop

Qtopia desktop should follow the same standards adhered to in Qtopia and should also follow close to the standards established by desktop user-interfaces.

Note: Creation of events, tasks and contacts should follow the creation rules specified in Qtopia, that is, if the user does not enter sufficient information the item is not created.


Copyright © 2005 Trolltech Trademarks
Qtopia version 2.2.0