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

# Qtopia - Writing Applications for Phones

- Introduction
  - User Interface Changes
- Modal Editing
- The Context Bar
- The Context Menu
- Supporting Qtopia PDA and Qtopia Phone
- Input Methods

## Introduction

The Qtopia phone edition is tuned for use on a mobile phone, without a touch screen. All Qt and Qtopia widgets have been modified for use with a small set of keys:

- a context key - usually used to display a context menu, or perform a specific task based on the current context.
- a select key - used to select a widget for editing, an item from a list, etc.
- a back key - used to cancel the current operation, or go back to the previous screen.
- arrow keys
- keypad - used for numeric and text input (via input methods).

Applications written for Qtopia and Qtopia Phone edition usually share 99% of their code, however, it is necessary to make some allowances for phone usage.

### User Interface Changes

The required user interface changes are:

- The phone should have no menu bar or tool bars.
- The user interface must be navigatable using only the keys specified above.

In addition, phones usually have lower resolution screens, but have higher visibility requirements than PDA's. This often requires changes to the user interface to allow using larger fonts on less available screen real-estate.

Code specific to the Qtopia phone edition can be included or excluded using the QTOPIA_PHONE macro.

    #ifdef QTOPIA_PHONE
        // phone specific code
    #endif

## Modal Editing

In order to navigate using only the keys specified above, widgets have two focus states:

- nonmodal editing
- modal editing

Nonmodal editing allows navigation between widgets. When a widget first gains focus it will be in nonmodal editing state. In this state, the widget should ignore all key events, except Qt::Key_Select, which can either:

- edit/activate the widget if sensible, e.g. pressing select on a QCheckBox will check/uncheck the box, otherwise,
- enter modal editing state so that further editing can be performed. In this case, either Qt::Key_Back or Qt::Key_Select may be used to end modal editing.

The modal editing state of a widget is set using

        QWidget::setModalEditing(bool)

and accessed using

        bool QWidget::isModalEditing().

## The Context Bar

Some phones have soft keys which may have different meanings in different contexts. On these phones the Qtopia phone edition server displays a Context bar at the bottom of the screen. This bar displays the actions that the corresponding button on the phone will perform. You can set the label to be displayed in the context bar using the ContextBar class.

For example, to set the Qt::Key_Context1 label of a widget to the standard Edit label when it is in modal editing state:

        ContextBar::setLabel(widget, Qt::Key_Context1, ContextBar::Edit, ContextBar::Modal);

It is also possible to set custom labels using:

        ContextBar::setLabel(QWidget *, int key, const QString &pixmap, const QString &text, EditingState state);

In this case the pixmap name and a short text label are specified. The pixmap must always be provided so that themes with limited space can display a pixmap rather than longer text. The text is optional, but recommeded. In future versions of Qtopia Phone Edition the user may be able to choose their preference for text over icons.

## The Context Menu

The Qt::Key_Menu button is used to display a menu of actions possible in the current application state. The ContextMenu class is a subclass of QPopupMenu that is bound to the Menu button. When the Menu button is pressed, the context menu for the currently focussed widget will be displayed. It follows the same rules as ContextBar, so if the current focus widget does not claim the Menu key or have a context menu, then the ContextMenu or label of an ancestor will be active.

ContextMenu is used identically to QPopupMenu, e.g.

        ContextMenu *contextMenu(this);
        contextMenu->insertItem(tr("Open"), this, SLOT(open()));
        QAction *a = new QAction(tr("New"), Resource::loadIconSet("filenew"), QString::null, 0, this, 0 );
        a->addTo(contextMenu);

## Supporting Qtopia PDA and Qtopia Phone

This section shows the recommended method for writing an application which can be deployed on both PDAs and phones. For simple applications this usually means supporting a menu bar and toolbars on the PDA and a ContextMenu on the phone. More complex applications may consider different data views and dialog layouts.

