Home · All Classes · Grouped Classes · Annotated · Functions

Tutorial: Writing Qtopia Phone Applications


Qtopia Phone Edition is tuned for use on a mobile phone. All Qt and Qtopia widgets have been modified for use with a small set of keys as follows:

User Interface Changes

Applications originally written for PDAs may require some interface changes. More specifically:

In addition, phones usually have lower resolution screens, but higher visibility requirements than PDAs. This often requires changes to the user interface to permit usage of larger fonts on less-available screen real-estate.

Keypad Navigation

To navigate using only the keys specified above, widgets have two focus states:

Navigation focus allows navigation between widgets using the arrow keys (Up and Down move between widgets on a tab, while Left and Right move between tabs). When a widget first gains focus it will be in navigation focus state. In this state, the widget should ignore all key events, except Qt::Key_Select, which can either:

When in the edit focus state, Qt::Key_Select is usually used to end editing (confirming the changes) and Qt::Key_Back is used to cancel editing.

The focus state of a widget can be set using:


and accessed using:

    bool QWidget::hasEditFocus().

In practice, it is usually unnecessary to manually set edit focus.

The Soft Menu Bar

Some phones have soft keys with different meanings in different contexts. On these phones the Qtopia phone edition server displays a Soft Menu Bar at the bottom of the screen. This bar displays the actions that the corresponding button on the phone will perform. The label to be displayed in the context bar is set using the QSoftMenuBar class.

For example, to set the Qt::Key_Select label of a widget to the standard EndEdit label when it is in edit focus state:

    QSoftMenuBar::setLabel(widget, Qt::Key_Select, QSoftMenuBar::EndEdit, QSoftMenuBar::EditFocus);

It is also possible to set custom labels using:

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

In this case the pixmap name and a short text label are specified. Both pixmap and text should always be provided, as the user can decide whether the soft menu bar will display text or icons via the Appearance settings application.


The Qt::Key_Menu (or Qt::Key_Context1 if Qt::Key_Menu is not available) button displays a menu of possible actions for the current application state. You can bind a QMenu to the menu button using:

    QSoftMenuBar::addMenuTo(QWidget *w, QMenu *menu, int state);

When the Menu button is pressed, the menu for the currently focused widget will be displayed. It follows the same rules as QSoftMenuBar, so if the current focus widget does not claim the Menu key or have a menu, then the menu or label of an ancestor will be active.

You can also get the menu for any widget using the QSoftMenuBar::menuFor() function. This will return the menu already associated with the widget if available, otherwise it will create a new menu.

    QMenu *menu = QSoftMenuBar::menuFor(this);
    menu->addAction(tr("Open"), this, SLOT(open()));

Input Methods

Input methods provide functionality for text input on a phone. Text is generated by the user using, for example, the normal phone keys. Since this can be very limited, hints are used to improve its usability. An input method type hint is generated whenever a widget gets focus. The hint can be either:

  1. specifically set using QtopiaApplication::setInputMethodHint().
  2. automatically set (for example, for a QLineEdit with a QIntValidator, the hint is automatically set to Number).
  3. null hint.

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

See also Input Methods Documentation.

Copyright © 2008 Nokia Trademarks
Qtopia 4.3.3