PhoneGap-for-Qt-5

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 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 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:

• http://qt.io/resources/getting_started
• http://harmattan-dev.nokia.com/docs/library/html/guide/html/Developer_Library_Getting_started_with_Harmattan_using_Qt_SDK.html

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

• http://phonegap.com/start/
• http://tv.adobe.com/show/adc-presents-phonegap/

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. It builds on both for Qt4 and Qt5.

For project discussion, use the callback-dev mailing list and mention cordova-qt in the subject line.

If you have any questions, feel free to e-mail 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
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. 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.

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

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

./configure -prefix $PWD/qtbase -opensource -confirm-license -nomake tests -nomake examples
make module-qtfeedback
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.

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

2. Check out the code for the Cordova tests.

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.

cd incubator-cordova-qt
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.

~/QtSDK/Simulator/Qt/gcc/bin/qmake
make

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

./cordova-qt

A video that shows the tests running can be found here

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 here . A video showing how to build and run it can be seen at here and another one at here .

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
2. PhoneGap project site
3. Apache Cordova project incubator site
4. Source code repository
5. Read-only mirror of repository for pull requests
6. QtonPi project
7. How to build Qt 5 from git
8. How to build QtWebKit from git
9. See this video from Bundyo showing initial PhoneGap support for MeeGo 1.2 Harmattan (Qt 4.7)
10. Github PhoneGap fork for Harmattan from Bundyo. Initial seed, started implementing Contacts API.
11. QMLWeb is another reference to consider. His maintainer, Lauri Paimen, is aware of this PhoneGap project.
12. Wikipedia_Android_PhoneGap-_Tomasz_and_Yuvi.pdf&page=1 Wikipedia PhoneGap app first hand experiences targeting Android (more complex than planned) and then porting to iOS, Blackberry, etc (a lot easier then expected).