GCC has some optimization for the inclusion guard, but they only work if
the check is the outermost one.
We're fairly inconsistent because of historical reasons, so we should
ensure that we follow the same pattern in every public header.
It can be useful to bind the children list to set of objects inside a
GListModel implementation; the GListModel stores the objects, and every
time the model changes, a function is called that maps each object in
the model to a newly created ClutterActor, which is then added as a
child. This API, along with the property binding one inside GObject,
allows automatic creation of views based on object models that update
themselves without manual intervention.
These are just terrible API that we've been stringing along since the
0.x days. We cannot truly deprecate them, because they are, in some
cases, the only actual API to perform some operation, and porting all
the code in the world is not going to make us any friends.
For the time being, we use a deprecation notice in the documentation.
The macros are useless for language bindings, and are terribly unsafe
from C as well. There's always the option of using the GObject
properties they refer to, but it's more efficient to just have a simple
getter function.
Toolkits may need to paint actors internally outside the normal tree
(for example to create a shadow shape), in which case they need to
control the opacity directly.
https://bugzilla.gnome.org/show_bug.cgi?id=677412
Signed-off-by: Emmanuele Bassi <ebassi@gnome.org>
There is no reasonable use case for having the functions, the virtual
functions, and the signals for realization and unrealization; the
concept belongs to an older era, when we though it would have been
possible to migrate actors across different GL contexts, of in case a GL
context would not have been available until the main loop started
spinning. That is most definitely not possible today, and too much code
would utterly break if we ever supported that.
We cannot fully deprecate Geometry, because ClutterActor and ClutterText
are actually using the type in signals and properties; but we can
deprecate the API that uses this type, so that 2.0 will be able to avoid
it entirely.
The :transform property controls the modelview matrix of an actor; it
can be used to set a custom modelview matrix on the actor, as opposed
to the decomposed transformations (rotation, scaling, translation)
provided by the ClutterActor class.
We need an alternative to the translation performed by the anchor point,
one that possibly applies to all three axes and is relative to the
pivot-point.
https://bugzilla.gnome.org/show_bug.cgi?id=677853
For some transformations we need to be able to set the Z component of
the pivot point.
Unlike :pivot-point, the Z coordinate is not normalized because actors
are 2D surfaces.
https://bugzilla.gnome.org/show_bug.cgi?id=677853
Given that the rotation transformations are now affected by the pivot
point, the Actor class should provide an accessors pair only for the
angle of rotation on a given axis.
https://bugzilla.gnome.org/show_bug.cgi?id=677853
The pivot point is a point in normalized coordinates space around which
all transformations revolve.
It supercedes the anchor point and the per-transformation center points
as well as the gravity settings, and tries to sort out the mess that
is the modelview matrix set up in ClutterActor.
https://bugzilla.gnome.org/show_bug.cgi?id=677853
The ClutterActor:depth property has always been a bit of a misnomer:
actors are 2D flat surfaces, so they cannot have "depth"; the property
defines the position on the Z axis.
Another side effect of the :depth property is that it decides the
default paint and allocation order on insertion, and that setting it
will call the ClutterContainer.sort_depth_order() method. This has
proven to be a fairly bad design decision that we strung along from the
0.x days, as it gives a false impression of being able to change the
paint and allocation order simply by changing the position on the Z
axis — something that, in reality, requires depth testing to be enabled
during the paint sequence of an actor's parent.
For 2.0 we need a clean break from the side effects, and a better
defined interface.
ClutterActor:z-position is essentially what ClutterActor:depth is, but
doesn't call into ClutterContainer, and has a more apt name.
https://bugzilla.gnome.org/show_bug.cgi?id=679465
It can be useful to check whether a ClutterActorIter is currently valid,
i.e. if the iterator has been initialized *and* if the actor to which it
refers to hasn't been updated.
We can also use the is_valid() method in the conformance test suite to
check that initialization has been successful, and that changing the
children list through the ClutterActorIter API leaves the iterator in a
valid state.
ClutterContent implementations may allow repeating their contents when
painting; we should provide the repeat policy on the actor, like we do
for scaling filters and content gravity.
The introspection scanner has become slightly more annoying, in the hope
that people start fixing their annotations. As it turns out, it was the
right move.
The :x-expand and :y-expand flags on ClutterActor are used to signal
that an actor should expand horizontally and/or vertically - i.e. that
its parent's layout management policy should try to assign extra space
to the actor when allocating it.
The expand flags are automatic: when set on a leaf node in the actor
tree, they will bubble up through the parent and grandparents up to the
top level actor; during allocation, the actors with children will lazily
compute whether their children needs to expand.
ClutterContent is an interface for creating delegate objects that handle
what an actor is going to paint.
Since they are a newly added type, they only hook into the new PaintNode
based API.
The position and size of the content is controlled in part by the
content's own preferred size, and by the ClutterContentGravity
enumeration.
The ::paint-node virtual inside ClutterActor is what we want people to
use when painting their actors.
Right now, it's a new code path, that gets called while painting; the
paint_node() implementation should only paint the actor itself, and not
its children — they will get their own paint_node() called when needed.
Internally, ClutterActor will automatically create a dummy PaintNode and
paint the background color; then control will be handed out to the
implementation on the class. This is required to maintain compatibility
with the old ::paint signal emission.
Once we are able to get rid of the paint (and pick) sequences, we'll
switch to a fully retained render tree.
ClutterActor should be able to hold all transitions, even the ones that
have been explicitly created.
This will allow to add new transitions types in the future, like the
keyframe-based one, or the transition group.
It should be possible to set up the delay of a transition, but since
we start the Transition instance before returning control to the caller,
we cannot use clutter_actor_get_transition() to do it without something
extra-awkward, like:
transition = clutter_actor_get_transition (actor, "width");
clutter_timeline_stop (transition);
clutter_timeline_set_delay (transition, 1000);
clutter_timeline_start (transition);
for each property involved. It's much easier to add a delay to the
easing state of an actor.
Clutter is meant to be, and I quote from the README, a toolkit:
for creating fast, compelling, portable, and dynamic graphical
user interfaces
and yet the default mode of operation for setting an actor's state on
the scene graph (position, size, opacity, rotation, scaling, depth,
etc.) is *not* dynamic. We assume a static UI, and then animate it.
This is the wrong way to design an API for a toolkit meant to be used to
create animated user interfaces. The default mode of operation should be
to implicitly animate every state transition, and only allow skipping
the animation if the user consciously decides to do so — i.e. the design
tenet of the API should be to make The Right Thing™ by default, and make
it really hard (or even impossible) to do The Wrong Thing™.
So we should identify "animatable" properties, i.e. those properties
that should be implicitly animated by ClutterActor, and use the
animation framework we provide to tween the transitions between the
current state and the desired state; the implicit animation should
happen when setting these properties using the public accessors, and not
through some added functionality. For instance, the following:
clutter_actor_set_position (actor, newX, newY);
should not make the actor jump to the (newX, newY) point; it should
tween the actor's position between the current point and the desired
point.
Since we have to maintain backward compatibility with existing
applications, we still need to mark the transitions explicitly, but we
can be smart about it, and treat transition states as a stack that can
be pushed and popped, e.g.:
clutter_actor_save_easing_state (actor);
clutter_actor_set_easing_duration (actor, 500);
clutter_actor_set_position (actor, newX, newY);
clutter_actor_set_opacity (actor, newOpacity);
clutter_actor_restore_easing_state (actor);
And we can even start stacking animations, e.g.:
clutter_actor_save_easing_state (actor);
clutter_actor_set_easing_duration (actor, 500);
clutter_actor_set_position (actor, newX, newY);
clutter_actor_save_easing_state (actor);
clutter_actor_set_easing_duration (actor, 500);
clutter_actor_set_easing_mode (actor, CLUTTER_LINEAR);
clutter_actor_set_opacity (actor, newOpacity);
clutter_actor_set_depth (actor, newDepth);
clutter_actor_restore_easing_state (actor);
clutter_actor_restore_easing_state (actor);
And so on, and so forth.
The implementation takes advantage of the newly added Transition API,
which uses only ClutterTimeline sub-classes and ClutterInterval, to cut
down the amount of signal emissions and memory management of object
instances; as well of using the ClutterAnimatable interface for custom
properties and interpolation of values.
Now that ClutterActor has a default paint volume, subclasses may wish
to retrieve it without chaining up to the parent's implementation of
the get_paint_volume() function.
The get_default_paint_volume() returns a ClutterPaintVolume pointer
to the paint volume as computed by the default implementation of the
get_paint_volume() virtual function; it can only be used immediately,
as it's not guaranteed to survive across multiple frames.
There are times when we don't want to remove all children and count of
the reference count to drop to 0 to ensure destruction; there are cases,
such as managed environments, where it's preferable to ensure that the
children of an actor get actually destroyed.
Similar to the clutter_actor_iter_remove(), but it'll call destroy()
instead of remove_child().
We can also reimplement the ::destroy default handler using it, and make
it more compact.
Iterating over children and ancestors of an actor is a relatively common
operation. Currently, you only have one option: start a for() loop, get
the first child of the actor, and advance to the next sibling for the
list of children; or start a for() loop and advance to the parent of the
actor.
These operations can be easily done through the ClutterActor API, but
they all require going through the public API, and performing multiple
type checks on the arguments.
Along with the DOM API, it would be nice to have an ancillary, utility
API that uses an iterator structure to hold the state, and can be
advanced in a loop.
https://bugzilla.gnome.org/show_bug.cgi?id=668669
The usual way to implement a container actor is to override the
allocate() virtual function, chain up, and then allocate the actor's
children.
Clutter now has the ability to delegate layout management to
ClutterLayoutManager directly; in the allocation, this is done by
checking whether the actor has children, and then call
clutter_layout_manager_allocate() from within the default implementation
of the ClutterActor::allocate() vfunc. The same vfunc that everyone, has
been chaining up to.
Whoopsie.
Well, we can check if there's a layout manager, and if it's NULL, we
bail out. Except that there's a default layout manager, and it's the
fixed layout manager, so that classes like Group and Stage work by
default.
Double whoopsie.
The fix for this scenario is a bit nasty; we have to check if the actor
class has overridden the allocate() vfunc or not, before actually
looking at the layout manager. This means that classes that override the
allocate() vfunc are expected to do everything that ClutterActor's
default implementation does - which I think it's a fair requirement to
have.
For newly written code, though, it would probably be best if we just
provided a function that does the right thing by default, and that
you're supposed to be calling from within the allocate() vfunc
implementation, if you ever chose to override it. This new function,
clutter_actor_set_allocation(), should come with a warning the size of
Texas, to avoid people thinking it's a way to override the whole "call
allocate() on each child" mechanism. Plus, it should check if we're
inside an allocation sequence, and bail out if not.
The hide_all() method is pretty much pointless, as hiding an actor will
automatically prevent its children from being painted. The show_all()
method would only be marginally useful, if actors weren't set to be
visible by default when added to another actor - which was the case when
we introduced show_all() and hide_all().
The concept of "internal child" only meant anything when we had a
separate API for containers and actors. Now that we plugged that
particular hole, we can drop all the hacks we used to have in place
to work around its design limitations.
It can be convenient to be able to set, or get, all the components of an
actor's margin at the same time; since we already have a boxed type for
storing a margin, an accessors pair based on it is not a complicated
addition to the API.
We have a replacement in ClutterActor, now.
The old ClutterContainer API needs to be deprecated, and the raise() and
lower() virtual functions need a default implementation, so we can check
for implementations overriding them, by using the diagnostic mode like
we do for add(), remove(), and foreach().
The sort_depth_order() virtual function just doesn't do anything, as it
should have been made ages ago.
The Actor wrappers for the Container methods also need to be deprecated.
ClutterActor provides four methods for changing the paint sequence order
of its children:
raise_top()
raise()
lower()
lower_bottom()
The first and last one being just wrappers around raise() and lower(),
respectively. These methods have various issues: they omit the parent,
preferring to retrieve it from the actor passed as the first argument;
this does not match the new style of API introduced to operate on the
list of children of an actor.
Additionally, the raise() and lower() methods of ClutterActor call into
the Container interface, and are not really aptly named (raise() in
particular collides with the completely unrelated 'raise' keyword in
Python, and usually needs to be wrapped in order to be used at all).
Furthermore, we need public methods that Container can call from its
default implementation, as well as methods to port current Container
implementations.
Finally, since we have insert_child_at_index(), we should also have an
equivalent set_child_at_index() as well.
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.
