Release Notes For Nokia N9 Device software

Release Note Harmattan target for Qt SDK

2012-02-01

The MeeGo 1.2 Harmattan (from here on onwards "Harmattan" is used as an abbreviation for previous) target for Qt SDK extends the software development kit with means to develop applications for Harmattan devices.

As with the previous update (released with Qt SDK 1.1.4), this version of the Harmattan target is no longer experimental, and you do not need to install it separately.

This version of the Harmattan target supports application development for the Nokia N9 device. (The resulting applications are usable on the Nokia N950 limited release developer device as well).

Full developer documentation is available through the N9 Development Portal page at: http://developer.nokia.com/swipe.

Supported host environments

The Harmattan target has been verified in the following development hosts:

  • Microsoft Windows 7
  • Apple Mac OS X 10.7 (Lion)
  • Ubuntu Linux 11.10 (Oneiric Ocelot)/li>
  • Debian Linux 6 (Squeeze)

The Harmattan target works on other hosts as well (such as Microsoft Windows XP, Mac OS X 10.6 (Snow Leopard), and other Linux distributions), but at this stage its functionality in these host environments has not yet been fully verified.

System requirements

The Harmattan target is an add-on to the Qt SDK. Verify that your development host complies with the requirements of the SDK (as shown at: http://doc.qt.nokia.com/latest/requirements.html).

The Harmattan target requires an additional 3 gigabytes of storage space.

Contents

The Harmattan target provides developers with the tools and application programming interfaces (APIs) to develop applications for Harmattan devices.

The API follows the MeeGo API, with some key Nokia-specific additions such as:

  • Qt Quick Components 1.0 - a full set of UI building blocks you can use in Qt Quick to easily create UIs with the Nokia N9 look and feel.
  • Qt Mobility 1.2 - adding support for Bluetooth and NFC technology to the existing Qt Mobility API interfaces.
  • Qt WebKit 2.1.1 - with features such as JIT JavaScript compilation.
  • Qt Games API - a Qt-style API for OpenGL ES 2.0 development.
  • OpenGL ES 1.1 and 2.0 - implement 2D and 3D graphics with full access to the native APIs.
  • PulseAudio and GStreamer - standard APIs for building high-end audio/video applications and plug-ins.
  • Telepathy-Qt4 - Qt-style API to implement e.g. instant messaging, voice and video call application.
  • Accounts and Single Sign On - An easy to use account management framework.

For more details, see the API reference documentation. It is available as part of the Developer Library at http://harmattan-dev.nokia.com/docs/library/.

The contents of Platform API is also included in the Harmattan target by default. More information on the available APIs can be found at: http://harmattan-dev.nokia.com/docs/platform-api-reference/.

The Harmattan target is built using the MADDE framework, version 0.8.16.

The Harmattan target provides the QEMU device emulator as an optionally installable component. The version of the device emulator is 0.13.50-0sdk8. QEMU image has been updated to reflect the bug fixes incorporated (20.2011.39-5).

Further information

For more information about e.g. the Harmattan devices, development tools and user interface guidelines For more information, see the one-stop distribution location (http://developer.nokia.com/swipe). The full developer library is also available online at http://harmattan-dev.nokia.com/docs/library/.

SDK-device connectivity

The updated device firmware no longer has two key settings enabled by default:

  • The Developer Mode (enabling key tools and access from the development host) must be activated in Settings > Security > Developer Mode. Note: Prior to enabling developer mode, verify that the device's date has been set correctly.
  • The ability to install applications from other sources than Nokia Store must be activated in Settings > Applications > Installations. Note: The Developer Mode can be activated without changing this setting.

When you connect the device to the host machine via USB cable, ensure that the "SDK" mode is selected. Alternatively, modify the USB settings on the device to always load the SDK mode when connected via USB cable (Settings -> Accessories -> USB)

Improvements and fixes in this version

The toolchain is the same as was used in the original non-experimental Harmattan target for Qt SDK.

The following issues in the original and updated Harmattan targets (as released on 21.6., 30.8., 28.9 and 8.11.2011, respectively) have been fixed during its evolution:

  • There's only one Harmattan target, there's no longer any need to select between Platform API and MeeGo API (those sysroots have been merged to a single instance in this version). If you encounter errors while working on projects created with older versions of the SDK, the following tricks may be of assistance:
    • Delete the *.user file in the project directory.
    • Check that you're using a valid Qt version (in projects-view, Build-tab/Build Settings/General/Qt version).
    • Contact us (via the channels described in developer library) in case of persistent problems.
    • If these steps are not sufficient, you can obviously create a new project and copy the source files and other content.
  • Simultaneous debugging of QML and c++ code works on the device.
  • QML debugging now works on device, QEMU and the simulator.
  • Qt Creator now creates single-instance applications by default if the application is created using the Qt Quick project template.
  • The Qt Quick project template also enables developer to select whether an application uses booster-technology to speed up its startup and limit memory consumption (see the Best Practices section in Developer Library for details).
  • Qt Quick Components are now supported in the simulator.
  • The simulator defaults to the portrait orientation (the primary orientation of Nokia N9).
  • Javascript files can now be imported into QML.
  • The following symbols are now defined and can now be used in .pro-files:
    • MEEGO_VERSION_MAJOR,
    • MEEGO_VERSION_MINOR,
    • MEEGO_VERSION_PATCH, and
    • MEEGO_EDITION_HARMATTAN.
  • The following new APIs have been added to the MeeGo API:
    • Events Feed, a.k.a. MeeGo Touch Events (libmeegotouchevents-dev)
  • The following new APIs have been added to the Platform API:
    • Synchronization Framework (sync-fw-dev).
  • The following packages have been added to platform API:
    • libpackage-manager-dbus-qt-dev,
    • libcontentaction-dev,
    • libgq-gconf-dev,
    • applauncherd-dev.
  • In the Qt Mobility System Information API, QSystemDeviceInfo::model() and QSystemDeviceInfo::productName() now return the model and product names correctly.
  • When you use QML Camera or Video or other Multimedia elements, an aegis file is generated automatically by the SDK.
  • The Qt Quick Components license has been changed from LGPL to BSD.
  • Virtual keyboard is not available in the simulator. Its presence is indicated on-screen. You can use the keyboard of the development host instead.
  • QEMU improvements:
    • support for device rotation and keyboard use.
    • proper rendering of fonts and device status bar.
  • The sample applications can be compiled out of the box, there is no longer any need to manually edit the .pro-file of the project or copy icon files between projects.
  • QEMU is not present in the offline installer. Use either the SDK maintenance tool to install it or choose "custom" install and select the additional component.

Known issues

A list of the issues identified in the Harmattan target is available at: http://harmattan-bugs.nokia.com/.

General

  • If the Harmattan target is not functional after installing it with the updater tool, restart Qt Creator.
  • Remote compilation does not work (not an issue, since the appropriate cross-compilation tools are available for all supported host environments).
  • To enable the interactive use of debugging tools on the device, run the develsh program (available on the device after the Developer Mode has been enabled).
  • If QML debug mode is enabled, Harmattan applications are not rendered correctly in the simulator.
  • Harmattan-specific Qt Quick Components are not supported in the Designer.
  • When using plain QML items (i.e., not Qt Quick Components), anchor them using other items in the UI instead of using explicit x,y positions as provided by the Designer.
  • Ensure that com.nokia.extras platform drop-down box in the Simulator control window is set to "Harmattan" to run Harmattan applications in the simulator. (It is set to "Symbian" by default.)
  • Simulator does not render fonts correctly when their size is specified using points. Workaround: use pixelSize instead of pointSize.

QEMU

  • In QEMU, occasional connection timeout errors may occur. The workaround is to increase the connection timeout settings from 30s (default) to 60s for QEMU in Qt Preferences (Tools -> Options -> Linux Devices -> Device Configurations).
  • If QEMU is installed separately:
    • QEMU configuration may not appear immediately in the device list. A restart of the QtCreator is required.
    • If a device configuration already exists, QEMU configuration may not be automatically added. In this case, you need to add it manually.
  • The QEMU environment does not support the full set of sensors (ambient light, magnetometer, proximity and tap are supported).

API

  • If you use TextEdit element in a plain QML application, the virtual keyboard is not hidden when the element loses focus. As a workaround, you can call TextEdit.closeSoftwareInputPanel() before setting its focus to false. However, it is recommeded to use the Qt Quick components and its TextArea element instead, that does not require any workarounds.
  • In applications developed with Qt WebKit the virtual keyboard is not automatically hidden when it is unfocused. A workaround consists of adding an event filter to the affected view instance: 
    class EventFilter : public QObject
{   
protected:
    bool eventFilter(QObject *obj, QEvent *event) {
        QInputContext *ic = qApp->inputContext();
        if (ic) {
            if (ic->focusWidget() == 0 && prevFocusWidget) {
                QEvent closeSIPEvent(QEvent::CloseSoftwareInputPanel);
                ic->filterEvent(&closeSIPEvent);
            } else if (prevFocusWidget == 0 && ic->focusWidget()) {
                QEvent openSIPEvent(QEvent::RequestSoftwareInputPanel);
                ic->filterEvent(&openSIPEvent);
            }
            prevFocusWidget = ic->focusWidget();
        }
        return QObject::eventFilter(obj,event);
    }

private:
    QWidget *prevFocusWidget;
};
    This filter can be installed on a QGraphicsView or (in QML) on a QDeclarativeView instance: 
    EventFilter ef;
view.installEventFilter(&ef);
  • If you use the QML Camera or Video elements of the Qt Mobility Multimedia API, use QGLWidget as a viewport or the application crashes when swiped. In other words, the main.cpp should look something like this: 
    #include 
#include 
#include 

int main(int argc, char *argv[])
{
     QApplication app(argc, argv);
     QDeclarativeView view;
     view.setViewport(new QGLWidget());
     view.setSource(QUrl("qrc:/qml/main.qml"));
     view.showFullScreen();
     return app.exec();
}
    Correspondingly, include the following line in the .pro file: 
    QT += opengl
  • When using the Maps API, a lot of warnings are output by platform code. Some of these are confusingly written, but can be safely ignored: e.g. even if the following appears, the application is able to successfully utilize the Nokia maps plugin. 
    QColor::setNamedColor: Unknown color name 'APPID'
QColor::setNamedColor: Unknown color name 'TOKEN'

Linux-specific issues

  • Some QML example applications default to QMLViewer instead of simulator when imported (leading to e.g. orientation being handled wrong).
  • If the Qt Simulator database is corrupted, messages such as 
    ( ID ) Failed to prepare query; error:"no such column: parentthreadid..."
    appear in compile output tab, remove the qmailstore.db file in ~/.local/share/data/Nokia/QtSimulator

Windows-specific issues

  • It may take several attempts before the host recognizes a newly plugged-in device. If connecting the device does not make it visible in the networking control panel, unplug and reconnect the device. Note, however, that the operating system may need to install additional drivers for USB connectivity. Do not interrupt these operations by unplugging the device too soon.
  • If the USB network driver is not installed automatically during the installation of the SDK, and it is not visible in the SDK maintenance tool's package manager, perform the installation manually (requires administrator privileges):
    1. Open the command prompt.
    2. Navigate to the Qt SDK installation directory.
    3. Run the SDK maintenance tool with the following additional argument: SDKMaintenanceTool.exe --show-virtual-components.
    4. Select "Package Manager" and click Next.
    5. Under Development Tools > Maemo Toolchain, select SB Network Driver and click "Next".
    6. Click "Update".
    This installs the USB driver, and you can connect the device to the Qt SDK.
    This sequence is explained in full detail in the Harmattan Developer Library.
  • Select the "Use asynchronous mode to control the inferior" checkbox in QtCreator debugging options. This ensures that no processes are left after when a debugging session is aborted.

Mac OS X-specific issues

  • If the Qt Simulator database is corrupted, messages like ( ID ) Failed to prepare query; error:"no such column: parentthreadid..." appear in compile output tab. Remove the qmailstore.db file in ~/Library/Application\ Support/Nokia/QtSimulator
  • Qmldump may occasionally fail during the import of an existing project. This is an error, but the project remains usable without any changes.

Disclaimer

Copyright (c) 2012 Nokia Corporation. All rights reserved.

Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation.