Difference between revisions of "Adding an activity"

From GCompris
Jump to: navigation, search
(Activity code)
Line 1: Line 1:
 
Adding an activity is very simple. There are 2 ways do develop activities, in C code or in Python.
 
Adding an activity is very simple. There are 2 ways do develop activities, in C code or in Python.
 
The easiest and recommended language is python.
 
The easiest and recommended language is python.
 +
 +
= Activity code =
 +
 +
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''.
 +
 +
 +
=== GCompris 8.4 and before ===
 +
 +
* In python, create src/boards/python/myactivity.py and add it in the Makefile.am there.
 +
* In C, create src/boards/myactivity.c and add it in the Makefile.am there.
 +
 +
=== After GCompris 8.4 (gcomprixo branch) ===
 +
 +
* Now all the activity code and resources are in their own directory under src/myactivity-activity.
 +
* In order to create one easily, you can use the src/pythontemplate-activity as a template. Do do this, ''cd src  && cp -a pythontest-activity/ myactivity-activity''.
 +
* Once your activity is created, you must add it in the toplevel configure.in in the AC_OUTPUT section.
 +
* Once done, you can run ''autoconf && sh sconfigure && make''.
 +
* Now you activity is compiles, test it without installation by going in you activity directory and running ''./runit.sh''
  
 
= Menu creation =
 
= Menu creation =
  
First, create a menu for your activity. The menus are XML formatted. They are located under the boards directory. They contain many informations about your activity. They must be in a file named myactivity.xml.in:
+
First, create a 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:
 
<pre>
 
<pre>
 
<?xml version="1.0" encoding="UTF-8"?>
 
<?xml version="1.0" encoding="UTF-8"?>
Line 51: Line 71:
 
|-
 
|-
 
|icon
 
|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 ''boardicons'' directory.
+
|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
 
|difficulty
Line 62: Line 82:
 
|-
 
|-
 
|boarddir
 
|boarddir
|Usualy empty. In some case, you want to create an antivity that parse specific data and behave accordingly. In this case, you can specify in this field, where is the data directory for this activity.
+
|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
 
|_title
Line 80: Line 100:
 
|}
 
|}
  
Last step, add your new menu to the file boards/Makefile.am and the file po/POTFILES.in.
+
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.
 
You can run make to be sure it is valid. The file boards/myactivity.xml will be created.
 
= Activity code =
 
 
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'''.
 
 
 
=== GCompris 8.4 and before ===
 
 
* In python, create src/boards/python/myactivity.py and add it in the Makefile.am there.
 
* In C, create src/boards/myactivity.c and add it in the Makefile.am there.
 
 
=== After GCompris 8.4 (gcomprixo branch) ===
 
 
* Now all the activity code and resources are in their own directory under src/myactivity-activity.
 
* In order to create one easily, you can use the src/pythontemplate-activity as a template. Do do this, '''cd src  && cp -a pythontest-activity/ myactivity-activity'''.
 
* Once your activity is created, you must add it in the toplevel configure.in in the AC_OUTPUT section.
 
* Once done, you can run '''autoconf && sh sconfigure && make'''.
 
* Now you activity is compiles, test it without installation by going in you activity directort and running '''./runit.sh'''
 

Revision as of 09:31, 15 August 2007

Adding an activity is very simple. There are 2 ways do develop activities, in C code or in Python. The easiest and recommended language is python.

Activity code

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.


GCompris 8.4 and before

  • In python, create src/boards/python/myactivity.py and add it in the Makefile.am there.
  • In C, create src/boards/myactivity.c and add it in the Makefile.am there.

After GCompris 8.4 (gcomprixo branch)

  • Now all the activity code and resources are in their own directory under src/myactivity-activity.
  • In order to create one easily, you can use the src/pythontemplate-activity as a template. Do do this, cd src && cp -a pythontest-activity/ myactivity-activity.
  • Once your activity is created, you must add it in the toplevel configure.in in the AC_OUTPUT section.
  • Once done, you can run autoconf && sh sconfigure && make.
  • Now you activity is compiles, test it without installation by going in you activity directory and running ./runit.sh

Menu creation

First, create a 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 (bruno@gxxx.net)"
        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 meaning of each field:

Field Description
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:
  • /administration: the administration menu. Not for activities
  • /computer
  • /discovery
  • /experience
  • /experimental: Put your activity there until it's ready to be used by any children. By default, experimental activities are hidden. To see them, start GCompris with the --experimental option.
  • /fun
  • /math
  • /puzzle
  • /reading
  • /strategy
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.
  • 1, 2 or 3 simple stars - from 2 to 6 years old
  • 1, 2 or 3 complex stars - 7 years and up
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.