This semi-aborted API was broken for various reasons:
- it strongly depended on ClutterAlpha, a class we're trying to
deprecate;
- it requires a lot of boilerplate and copy-and-paste code;
- it requires a full relayout of the actor tree for something
that ought to be automatically handled by ClutterActor.
Now that clutter_actor_allocate() handles transitions using the easing
state of the actor, we can deprecate the LayoutManager API for the 1.x
series, and remove it for the 2.x series.
I don't feel comfortable with this feature, and its implementation
still has too many rough edges. We can safely punt it for now, and
introduce it at a later point, as it doesn't block existing features
or API.
This virtual function will let layout managers with legacy expansion
flags be able to influence the lazy computation of the expansion flags
on ClutterActor.
Now that ClutterActor implements the Container contract we can actually
defer the size negotiation to a ClutterLayoutManager directly from the
default implementation of the Actor's virtual functions.
When beginning a new animation for a LayoutManager, the implementation
should return the ClutterAlpha used. This allows controlling the
timeline and/or modifying the animation parameters on the fly.
In order to animate a fluid layout we cannot use the common animation
code paths as they will override the size request and allocation paths
that are handled by the layout manager itself.
One way to introduce animations in the allocation sequence is to use a
Timeline and an Alpha to compute a progress value and then use that
value to interpolate an ActorBox between the initial and final states of
the animation - with the initial state being the last allocation of the
child prior to the animation start, and the final state the allocation
of the child at the end; for every frame of the Timeline we then queue a
relayout on the layout manager's container, which will result in an
animation.
ClutterLayoutManager is the most likely place to add a generic API for
beginning and ending an animation, as well as the place to provide a
default code path to create the ancillary Timeline and Alpha instances
needed to drive the animation.
A LayoutManager sub-class will need to:
• call clutter_layout_manager_begin_animation() whenever it should
animate between two states, for instance: whenever a layout property
changes value;
• eventually override begin_animation() and end_animation() in case
further state needs to be set up, and then chain up to the default
implementation provided by LayoutManager;
• if a completely different implementation is required, the layout
manager sub-class should override begin_animation(), end_animation()
and get_animation_progress().
Inside the allocate() implementation the sub-class should also
interpolate between the last known allocation of a child and the newly
computed allocation.
The ClutterLayoutMeta instances should be created on demand, whenever
the layout manager needs them - if the layout manager supports layout
properties.
This removes the requirement to call add_child_meta() and
remove_child_meta() on add and remove respectively; it also simplifies
the implementation of LayoutManager sub-classes since we can add
fallback code in the base abstract class.
Eventually, this will also lead to an easier to implement ClutterScript
parser for layout properties.
With the new scheme, the ClutterLayoutMeta instance is created whenever
the layout manager tries to access it; if there isn't an instance
already attached to the container's child, one is created -- assuming
that the LayoutManager sub-class has overridden the
get_child_meta_type() virtual function and it's returning a valid GType.
We can also provide a default implementation for create_child_meta(),
by getting the GType and instantiating a ClutterLayoutMeta with all the
fields already set. If the layout manager requires more work then it can
obviously override the default implementation (and even chain up to it).
The ClutterBox actor has been updated, as well as the ClutterBoxLayout
layout manager, to take advantage of the changes of LayoutManager.
In order to know if a layout property exists and retrieve its
description in form of a GParamSpec, we need a wrapper API inside
ClutterLayoutManager. This allows introspecting a LayoutManager
sub-class and eventually serialize and deserialize it.
The LayoutManager implementation might opt to take a back pointer
to the Container that is using the layout instance; this allows
direct access to the container itself from within the implementation.
Instead of overloading ClutterChildMeta with both container and layout
metadata and delegate to every LayoutManager implementation to keep a
backpointer to the layout manager instance, we can simply subclass
ChildMeta into LayoutMeta and presto! everything works out pretty well
for everyone.
The ChildMeta object is a storage for child-container properties,
that is properties that exist only when an actor is inside a specific
container. The LayoutManager delegate class should also have
layout-specific properties -- so, for this job, we can "recycle"
ChildMeta as the storage.
If a sub-class of LayoutManager wishes to implement a parametrized
layout policy it also needs a way to notify the container using the
layout manager that the layout has changed. We cannot do it directly
and automatically from the LayoutManager because a) it has no back
link to the actor that it is using it and b) it can be attached to
multiple actors.
This is a job for <cue raising dramatic music> signals!
By adding ClutterLayoutManager::layout-changed (and its relative
emitted function) we can notify actors using the layout manager that
the layout parameters have been changed, and thus they should queue
a relayout.
A layout manager instance makes only sense if it's owned by a
container. For this reason, it should have a floating reference
instead of a full reference on construction; this allows constructing
Boxes like:
box = clutter_box_new (clutter_fixed_layout_new ());
without leaking the layout manager instance.
The LayoutManager class is an abstract proxy for the size requesition
and size allocation process in ClutterActor.
A ClutterLayoutManager sub-class must implement get_preferred_width(),
get_preferred_height() and allocate(); a ClutterContainer using the
LayoutManager API will then proxy the corresponding Actor virtual
functions to the LayoutManager instance. This allows having a generic
"blank" ClutterActor sub-class, implementing the ClutterContainer
interface, which leaves only the layout management implementation to
the application developers.
