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

Qtopia - Writing Applications for Phones

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:

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:

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 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:

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:


Copyright © 2001-2005 Trolltech Trademarks
Qtopia version 2.1.1