mirror of
https://github.com/brl/mutter.git
synced 2024-11-27 10:30:47 -05:00
180 lines
8.7 KiB
C
180 lines
8.7 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
|
|
* <function>update_allocation()</function> 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>
|
|
* <programlisting>
|
|
* <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../../../../tests/interactive/test-snap-constraint.c" parse="text"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include>
|
|
* </programlisting>
|
|
* <figure id="constraints-example">
|
|
* <title>Constraints</title>
|
|
* <graphic fileref="constraints-example.png" format="PNG"/>
|
|
* </figure>
|
|
* <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 "clutter-constraint.h"
|
|
|
|
#include "clutter-actor.h"
|
|
#include "clutter-actor-meta-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_class_init (ClutterConstraintClass *klass)
|
|
{
|
|
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);
|
|
}
|