Consider the code commonly used to construct the user interface:

    MainWindow::MainWindow(QWidget *parent, const char *name, WFlags f)
        : QMainWindow(parent, name, f)
    {
        // Create menu
        QToolBar *bar = new QToolBar(this);
        bar->setHorizontalStretchable(TRUE);
        QMenuBar *menubar = new QMenuBar(bar);
        QPopupMenu *fileMenu = new QPopupMenu(menubar);

        // Create toolbar
        fileTools = new QToolBar(this);

        // Create actions and add to the menu/toolbar
        newAction = new QAction(tr("New"), Resource::loadIconSet("filenew"), QString::null, 0, this, 0 );
        connect(newAction, SIGNAL(activated()), this, SLOT(new()));
        newAction->addTo(fileMenu);
        newAction->addTo(fileTools);

        openAction = new QAction(tr("Open"), Resource::loadIconSet("fileopen"), QString::null, 0, this, 0 );
        connect(openAction, SIGNAL(activated()), this, SLOT(open()));
        openAction->addTo(fileMenu);
        openAction->addTo(fileTools);

        // Create central widget
        view = new View(this);
        setCentralWidget(view);

        // Other initialization
    }

The same application on a phone will have no menubar or toolbar. It will instead have a ContextMenu activated by a context key. The above code can be modified to support both PDA and phone as follows:

    MainWindow::MainWindow(QWidget *parent, const char *name, WFlags f)
        : QMainWindow(parent, name, f)
    {
        // Create actions
        newAction = new QAction(tr("New"), Resource::loadIconSet("filenew"), QString::null, 0, this, 0 );
        connect(newAction, SIGNAL(activated()), this, SLOT(new()));

        openAction = new QAction(tr("Open"), Resource::loadIconSet("fileopen"), QString::null, 0, this, 0 );
        connect(openAction, SIGNAL(activated()), this, SLOT(open()));

    #ifndef QTOPIA_PHONE
        // Create menu
        QToolBar *bar = new QToolBar(this);
        bar->setHorizontalStretchable(TRUE);
        QMenuBar *menubar = new QMenuBar(bar);
        QPopupMenu *fileMenu = new QPopupMenu(menubar);

        // Create toolbar
        fileTools = new QToolBar(this);

        // Add actions to menu and toolbar
        newAction->addTo(fileMenu);
        newAction->addTo(fileTools);
        openAction->addTo(fileMenu);
        openAction->addTo(fileTools);
    #else
        // Create context menu
        contextMenu = new ContextMenu(this);

        // Add actions to the context menu.
        contextMenu->addTo(fileTools);
        contextMenu->addTo(fileMenu);
    #endif

        // Create central widget
        view = new View(this);
        setCentralWidget(view);

        // Other initialization
    }

In the above code, all actions are created and then either the menu and toolbar created and populated, or a context menu populated and created.

In larger applications some of the actions available in the PDA version may be handled in other ways, e.g. by assigning them to key presses (see QAction::setAccel) rather than tool buttons/menu items, or they may be disabled completely if they are unsuitable for use on a phone.

## Input Methods

Text input on a phone is accomplished by input methods. These allow the user to generate text using, for example, the normal phone keys. Since this can be very limited, hints are used to improve its useability. A input method type hint is generated whenever a widget gets focus. The hint is either:

1. The hint specifically set using QPEApplication::setInputMethodHint().
2. For QLineEdit and QMultiLineEdit with a QIntValidator, the hint is to Number.
3. The null hint.

The hints are presented as text (for future extensibility) to the Input Methods and they respond thusly:

- For "int", the phone number keys input corresponding digits.
- For "phone", "*" and "#" also work, and conventions are honoured, such as press-and-hold the "0" key for "+", and the "*" key for "p".
- For "words", the standard key text associations are used, and a dictionary-lookup is used to guess the desired letter.
- For "text", the standard key text associations are used, with multiple presses by the user and used to choose the desired letter.
- For the null hint, no method is used - keys are passed unchanged.