/usr/share/gtk-doc/html/clutter/ClutterConstraint.html is in libclutter-1.0-doc 1.16.4-0ubuntu2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Clutter Reference Manual: ClutterConstraint</title>
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
<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.20 (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="10"><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 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
<code class="function">ClutterConstraintClass.update_allocation()</code> virtual function.</p>
<div class="refsect2">
<a name="ClutterConstraint-usage"></a><h3>Using Constraints</h3>
<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 class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>s, 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="variablelist"><table border="0" class="variablelist">
<colgroup>
<col align="left" valign="top">
<col>
</colgroup>
<tbody>
<tr>
<td><p><span class="term"><a class="link" href="ClutterAlignConstraint.html" title="ClutterAlignConstraint"><span class="type">ClutterAlignConstraint</span></a></span></p></td>
<td>this constraint can be used to align an actor
to another one, on either the horizontal or the vertical axis; the
<a class="link" href="ClutterAlignConstraint.html" title="ClutterAlignConstraint"><span class="type">ClutterAlignConstraint</span></a> 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).</td>
</tr>
<tr>
<td><p><span class="term"><a class="link" href="ClutterBindConstraint.html" title="ClutterBindConstraint"><span class="type">ClutterBindConstraint</span></a></span></p></td>
<td>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.</td>
</tr>
<tr>
<td><p><span class="term"><a class="link" href="ClutterSnapConstraint.html" title="ClutterSnapConstraint"><span class="type">ClutterSnapConstraint</span></a></span></p></td>
<td>this constraint "snaps" together the edges of
two <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>s; if an actor uses two constraints on
both its horizontal or vertical edges then it can also expand to
fit the empty space.</td>
</tr>
</tbody>
</table></div>
<div class="example">
<a name="ClutterConstraint-usage-example"></a><p class="title"><b>Example 2. Usage of constraints</b></p>
<div class="example-contents">
<p>The example below uses various <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a>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.</p>
<div class="orderedlist"><ol class="orderedlist" type="1">
<li class="listitem">The <a class="link" href="ClutterRectangle.html" title="ClutterRectangle"><span class="type">ClutterRectangle</span></a> with <a class="link" href="ClutterActor.html#ClutterActor--name" title="The “name” property"><span class="type">“name”</span></a>
<span class="emphasis"><em>layerA</em></span> 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>;</li>
<li class="listitem">two <a class="link" href="ClutterAlignConstraint.html" title="ClutterAlignConstraint"><span class="type">ClutterAlignConstraint</span></a>s are used
to anchor <span class="emphasis"><em>layerA</em></span> 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.</li>
<li class="listitem">the <a class="link" href="ClutterRectangle.html" title="ClutterRectangle"><span class="type">ClutterRectangle</span></a> with <a class="link" href="ClutterActor.html#ClutterActor--name" title="The “name” property"><span class="type">“name”</span></a>
<span class="emphasis"><em>layerB</em></span> is added to the <a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a> with
no explicit size;</li>
<li class="listitem">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 <span class="emphasis"><em>layerB</em></span> are bound to the same properties
of <span class="emphasis"><em>layerA</em></span> using two <a class="link" href="ClutterBindConstraint.html" title="ClutterBindConstraint"><span class="type">ClutterBindConstraint</span></a>
objects, thus keeping <span class="emphasis"><em>layerB</em></span> aligned to
<span class="emphasis"><em>layerA</em></span>;</li>
<li class="listitem">the top edge of <span class="emphasis"><em>layerB</em></span> is
snapped together with the bottom edge of <span class="emphasis"><em>layerA</em></span>;
the bottom edge of <span class="emphasis"><em>layerB</em></span> 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 <a class="link" href="ClutterSnapConstraint.html" title="ClutterSnapConstraint"><span class="type">ClutterSnapConstraint</span></a>s to allow for some
padding; since <span class="emphasis"><em>layerB</em></span> is snapped between two
different <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>s, its height is stretched to match
the gap;</li>
<li class="listitem">the <a class="link" href="ClutterRectangle.html" title="ClutterRectangle"><span class="type">ClutterRectangle</span></a> with <a class="link" href="ClutterActor.html#ClutterActor--name" title="The “name” property"><span class="type">“name”</span></a>
<span class="emphasis"><em>layerC</em></span> mirrors <span class="emphasis"><em>layerB</em></span>,
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
<span class="emphasis"><em>layerC</em></span> and the top edge of
<span class="emphasis"><em>layerA</em></span> to the bottom edge of
<span class="emphasis"><em>layerC</em></span>;</li>
</ol></div>
<div class="figure">
<a name="constraints-example"></a><p class="title"><b>Figure 3. Constraints</b></p>
<div class="figure-contents"><div><img src="constraints-example.png" alt="Constraints"></div></div>
</div>
<br class="figure-break"><pre class="programlisting">
#include <stdlib.h>
#include <clutter/clutter.h>
int
main (int argc, char *argv[])
{
ClutterActor *stage, *layer_a, *layer_b, *layer_c;
if (clutter_init (&argc, &argv) != CLUTTER_INIT_SUCCESS)
return 1;
/* the main container */
stage = clutter_stage_new ();
clutter_actor_set_name (stage, "stage");
clutter_stage_set_title (CLUTTER_STAGE (stage), "Snap Constraint");
clutter_actor_set_background_color (stage, CLUTTER_COLOR_Aluminium1);
clutter_stage_set_user_resizable (CLUTTER_STAGE (stage), TRUE);
g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);
/* first layer, with a fixed (100, 25) size */
layer_a = clutter_actor_new ();
clutter_actor_set_background_color (layer_a, CLUTTER_COLOR_ScarletRed);
clutter_actor_set_name (layer_a, "layerA");
clutter_actor_set_size (layer_a, 100.0, 25.0);
clutter_actor_add_child (stage, layer_a);
/* the first layer is anchored to the middle of the stage */
clutter_actor_add_constraint (layer_a, clutter_align_constraint_new (stage, CLUTTER_ALIGN_BOTH, 0.5));
/* second layer, with no implicit size */
layer_b = clutter_actor_new ();
clutter_actor_set_background_color (layer_b, CLUTTER_COLOR_DarkButter);
clutter_actor_set_name (layer_b, "layerB");
clutter_actor_add_child (stage, layer_b);
/* the second layer tracks the X coordinate and the width of
* the first layer
*/
clutter_actor_add_constraint (layer_b, clutter_bind_constraint_new (layer_a, CLUTTER_BIND_X, 0.0));
clutter_actor_add_constraint (layer_b, clutter_bind_constraint_new (layer_a, CLUTTER_BIND_WIDTH, 0.0));
/* the second layer is snapped between the bottom edge of
* the first layer, and the bottom edge of the stage; a
* spacing of 10 pixels in each direction is added for padding
*/
clutter_actor_add_constraint (layer_b,
clutter_snap_constraint_new (layer_a,
CLUTTER_SNAP_EDGE_TOP,
CLUTTER_SNAP_EDGE_BOTTOM,
10.0));
clutter_actor_add_constraint (layer_b,
clutter_snap_constraint_new (stage,
CLUTTER_SNAP_EDGE_BOTTOM,
CLUTTER_SNAP_EDGE_BOTTOM,
-10.0));
/* the third layer, with no implicit size */
layer_c = clutter_actor_new ();
clutter_actor_set_background_color (layer_c, CLUTTER_COLOR_LightChameleon);
clutter_actor_set_name (layer_c, "layerC");
clutter_actor_add_child (stage, layer_c);
/* as for the second layer, the third layer tracks the X
* coordinate and width of the first layer
*/
clutter_actor_add_constraint (layer_c, clutter_bind_constraint_new (layer_a, CLUTTER_BIND_X, 0.0));
clutter_actor_add_constraint (layer_c, clutter_bind_constraint_new (layer_a, CLUTTER_BIND_WIDTH, 0.0));
/* the third layer is snapped between the top edge of the stage
* and the top edge of the first layer; again, a spacing of
* 10 pixels in each direction is added for padding
*/
clutter_actor_add_constraint (layer_c,
clutter_snap_constraint_new (layer_a,
CLUTTER_SNAP_EDGE_BOTTOM,
CLUTTER_SNAP_EDGE_TOP,
-10.0));
clutter_actor_add_constraint (layer_c,
clutter_snap_constraint_new (stage,
CLUTTER_SNAP_EDGE_TOP,
CLUTTER_SNAP_EDGE_TOP,
10.0));
clutter_actor_show (stage);
clutter_main ();
return EXIT_SUCCESS;
}
</pre>
<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 class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>s 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>
</div>
</div>
<br class="example-break"><div class="warning"><p>It's important to note that Clutter does not avoid loops
or competing constraints; if two or more <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a>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.</p></div>
</div>
<hr>
<div class="refsect2">
<a name="ClutterConstraint-implementation"></a><h3>Implementing a ClutterConstraint</h3>
<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 <code class="function"><code class="function">update_allocation()</code></code>
virtual function.</p>
<p>The <code class="function"><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 <code class="function"><code class="function">allocate()</code></code>
implementation.</p>
<p>The <a class="link" href="clutter-Base-geometric-types.html#ClutterActorBox" title="struct ClutterActorBox"><span class="type">ClutterActorBox</span></a> passed to the
<code class="function"><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 class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a>s.</p>
<div class="note"><p>Constraints are queried in the same order as they were
applied using <a class="link" href="ClutterActor.html#clutter-actor-add-constraint" title="clutter_actor_add_constraint ()"><code class="function">clutter_actor_add_constraint()</code></a> or
<a class="link" href="ClutterActor.html#clutter-actor-add-constraint-with-name" title="clutter_actor_add_constraint_with_name ()"><code class="function">clutter_actor_add_constraint_with_name()</code></a>.</p></div>
<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>
<p><a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> is available since Clutter 1.4</p>
</div>
<div class="refsect1">
<a name="ClutterConstraint.functions_details"></a><h2>Functions</h2>
</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 <span class="structname">ClutterConstraint</span> structure contains only
private data and should be accessed using the provided API</p>
<p class="since">Since 1.4</p>
</div>
<hr>
<div class="refsect2">
<a name="ClutterConstraintClass"></a><h3>struct ClutterConstraintClass</h3>
<pre class="programlisting">struct ClutterConstraintClass {
};
</pre>
<p>The <span class="structname">ClutterConstraintClass</span> structure contains
only private data</p>
<p class="since">Since 1.4</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.20</div>
</body>
</html>
|