========================================================================= Release Notes for Harmattan target for Qt SD 2011-11-08 ========================================================================= 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. This update to the Harmattan target for Qt SDK updates the tools and programming interfaces to correspond to the current public firmware release. This version of the Harmattan target is no longer experimental, and you no longer need to install it separately. This version of the Harmattan target supports application development for the Nokia N9 and N950 devices. 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.04 (Natty Narwhal) * 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. However, the current version of Qt SDK does not work on Ubuntu 11.10 (Oneiric Ocelot). 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 (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 (this release is geared especially for N950). 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 create UIs with the Nokia N9 look and feel easily. * 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 applications * Accounts and Single Sign On - An easy to use account management framework. Please view the API reference documentation for additional details (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 uses the same software baseline as PR1.1 update that has been published for the N950 device (2.2011.39-5). Further information ------------------- For more information about e.g. the Harmattan devices, development tools and user interface guidelines please refer to 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 Ovi 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 following issues in the original and updated Harmattan targets (as released on 21.6., 30.8. and 28.9.2011, respectively) have been fixed in this version: - 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). * Please contact us (via the channels described in here: http://harmattan-dev.nokia.com/docs/library/html/guide/ html/Developer_Library_Feedback.html) 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. - 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 simulator, the simulator defaults to the portrait orientation (the primary orientation in Nokia N9). - QML debugging now works on device, QEMU and the simulator. - 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 simulator, its presence is indicated on-screen appropriately, and you can use the keyboard of the development host instead. - QEMU improvements include: * 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. Known issues ------------ A list of the issues identified in the Harmattan target is available at: http://www.developer.nokia.com/bugs/buglist.cgi?query_format=specific&order=relevance+desc&bug_status=__open__&product=&content=Harmattan 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). - Simultaneous debugging of QML and c++ code does not work. - If the Harmattan target is manually added to a project after its creation, MeeGo 1.2 Harmattan target is missing from the build configurations. - 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). - Qt Quick Components are not supported in the Designer. - If QML debug mode is enabled, Harmattan applications are not rendered correctly in the simulator. - When using plain (i.e. not part of the Qt Quick Components) QML items, anchor them using other items in the UI instead of using explicit x,y positions as provided by the Designer. - The booster implementation in the QmlApplicationViewer class of the Harmattan Qt Quick Components template has a small bug which causes two instances of QDeclarativeView being created. That can cause problems in certain applications. As a workaround, change one line in the generated main function of your application. Replace QScopedPointer viewer(QmlApplicationViewer::create()); with: QScopedPointer viewer(new QmlApplicationViewer()); - 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. Example applications (see also host-specific sections below): - Notifications example application is not usable. Documentation: - The developer library seems to be unscrollable (and thus of limited use) on the Harmattan devices. However, if you use TWO fingers to pan, the content actually scrolls. 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 does not appear immediately in the device list. A restart of the QtCreator is required. - QEMU runtime is bound with the MeeGo 1.2 Harmattan API target. The start/stop Maemo Emulator button becomes visible only when the MeeGo 1.2 Harmattan API target is selected for your project. - 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); Also, if you used the Harmattan Qt Quick components template, ensure that you have implemented the fix described above on how the QmlApplicationViewer instance is created in the main function of your application. - 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 Linux-specific: - 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, please remove the qmailstore.db file in ~/.local/share/data/Nokia/QtSimulator Windows-specific: - 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, follow these instructions on how to perform the installation manually. 1. open command prompt 2. move to the installation directory of the Qt SDK 3. run the SDK maintenance tool with an additional argument SDKMaintenanceTool.exe --show-virtual-components 4. select "package manager" and click "Next". 5. select USB Network Driver from Development Tools > Maemo Toolchain and click "Next". 6. click "Update" This sequence installs the necessary USB driver, and you can proceed to connecting the device to the Qt SDK. Note: driver installation requires administrator-privileges. This sequence will be explained in full detail in the Harmattan Developer Library (http://harmattan-dev.nokia.com/docs/library/html/guide/ html/Developer_Library_Getting_started_with_Harmattan_using_Qt_SDK _Connecting_the_device_to_Qt_SDK.html) Mac OS X-specific: - 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, please 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 needed. Disclaimer ---------- Copyright (c) 2011 Nokia Corporation. All rights reserved. Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation.