Reviewing an activity

Code level

Design / Ergonomy

Resolution independence

Activities must look nice and be usable on phones, tablets and desktops. Test must be done for the three devices.

Setting image size according ApplicationInfo.ratio

On mobile with high dpi the size of your images and graphics will look smaller. Initial size must be set related to ApplicationInfo.ratio like this:

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

Convert png images to svg

We prefer svg format for images for activities. Convert your 'png' images to 'svg' like this:

1) Copy all your png images inside a folder.
2) Copy this python script inside the same folder.
3) Run the above python script.

Voila! New converted svg images are created in the same directory.

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.

Code Level

Javascript and QML files

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.