Creating Activities

Activity Structure

You create a new Sugar Activity by placing the source code, images, and other files into a directory tree. Keeping the files related to the activity in one place makes it easy to package and distribute your activity.

In this chapter you can see how Activities are built. The file structure for the Helloworld activity that we create in this chapter is listed below.

Creating an Activity

Step 1: Designing an Activity

Anytime you want to build something, you must architect it. Building code is much like building a structure. The way you design your code may depend on the intricacies of Sugar.

Just like building a small structure to practice before building a larger one, it helps to gain some experience by building simple Sugar Activities or looking through existing work before designing a large-scale project. Look through the source code of popular activities like Read and Browse to see how activities are designed and structured in Sugar. Start by looking in the /home/olpc/Activities directory for "tours" of larger structures to model yours after.

For our example, we create an activity that displays the message "Hello World". Below is a mockup of roughly what our activity window looks like on the screen when it's running:

Step 2: Creating the directory structure

First, create the base directory that contains your activity's contents. Then create the "Helloworld.activity" directory. Create the "activity" directory within that. The activity directory contains two files:

An image file in ".svg" format that contains the icon for your activity. Sugar uses this image to allow users to launch your activity by clicking on it.
The activity.info file, which tells sugar what the name of your activity is and how to run it.

Below is the activity.info file created for our Helloworld activity:

[Activity]
name = Helloworld
service_name = org.laptop.HelloworldActivity
class = helloworld.Helloworld
icon = activity-helloworld
activity_version = 1
show_launcher = yes

The first line of the file should always read [Activity]. The next two lines identify the activity: name=Helloworld, service_name=org.laptop.HelloworldActivity. The "class = helloworld.Helloworld" line tells Sugar that the initial startup class is Helloworld in helloworld.py. The activity tree, printed earlier, lists the helloworld.py file. Within this file, we define a class called Helloworld.

The next line specifies the activity's icon. This is the name of the .svg file you also saved in the Helloworld.Activity/activity/ directory. For help creating icons, see http://wiki.laptop.org/go/Making_Sugar_Icons. The show_launcher option ensures that Sugar displays your activity icon so that users can launch your activity in the main Sugar window.

You can specify other options in activity.info to control how the activity interacts with Sugar. For a complete listing, see chapter 3 of the Sugar Activity Handbook online at http://www.olpcaustria.org/mediawiki/upload/a/a1/Handbook_200805.pdf.

After you have created your activity.info file, you should include a MANIFEST file describing the contents, and a setup.py file in your activity directory. These files are fairly generic. You can copy them from another activity and make modifications. For the localization directories, you should look at some existing references for making your activity usable in multiple languages:

http://wiki.laptop.org/go/Internationalization_in_Sugar
http://wiki.laptop.org/go/Python_i18n

Finally include the images and icons that you plan to use in the the Icons directory. The example tree shows a few icons that could be used in the Activity.

Step 3: Writing the code for Your Activity

Below is helloworld.py source code that implements our Activity.

from gettext import gettext as _
import logging
_logger = logging.getLogger('helloworld-activity')

import pygtk
pygtk.require('2.0')
import gtk
from sugar.activity import activity

class Helloworld(activity.Activity):

    #### Method: __init__, initialize this Helloworld instance
    def __init__(self, handle):
         activity.Activity.__init__(self, handle)

        #Create the main toolbox for this activity and
        #rely on _createToolBox() to populate with any
        #additional toolbars that may be needed.
        tlbx = activity.ActivityToolbox(self)
        self.set_toolbox(tlbx)

        main_canvas = gtk.HBox()
            

        #Create a "Hello World" Label and add it to the UI
        hello_label = gtk.Label("Hello World!")
        main_canvas.pack_start(hello_label)

        self.set_canvas(main_canvas)
        self.show_all()

def main():
    win = gtk.Window(gtk.WINDOW_TOPLEVEL)
    t = Helloworld(win)
    gtk.main()
    return 0

if __name__ == "__main__":
    main()

Copy the activity directory tree to /home/olpc/Activities and restart Sugar (Control-Alt-Erase) to have Sugar recognize It. The Activity can be launched from the Home View. Activities can be edited in place, but after making changes you want to restart Sugar before launching the Activity. Any text output, like error messages, can be viewed with the Log activity.

When you launch the Helloworld activity, you see a new window:

The toolbar is created by the activity.ActivityToolbox object and the set_toolbox function call. The ActivityToolbox is a standard toolbox that includes a toolbar with controls for closing the activity, sharing it with other users and saving the activity to the journal. For more information on creating and extending toolbars, see the Sugar Almanac online at http://wiki.laptop.org/go/Sugar.graphics.toolbox.

Packaging and Sharing Your Activities

After implementing and testing your Activity, package it in a zip file with a ".xo" extension. For our example, we create a "Helloworld.xo" file that contains the entire contents of Helloworld.Activity. This packaged file can then be shared with others.

The easiest way to share a package is to publish it on OLPC's Activities page. Navigate to http://wiki.laptop.org/go/Activities and you find many activities. With a wiki login, you can upload your Activity package, then link to it from the Activities page. You can also download and install existing Activities.

Resources to Help You Build Cooler Activities

Now you know what is needed to create a successful and engaging Activity. Hopefully, your next Activity does more than just say "Hello World". Among the issues and ideas you may want to consider when designing your activity are:

What Activity state do I want to store so that users can resume work at different times? How can I use the Sugar Datastore to save state?
How can I integrate cool technologies like GStreamer (for audio and video) or Pango (for customized fonts) into my Activity?
Will users be able to share in an activity over the mesh network? If so, how will they interact and what data will need to be shared?
How can I get my Activities to interact with different pieces of hardware on my laptop?

There are many resources out there to help you implement Activities around the ideas above. Some recommended references are:

The Sugar Almanac - http://wiki.laptop.org/go/Sugar_Almanac
OLPC Austria's Activity Handbook - http://www.olpcaustria.org/mediawiki/index.php/Activity_handbook
API Reference - http://wiki.laptop.org/go/API_Reference#Sugar_Specs