Adding an activity
Adding an activity is very simple. There are 2 ways to develop activities, in C code or in Python. The easiest and recommended language is python. This is the one documented here.
Picking an example
GCompris already includes many activities. One of the easiest ways to learn is to pick one close to your need and modify it to do what you want.
We also provide 2 special activities:
- pythontest is a showcase activity, its sole goal is to provide code example
- pythontemplate is an empty python activity project, it makes sense to copy it to create your own.
Create your activity
The easiest way to create an activity is to use the supplied createit.sh script. It creates an empty python activity with your supplied name.
cd src ./createit.sh myactivity
Now you are ready to test it. Even if python activities do not require compilation, we need to keep makefiles up to date for the installation and packaging process to work. The script takes care of that, you just have to run 'make':
make ./runit.sh myactivity-activity
When ready, you can test that your activity is well installed and integrated in GCompris. To check this, you must go to the project's top level and run:
make install gcompris --reread-menu
The --reread-menu option forces GCompris to rescan all the xml menu activities description of GCompris and recreate our internal sqlite database. This step is to be done when you added or changed a menu file.
You must create or update the menu for your activity. The menus are XML formatted. They contain many informations about your activity. They must be in a file named myactivity.xml.in. All tags starting with an _ sign means that a translation will be requested for them:
<?xml version="1.0" encoding="UTF-8"?> <GCompris> <Board name="pythontest" type="python:myactivity" section="/experimental" icon="boardicons/python.png" difficulty="1" author="Bruno (email@example.com)" boarddir=""> <_title>Python Test</_title> <_description>Test board for the python plugin</_description> <_prerequisite>Advanced Python Programmer :)</_prerequisite> <_goal>Add a language-binding to gcompris.</_goal> <_credit>Thanks to Guido van Rossum and the python team for this powerful language!</_credit> </Board> <Data directory=""/> </GCompris>
Here are the meanings of each field:
|name||Must be the name of this file|
|type||This let GCompris knows where is the code for your activity. Note that several menu enties can use the same activity code. If the code is in python, the prefix python: must be added.|
|section||Where in the directory structure of the menu this activity will be placed. It must be one of those:
|icon||Points to a png image representing your activity. The directory is relative to the boards directory. By convention, all icons are always placed in the same package_data_dir directory.|
|difficulty||The level of difficulty, must be a number from 1 to 6.
|author||Who wrote the code, who made the graphism|
|boarddir||Usually empty. In some case, you want to create an activity that parse specific data and behave accordingly. In this case, you can specify in this field, where is the data directory for this activity. This is relative to the package_data_dir.|
|_title||Note the underscore, it's very important. It means this field will be translated. Put here a title name for your activity. GCompris is dedicated to children. You must use words they can understand.|
|_description||Provide here a little bit more information about the activity|
|_prerequisite||What competencies are needed to play this activity. This information is part of the inline (and online on gcompris.net) help.|
|_goal||What are you going to teach, what must be achieved in the activity.|
|_credit||Did you get help, rewards goes here|
Last step, add your new menu in the Makefile.am (in the same directory) and the file po/POTFILES.in. You can run make to be sure it is valid. The file boards/myactivity.xml will be created.
Now your menu is ready, you need the add your activity code. Check more information on the GCompris internals page to see how to write the activity code. It's usually easy to copy an activity close to yours. You can have a look at the pythontest activity, it contains several examples of code.
For C activity, modify the is_our_board function to match your activity type. In python, the activity type must be the name of the file. In python, it's mandatory to set the class name in your activity code to Gcompris_myactivity.