Files
build
clutter
cally
cex100
cogl
deprecated
egl
evdev
gdk
osx
tslib
wayland
win32
x11
Makefile.am
abicheck.sh
clutter-action.c
clutter-action.h
clutter-actor-box.c
clutter-actor-meta-private.h
clutter-actor-meta.c
clutter-actor-meta.h
clutter-actor-private.h
clutter-actor.c
clutter-actor.h
clutter-align-constraint.c
clutter-align-constraint.h
clutter-animatable.c
clutter-animatable.h
clutter-backend-private.h
clutter-backend.c
clutter-backend.h
clutter-base-types.c
clutter-bezier.c
clutter-bezier.h
clutter-bin-layout.c
clutter-bin-layout.h
clutter-bind-constraint.c
clutter-bind-constraint.h
clutter-binding-pool.c
clutter-binding-pool.h
clutter-blur-effect.c
clutter-blur-effect.h
clutter-box-layout.c
clutter-box-layout.h
clutter-brightness-contrast-effect.c
clutter-brightness-contrast-effect.h
clutter-cairo.c
clutter-cairo.h
clutter-canvas.c
clutter-canvas.h
clutter-child-meta.c
clutter-child-meta.h
clutter-click-action.c
clutter-click-action.h
clutter-clone.c
clutter-clone.h
clutter-cogl-compat.h
clutter-color-static.h
clutter-color.c
clutter-color.h
clutter-colorize-effect.c
clutter-colorize-effect.h
clutter-config.h.in
clutter-config.h.win32
clutter-config.h.win32_GDK
clutter-constraint.c
clutter-constraint.h
clutter-container.c
clutter-container.h
clutter-content-private.h
clutter-content.c
clutter-content.h
clutter-debug.h
clutter-deform-effect.c
clutter-deform-effect.h
clutter-deprecated.h
clutter-desaturate-effect.c
clutter-desaturate-effect.h
clutter-device-manager-private.h
clutter-device-manager.c
clutter-device-manager.h
clutter-drag-action.c
clutter-drag-action.h
clutter-drop-action.c
clutter-drop-action.h
clutter-easing.c
clutter-easing.h
clutter-effect-private.h
clutter-effect.c
clutter-effect.h
clutter-enum-types.c.in
clutter-enum-types.h.in
clutter-enums.h
clutter-event-private.h
clutter-event-translator.c
clutter-event-translator.h
clutter-event.c
clutter-event.h
clutter-feature.c
clutter-feature.h
clutter-fixed-layout.c
clutter-fixed-layout.h
clutter-flatten-effect.c
clutter-flatten-effect.h
clutter-flow-layout.c
clutter-flow-layout.h
clutter-gesture-action-private.h
clutter-gesture-action.c
clutter-gesture-action.h
clutter-grid-layout.c
clutter-grid-layout.h
clutter-group.h
clutter-id-pool.c
clutter-id-pool.h
clutter-image.c
clutter-image.h
clutter-input-device.c
clutter-input-device.h
clutter-interval.c
clutter-interval.h
clutter-keyframe-transition.c
clutter-keyframe-transition.h
clutter-keysyms-table.c
clutter-keysyms-update.pl
clutter-keysyms.h
clutter-layout-manager.c
clutter-layout-manager.h
clutter-layout-meta.c
clutter-layout-meta.h
clutter-list-model.c
clutter-list-model.h
clutter-macros.h
clutter-main.c
clutter-main.h
clutter-marshal.list
clutter-master-clock.c
clutter-master-clock.h
clutter-model-private.h
clutter-model.c
clutter-model.h
clutter-offscreen-effect-private.h
clutter-offscreen-effect.c
clutter-offscreen-effect.h
clutter-page-turn-effect.c
clutter-page-turn-effect.h
clutter-paint-node-private.h
clutter-paint-node.c
clutter-paint-node.h
clutter-paint-nodes.c
clutter-paint-nodes.h
clutter-paint-volume-private.h
clutter-paint-volume.c
clutter-pan-action.c
clutter-pan-action.h
clutter-path-constraint.c
clutter-path-constraint.h
clutter-path.c
clutter-path.h
clutter-private.h
clutter-profile.c
clutter-profile.h
clutter-property-transition.c
clutter-property-transition.h
clutter-rotate-action.c
clutter-rotate-action.h
clutter-script-parser.c
clutter-script-private.h
clutter-script.c
clutter-script.h
clutter-scriptable.c
clutter-scriptable.h
clutter-scroll-actor.c
clutter-scroll-actor.h
clutter-settings-private.h
clutter-settings.c
clutter-settings.h
clutter-shader-effect.c
clutter-shader-effect.h
clutter-shader-types.c
clutter-shader-types.h
clutter-snap-constraint.c
clutter-snap-constraint.h
clutter-stage-manager-private.h
clutter-stage-manager.c
clutter-stage-manager.h
clutter-stage-private.h
clutter-stage-window.c
clutter-stage-window.h
clutter-stage.c
clutter-stage.h
clutter-swipe-action.c
clutter-swipe-action.h
clutter-table-layout.c
clutter-table-layout.h
clutter-tap-action.c
clutter-tap-action.h
clutter-text-buffer.c
clutter-text-buffer.h
clutter-text.c
clutter-text.h
clutter-texture.h
clutter-timeline.c
clutter-timeline.h
clutter-transition-group.c
clutter-transition-group.h
clutter-transition.c
clutter-transition.h
clutter-types.h
clutter-units.c
clutter-units.h
clutter-util.c
clutter-version.h.in
clutter-zoom-action.c
clutter-zoom-action.h
clutter.h
clutter.pc.in
clutter.symbols
config.h.win32.in
doc
examples
po
tests
.gitignore
COPYING
ChangeLog.pre-git-import
Makefile.am
NEWS
README.in
README.md
autogen.sh
clutter.doap
configure.ac
mutter/clutter/clutter-constraint.c
Emmanuele Bassi 07c95ebf0c Move examples from tests/interactive to a new top-level
The example code that is meant to be XIncluded into the API reference
should not be part of the interactive test suite: it's code that it is
meant to be used as a reference implementation - whereas the interactive
test suite should be allowed to be lean and test behaviour even in nasty
ways. In short: the test suite should not be the place where we show off
idiomatic code for educational purposes.
2012-05-01 19:00:35 +01:00

