doc/reference/clutter/html/ClutterConstraint.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>ClutterConstraint</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="Clutter Reference Manual">
   8 <link rel="up" href="ch01.html" title="Abstract classes and interfaces">
   9 <link rel="prev" href="ClutterAction.html" title="ClutterAction">
  10 <link rel="next" href="ClutterEffect.html" title="ClutterEffect">
  11 <meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="ClutterAction.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="ch01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">Clutter Reference Manual</th>
  21 <td><a accesskey="n" href="ClutterEffect.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#ClutterConstraint.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#ClutterConstraint.description" class="shortcut">Description</a>
  27                    |
  28                   <a href="#ClutterConstraint.object-hierarchy" class="shortcut">Object Hierarchy</a>
  29 </td></tr>
  30 </table>
  31 <div class="refentry">
  32 <a name="ClutterConstraint"></a><div class="titlepage"></div>
  33 <div class="refnamediv"><table width="100%"><tr>
  34 <td valign="top">
  35 <h2><span class="refentrytitle"><a name="ClutterConstraint.top_of_page"></a>ClutterConstraint</span></h2>
  36 <p>ClutterConstraint — Abstract class for constraints on position or size</p>
  37 </td>
  38 <td valign="top" align="right"></td>
  39 </tr></table></div>
  40 <div class="refsynopsisdiv">
  41 <a name="ClutterConstraint.synopsis"></a><h2>Synopsis</h2>
  42 <pre class="synopsis">                    <a class="link" href="ClutterConstraint.html#ClutterConstraint-struct" title="ClutterConstraint">ClutterConstraint</a>;
  43 struct              <a class="link" href="ClutterConstraint.html#ClutterConstraintClass" title="struct ClutterConstraintClass">ClutterConstraintClass</a>;
  44 </pre>
  45 </div>
  46 <div class="refsect1">
  47 <a name="ClutterConstraint.object-hierarchy"></a><h2>Object Hierarchy</h2>
  48 <pre class="synopsis">
  49   GObject
  50    +----GInitiallyUnowned
  51          +----<a class="link" href="ClutterActorMeta.html" title="ClutterActorMeta">ClutterActorMeta</a>
  52                +----ClutterConstraint
  53                      +----<a class="link" href="ClutterAlignConstraint.html" title="ClutterAlignConstraint">ClutterAlignConstraint</a>
  54                      +----<a class="link" href="ClutterBindConstraint.html" title="ClutterBindConstraint">ClutterBindConstraint</a>
  55                      +----<a class="link" href="ClutterPathConstraint.html" title="ClutterPathConstraint">ClutterPathConstraint</a>
  56                      +----<a class="link" href="ClutterSnapConstraint.html" title="ClutterSnapConstraint">ClutterSnapConstraint</a>
  57 </pre>
  58 </div>
  59 <div class="refsect1">
  60 <a name="ClutterConstraint.description"></a><h2>Description</h2>
  61 <p>
  62 <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>
  63 position or size.
  64 </p>
  65 <p>
  66 A <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> sub-class should contain the logic for modifying
  67 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
  68 updating the actor's allocation. Each <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> can change the
  69 allocation of the actor to which they are applied by overriding the
  70 <code class="function"><code class="function">update_allocation()</code></code> virtual function.
  71 </p>
  72 <p>
  73 </p>
  74 <div class="refsect2">
  75 <a name="ClutterConstraint-usage"></a><h3>Using Constraints</h3>
  76 <p>Constraints can be used with fixed layout managers, like
  77   <a class="link" href="ClutterFixedLayout.html" title="ClutterFixedLayout"><span class="type">ClutterFixedLayout</span></a>, or with actors implicitly using a fixed layout
  78   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>
  79 <p>Constraints provide a way to build user interfaces by using
  80   relations between <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>s, without explicit fixed
  81   positioning and sizing, similarly to how fluid layout managers like
  82   <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>
  83 <p>Constraints are attached to a <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>, and are available
  84   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>
  85 <p>Clutter provides different implementation of the <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a>
  86   abstract class, for instance:</p>
  87 <div class="variablelist"><table border="0">
  88 <col align="left" valign="top">
  89 <tbody>
  90 <tr>
  91 <td><p><span class="term"><a class="link" href="ClutterAlignConstraint.html" title="ClutterAlignConstraint"><span class="type">ClutterAlignConstraint</span></a></span></p></td>
  92 <td>this constraint can be used to align an actor
  93       to another one, on either the horizontal or the vertical axis; the
  94       <a class="link" href="ClutterAlignConstraint.html" title="ClutterAlignConstraint"><span class="type">ClutterAlignConstraint</span></a> uses a normalized offset between 0.0 (the
  95       top or the left of the source actor, depending on the axis) and
  96       1.0 (the bottom or the right of the source actor, depending on the
  97       axis).</td>
  98 </tr>
  99 <tr>
 100 <td><p><span class="term"><a class="link" href="ClutterBindConstraint.html" title="ClutterBindConstraint"><span class="type">ClutterBindConstraint</span></a></span></p></td>
 101 <td>this constraint binds the X, Y, width or height
 102       of an actor to the corresponding position or size of a source
 103       actor; it can also apply an offset.</td>
 104 </tr>
 105 <tr>
 106 <td><p><span class="term"><a class="link" href="ClutterSnapConstraint.html" title="ClutterSnapConstraint"><span class="type">ClutterSnapConstraint</span></a></span></p></td>
 107 <td>this constraint "snaps" together the edges of
 108       two <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>s; if an actor uses two constraints on
 109       both its horizontal or vertical edges then it can also expand to
 110       fit the empty space.</td>
 111 </tr>
 112 </tbody>
 113 </table></div>
 114 <div class="example">
 115 <a name="ClutterConstraint-usage-example"></a><p class="title"><b>Example 2. Usage of constraints</b></p>
 116 <div class="example-contents">
 117 <p>The example below uses various <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a>s to
 118     lay out three actors on a resizable stage. Only the central actor has
 119     an explicit size, and no actor has an explicit position.</p>
 120 <div class="orderedlist"><ol class="orderedlist" type="1">
 121 <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>
 122       <span class="emphasis"><em>layerA</em></span> is explicitly sized to 100 pixels by 25
 123       pixels, and it's added to the <a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a>;</li>
 124 <li class="listitem">two <a class="link" href="ClutterAlignConstraint.html" title="ClutterAlignConstraint"><span class="type">ClutterAlignConstraint</span></a>s are used
 125       to anchor <span class="emphasis"><em>layerA</em></span> to the center of the stage,
 126       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
 127       both the X and Y axis.</li>
 128 <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>
 129       <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
 130       no explicit size;</li>
 131 <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>
 132       of <span class="emphasis"><em>layerB</em></span> are bound to the same properties
 133       of <span class="emphasis"><em>layerA</em></span> using two <a class="link" href="ClutterBindConstraint.html" title="ClutterBindConstraint"><span class="type">ClutterBindConstraint</span></a>
 134       objects, thus keeping <span class="emphasis"><em>layerB</em></span> aligned to
 135       <span class="emphasis"><em>layerA</em></span>;</li>
 136 <li class="listitem">the top edge of <span class="emphasis"><em>layerB</em></span> is
 137       snapped together with the bottom edge of <span class="emphasis"><em>layerA</em></span>;
 138       the bottom edge of <span class="emphasis"><em>layerB</em></span> is also snapped
 139       together with the bottom edge of the <a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a>; an offset is
 140       given to the two <a class="link" href="ClutterSnapConstraint.html" title="ClutterSnapConstraint"><span class="type">ClutterSnapConstraint</span></a>s to allow for some
 141       padding; since <span class="emphasis"><em>layerB</em></span> is snapped between two
 142       different <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>s, its height is stretched to match
 143       the gap;</li>
 144 <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>
 145       <span class="emphasis"><em>layerC</em></span> mirrors <span class="emphasis"><em>layerB</em></span>,
 146       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
 147       <span class="emphasis"><em>layerC</em></span> and the top edge of
 148       <span class="emphasis"><em>layerA</em></span> to the bottom edge of
 149       <span class="emphasis"><em>layerC</em></span>;</li>
 150 </ol></div>
 151 <div class="figure">
 152 <a name="constraints-example"></a><p class="title"><b>Figure 3. Constraints</b></p>
 153 <div class="figure-contents"><div><img src="constraints-example.png" alt="Constraints"></div></div>
 154 </div>
 155 <br class="figure-break"><pre class="programlisting">
 156 #include &lt;stdlib.h&gt;
 157 #include &lt;gmodule.h&gt;
 158
 159 #include &lt;clutter/clutter.h&gt;
 160
 161 G_MODULE_EXPORT int
 162 test_snap_constraint_main (int   argc,
 163                            char *argv[])
 164 {
 165   ClutterActor *stage, *layer_a, *layer_b, *layer_c;
 166
 167   if (clutter_init (&amp;argc, &amp;argv) != CLUTTER_INIT_SUCCESS)
 168     return 1;
 169
 170   /* the main container */
 171   stage = clutter_stage_new ();
 172   clutter_actor_set_name (stage, "stage");
 173   clutter_stage_set_title (CLUTTER_STAGE (stage), "Snap Constraint");
 174   clutter_stage_set_color (CLUTTER_STAGE (stage), CLUTTER_COLOR_Aluminium1);
 175   clutter_stage_set_user_resizable (CLUTTER_STAGE (stage), TRUE);
 176   g_signal_connect (stage, "destroy", G_CALLBACK (clutter_main_quit), NULL);
 177
 178   /* first layer, with a fixed (100, 25) size */
 179   layer_a = clutter_rectangle_new_with_color (CLUTTER_COLOR_ScarletRed);
 180   clutter_actor_set_name (layer_a, "layerA");
 181   clutter_container_add_actor (CLUTTER_CONTAINER (stage), layer_a);
 182   clutter_actor_set_size (layer_a, 100.0, 25.0);
 183
 184   /* the first layer is anchored to the middle of the stage */
 185   clutter_actor_add_constraint (layer_a, clutter_align_constraint_new (stage, CLUTTER_ALIGN_BOTH, 0.5));
 186
 187   /* second layer, with no implicit size */
 188   layer_b = clutter_rectangle_new_with_color (CLUTTER_COLOR_DarkButter);
 189   clutter_actor_set_name (layer_b, "layerB");
 190   clutter_container_add_actor (CLUTTER_CONTAINER (stage), layer_b);
 191
 192   /* the second layer tracks the X coordinate and the width of
 193    * the first layer
 194    */
 195   clutter_actor_add_constraint (layer_b, clutter_bind_constraint_new (layer_a, CLUTTER_BIND_X, 0.0));
 196   clutter_actor_add_constraint (layer_b, clutter_bind_constraint_new (layer_a, CLUTTER_BIND_WIDTH, 0.0));
 197
 198   /* the second layer is snapped between the bottom edge of
 199    * the first layer, and the bottom edge of the stage; a
 200    * spacing of 10 pixels in each direction is added for padding
 201    */
 202   clutter_actor_add_constraint (layer_b,
 203                                 clutter_snap_constraint_new (layer_a,
 204                                                              CLUTTER_SNAP_EDGE_TOP,
 205                                                              CLUTTER_SNAP_EDGE_BOTTOM,
 206                                                              10.0));
 207
 208   clutter_actor_add_constraint (layer_b,
 209                                 clutter_snap_constraint_new (stage,
 210                                                              CLUTTER_SNAP_EDGE_BOTTOM,
 211                                                              CLUTTER_SNAP_EDGE_BOTTOM,
 212                                                              -10.0));
 213
 214   /* the third layer, with no implicit size */
 215   layer_c = clutter_rectangle_new_with_color (CLUTTER_COLOR_LightChameleon);
 216   clutter_actor_set_name (layer_c, "layerC");
 217   clutter_container_add_actor (CLUTTER_CONTAINER (stage), layer_c);
 218
 219   /* as for the second layer, the third layer tracks the X
 220    * coordinate and width of the first layer
 221    */
 222   clutter_actor_add_constraint (layer_c, clutter_bind_constraint_new (layer_a, CLUTTER_BIND_X, 0.0));
 223   clutter_actor_add_constraint (layer_c, clutter_bind_constraint_new (layer_a, CLUTTER_BIND_WIDTH, 0.0));
 224
 225   /* the third layer is snapped between the top edge of the stage
 226    * and the top edge of the first layer; again, a spacing of
 227    * 10 pixels in each direction is added for padding
 228    */
 229   clutter_actor_add_constraint (layer_c,
 230                                 clutter_snap_constraint_new (layer_a,
 231                                                              CLUTTER_SNAP_EDGE_BOTTOM,
 232                                                              CLUTTER_SNAP_EDGE_TOP,
 233                                                              -10.0));
 234   clutter_actor_add_constraint (layer_c,
 235                                 clutter_snap_constraint_new (stage,
 236                                                              CLUTTER_SNAP_EDGE_TOP,
 237                                                              CLUTTER_SNAP_EDGE_TOP,
 238                                                              10.0));
 239
 240   clutter_actor_show (stage);
 241
 242   clutter_main ();
 243
 244   return EXIT_SUCCESS;
 245 }
 246
 247     </pre>
 248 <p>You can try resizing interactively the <a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a> and verify
 249     that the three <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>s maintain the same position and
 250     size relative to each other, and to the <a class="link" href="ClutterStage.html" title="ClutterStage"><span class="type">ClutterStage</span></a>.</p>
 251 </div>
 252 </div>
 253 <br class="example-break"><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 254 <h3 class="title">Warning</h3>
 255 <p>It's important to note that Clutter does not avoid loops
 256   or competing constraints; if two or more <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a>s
 257   are operating on the same positional or dimensional attributes of an
 258   actor, or if the constraints on two different actors depend on each
 259   other, then the behavior is undefined.</p>
 260 </div>
 261 </div>
 262 <p>
 263 </p>
 264 <p>
 265 </p>
 266 <div class="refsect2">
 267 <a name="ClutterConstraint-implementation"></a><h3>Implementing a ClutterConstraint</h3>
 268 <p>Creating a sub-class of <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> requires the
 269   implementation of the <code class="function"><code class="function">update_allocation()</code></code>
 270   virtual function.</p>
 271 <p>The <code class="function"><code class="function">update_allocation()</code></code> virtual function
 272   is called during the allocation sequence of a <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>, and
 273   allows any <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> attached to that actor to modify the
 274   allocation before it is passed to the <code class="function"><code class="function">allocate()</code></code>
 275   implementation.</p>
 276 <p>The <a class="link" href="ClutterActor.html#ClutterActorBox" title="struct ClutterActorBox"><span class="type">ClutterActorBox</span></a> passed to the
 277   <code class="function"><code class="function">update_allocation()</code></code> implementation contains the
 278   original allocation of the <a class="link" href="ClutterActor.html" title="ClutterActor"><span class="type">ClutterActor</span></a>, plus the eventual modifications
 279   applied by the other <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a>s.</p>
 280 <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
 281 <h3 class="title">Note</h3>
 282 <p>Constraints are queried in the same order as they were
 283   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
 284   <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>
 285 </div>
 286 <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
 287   up to the parent's implementation.</p>
 288 <p>If a <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> is parametrized - i.e. if it contains
 289   properties that affect the way the constraint is implemented - it should
 290   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
 291   to whenever any parameter is changed. The actor to which it is attached
 292   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>
 293 </div>
 294 <p>
 295 </p>
 296 <p>
 297 <a class="link" href="ClutterConstraint.html" title="ClutterConstraint"><span class="type">ClutterConstraint</span></a> is available since Clutter 1.4
 298 </p>
 299 </div>
 300 <div class="refsect1">
 301 <a name="ClutterConstraint.details"></a><h2>Details</h2>
 302 <div class="refsect2">
 303 <a name="ClutterConstraint-struct"></a><h3>ClutterConstraint</h3>
 304 <pre class="programlisting">typedef struct _ClutterConstraint ClutterConstraint;</pre>
 305 <p>
 306 The <span class="structname">ClutterConstraint</span> structure contains only
 307 private data and should be accessed using the provided API
 308 </p>
 309 <p class="since">Since 1.4</p>
 310 </div>
 311 <hr>
 312 <div class="refsect2">
 313 <a name="ClutterConstraintClass"></a><h3>struct ClutterConstraintClass</h3>
 314 <pre class="programlisting">struct ClutterConstraintClass {
 315 };
 316 </pre>
 317 <p>
 318 The <span class="structname">ClutterConstraintClass</span> structure contains
 319 only private data
 320 </p>
 321 <p class="since">Since 1.4</p>
 322 </div>
 323 </div>
 324 <div class="refsect1">
 325 <a name="ClutterConstraint.see-also"></a><h2>See Also</h2>
 326 <a class="link" href="ClutterAction.html" title="ClutterAction"><span class="type">ClutterAction</span></a>
 327 </div>
 328 </div>
 329 <div class="footer">
 330 <hr>
 331           Generated by GTK-Doc V1.18.1</div>
 332 </body>
 333 </html>