Qt Quick development process

Learning Qt Quick

Some pointers to discover Qt Quick:

• http://qt-project.org/doc/qt-5/gettingstarted.html
• http://qt-project.org/doc/qt-5/gettingstartedqml.html
• http://qmlbook.org/index.html

A step by step exercise to dig into Qt Quick with the QtCreator development environment:

• http://qt-project.org/doc/qtcreator

Coding Style

We follow this coding style.

Source code

Here is the official repository for the source code. Alternatively you can also get the code on GitHub.

Compilation

• Get the source code
• Download and Install the lastest stable version of QtCreator for Android
• Start QtCreator and open the project file GCompris.pro at the root of the source code
• Compile and run it.

To make it run on Android you need first to follow these instructions.

Adding a new activity

Automatically

Let's say you want to port the algebra_by activity.

cd src/activities
./createit.sh algebra_by

And you're done, you can run GCompris in QtCreator and your activity should appear on the list.

Manually

You must create a directory for your activity in src/activities. In it, create an ActivityInfo.qml, algebra_by.pri and your qml entry point Algebra_by.qml.

• in src/activities/activities.txt add the directory name of your activity (keep the file sorted).
• add an include for your .pri in the top level GCompris.pro (to be correct it should be kept sorted with the others): include(src/activities/algebra_by/algebra_by.pri)
• check algebra_by/ActivityInfo.qml that the name references you Qml activity entry point and that the icon point to your icon name.

Getting old menus

If your activity is an existing one, you can move its ported ActivityInfo

• git mv menus/algebra_by.qml algebra_by/Algebra_by.qml

The associated svg icon is also under git

• git mv menus/resource/algebra_by.svg algebra_by

Extending another activity

If the activity is just an extension of an existing one you have to create it either manually or automatically and then change you .qml file to extend another one. The 'erase_clic' activity is a good example.

In your .qml file:

• just import the activity you want to extend with for example: import "qrc:/gcompris/src/activities/erase"
• instead of have your root item being an 'ActivityBase' you just create an object of the base type you want to extend like Erase.
• Use a property to pass parameters to your base item and customize it

Speeding startup

When you work on an activity you will run GCompris many time and the final stage that combines the qrc in the binary is long. To speed your development process, just comment the include of the activities you don't need in the top level GCompris.pro (In QtCreator you can select several lines and comment them in one shot with the 'ctrl /' shortcut).

Coding guidelines

Keep only small javascript in the QML code, all the game logic must be in your javascript file. This makes it easier to read the activity logic. It is possible to have several javascript files if needed. The QML files must be seen as the graphical interface description and the javascript the logic of the game.

Resolution independence

Your activity must look nice on tablets and desktops. The resolution and dpi value may differ a lot. On mobile with high dpi the size of your images will look smaller. You must set an initial size related to ApplicationInfo.ratio like this:

Image {
    id: ball
    source: "qrc:/gcompris/src/activities/ballcatch/resource/ball.svgz"
    sourceSize.height: 100 * ApplicationInfo.ratio
}

Window resize

Your activity must adapt its content properly when the window is resized.

Screen rotation

Your activity must support screen rotation. If you use a layout or you specify an item coordinated related to the window width you are safe. If you create absolute coordinate items, you may need to reset them when the screen is changed. To detect a rotation you can add a code like this in your ActivityBase:

    onWidthChanged: Activity.widthChanged()

Audio

Creating Audio items is rather slow. If you have a lot of items on the screen, do not create an Audio item for each. Instead create a single Audio and pass it to all your items.

Adding resources

• For the media, you have to put them in the qrc file and then reference it by qrc: in the source. The path is defined in the qrc file.
• You can see the qrc in qtcreator, it is Ressources/gcompris.qrc it is auto generated at build time
• To add new images, create a resource directory in your activity folder and in you .pri file add:

APP_FILES += \
	  $$PWD/resource/myCuteImage.jpg \

• And in your source use : qrc:/gcompris/src/activities/algebra_by/resource/myCuteImage.jpg

Background image

You must not use a background image to bring useful informations. It is not possible to keep the background aligned with items when the resolution is changed.

Compilation using CMake

CMake is a cross-platform free software program for managing the build process of software using a compiler-independent method. The minimum version to compile GCompris is 2.8.

Compiling GCompris for Desktop

You can still use QtCreator to develop. Within it, open the CMakeLists.txt on top-level of GCompris. Select a directory (create a folder at same level as the gcompris folder for example) and then click on "Run CMake" button then finish.

To compile GCompris on command line, you can create a folder at same level as the gcompris folder and into it type "cmake ../gcompris && make". You have the possibility to check which activities you want to compile or not.

Compiling GCompris for Android

Create a folder at same level as the gcompris folder and into it type "ccmake -DCMAKE_TOOLCHAIN_FILE=../gcompris/platforms/android.cmake -Wno-dev ../gcompris && make && make apk_debug" to get a GCompris apk. Be careful that you'll need a Qt version compiled for Android. So the paths to Qt directories should not be like the ones for Desktop version (for example, I have in /usr/lib/cmake/Qt5* the folders for Desktop and in /opt/Qt5.2.1/5.2.1/android_arm7/lib/cmake/Qt5* the folders for Android version). You'll need to change all the Qt5*_DIR (Qt5Core_DIR, Qt5Gui_DIR...) in ccmake.

Compiling translations

By default, no translation are compiled. You need to create the Makefile using cmake (see above) and type:

make BuildTranslations

Then go into the bin directory and type ./GCompris to launch the software (or running from QtCreator). In the configuration dialog box, you can choose your language. Restart the application to see the language change.

If you're compiling using Qt Creator, you can go to the Projects tab and in Build Steps, add a build step and check BuildTranslations.

Getting translations from the Gtk version

When adding a Gtk ported activity in the QtQuick version, if you used the strings for texts of the Gtk version, you can update all existing translation files. For this, first you need to update existing translation files using (this will add the new strings which will be untranslated for now):

   make UpdateTranslations

Then, using the convertPo.py tool (and the updateAll.sh which applies it to all translations), you can update the files to get the translations from the Gtk version (if they existed).

Updating an activity from .pri file to cmake

Using CMake implies we don't use the .pro project anymore and we have to tell CMake to look for the new project. Some changes has been made.

Convert .pri file to CMake files

If you already did an activity using .pri, you can use the priToCMake tool (in tools/) which will create a CMakeLists_{activity}.txt file (telling CMake to add this activity to the compilation). Move it to your activity directory and rename it CMakeLists.txt.

To compile priToCMake use the command: 'g++ -o converter converter.cpp'

Using GCAudio instead of Audio to play sounds

In order to play audio only if audio has been enabled on preferences, we need to update all Audio elements to GCAudio. On files updated, make sure that the following is set at beginning (else the activity could not run well):

 import "../../core"

Adding an activity

The script createit.sh still works.

Automatically

Let's say you want to port the algebra_by activity.

cd src/activities
./createit.sh algebra_by

And you're done, you need to re-run CMake in QtCreator and your activity should appear on the list.

Adding resources

• For resources, you have to put them in the resource directory of your activity
• A compiled qrc file named youractivity.rcc is auto generated by the compilation chain
• You must run cmake again to have new resources included in the qrc
• If you change a resource, a simple make will update the rcc file
• To reference your resource, use a qrc:/ url in the source. The path is:

qrc:/gcompris/src/activities/*youractivity*/resource/*myfile.svgz*