Activity tutorial
<< Tutorials
This tutorial explains step by step how to create the Hello World Activity bundle. You can download a completed .xo package, though the package will not exactly match the below contents.
This tutorial assumes you have read the Developer's Manual, have installed a Sugar development environment and wish to use the PyGTK development approach (the standard approach to developing activities for the OLPC).
- Create the bundle directory structure:
mkdir -p HelloWorldActivity.activity/activity
- Write the activity.info file, to describe your bundle in the activity sub-directory (e.g. HelloWorldActivity.activity/activity/activity.info). The Activity Bundles specification explain in detail the meaning of each field.
- Note: in a joyride-1525 build, sugar could not locate the icon when I tried this unless I removed the '.svg' extension from the 'icon = activity-helloworld.svg' line.
[Activity] name = HelloWorld service_name = org.laptop.HelloWorldActivity #class = HelloWorldActivity.HelloWorldActivity exec = sugar-activity HelloWorldActivity.HelloWorldActivity icon = activity-helloworld.svg activity_version = 1 show_launcher = yes
- Design an icon for your activity, according to the icon format and place it in the activity sub-directory. The file name should match the icon file name specified in the info file (e.g. activity-helloworld.svg).
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd" [ <!ENTITY fill_color "#FFFFFF"> <!ENTITY stroke_color "#000000"> ]> <svg xmlns="http://www.w3.org/2000/svg" width="50" height="50"> <rect x="1" y="1" width="48" height="48" style="fill:&fill_color;;stroke:&stroke_color;;stroke-width:2"/> </svg>
- Write the setup.py script in the top level directory (e.g. HelloWorldActivity.activity/setup.py), which in most cases will look like this:
#!/usr/bin/env python
try:
from sugar.activity import bundlebuilder bundlebuilder.start("HelloWorldActivity") except ImportError: import os os.system("find ./ | sed 's,^./,HelloWorlActivity.activity/,g' > MANIFEST") os.system('rm HelloWorldActivity.xo') os.chdir('..') os.system('zip -r HelloWorldActivity.xo HelloWorldActivity.activity') os.system('mv HelloWorldActivity.xo ./HelloWorldActivity.activity') os.chdir('HelloWorldActivity.activity')
- Code your activity in Python. The name you specified in the .info file as "class" is the name of the class which runs your code. For the activity.info file above, we specify a top-level module named HelloWorldActivity.HelloWorldActivity (please note that the use of uppercase names in module names is considered poor Python style, feel free to use an activity name with more standard style names).
| File: HelloWorldActivity.py |
from sugar.activity import activity
import logging
import sys, os
import gtk
class HelloWorldActivity(activity.Activity):
def hello(self, widget, data=None):
logging.info('Hello World')
def __init__(self, handle):
print "running activity init", handle
activity.Activity.__init__(self, handle)
print "activity running"
# Creates the Toolbox. It contains the Activity Toolbar, which is the
# bar that appears on every Sugar window and contains essential
# functionalities, such as the 'Collaborate' and 'Close' buttons.
toolbox = activity.ActivityToolbox(self)
self.set_toolbox(toolbox)
toolbox.show()
# Creates a new button with the label "Hello World".
self.button = gtk.Button("Hello World")
# When the button receives the "clicked" signal, it will call the
# function hello() passing it None as its argument. The hello()
# function is defined above.
self.button.connect("clicked", self.hello, None)
# Set the button to be our canvas. The canvas is the main section of
# every Sugar Window. It fills all the area below the toolbox.
self.set_canvas(self.button)
# The final step is to display this newly created widget.
self.button.show()
print "AT END OF THE CLASS"
|
The above file is called HelloWorldActivity.py
- Create a MANIFEST (e.g. HelloWorldActivity.activity/MANIFEST), containing the list of the files to include in the package. (Note: Be sure not to leave blank lines at the end of the file.) This script does that in linux:
find ./ | sed 's,^./,HelloWorldActivity.activity/,g' > MANIFEST
Your directory structure should now look like this:
HelloWorldActivity.activity/ HelloWorldActivity.activity/setup.py HelloWorldActivity.activity/activity HelloWorldActivity.activity/activity/activity.info HelloWorldActivity.activity/activity/activity-helloworld.svg HelloWorldActivity.activity/HelloWorldActivity.py HelloWorldActivity.activity/MANIFEST
Make sure that all your python files have the required permissions to be used.
chmod a+x setup.py chmod a+x HelloWorldActivity.py
Setup your bundle for development (must be user olpc when you do this) to become user olpc, type: su - olpc
python setup.py dev
(It appears this just creates a symlink in ~/Activities .)
Running
If you now run sugar the activity icon should be visible on the frame. (You have to restart sugar to get it to pick up the change if you just installed it. Hit ctrl-alt-erase.)
You can also edit the code in your bundle directory directly. Note that the first time your Activity is launched, it leaves a process around even if you close the window, so you must kill the sugar-activity-factory to get it to reload when you click again.
Distribution
Create a .xo package to distribute your bundle. (An .xo file is essentially a zip file built from the MANIFEST with some extra metadata, like a JAR file. It also has some localization ability, and in the future we expect to be able to sign these too.) The bundle name is automatically generated from the 'name' and 'activity_version' values found in the activity.info file, separated by a dash, with a .xo extension.
./setup.py dist
To install the xo on a laptop you can use the installer script.
sugar-install-bundle HelloWorld-1.xo
See also
- Activity bundles
- Hacking Sugar
- Localization -- you will need to localize your activity to make it accessible to users of the OLPC
- Game development HOWTO