|
Home · All Classes · Annotated · Functions | |
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 as follows:
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.
The required user interface changes are:
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.
Note: Code that is specific to the Qtopia phone edition can be included or excluded using the QTOPIA_PHONE macro.
#ifdef QTOPIA_PHONE
// phone specific code
#endif
To navigate using only the keys specified above, widgets have two focus states:
Navigation focus allows navigation between widgets. 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:
The navigation state of a widget is set using:
QWidget::setEditFocus(bool)
and accessed using:
bool QWidget::hasEditFocus().
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_Context1 label of a widget to the standard Edit label when it is in edit focus state:
QSoftMenuBar::setLabel(widget, Qt::Key_Context1, QSoftMenuBar::Edit, 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. 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 recommended. In future versions of Qtopia Phone Edition the user may have a choice of preference for text over icons.
The Qt::Key_Menu 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()));
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 soft menu 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, Qt::WFlags f)
: QMainWindow(parent, f)
{
// Create menu
QMenuBar *menubar = menuBar();
QToolBar *bar = new QToolBar(this);
bar->setMovable(false);
addToolBar(Qt::TopToolBarArea, bar);
QMenu *fileMenu = new QMenu(menubar);
// Create toolbar
fileTools = new QToolBar(this);
// Create actions and add to the menu/toolbar
newAction = new QAction(QIcon(":image/filenew"), tr("New"), this);
connect(newAction, SIGNAL(triggered()), this, SLOT(new()));
fileMenu->addAction(newAction);
fileTools->addAction(newAction);
openAction = new QAction(QIcon(":image/fileopen"), tr("Open"), this);
connect(openAction, SIGNAL(triggered()), this, SLOT(open()));
fileMenu->addAction(openAction);
fileTools->addAction(openAction);
// 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 menu activated by a context key. The above code can be modified to support both PDA and phone as follows:
MainWindow::MainWindow(QWidget *parent, Qt::WFlags f)
: QMainWindow(parent, f)
{
// Create actions
newAction = new QAction(tr("New"), QIcon(":image/filenew"), this);
connect(newAction, SIGNAL(triggered()), this, SLOT(new()));
openAction = new QAction(tr("Open"), QIcon(":image/fileopen"), this);
connect(openAction, SIGNAL(triggered()), this, SLOT(open()));
#ifndef QTOPIA_PHONE
// Create menu
QMenuBar *menubar = menuBar();
QToolBar *bar = new QToolBar(this);
bar->setMovable(false);
addToolBar(Qt::TopToolBarArea, bar);
QMenu *fileMenu = new QMenu(menubar);
// Create toolbar
fileTools = new QToolBar(this);
// Add actions to menu and toolbar
fileMenu->addAction(newAction);
fileTools->addAction(newAction);
fileMenu->addAction(openAction);
fileTools->addAction(openAction);
#else
QMenu *menu = QSoftMenuBar::menuFor(this);
// Add actions to the menu.
menu->addAction(newAction);
menu->addAction(openAction);
#endif
// Create central widget
view = new View(this);
setCentralWidget(view);
// Other initialization
}
In the above code, all actions are created and either the menu and toolbar are created and populated, or a context menu is populated and created.
In larger applications some of the actions available in the PDA version may be handled in other ways, for example, by assigning them to key presses (see QShortcut) rather than tool buttons/menu items, or they may be disabled completely if they are unsuitable for use on a phone.
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. A input method type hint is generated whenever a widget gets focus. The hint is either:
The hints are presented as text (for future extensibility) to the Input Methods and they respond as follows:
See also Input Methods Documentation.
| Copyright © 2006 Trolltech | Trademarks | Qtopia 4.1.7 |