[clutter] docs: Mention the DELEGATE_LAYOUT flag in set_allocation()

[Emmanuele Bassi <ebassi src gnome org>]

commit 842ff82d77b020f6033f418232c7a662fbfae078
Author: Emmanuele Bassi <ebassi linux intel com>
Date:   Fri Jan 27 17:07:33 2012 +0000

    docs: Mention the DELEGATE_LAYOUT flag in set_allocation()
    
    With code examples.

 clutter/clutter-actor.c |   46 +++++++++++++++++++++++++++++++++++++++++++++-
 1 files changed, 45 insertions(+), 1 deletions(-)
---
diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 8999e4e..803fa41 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -7765,7 +7765,51 @@ clutter_actor_allocate (ClutterActor           *self,
  *
  * If the #ClutterActor is using a #ClutterLayoutManager delegate object
  * to handle the allocation of its children, this function will call
- * the clutter_layout_manager_allocate() function.
+ * the clutter_layout_manager_allocate() function only if the
+ * %CLUTTER_DELEGATE_LAYOUT flag is set on @flags, otherwise it is
+ * expected that the subclass will call clutter_layout_manager_allocate()
+ * by itself. For instance, the following code:
+ *
+ * |[
+ * static void
+ * my_actor_allocate (ClutterActor *actor,
+ *                    const ClutterActorBox *allocation,
+ *                    ClutterAllocationFlags flags)
+ * {
+ *   ClutterActorBox new_alloc;
+ *   ClutterAllocationFlags new_flags;
+ *
+ *   adjust_allocation (allocation, &amp;new_alloc);
+ *
+ *   new_flags = flags | CLUTTER_DELEGATE_LAYOUT;
+ *
+ *   /&ast; this will use the layout manager set on the actor &ast;/
+ *   clutter_actor_set_allocation (actor, &amp;new_alloc, new_flags);
+ * }
+ * ]|
+ *
+ * is equivalent to this:
+ *
+ * |[
+ * static void
+ * my_actor_allocate (ClutterActor *actor,
+ *                    const ClutterActorBox *allocation,
+ *                    ClutterAllocationFlags flags)
+ * {
+ *   ClutterLayoutManager *layout;
+ *   ClutterActorBox new_alloc;
+ *
+ *   adjust_allocation (allocation, &amp;new_alloc);
+ *
+ *   clutter_actor_set_allocation (actor, &amp;new_alloc, flags);
+ *
+ *   layout = clutter_actor_get_layout_manager (actor);
+ *   clutter_layout_manager_allocate (layout,
+ *                                    CLUTTER_CONTAINER (actor),
+ *                                    &amp;new_alloc,
+ *                                    flags);
+ * }
+ * ]|
  *
  * Since: 1.10
  */