wip/apocalypses/apocalypse-1

[Emmanuele Bassi <ebassi linux intel com>]

hi everyone;

• executive summary (for those who know what I'm talking about already):

after spending the last 2 weeks testing it with any random piece of code
I could come up with, I feel confident enough to land the apocalypse-1
branch into master. I could not port complex, multi-dependency
application code like St and gnome-shell — mostly because of -Werror
usage and all-or-nothing porting — but I can definitely help out with
the porting process. porting would also allow giving feedback on the API
before the 3.4 freeze, so please: give as much feedback as you can
*now*, because complaining *later* will not do much to endear you to me.

• longer explanation (for those who don't know what I'm talking about):

the wip/apocalypses/apocalypse-1 is the translation into API of the
first Apocalypse document that has been on the wiki for more than a
month:

  http://wiki.clutter-project.org/wiki/Clutter/Apocalypses/Apocalypse1

it details how I want to transition the Actor API from 1.x to 2.x, and
introduces a series of API additions and deprecations that anyone
dealing with Clutter has to be aware of.

the transition can be broken down into various pieces:

- All children API is in ClutterActor

the Actor class has API to add, remove, and replace child actors, as
well as iterate and mutate the list of children. this API was already
there internally, but now it has been extended and exposed. the old
set_parent(), unparent(), and reparent() API has been deprecated, as
well as raise(), raise_top(), lower(), and lower_bottom(). the API has
been cleaned up as well, so it's more rational and less of a copy of
gtk+'s bad patterns. ClutterActor's API for iterating over the children
list is DOM-like, and should allow you to efficiently track first/last
children, insertion, appending, prepending, and other things that with
the current API require a copy of a GList and an iteration over it.

- ClutterContainer only deals with the children properties API

add, remove, foreach, raise, lower, and sort_depth_order are deprecated
vfuncs; Container will provide a default implementation for those
vfuncs, which defer to the Actor API.

- Implementing Actor and Container

ClutterActor implements the ClutterContainer interface by default. if
you have an actor that implements the Container interface most likely
you can drop every custom Container vfunc implementation and the actor
class will behave exactly the same.

- Actor can be instantiated

the base Actor class now knows everything there is to know about its
children, so there is no need for it to be abstract any more; a
ClutterActor instance behaves like a ClutterGroup by default, and if you
don't override the paint() virtual function (or if you chain up) the
default implementation of it will automatically paint the Actor's
children. the ClutterGroup API has been deprecated — the type, sadly, is
needed for ClutterStage.

- Layout managers

given that ClutterActor implements ClutterContainer, it's now possible
to defer any Actor that has children to use a LayoutManager instance.
this means that ClutterBox has been deprecated.

- Subclassing ClutterActor

all the changes above allow you to avoid subclassing ClutterActor except
in special circumstances — essentially only if you have a special paint
sequence. it is strongly recommended to chain up to the newly added
default implementation of the paint() virtual function — though it's
still entirely possible to just implement iteration over the children
using the Actor API.

there are other additions in the branch, like the background color
property for each Actor (which allows us to deprecate ClutterRectangle);
the margin properties; and the horizontal and vertical alignment for
children. all in all, ClutterActor should become more rational, more
easily usable out of the box, and reduce the amount of subclassing
needed to make Clutter work.

again, feedback from application developers is most welcome, but please:
read the wiki first.

ciao,
 Emmanuele.

-- 
Emmanuele Bassi,
Intel Open Source Technology Center