So you’ve seen the first iteration, you’ve checked out the code and you want to get coding? Sure thing! Since we would appreciate any help, we are even willing to give you a bunch of spoilers! Here is a quick rundown of what you absolutely need to know:

Where is our code?

In our git repository, you will find a lot of things. But a lot of that is the original sugar code and a bunch of libraries that are bundled with it. So, which folders are interesting?

• source/activities : Different activities developed or modified by us for testing/demo purposes
• source/external : Working jhbuild environment for building and testing. In there, install/share/sugar/activities/ is your friend for adding activities to the test environment.
• source/external/source/sugar-toolkit/src/sugar/ : Sugar Toolkit sources. So far we have played a bit in the sugar toolkit, but most of our work is in the tutorius folder in there.
  • tutorius/core.py: Finite State Machine, Tutorial and States. Those are the big gears that make everything turn
  • tutorius/filters.py: EventFilters that allow defining State transitions
  • tutorius/actions.py: Actions that can be executed when entering a new State
  • tutorius/gtkutils.py: Utility functions for playing with Gtk object hierarchies
  • tutorius/services.py: Currently contains only the ObjectStore “service”
  • tutorius/tests: Our tests
  • activity/activity.py: A few changes have been made to the ActivityToolbar to allow launching Tutorials
• docs/: We keep documents there. Some are reports written for our classes, but the main areas of interest should be the arch and Design subfolders. There is a small amount of stuff there, including some ArgoUML class diagrams and use cases.
• Branches : We are a small team of people working on this, and we should try to push everything into the master branch. So far, though, there might be a few new features in some of our branches. So far, mike, simpoir and tutorial_toolkit have the most stuff.

So now you know where most of our interesting stuff is. You should be able to explore on your own if you feel adventurous. If you do, you can use the small amount of docs we have to help you, and tell us where it is lacking the most.

What does the code do?

Now, if you want to understand how current tutorials work, here is where you should be looking:

1. Tutorials are defined in the Activity code itself for now. They are listed from the activity’s get_tutorials function.
2. The sugar.activity.activity.ActivityToolbar uses get_tutorials to create a combo box to choose tutorials from. A callback triggers attaching the tutorial to the activity via Tutorial.attach()
3. The tutorial’s FSM is set to the initial state, and everything begins. Actions are performed, EventFilters are installed. The tutorial runs.

Apart from that, you should note how widgets are resolved for EventFilters. A treeish string in the form “0.1.0.0.1.2.1.0.0″ is what we currently use as identifiers for widgets. This represents the path to take down the GtkWidget hiearchy, starting with the Activity itself. Each step has an index in the current widget’s children list. It is possible to obtain those numbers via the gtkutils functions by registering event filters on the whole widget hierarchy, and logging the events by sending them to a default handler that logs the widget name and event name. The Tutorial editor will make this easier, and and in the meantime there is a WidgetIdentifier that allows viewing some events in an activity.

That is really the base, there are plenty more things to know.

What can you do?

If you are searching for something to do, check the project page on launchpad. It has our bugs and tasks so far. We should be adding a lot more tasks and bugs once we go through our current list, and through the code looking for FIXME’s. Also, if you have great ideas feel free to email us or file a bug on launchpad. You can also try to find me (vvinet) on freenode irc in #sugar or alone in #tutorius.