206 lines
9.4 KiB
C

/**
* SECTION:clutter-constraint
* @Title: ClutterConstraint
* @Short_Description: Abstract class for constraints on position or size
* @See_Also: #ClutterAction
*
* #ClutterConstraint is a base abstract class for modifiers of a #ClutterActor
* position or size.
*
* A #ClutterConstraint sub-class should contain the logic for modifying
* the position or size of the #ClutterActor to which it is applied, by
* updating the actor's allocation. Each #ClutterConstraint can change the
* allocation of the actor to which they are applied by overriding the
* #ClutterConstraintClass.update_allocation() virtual function.
*
* <refsect2 id="ClutterConstraint-usage">
* <title>Using Constraints</title>
* <para>Constraints can be used with fixed layout managers, like
* #ClutterFixedLayout, or with actors implicitly using a fixed layout
* manager, like #ClutterGroup and #ClutterStage.</para>
* <para>Constraints provide a way to build user interfaces by using
* relations between #ClutterActor<!-- -->s, without explicit fixed
* positioning and sizing, similarly to how fluid layout managers like
* #ClutterBoxLayout and #ClutterTableLayout lay out their children.</para>
* <para>Constraints are attached to a #ClutterActor, and are available
* for inspection using clutter_actor_get_constraints().</para>
* <para>Clutter provides different implementation of the #ClutterConstraint
* abstract class, for instance:</para>
* <variablelist>
* <varlistentry>
* <term>#ClutterAlignConstraint</term>
* <listitem><simpara>this constraint can be used to align an actor
* to another one, on either the horizontal or the vertical axis; the
* #ClutterAlignConstraint uses a normalized offset between 0.0 (the
* top or the left of the source actor, depending on the axis) and
* 1.0 (the bottom or the right of the source actor, depending on the
* axis).</simpara></listitem>
* </varlistentry>
* <varlistentry>
* <term>#ClutterBindConstraint</term>
* <listitem><simpara>this constraint binds the X, Y, width or height
* of an actor to the corresponding position or size of a source
* actor; it can also apply an offset.</simpara></listitem>
* </varlistentry>
* <varlistentry>
* <term>#ClutterSnapConstraint</term>
* <listitem><simpara>this constraint "snaps" together the edges of
* two #ClutterActor<!-- -->s; if an actor uses two constraints on
* both its horizontal or vertical edges then it can also expand to
* fit the empty space.</simpara></listitem>
* </varlistentry>
* </variablelist>
* <example id="ClutterConstraint-usage-example">
* <title>Usage of constraints</title>
* <para>The example below uses various #ClutterConstraint<!-- -->s to
* lay out three actors on a resizable stage. Only the central actor has
* an explicit size, and no actor has an explicit position.</para>
* <orderedlist>
* <listitem><simpara>The #ClutterRectangle with #ClutterActor:name
* <emphasis>layerA</emphasis> is explicitly sized to 100 pixels by 25
* pixels, and it's added to the #ClutterStage;</simpara></listitem>
* <listitem><simpara>two #ClutterAlignConstraint<!-- -->s are used
* to anchor <emphasis>layerA</emphasis> to the center of the stage,
* by using 0.5 as the alignment #ClutterAlignConstraint:factor on
* both the X and Y axis.</simpara></listitem>
* <listitem><simpara>the #ClutterRectangle with #ClutterActor:name
* <emphasis>layerB</emphasis> is added to the #ClutterStage with
* no explicit size;</simpara></listitem>
* <listitem><simpara>the #ClutterActor:x and #ClutterActor:width
* of <emphasis>layerB</emphasis> are bound to the same properties
* of <emphasis>layerA</emphasis> using two #ClutterBindConstraint
* objects, thus keeping <emphasis>layerB</emphasis> aligned to
* <emphasis>layerA</emphasis>;</simpara></listitem>
* <listitem><simpara>the top edge of <emphasis>layerB</emphasis> is
* snapped together with the bottom edge of <emphasis>layerA</emphasis>;
* the bottom edge of <emphasis>layerB</emphasis> is also snapped
* together with the bottom edge of the #ClutterStage; an offset is
* given to the two #ClutterSnapConstraint<!-- -->s to allow for some
* padding; since <emphasis>layerB</emphasis> is snapped between two
* different #ClutterActor<!-- -->s, its height is stretched to match
* the gap;</simpara></listitem>
* <listitem><simpara>the #ClutterRectangle with #ClutterActor:name
* <emphasis>layerC</emphasis> mirrors <emphasis>layerB</emphasis>,
* snapping the top edge of the #ClutterStage to the top edge of
* <emphasis>layerC</emphasis> and the top edge of
* <emphasis>layerA</emphasis> to the bottom edge of
* <emphasis>layerC</emphasis>;</simpara></listitem>
* </orderedlist>
* <figure id="constraints-example">
* <title>Constraints</title>
* <graphic fileref="constraints-example.png" format="PNG"/>
* </figure>
* <programlisting>
*<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../examples/constraints.c" parse="text">
* <xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback>
*</xi:include>
* </programlisting>
* <para>You can try resizing interactively the #ClutterStage and verify
* that the three #ClutterActor<!-- -->s maintain the same position and
* size relative to each other, and to the #ClutterStage.</para>
* </example>
* <warning><para>It's important to note that Clutter does not avoid loops
* or competing constraints; if two or more #ClutterConstraint<!-- -->s
* are operating on the same positional or dimensional attributes of an
* actor, or if the constraints on two different actors depend on each
* other, then the behavior is undefined.</para></warning>
* </refsect2>
*
* <refsect2 id="ClutterConstraint-implementation">
* <title>Implementing a ClutterConstraint</title>
* <para>Creating a sub-class of #ClutterConstraint requires the
* implementation of the <function>update_allocation()</function>
* virtual function.</para>
* <para>The <function>update_allocation()</function> virtual function
* is called during the allocation sequence of a #ClutterActor, and
* allows any #ClutterConstraint attached to that actor to modify the
* allocation before it is passed to the <function>allocate()</function>
* implementation.</para>
* <para>The #ClutterActorBox passed to the
* <function>update_allocation()</function> implementation contains the
* original allocation of the #ClutterActor, plus the eventual modifications
* applied by the other #ClutterConstraint<!-- -->s.</para>
* <note><para>Constraints are queried in the same order as they were
* applied using clutter_actor_add_constraint() or
* clutter_actor_add_constraint_with_name().</para></note>
* <para>It is not necessary for a #ClutterConstraint sub-class to chain
* up to the parent's implementation.</para>
* <para>If a #ClutterConstraint is parametrized - i.e. if it contains
* properties that affect the way the constraint is implemented - it should
* call clutter_actor_queue_relayout() on the actor to which it is attached
* to whenever any parameter is changed. The actor to which it is attached
* can be recovered at any point using clutter_actor_meta_get_actor().</para>
* </refsect2>
*
* #ClutterConstraint is available since Clutter 1.4
*/
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif
#include <string.h>
#include "clutter-constraint.h"
#include "clutter-actor.h"
#include "clutter-actor-meta-private.h"
#include "clutter-private.h"
G_DEFINE_ABSTRACT_TYPE (ClutterConstraint,
clutter_constraint,
CLUTTER_TYPE_ACTOR_META);
static void
constraint_update_allocation (ClutterConstraint *constraint,
ClutterActor *actor,
ClutterActorBox *allocation)
{
}
static void
clutter_constraint_notify (GObject *gobject,
GParamSpec *pspec)
{
if (strcmp (pspec->name, "enabled") == 0)
{
ClutterActorMeta *meta = CLUTTER_ACTOR_META (gobject);
ClutterActor *actor = clutter_actor_meta_get_actor (meta);
if (actor != NULL)
clutter_actor_queue_relayout (actor);
}
if (G_OBJECT_CLASS (clutter_constraint_parent_class)->notify != NULL)
G_OBJECT_CLASS (clutter_constraint_parent_class)->notify (gobject, pspec);
}
static void
clutter_constraint_class_init (ClutterConstraintClass *klass)
{
GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
gobject_class->notify = clutter_constraint_notify;
klass->update_allocation = constraint_update_allocation;
}
static void
clutter_constraint_init (ClutterConstraint *self)
{
}
void
_clutter_constraint_update_allocation (ClutterConstraint *constraint,
ClutterActor *actor,
ClutterActorBox *allocation)
{
g_return_if_fail (CLUTTER_IS_CONSTRAINT (constraint));
g_return_if_fail (CLUTTER_IS_ACTOR (actor));
g_return_if_fail (allocation != NULL);
CLUTTER_CONSTRAINT_GET_CLASS (constraint)->update_allocation (constraint,
actor,
allocation);
}