<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>ClutterConstraint: Clutter Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="Clutter Reference Manual">
<link rel="up" href="ch01.html" title="Abstract classes and interfaces">
<link rel="prev" href="ClutterAction.html" title="ClutterAction">
<link rel="next" href="ClutterEffect.html" title="ClutterEffect">
<meta name="generator" content="GTK-Doc V1.25.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts">
<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span>
<a href="#ClutterConstraint.description" class="shortcut">Description</a></span><span id="nav_hierarchy"> <span class="dim">|</span>
<a href="#ClutterConstraint.object-hierarchy" class="shortcut">Object Hierarchy</a></span>
</td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="ch01.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="ClutterAction.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="ClutterEffect.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="ClutterConstraint"></a><div class="titlepage"></div>
<div class="refnamediv"><table width="100%"><tr>
<td valign="top">
<h2><span class="refentrytitle"><a name="ClutterConstraint.top_of_page"></a>ClutterConstraint</span></h2>
<p>ClutterConstraint — Abstract class for constraints on position or size</p>
</td>
<td class="gallery_image" valign="top" align="right"></td>
</tr></table></div>
<div class="refsect1">
<a name="ClutterConstraint.other"></a><h2>Types and Values</h2>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="150px" class="name">
<col class="description">
</colgroup>
<tbody>
<tr>
<td class="datatype_keyword"> </td>
<td class="function_name"><a class="link" href="ClutterConstraint.html#ClutterConstraint-struct" title="ClutterConstraint">ClutterConstraint</a></td>
</tr>
<tr>
<td class="datatype_keyword">struct</td>
<td class="function_name"><a class="link" href="ClutterConstraint.html#ClutterConstraintClass" title="struct ClutterConstraintClass">ClutterConstraintClass</a></td>
</tr>
</tbody>
</table></div>
</div>
<div class="refsect1">
<a name="ClutterConstraint.object-hierarchy"></a><h2>Object Hierarchy</h2>
<pre class="screen"> GObject
<span class="lineart">╰──</span> GInitiallyUnowned
<span class="lineart">╰──</span> <a class="link" href="ClutterActorMeta.html" title="ClutterActorMeta">ClutterActorMeta</a>
<span class="lineart">╰──</span> ClutterConstraint
<span class="lineart">├──</span> <a class="link" href="ClutterAlignConstraint.html" title="ClutterAlignConstraint">ClutterAlignConstraint</a>
<span class="lineart">├──</span> <a class="link" href="ClutterBindConstraint.html" title="ClutterBindConstraint">ClutterBindConstraint</a>
<span class="lineart">├──</span> <a class="link" href="ClutterPathConstraint.html" title="ClutterPathConstraint">ClutterPathConstraint</a>
<span class="lineart">╰──</span> <a class="link" href="ClutterSnapConstraint.html" title="ClutterSnapConstraint">ClutterSnapConstraint</a>
</pre>
</div>
<div class="refsect1">
<a name="ClutterConstraint.description"></a><h2>Description</h2>
<p><a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> is a base abstract class for modifiers of a <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>
position or size.</p>
<p>A <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> sub-class should contain the logic for modifying
the position or size of the <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> to which it is applied, by
updating the actor's allocation. Each <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> can change the
allocation of the actor to which they are applied by overriding the
<a class="link" href="ClutterConstraint.html#ClutterConstraintClass.update-allocation"><code class="function">ClutterConstraintClass.update_allocation()</code></a> virtual function.</p>
<p><a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> is available since Clutter 1.4</p>
<div class="refsect3">
<a name="id-1.5.2.10.5.5"></a><h4>Using Constraints</h4>
<p>Constraints can be used with fixed layout managers, like
<a class="link" href="ClutterFixedLayout.html" title="ClutterFixedLayout"><span class="type">ClutterFixedLayout</span></a>, or with actors implicitly using a fixed layout
manager, like <a class="link" href="ClutterGroup.html" title="ClutterGroup"><span class="type">ClutterGroup</span></a> and <a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a>.</p>
<p>Constraints provide a way to build user interfaces by using
relations between <a href="ClutterActor.html#ClutterActor-struct"><span class="type">ClutterActors</span></a>, without explicit fixed
positioning and sizing, similarly to how fluid layout managers like
<a class="link" href="ClutterBoxLayout.html" title="ClutterBoxLayout"><span class="type">ClutterBoxLayout</span></a> and <a class="link" href="ClutterTableLayout.html" title="ClutterTableLayout"><span class="type">ClutterTableLayout</span></a> lay out their children.</p>
<p>Constraints are attached to a <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>, and are available
for inspection using <a class="link" href="ClutterActor.html#clutter-actor-get-constraints" title="clutter_actor_get_constraints ()"><code class="function">clutter_actor_get_constraints()</code></a>.</p>
<p>Clutter provides different implementation of the <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a>
abstract class, for instance:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p><a class="link" href="ClutterAlignConstraint.html" title="ClutterAlignConstraint"><span class="type">ClutterAlignConstraint</span></a>, a constraint that can be used to align
an actor to another one on either the horizontal or the vertical
axis, using a normalized value between 0 and 1.</p></li>
<li class="listitem"><p><a class="link" href="ClutterBindConstraint.html" title="ClutterBindConstraint"><span class="type">ClutterBindConstraint</span></a>, a constraint binds the X, Y, width or height
of an actor to the corresponding position or size of a source actor,
with or without an offset.</p></li>
<li class="listitem"><p><a class="link" href="ClutterSnapConstraint.html" title="ClutterSnapConstraint"><span class="type">ClutterSnapConstraint</span></a>, a constraint that "snaps" together the edges
of two <a href="ClutterActor.html#ClutterActor-struct"><span class="type">ClutterActors</span></a>; if an actor uses two constraints on both its
horizontal or vertical edges then it can also expand to fit the empty
space.</p></li>
</ul></div>
<p>The <a class="ulink" href="https://git.gnome.org/browse/clutter/tree/examples/constraints.c?h=clutter-1.18" target="_top">constraints example</a>
uses various types of <a href="ClutterConstraint.html#ClutterConstraint-struct"><span class="type">ClutterConstraints</span></a> to lay out three actors on a
resizable stage. Only the central actor has an explicit size, and no
actor has an explicit position.</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>The <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> with <a class="link" href="ClutterActor.html#ClutterActor--name" title="The “name” property"><span class="type">“name”</span></a> <code class="literal">layerA</code> is explicitly
sized to 100 pixels by 25 pixels, and it's added to the <a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a></p></li>
<li class="listitem"><p>two <a href="ClutterAlignConstraint.html#ClutterAlignConstraint-struct"><span class="type">ClutterAlignConstraints</span></a> are used to anchor <code class="literal">layerA</code> to the
center of the stage, by using 0.5 as the alignment <a class="link" href="ClutterAlignConstraint.html#ClutterAlignConstraint--factor" title="The “factor” property"><span class="type">“factor”</span></a> on
both the X and Y axis</p></li>
<li class="listitem"><p>the <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> with <a class="link" href="ClutterActor.html#ClutterActor--name" title="The “name” property"><span class="type">“name”</span></a> <code class="literal">layerB</code> is added to the
<a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a> with no explicit size</p></li>
<li class="listitem"><p>the <a class="link" href="ClutterActor.html#ClutterActor--x" title="The “x” property"><span class="type">“x”</span></a> and <a class="link" href="ClutterActor.html#ClutterActor--width" title="The “width” property"><span class="type">“width”</span></a> of <code class="literal">layerB</code> are bound
to the same properties of <code class="literal">layerA</code> using two <a class="link" href="ClutterBindConstraint.html" title="ClutterBindConstraint"><span class="type">ClutterBindConstraint</span></a>
objects, thus keeping <code class="literal">layerB</code> aligned to <code class="literal">layerA</code></p></li>
<li class="listitem"><p>the top edge of <code class="literal">layerB</code> is snapped together with the bottom edge
of <code class="literal">layerA</code>; the bottom edge of <code class="literal">layerB</code> is also snapped together with
the bottom edge of the <a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a>; an offset is given to the two
<span class="type">ClutterSnapConstraintss</span> to allow for some padding; since <code class="literal">layerB</code> is
snapped between two different <a href="ClutterActor.html#ClutterActor-struct"><span class="type">ClutterActors</span></a>, its height is stretched
to match the gap</p></li>
<li class="listitem"><p>the <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> with <a class="link" href="ClutterActor.html#ClutterActor--name" title="The “name” property"><span class="type">“name”</span></a> <code class="literal">layerC</code> mirrors <code class="literal">layerB</code>,
snapping the top edge of the <a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a> to the top edge of <code class="literal">layerC</code>
and the top edge of <code class="literal">layerA</code> to the bottom edge of <code class="literal">layerC</code></p></li>
</ul></div>
<p>You can try resizing interactively the <a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a> and verify
that the three <a href="ClutterActor.html#ClutterActor-struct"><span class="type">ClutterActors</span></a> maintain the same position and
size relative to each other, and to the <a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a>.</p>
<p>It is important to note that Clutter does not avoid loops or
competing constraints; if two or more <a href="ClutterConstraint.html#ClutterConstraint-struct"><span class="type">ClutterConstraints</span></a>
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.</p>
</div>
<div class="refsect3">
<a name="id-1.5.2.10.5.6"></a><h4>Implementing a ClutterConstraint</h4>
<p>Creating a sub-class of <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> requires the
implementation of the <a class="link" href="ClutterConstraint.html#ClutterConstraintClass.update-allocation"><code class="function">ClutterConstraintClass.update_allocation()</code></a>
virtual function.</p>
<p>The <code class="literal"><code class="function">update_allocation()</code></code> virtual function is called during the
allocation sequence of a <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>, and allows any <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a>
attached to that actor to modify the allocation before it is passed to
the actor's <a class="link" href="ClutterActor.html#ClutterActorClass.allocate"><code class="function">ClutterActorClass.allocate()</code></a> implementation.</p>
<p>The <a class="link" href="clutter-Base-geometric-types.html#ClutterActorBox"><span class="type">ClutterActorBox</span></a> passed to the <code class="literal"><code class="function">update_allocation()</code></code> implementation
contains the original allocation of the <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>, plus the eventual
modifications applied by the other <a href="ClutterConstraint.html#ClutterConstraint-struct"><span class="type">ClutterConstraints</span></a>, in the same order
the constraints have been applied to the actor.</p>
<p>It is not necessary for a <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> sub-class to chain
up to the parent's implementation.</p>
<p>If a <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> is parametrized - i.e. if it contains
properties that affect the way the constraint is implemented - it should
call <a class="link" href="ClutterActor.html#clutter-actor-queue-relayout" title="clutter_actor_queue_relayout ()"><code class="function">clutter_actor_queue_relayout()</code></a> 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 <a class="link" href="ClutterActorMeta.html#clutter-actor-meta-get-actor" title="clutter_actor_meta_get_actor ()"><code class="function">clutter_actor_meta_get_actor()</code></a>.</p>
</div>
</div>
<div class="refsect1">
<a name="ClutterConstraint.functions_details"></a><h2>Functions</h2>
<p></p>
</div>
<div class="refsect1">
<a name="ClutterConstraint.other_details"></a><h2>Types and Values</h2>
<div class="refsect2">
<a name="ClutterConstraint-struct"></a><h3>ClutterConstraint</h3>
<pre class="programlisting">typedef struct _ClutterConstraint ClutterConstraint;</pre>
<p>The <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> structure contains only
private data and should be accessed using the provided API</p>
<p class="since">Since: <a class="link" href="ix09.html#api-index-1.4">1.4</a></p>
</div>
<hr>
<div class="refsect2">
<a name="ClutterConstraintClass"></a><h3>struct ClutterConstraintClass</h3>
<pre class="programlisting">struct ClutterConstraintClass {
void (* update_allocation) (ClutterConstraint *constraint,
ClutterActor *actor,
ClutterActorBox *allocation);
void (* update_preferred_size) (ClutterConstraint *constraint,
ClutterActor *actor,
ClutterOrientation direction,
float for_size,
float *minimum_size,
float *natural_size);
};
</pre>
<p>The <a class="link" href="ClutterConstraint.html#ClutterConstraintClass" title="struct ClutterConstraintClass"><span class="type">ClutterConstraintClass</span></a> structure contains
only private data</p>
<div class="refsect3">
<a name="ClutterConstraintClass.members"></a><h4>Members</h4>
<div class="informaltable"><table class="informaltable" width="100%" border="0">
<colgroup>
<col width="300px" class="struct_members_name">
<col class="struct_members_description">
<col width="200px" class="struct_members_annotations">
</colgroup>
<tbody>
<tr>
<td class="struct_member_name"><p><em class="structfield"><code><a name="ClutterConstraintClass.update-allocation"></a>update_allocation</code></em> ()</p></td>
<td class="struct_member_description"><p>virtual function used to update the allocation
of the <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> using the <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a></p></td>
<td class="struct_member_annotations"> </td>
</tr>
<tr>
<td class="struct_member_name"><p><em class="structfield"><code><a name="ClutterConstraintClass.update-preferred-size"></a>update_preferred_size</code></em> ()</p></td>
<td class="struct_member_description"><p>virtual function used to update the preferred
size of the <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a> using the <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a>; optional,
since 1.22</p></td>
<td class="struct_member_annotations"> </td>
</tr>
</tbody>
</table></div>
</div>
<p class="since">Since: <a class="link" href="ix09.html#api-index-1.4">1.4</a></p>
</div>
</div>
<div class="refsect1">
<a name="ClutterConstraint.see-also"></a><h2>See Also</h2>
<p><a class="link" href="ClutterAction.html" title="ClutterAction"><span class="type">ClutterAction</span></a></p>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.25.1</div>
</body>
</html>