Qt Quick development process

Learning Qt Quick

Some pointers to discover Qt Quick:

• Getting Started with Qt
• Getting Started Programming with Qt Quick
• Qml Book

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

• 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

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.

• Get the source code
• Download and Install the latest stable version of Qt for Android (This includes QtCreator in the Tools/QtCreator directory)
• Start QtCreator and open the project file CMakeLists.txt at the root of the source code
• Create a build directory and set it in Qt Creator
• Compile and run it. (No need of giving any arguments to CMake, if QtCreator asks for 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 CMake again 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, CMakeLists.txt and your qml entry point Algebra_by.qml.

• in src/activities/activities.txt add the directory name of your activity (keep the file sorted).
• check algebra_by/ActivityInfo.qml that the name references you Qml activity entry point and that the icon point to your icon name (preferred format is svg).

Getting old menus

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

git mv tools/menus/algebra_by.qml src/activities/algebra_by/Algebra_by.qml
git mv tools/menus/resource/algebra_by.svg src/activities/algebra_by/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

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.

Images and Graphics

On mobile with high dpi the size of your images and graphics 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.svg"
    sourceSize.height: 100 * ApplicationInfo.ratio
}

Fonts

The situation for fonts is comparable. The font.pointSize property of Text-like QML elements handles device independence to a certain degree. An exception are devices with relativ low-dpi and a high resolution (i.e. many tablet devices >= 10'), where fonts are rendered too small when using pointSize.

For this case we use calculated constant ApplicationInfo.fontRatio, that must be used a factor to a font.pointSize value. This is done automatically when the size is set via the fontSize property of the GCFont type, which is the recommended way to specify font-sizes. Example:

GCText {
    id: text
    text: "Text"
    fontSize: 14
    font.weight: Font.DemiBold
    color: "white"
}

You can also use the internal pseudo enum values of GCText, that specify some often used font-sizes:

    readonly property int tinySize:     10.0
    readonly property int smallSize:    12.0
    readonly property int regularSize:  14.0
    readonly property int mediumSize:   16.0
    readonly property int largeSize:    24.0
    readonly property int hugeSize:     32.0

GCText {
...
    fontSize: regularSize
...
}

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.

In order to play audio only if audio has been enabled in the preferences, use the core GCAudio item instead of Audio. Make sure to use import "../../core".

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.

Adding a configuration for a specific activity

Each activity can have a specific configuration (for example, changing the locale of the activity, having different modes...). A simple example can be found on Traffic activity where you can change between images and colors to display the cars.

To add configuration, you need to add the "config" value in the Bar. Then you have to add a DialogActivityConfig item where you will define the component item of the dialog. You need to define the following functions:

• setDefaultValues to set the values when displaying the configuration.
• onLoadData which is called to load the existing data from configuration.
• onSaveData which is called to save the configuration in configuration file and where you can also send signals to dynamically change current activity settings.

The data should be set in "dataToSave" attribute which is a map (pairs of key, values) where the keys are strings and values are javascript var (can be strings, lists...).

Accessing the component items can be done using: dialogActivityConfig.configItem.

For the data to be loaded at start of activity, you also need to call "dialogActivityConfig.getInitialConfiguration()" on Component.onCompleted() of your pageComponent item.

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 directory GCompris-qt-build at same level as the gcompris folder, go into it and type "cmake ../gcompris && make". You have the possibility to check which activities you want to compile or not.

If you want to create an auto extractible package for linux platforms, you need to launch cmake using: "cmake -DBUILD_STANDALONE=ON ../gcompris && make".

Troubleshooting

• If you get the error: "The imported target "Qt5::Gui" references the file "Qt5Gui_EGL_LIBRARY-NOTFOUND" but this file does not exist."

sudo apt-get install libgl1-mesa-glx

try again and if this still show the error do:

cd /usr/lib/x86_64-linux-gnu
sudo ln -s /usr/lib/x86_64-linux-gnu/mesa/libGL.so.1 libGL.so

• If you miss the GL/gl.h header, install it with sudo apt-get install mesa-common-dev

Compiling GCompris for Android

You need to download and install android ndk (NDK) and android sdk (SDK).

To make it easier and because we don't need eclipse contained in adt-bundle-linux-x86-xxxxx, copy the directory sdk under for example /home/Android/ and rename it as android-sdk. Also, rename android-ndk-r9d as android-ndk and copy it under /home/Android/

Then you need to add some environment variables by editing ~/.bashrc to add at the end (put the directories where you installed ndk/sdk):

export ANDROID_NDK=/home/Android/android-ndk
export ANDROID_SDK=/home/Android/android-sdk
export PATH=$PATH:/home/Android/android-sdk/platform-tools

With Qt5.3, you'll probably need to create symbolic links for Qt libraries (if you have the error Qt5.3.0/5.3/android_armv7/lib/libQt5Core.so.5.3.0 not found):

cd Qt5.3.0/5.3/android_armv7/lib
for f in $(ls *.so); do ln -s $f $f.5.3.0; done

Create a folder at the 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. This opens ccmake which is a console application. Run the configuration step by typing "C" on you keyboard.

If it tells you "Could not find a package configuration file provided by Qt5", press "e" to set the path for QT5_DIR. To do this, press "enter", this will place the cursor on the first path line. With the down key go to Qt5_DIR line, press again "Enter" then modify the path. For example the path can be: /home/myname/Qt5.3.0/5.3/android_armv7/lib/cmake/Qt5 where Qt5.3.0 is the Qt installation directory.

Then press on enter to access ccmake command followed by "G" to build and "E" to quit.

Creating the apk

To create the apk in your android build directory:

make BuildTranslations
make apk_release

Deploying on android device

To deploy, plug you computer to your tablet. Go into you tablet preferences, switch on the developer mode.

Into the console, type the following command:

adb install -r GCompris-debug.apk

Getting and compiling translations

By default, no translation are present in the git repository. We need to get them from the KDE svn KDE i10n svn. You can see the translation status at GCompris translation status.

To get all the translation files, you need to create the Makefile using cmake (see above) and type:

make getSvnTranslations

Once you have done this, you need to run again cmake in order to have all the translations handled. Then, to build the translations used by GCompris, type:

make BuildTranslations

Then go into the bin directory and type ./gcompris-qt 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).

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.svg*