Difference between revisions of "GCompris internals"

From GCompris
Jump to: navigation, search
(The GCompris core engine)
Line 23: Line 23:
 
* timer: Some activities use this to restrict the user to a specified number of 'try' or a timer.
 
* 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.
 
* 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.
+
* 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.
 
* 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.
 +
 +
= Developers documentation =
 +
 +
== C ==
 +
* An introduction to the [http://www-128.ibm.com/developerworks/library/l-gnomenclature/ Gnome Canvas widget].
 +
* Have a look also at the [http://developer.gnome.org/doc/API/2.0/libgnomecanvas/GnomeCanvas.html API of the gnomecanvas]
 +
* Check also [http://www.gtk.org/ GTK] for documentation and tutorial for GTK programming.
 +
* In order to keep the code portable, C code must be based on the [http://developer.gnome.org/doc/API/2.0/glib/index.html 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 ==
 +
* [http://gcompris.net/docs/en/python.html  GCompris python API]
 +
* [http://www.brunningonline.net/simon/python/quick-ref2_0.html Python reference]
 +
* [http://www.python.org/doc/2.2.3/tut/tut.html Python tutorial]
  
 
= The activities =
 
= The activities =

Revision as of 05:36, 20 August 2006

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 and 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 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.
  • help: The inline help is extracted from the board menu. If no help is provided in the menu entry, the help button if 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 usefull to display a dialog box that integrates well in GCompris and the current skin.
  • locale: Unlike regular desktop application, it maybe usefull 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 contains 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 kind of bonus and is available congratulation voices.
  • 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.

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

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 independant plugin. The plugin must implements a set a function 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.