Cordova (PhoneGap) for Qt

Goals

The goal of the project is to develop a version of Cordova for Qt 5. This will help the adoption of Qt 5 in general, and on platforms using Qt 5 such as the Raspberry Pi board, Nokia N9 (in future), and any future devices that run Qt 5.

The code is backwards source compatible with Qt 4 (using #ifdefs, etc. as needed).

Note that Cordova was formerly known as PhoneGap before being acquired by Adobe (you may also see references to the name Apache Callback).

The code is being developed publicly as an open source project. We have a blog [ics.com] hat reports progress on the project.

As of April 2012 the code is considered beta quality and works with the Qt 5 alpha release. It also works with Qt 4.

Getting Started

The README.md [git-wip-us.apache.org] file has some basic instructions on using Cordova for Qt.

If you are familiar with PhoneGap/Cordova but not Qt, you may find these links helpful:

If you are familiar with Qt but not PhoneGap/Cordova you may find these links helpful:

How To Contribute

We welcome anyone who wants to contribute to the the project in any way, whether it is development, testing, documentation, etc.

You can access the source code here [github.com]. It builds on both for Qt4 and Qt5.

For project discussion, use the callback-dev mailing list [mail-archives.apache.org] and mention cordova-qt in the subject line.

If you have any questions, feel free to e-mail [mailto:jtranter@ics.com Jeff Tranter].

Project Team

At ICS:

  • Jeff Tranter, Engineering Manager
  • David Jacobs, Project Manager
  • Alejandro Narancio, Developer
  • Denis Kormalev, Developer
  • Longwei Su, Developer

Other developers who may help:

  • Wolfgang Koller (Viras)- working on Qt 4 port
  • Anis Kadri – liaison at Adobe
  • Lauri Paimen – created experimental port of QML to the web browser. May be able to share code.
  • Arend van Beelen jr. (Arendjr) – worked on Qt 4 PhoneGap
  • Igor Montagner (igordsm) – worked on Qt 4 PhoneGap
  • Bundyo – working on Harmattan PhoneGap port (unfortunately uses native Harmattan libs too) (Qt 4.7)

Strategy

  • Use the simulator provided by the Qt SDK.
  • Use the Nokia N9 running Qt 5 as the reference platform for phone-specific hardware (GPS, touchscreen, sensors, etc.).
  • Also use the Raspberry Pi running the QtonPi as a Qt 5 platform.
  • The port should only call APIs from Qt 5 (including mobility) and so not be specific to the Raspberry Pi or N9.
  • In general we won’t implement any PhoneGap API functions that aren’t supported by the underlying Qt 5.

Risks/Challenges

Qt 5.0 will not be released until around summer 2012. Need a stable version that we can use before then. We are currently using what is in git and the Qt 5 alpha and beta releases as they become available.

The interface to WebKit exposed by QtWebKit is changing significantly with Qt 5 due to changes in WebKit.

Major Tasks and Milestones

These are the current planned tasks and dates we are working against.

Task/Milestone Forecast/Actual Date Comments
Project Start 19-Dec-2011 Done
Set up git 23-Dec-2011 Done
Set up blog 23-Dec-2011 Done. https://www.ics.com/blog/category/phonegap
Set up mailing list 23-Dec-2011 Using callback-dev list
Select Qt 5 build 30-Dec-2011 Done
Set up Qt Creator/SDK 30-Dec-2011 Done
Finalize devices 30-Dec-2011 N9, Simulator, Emulator, Raspberry Pi
Obtain Raspberry Pi boards 01 Feb 2011 Not yet available
Connection 30-Dec-2011 Fully implemented
Device 30-Dec-2011 Fully implemented
Geolocation 06-Jan-2012 Uses the W3C Geolocation API specification which is supported by WebKit 2.
Media 06-Jan-2012 PhoneGap will be moving to follow the W3C specification which is supported by WebKit. For this reason we likely won’t implement the PhoneGap Media APIs.
Storage 06-Jan-2012 Uses the W3C WebSQL Database and Web Storage API specifications which are supported by WebKit 2.
Accelerometer 10-Feb-2012 Fully implemented
Compass 10-Feb-2012 Fully implemented
File 10-Feb-2012 Done. File Transfer API has no direct support in Qt Mobility so will not be implemented for now.
Notification 10-Feb-2012 Needs some reword for proper look and feel on different devices
Camera 17-Feb-2012 Implemented for Harmattan platform
Capture 17-Feb-2012 Not implemented, not supported by Qt Mobility
Contacts 24-Feb-2012 Fully implemented
Events 02-Mar-2012 Fully implemented
Qt 5 Feature Freeze 04 Feb 2012 Happenned
Qt 5 Alpha release 04 Apr 2012 Happenned
Testing on N9 (Qt 4) Ongoing
Testing on N9 (Qt 5) Ongoing
Qt 5 Beta release TBD Expected end of June 2012
Qt 5.0.0 release TBD Expected end of Aug 2012
Qt 5 Testing Completed 30 Aug 2012 Based on late Aug Qt 5 release

Building Cordova Qt Using Qt 5 Alpha

The software will build using the Qt 5 Alpha. Build Qt 5 as per the instructions here [qt-project.org]. Cordova Qt also needs the add-on modules qtfeedback and qtpim which are not part of the Alpha. You need to check these out of git and build them as well, e.g.

  1. tar xzf qt-everywhere-opensource-src-5.0.0-alpha.tar.gz
  2. cd qt-everywhere-opensource-src-5.0.0
  3. git clone git://qt.gitorious.org/qt/qtfeedback.git
  4. git clone git://qt.gitorious.org/qt/qtpim.git
  5. export PATH=$PATH:$PWD/qtbase/bin
  6. ./configure -prefix $PWD/qtbase -opensource -confirm-license -nomake tests -nomake examples
  7. ./build -j 3

Or, if you have already built the Qt 5 Alpha, build the additional two modules using:

  1. ./configure -prefix $PWD/qtbase -opensource -confirm-license -nomake tests -nomake examples
  2. make module-qtfeedback
  3. make module-qtpim

Then build Cordova Qt as usual, i.e. make sure that the Qt 5 qmake is in your PATH, and run qmake and then make (or do the equivalent if using an IDE like Qt Creator).

Known Issues

  • Some features are only supported on certain platforms due to limitations of Qt Mobility or platform-specific code
  • QtWebKit2 in Qt 5 alpha has an issue with mouse press events not working on the desktop. Waiting on QtWebKit team to resolve it. This is not an issue on embedded devices.

Running Cordova Tests

There is a test suite for Cordova. Here are the steps to follow to run the Cordova tests with Cordova Qt. Currently a number of tests fail but this is improving over time. After each step is listed a command that should work to do this on a Linux system from the command line. Adjust it as needed for the locations of Qt and the Qt SDK on your system.

1. Check out the code for Cordova Qt if you have not already done so.

  1. git clone git://git.apache.org/incubator-cordova-qt.git

2. Check out the code for the Cordova tests.

  1. git clone git://git.apache.org/incubator-cordova-mobile-spec.git

3. Go into the Cordova Qt project and copy the files from the Cordova Mobile Spec project into the www directory.

  1. cd incubator-cordova-qt
  2. cp -a ../incubator-cordova-mobile-spec/* www

4. Build Cordova Qt (using command line or Qt Creator as you prefer). You can build it for the desktop simulator or a real device.

  1. ~/QtSDK/Simulator/Qt/gcc/bin/qmake
  2. make

5. Run Cordova Qt. You will see the lists of tests, and can run individual tests or all tests.

  1. ./cordova-qt

A video that shows the tests running can be found here [youtu.be]

Here is a summary of the automated test results as of 1 Jun 2012:

Qt 4.7.4 using the Qt Desktop Simulator: 179 pass, 50 fail, of 229 tests (78%)

Nokia N9 running Harmattan PR1.2 Qt 4: 178 pass, 51 fail of 229 tests (78%)

Nokia E7 running Symbian Qt 4: 103 pass, 126 fail of 229 tests (45%)

Failures are currently in these areas:

Capture – APIs not implemented due to lack of support in Qt Mobility.
Contacts – some miscellaneous test failures.
File – some misc. failures.
Media – APIs not implemented as these are being deprecated in favor of W3C specs.

Wikipedia Mobile Demo Application

We have done some preliminary work to port Wikipedia Mobile to Cordova Qt. A demo video of it running can be seen at http://youtu.be/U_ay0U5FIts . A video showing how to build and run it can be seen at http://youtu.be/cMx-tyyOXgc and another one at http://youtu.be/43WE1vkYBY4 .

The code is available at https://github.com/dkormalev/WikipediaMobile.git . To check the code out do a git clone of https://github.com/dkormalev/WikipediaMobile.git and then git checkout the “qt” branch. Open Qt/WikipediaMobile.pro in Qt Creator and build for your desired platform, e.g. Qt Simulator or or a real phone.

Tips and Tricks

Here are some things we found when building Qt 5, WebKit, and Cordova Qt.

  • When running cordova-qt on a real device (e.g. N9) it helps to run it by sshing to the device and starting it in the right directory so it will find the www/index.html and other files (you also had to copy these files to the phone).
  • You may want to build each module of Qt 5 individually to save time and have better control over what is built
  • If you want Geolocation support, build WebKit with the —-geolocation —client-based-geolocation

References

  1. Project Blog [ics.com]
  2. PhoneGap project site [phonegap.com]
  3. Apache Cordova project incubator site [incubator.apache.org]
  4. Source code repository [git-wip-us.apache.org]
  5. Read-only mirror of repository for pull requests [github.com]
  6. QtonPi project [wiki.qt-project.org]
  7. How to build Qt 5 from git [developer.qt.nokia.com]
  8. How to build QtWebKit from git [trac.webkit.org]
  9. See this video [youtube.com] from Bundyo showing initial PhoneGap support for MeeGo 1.2 Harmattan (Qt 4.7)
  10. Github PhoneGap fork for Harmattan [github.com] from Bundyo. Initial seed, started implementing Contacts API.
  11. QMLWeb [gitorious.org] is another reference to consider. His maintainer, Lauri Paimen, is aware of this PhoneGap project.
  12. Wikipedia PhoneGap app [wikitech.wikimedia.org] first hand experiences targeting Android (more complex than planned) and then porting to iOS, Blackberry, etc (a lot easier then expected).
  13. Video [youtube.com] with Wikipedia PhoneGap app running on Harmattan (using qt4).