GCompris internals

GCompris is made of 2 major distinct parts. The core engine and the activities.

The GCompris core engine

In many games the concept of an engine has been introduced. The goal of the engine is to separate the gaming data from the general and common utilities. For example, in GCompris we provide an advanced way to manage users, classroom, profiles. It is not up to each activity developer to take care of that. An API is provided to let them focus on what matter to them, making a fun and highly educational activity.

Core services

GCompris core provides:

• configuration: A configuration dialog that let the user select his/her preference. The preferences are saved in the home directory under .gcompris/gcompris.conf
• control bar: An activity can select which icons in the control bar are available to the user. It can also hide the bar when no control must be accepted.
• help: The inline help is extracted from the board menu. If no help is provided in the menu entry, the help button is not displayed in the bar.
• file manager: A simplistic but children friendly file manager.
• image selector: Provides a way for image drawing activity to let the children select an image. Images can come from predefined dataset or by dynamically scanning a specified directory.
• dialog box: It's sometimes useful to display a dialog box that integrates well in GCompris and the current skin.
• locale: Unlike regular desktop application, it may be useful to run GCompris in a target language. In this case, the user can select the language to use in GCompris. Only the language for which we have a translation, even outdated is listed.
• logging: A log with the date, activity, level/sublevel, success and in some case bad response.
• skin: We provide a way to create new skin for GCompris. A skin must have a separate directory in boards/skins and must contain at least a file named skin.xml. Two skins are provided by default, it's easy to create one by creating new images and changing the content of skin.xml
• cursor: Activity can select an alternate cursor
• audio player: We include a threaded audio player. It plays ogg vorbis encoded file (based on the SDL Mixer library). There is 2 threads, one for background music, one for voices / sound effects. Each one can be disabled independantly in the configuration dialog.
• relative file loading: Activities don't have to care where files are located on the system.
• bonus: When an activity is complete, we can display different kinds of bonus. Also are available audio voices to encourage your results.
• timer: Some activities use this to restrict the user to a specified number of 'try' or a timer.
• score: To display the current score within the activity.
• animation: An API to play predefined animation. All the state of a graphical object can be described in a single file. Then the activity will request a specific state of the object to be displayed. Each state points to a graphical image which can be a static image or an animated gif.
• activity configuration: Each activity can implement some specific configuration. For example, you may want to let the teacher play your activity only with captital letters. These options are saved within the sqlite database if present.

Startup sequence

When GCompris is started, it first start the menu named menu, unless a specific activity is provided using gcompris -l. In GCompris, the menu is an activity like any other one. Only it's role is different, it is in charge to start other activity.

GCompris doesn't know statically which menu entry goes with which activity code. When parsing the menus, it checks it can find an activity code abble to handle it. If not, the activity icon won't appear in the list.

When the children click on the activity, it's start entry point is called. Then the activity code is in charge of the activity area, it needs to initialize it with it's the graphical elements and initiate the activity game. It must initialize the control bar to display only the relevant buttons.

When the activity is done, or the user click on the activity exit button, the end entry point is called. The activity must cleanup the display area and all it's internal structure.

Developers documentation

C

• An introduction to the Gnome Canvas widget.
• Have a look also at the API of the gnomecanvas
• Check also GTK for documentation and tutorial for GTK programming.
• In order to keep the code portable, C code must be based on the GLib. Glib is the low-level core library that forms the basis of GTK+ and GNOME. It provides data structure handling for C, portability wrappers, and interfaces for such runtime functionality as an event loop, threads, dynamic loading, and an object system.

Python

• GCompris python API
• Python reference
• Python tutorial

The activities

The legacy way for creating new activities is to code them in C using GTK/GLib and the gnomecanvas.

To make a clean separation between the core and the activity, each activity is an independent plugin. The plugin must implements a set of functions in order to be operated by the core:

Mandatory entry point:

• start: You are requested to start. You get the board display area for you to display your activity.
• end: You are requested to end now. Cleanup the board display area, free the memory.
• is_our_board: The activity is provided with a menu entry. It tell the core if it knows how to run it. This is the process we use to bind a menu entry to an activity.

Optional entry point:

• pause: If your activity includes a timer, you must stop it. It is called when we display dialog over the activity like the configuration or the about box.
• set_level: The user clicked on the level change button. the activity must display the requested level.
• repeat: The user did not understood the goal of the activity. She want you to repeat the question.
• config: You can have a specific set of configuration option for your activity. If you implement this entry point, the core will display the 'configuration' icon in the bar. You then display a config dialog specific to your activity. The core provides an API to easily create such dialog. It will take care of the persistence, the options selected will be saved in the database.