Platform Notes - Maemo 5

Maemo 5 (Fremantle)

Although Maemo 5 uses a fairly standard Linux/X11 setup, its compositing window manager and native UI toolkit (Hildon) make it necessary to be aware of a few specialities of this platform, if the Qt application should look and feel the same as a native Maemo 5 application.

The Qt Maemo 5 Examples show how to achieve deeper UI integration with the platform. The Q_WS_MAEMO_5 macro can be used to conditionally compile Maemo 5 specific features.

Window Manager

• The Qt::WindowMinimized state is not supported. As an alternative, you can use D-Bus calls to switch to the home screen or the window overview (see the maemo5 examples' source code for detailed information).
• The window manager applies compositing for all top-level windows by default. This behavior can be disabled by setting the Qt::WA_Maemo5NonComposited widget attribute on a top-level widget.
• Maemo 5 Stacked Windows are support by setting the Qt::WA_Maemo5StackedWindow widget attribute on all top-level windows that should be part of the stack. The root window should not have a parent, while all other windows in the stack should have their predecessor in the stack set as their parent (do not forget to use the Qt::Window widget flag, if you are not using QMainWindow derived classes).

  The Maemo 5 Stacked Windows Example shows how to do stacked windows with arbitrary widgets.

• The portrait or landscape orientation is not a global setting, but is handled on a per window basis. Qt's windows use landscape orientation by default. For top-level widgets this default can be changed by setting the Qt::WA_Maemo5PortraitOrientation, Qt::WA_Maemo5LandscapeOrientation or Qt::WA_Maemo5AutoOrientation widget attributes.

  The Maemo 5 Rotation Example shows how to dynamically rotate top-level widgets.

• Telling the user that the application is busy should be done by setting the Qt::WA_Maemo5ShowProgressIndicator widget attribute on any top-level widget or dialog. If blocking the UI is required, QProgressDialog can be used.
• The Qt::WA_TranslucentBackground window attribute does not work with the current Maemo 5 compositing window manager. All transparent areas are filled with black. An exception are homescreen widgets, whose semi-transparent areas are correctly composited with the home screen.

UI style guides

Style guides are available from Forum Nokia, which describe in detail how a Maemo 5 user interface should look and behave. Qt tries to follow the style guide closely, but there are many things which have to be done on the application side to completely follow these guidelines:

• Master Layout Guide.
• UI Style Guide.
• Widget UI Specification.

Here is a list of common questions and problems when developing for Maemo 5:

• Not all of Qt's standard widgets are styled in a Maemo 5 way, simply because the Hildon toolkit only supports a limited number of widgets. Those widgets classes are fully supported: QLabel, QPushButton, QToolButton, QCheckBox, QRadioButton, QComboBox (though combo boxes behave a bit differently to those on desktop platforms), QSpinBox, QSlider, QLineEdit, QTextEdit, QPlainTextEdit, QProgressBar, QAbstractItemView (and derived classes).
• Qt's built-in dialogs are deprecated since they do not follow the Maemo 5 style guide. For QFileDialog, only the static functions are supported, since they use the native, style guide compliant Maemo file dialogs. Maemo 5 pickers (see QMaemo5AbstractPickSelector) should be used for letting the user choose values. Instead of QFontDialog, a QFontComboBox can be used.
• Qt for Maemo 5 ships with a separate library (QtMaemo5) which implements all the special Hildon UI elements that could not be mapped to already existing Qt widgets: QMaemo5ValueButton, QMaemo5AbstractPickSelector (and derived classes), QMaemo5EditBar and QMaemo5InformationBox.
• Qt fully supports the kinetic finger-scrolling that is used everywhere in the native Maemo 5 software. The algorithm for this is implemented in the Maemo 5 specific, public QAbstractKineticScroller class, while the specific implementations of this interface for QAbstractScrollArea (and derived classes) as well as QWebView are private to those classes. Please see the QAbstractKineticScroller documentation for more information.

  The Maemo 5 QWebView Example in examples/maemo5 shows how to switch QWebView between text selection and scrolling behavior when the user swipes his finger.

  The Maemo 5 QGraphicsWebView Example in examples/maemo5 shows one way how to implement kinetic scrolling of a QGraphicsWebView.

• Maemo 5 has a special application menu that is triggered by clicking on the application's title bar. Qt will use all visible and enabled actions it can find in the uppermost QMenuBar of the active window to fill this menu. All QMenuBar widgets will be hidden automatically on creation. In order to support the Maemo 5 filter groups in the application menu, Qt will map all QActions within the menu bar belonging to an exclusive QActionGroup to these filter buttons.
• Dialogs are not allowed to have a Cancel button, but clicking into the blurred area above the dialog will effectively cancel it. Qt supports this special behavior via QDialogButtonBox. Please note that if your QDialogButtonBox does not include a Cancel button, the QDialog cannot be cancelled by clicking into the blurred area, which means that the dialog works exactly like a Hildon Confirmation Note in this case.
• QTextEdit and QPlainTextEdit are fully Maemo 5 style guide compliant. This means that these widgets will not show scrollbars, will not allow the user to select text and will not have kinetic scrolling enabled by default.

  The textedit example in examples/maemo5 shows how to dynamically resize QTextEdits the Maemo 5 way.

• Despite the QtWebKit User Agent string containing "Mobile Safari", some video sites send high-res videos, which render slowly on the N900. For some video sites, a work around exists by telling the site to send embedded friendly video streams. For YouTube, the fmt=5 query item (see QUrl::addQueryItem()) can be appended to greatly increase video frame rates. Example: Instead of http://www.youtube.com/watch?v=DN40PH4wfr8, request http://www.youtube.com/watch?v=DN40PH4wfr8&fmt=5 for a smooth video experience.

Known Limitations

• QSound does not work due to missing NAS libraries.
• QApplication::beep() does nothing since the X11 server's X XBell() function call is not implemented on the N900.
• Style sheets and the native QMaemo5Style do not mix very well, since Maemo 5 lays out and draws some widgets very differently (e.g. QRadioButton). We recommend using local style sheets on specific widgets only, instead of setting one via QApplication::setStyleSheet().
• Qt3Support is not available.