[sugar] Graphics API

[Marco Pesenti Gritti]

Hello,

in the last couple of days we started moving Sugar to the new UI
framework. I posted about the reasons of the direction change already.
Here are more concrete information for activity authors.

What is changed
---------------

* The toolbar is being moved to use gtk widgets.

* The activity API has been changed a bit to make it easy to setup a
layout which is HIG compliant.

* The activity menu (the one in the top-left of the frame) has been
dropped and replaced by an Activity toolbar.

How to switch to the new system
------------------------------------

* Activities which follow the HIG layout (ex. Web, Write, Read)

This is a good overview of the overall layout and controls:

http://wiki.laptop.org/go/Write

Rework your toolbar implementation to use the new controls. There is an
example here:

http://wiki.laptop.org/go/Graphics_API#Activity

Web has been already ported, Tomeu is working on Read and Write.

* Activities which run full screen or use a GtkSocket (ex. TamTam,
Etoys)

Use the set_canvas() method of the Activity to set the toplevel widget
of your view. This is what I had to do in Etoys, for example:

- self.add(socket)
+ self.set_canvas(socket)

Which control should I use for... ?
-----------------------------------

This is tricky and suffer for the parallel nature of Sugar development,
but we are trying to alleviate the problems (using gtk clearly helps a
lot in this respect).

The HIG has a section on the controls. Unfortunately it's not complete
and so not particularly useful, other than for getting an high level
idea of the look of the control and on the high level layout and colors
system.

http://wiki.laptop.org/go/OLPC_Human_Interface_Guidelines/The_Sugar_Interface/Controls

I put on the wiki some notes about the Graphics API features and
implementation:

http://wiki.laptop.org/go/Graphics_API

It isn't really a reference yet but you can use it to figure which
widgets you should use, while implementation and documentation is in
progress. Just after the section name you can see the class of each
control:

* For gtk.* you can just use the gtk control. If we decide to subclass
one of these, they will be compatible with the gtk ones. (Hence porting
over will be trivial).

* For sugar.*. A few of them are already (partially) implemented, others
will be implemented soon. We will generally implement those on demand
and especially for the low priority ones, we would welcome
contributions. If you need any of them in your activity let us know
about it.

Let me know if you have any question, doubt or complaint!

Marco