[layout, docs] Add layout managers sections

Add LayoutManager and its subclasses, and the Box actor to the
gtk-doc machinery needed to generate the API reference.

clutter/clutter-bin-layout.c

@@ -639,8 +639,8 @@ clutter_bin_layout_new (ClutterBinAlignment x_align,
 /**
  * clutter_bin_layout_set_alignment:
  * @self: a #ClutterBinLayout
- * @container: a #ClutterContainer with a layout managed by @self
+ * @container: a #ClutterContainer using the #ClutterBinLayout
- * @child: a #ClutterActor child of @container
+ * @child: a child of @container
  * @x_align: the horizontal alignment policy to be used for the @child
  *   inside @container
  * @y_align: the vertical aligment policy to be used on the @child
@@ -677,6 +677,8 @@ clutter_bin_layout_set_alignment (ClutterBinLayout    *self,
 /**
  * clutter_bin_layout_get_alignment:
  * @self: a #ClutterBinLayout
+ * @container: a #ClutterContainer using the #ClutterBinLayout
+ * @child: a child of @container
  * @x_align: (out) (allow-none): return location for the horizontal
  *   alignment policy
  * @y_align: (out) (allow-none): return location for the vertical

clutter/clutter-bin-layout.h

@@ -77,8 +77,8 @@ struct _ClutterBinLayoutClass
 
 GType clutter_bin_layout_get_type (void) G_GNUC_CONST;
 
-ClutterLayoutManager *clutter_bin_layout_new           (ClutterBinAlignment  align_x,
+ClutterLayoutManager *clutter_bin_layout_new           (ClutterBinAlignment  x_align,
-                                                        ClutterBinAlignment  align_y);
+                                                        ClutterBinAlignment  y_align);
 
 void                  clutter_bin_layout_set_alignment (ClutterBinLayout    *self,
                                                         ClutterContainer    *container,

clutter/clutter-layout-manager.c

@@ -351,6 +351,46 @@ clutter_layout_manager_get_child_meta (ClutterLayoutManager *manager,
   return get_child_meta (manager, container, actor);
 }
 
+/**
+ * clutter_layout_manager_add_child_meta:
+ * @manager: a #ClutterLayoutManager
+ * @container: a #ClutterContainer using @manager
+ * @actor: a #ClutterActor child of @container
+ *
+ * Creates and binds a #ClutterChildMeta for @manager to
+ * a child of @container
+ *
+ * This function should only be used when implementing containers
+ * using #ClutterLayoutManager and not by application code
+ *
+ * Typically, containers should bind a #ClutterChildMeta created
+ * by a #ClutterLayoutManager when adding a new child, e.g.:
+ *
+ * |[
+ *   static void
+ *   my_container_add (ClutterContainer *container,
+ *                     ClutterActor     *actor)
+ *   {
+ *     MyContainer *self = MY_CONTAINER (container);
+ *
+ *     self->children = g_slist_append (self->children, actor);
+ *     clutter_actor_set_parent (actor, CLUTTER_ACTOR (self));
+ *
+ *     clutter_layout_manager_add_child_meta (self->layout,
+ *                                            container,
+ *                                            actor);
+ *
+ *     clutter_actor_queue_relayout (CLUTTER_ACTOR (self));
+ *
+ *     g_signal_emit_by_name (container, "actor-added");
+ *   }
+ * ]|
+ *
+ * The #ClutterChildMeta should be removed when removing an
+ * actor; see clutter_layout_manager_remove_child_meta()
+ *
+ * Since: 1.2
+ */
 void
 clutter_layout_manager_add_child_meta (ClutterLayoutManager *manager,
                                        ClutterContainer     *container,
@@ -367,13 +407,54 @@ clutter_layout_manager_add_child_meta (ClutterLayoutManager *manager,
                            (GDestroyNotify) g_object_unref);
 }
 
+/**
+ * clutter_layout_manager_remove_child_meta:
+ * @manager: a #ClutterLayoutManager
+ * @container: a #ClutterContainer using @manager
+ * @actor: a #ClutterActor child of @container
+ *
+ * Unbinds and unrefs a #ClutterChildMeta for @manager from
+ * a child of @container
+ *
+ * This function should only be used when implementing containers
+ * using #ClutterLayoutManager and not by application code
+ *
+ * Typically, containers should remove a #ClutterChildMeta created
+ * by a #ClutterLayoutManager when removing a child, e.g.:
+ *
+ * |[
+ *   static void
+ *   my_container_remove (ClutterContainer *container,
+ *                        ClutterActor     *actor)
+ *   {
+ *     MyContainer *self = MY_CONTAINER (container);
+ *
+ *     g_object_ref (actor);
+ *
+ *     self->children = g_slist_remove (self->children, actor);
+ *     clutter_actor_unparent (actor);
+ *
+ *     clutter_layout_manager_remove_child_meta (self->layout,
+ *                                               container,
+ *                                               actor);
+ *
+ *     clutter_actor_queue_relayout (CLUTTER_ACTOR (self));
+ *
+ *     g_signal_emit_by_name (container, "actor-removed");
+ *
+ *     g_object_unref (actor);
+ *   }
+ * ]|
+ *
+ * See also clutter_layout_manager_add_child_meta()
+ *
+ * Since: 1.2
+ */
 void
 clutter_layout_manager_remove_child_meta (ClutterLayoutManager *manager,
                                           ClutterContainer     *container,
                                           ClutterActor         *actor)
 {
-  ClutterChildMeta *meta;
-
   g_return_if_fail (CLUTTER_IS_LAYOUT_MANAGER (manager));
   g_return_if_fail (CLUTTER_IS_CONTAINER (container));
   g_return_if_fail (CLUTTER_IS_ACTOR (actor));
@@ -428,6 +509,22 @@ layout_get_property_internal (ClutterLayoutManager *manager,
   return TRUE;
 }
 
+/**
+ * clutter_layout_manager_child_set:
+ * @manager: a #ClutterLayoutManager
+ * @container: a #ClutterContainer using @manager
+ * @actor: a #ClutterActor child of @container
+ * @first_property: the first property name
+ * @Varargs: a list of property name and value pairs
+ *
+ * Sets a list of properties and their values on the #ClutterChildMeta
+ * associated by @manager to a child of @container
+ *
+ * Languages bindings should use clutter_layout_manager_child_set_property()
+ * instead
+ *
+ * Since: 1.2
+ */
 void
 clutter_layout_manager_child_set (ClutterLayoutManager *manager,
                                   ClutterContainer     *container,
@@ -499,6 +596,19 @@ clutter_layout_manager_child_set (ClutterLayoutManager *manager,
   va_end (var_args);
 }
 
+/**
+ * clutter_layout_manager_child_set_property:
+ * @manager: a #ClutterLayoutManager
+ * @container: a #ClutterContainer using @manager
+ * @actor: a #ClutterActor child of @container
+ * @property_name: the name of the property to set
+ * @value: a #GValue with the value of the property to set
+ *
+ * Sets a property on the #ClutterChildMeta created by @manager and
+ * attached to a child of @container
+ *
+ * Since: 1.2
+ */
 void
 clutter_layout_manager_child_set_property (ClutterLayoutManager *manager,
                                            ClutterContainer     *container,
@@ -539,6 +649,20 @@ clutter_layout_manager_child_set_property (ClutterLayoutManager *manager,
   layout_set_property_internal (manager, G_OBJECT (meta), pspec, value);
 }
 
+/**
+ * clutter_layout_manager_child_get:
+ * @manager: a #ClutterLayoutManager
+ * @container: a #ClutterContainer using @manager
+ * @actor: a #ClutterActor child of @container
+ * @first_property: the name of the first property
+ * @Varargs: a list of property name and return location for the value pairs
+ *
+ * Retrieves the values for a list of properties out of the
+ * #ClutterChildMeta created by @manager and attached to the
+ * child of a @container
+ *
+ * Since: 1.2
+ */
 void
 clutter_layout_manager_child_get (ClutterLayoutManager *manager,
                                   ClutterContainer     *container,
@@ -614,6 +738,23 @@ clutter_layout_manager_child_get (ClutterLayoutManager *manager,
   va_end (var_args);
 }
 
+/**
+ * clutter_layout_manager_child_get_property:
+ * @manager: a #ClutterLayoutManager
+ * @container: a #ClutterContainer using @manager
+ * @actor: a #ClutterActor child of @container
+ * @property_name: the name of the property to get
+ * @value: a #GValue with the value of the property to get
+ *
+ * Gets a property on the #ClutterChildMeta created by @manager and
+ * attached to a child of @container
+ *
+ * The #GValue must already be initialized to the type of the property
+ * and has to be unset with g_value_unset() after extracting the real
+ * value out of it
+ *
+ * Since: 1.2
+ */
 void
 clutter_layout_manager_child_get_property (ClutterLayoutManager *manager,
                                            ClutterContainer     *container,

clutter/clutter-layout-manager.h

@@ -69,9 +69,9 @@ struct _ClutterLayoutManager
  * @allocate: virtual function; override to allocate the children of the
  *   layout manager. See also the allocate() virtual function in
  *   #ClutterActor
- * @get_child_meta: virtual function; override to create a #ClutterChildMeta
+ * @create_child_meta: virtual function; override to create a
- *   instance associated to a #ClutterContainer and a child #ClutterActor,
+ *   #ClutterChildMeta instance associated to a #ClutterContainer and a
- *   used to maintain layout manager specific properties
+ *   child #ClutterActor, used to maintain layout manager specific properties
  * @layout_changed: class handler for the #ClutterLayoutManager::layout-changed
  *   signal
  *
@@ -148,6 +148,16 @@ void              clutter_layout_manager_remove_child_meta    (ClutterLayoutMana
                                                                ClutterContainer       *container,
                                                                ClutterActor           *actor);
 
+void              clutter_layout_manager_child_set            (ClutterLayoutManager   *manager,
+                                                               ClutterContainer       *container,
+                                                               ClutterActor           *actor,
+                                                               const gchar            *first_property,
+                                                               ...) G_GNUC_NULL_TERMINATED;
+void              clutter_layout_manager_child_get            (ClutterLayoutManager   *manager,
+                                                               ClutterContainer       *container,
+                                                               ClutterActor           *actor,
+                                                               const gchar            *first_property,
+                                                               ...) G_GNUC_NULL_TERMINATED;
 void              clutter_layout_manager_child_set_property   (ClutterLayoutManager   *manager,
                                                                ClutterContainer       *container,
                                                                ClutterActor           *actor,

doc/reference/clutter/clutter-docs.xml.in

@@ -55,6 +55,7 @@
       <xi:include href="xml/clutter-container.xml"/>
       <xi:include href="xml/clutter-child-meta.xml"/>
       <xi:include href="xml/clutter-media.xml"/>
+      <xi:include href="xml/clutter-layout-manager.xml"/>
     </chapter>
 
     <chapter>
@@ -71,6 +72,14 @@
 
       <xi:include href="xml/clutter-group.xml"/>
       <xi:include href="xml/clutter-stage.xml"/>
+      <xi:include href="xml/clutter-box.xml"/>
+    </chapter>
+
+    <chapter>
+      <title>Layout managers</title>
+
+      <xi:include href="xml/clutter-fixed-layout.xml"/>
+      <xi:include href="xml/clutter-bin-layout.xml"/>
     </chapter>
 
   </part>

doc/reference/clutter/clutter-sections.txt

@@ -1725,3 +1725,97 @@ CLUTTER_STAGE_MANAGER_GET_CLASS
 <SUBSECTION Private>
 clutter_stage_manager_get_type
 </SECTION>
+
+<SECTION>
+<TITLE>Layout Managers</TITLE>
+<FILE>clutter-layout-manager</FILE>
+ClutterLayoutManager
+ClutterLayoutManagerClass
+clutter_layout_manager_get_preferred_width
+clutter_layout_manager_get_preferred_height
+clutter_layout_manager_allocate
+clutter_layout_manager_layout_changed
+
+<SUBSECTION>
+clutter_layout_manager_add_child_meta
+clutter_layout_manager_remove_child_meta
+clutter_layout_manager_get_child_meta
+clutter_layout_manager_child_set
+clutter_layout_manager_child_set_property
+clutter_layout_manager_child_get
+clutter_layout_manager_child_get_property
+
+<SUBSECTION Standard>
+CLUTTER_TYPE_LAYOUT_MANAGER
+CLUTTER_LAYOUT_MANAGER
+CLUTTER_LAYOUT_MANAGER_CLASS
+CLUTTER_IS_LAYOUT_MANAGER
+CLUTTER_IS_LAYOUT_MANAGER_CLASS
+CLUTTER_LAYOUT_MANAGER_GET_CLASS
+
+<SUBSECTION Private>
+clutter_layout_manager_get_type
+</SECTION>
+
+<SECTION>
+<TITLE>ClutterFixedLayout</TITLE>
+<FILE>clutter-fixed-layout</FILE>
+ClutterFixedLayout
+ClutterFixedLayoutClass
+clutter_fixed_layout_new
+
+<SUBSECTION Standard>
+CLUTTER_TYPE_FIXED_LAYOUT
+CLUTTER_FIXED_LAYOUT
+CLUTTER_FIXED_LAYOUT_CLASS
+CLUTTER_IS_FIXED_LAYOUT
+CLUTTER_IS_FIXED_LAYOUT_CLASS
+CLUTTER_FIXED_LAYOUT_GET_CLASS
+
+<SUBSECTION Private>
+clutter_fixed_layout_get_type
+</SECTION>
+
+<SECTION>
+<TITLE>ClutterBinLayout</TITLE>
+<FILE>clutter-bin-layout</FILE>
+ClutterBinAlignment
+ClutterBinLayout
+ClutterBinLayoutClass
+clutter_bin_layout_new
+clutter_bin_layout_set_alignment
+clutter_bin_layout_get_alignment
+
+<SUBSECTION Standard>
+CLUTTER_TYPE_BIN_LAYOUT
+CLUTTER_BIN_LAYOUT
+CLUTTER_BIN_LAYOUT_CLASS
+CLUTTER_IS_BIN_LAYOUT
+CLUTTER_IS_BIN_LAYOUT_CLASS
+CLUTTER_BIN_LAYOUT_GET_CLASS
+
+<SUBSECTION Private>
+ClutterBinLayoutPrivate
+clutter_bin_layout_get_type
+</SECTION>
+
+<SECTION>
+<TITLE>ClutterBox</TITLE>
+<FILE>clutter-box</FILE>
+ClutterBox
+ClutterBoxClass
+clutter_box_new
+clutter_box_get_layout_manager
+
+<SUBSECTION Standard>
+CLUTTER_TYPE_BOX
+CLUTTER_BOX
+CLUTTER_BOX_CLASS
+CLUTTER_IS_BOX
+CLUTTER_IS_BOX_CLASS
+CLUTTER_BOX_GET_CLASS
+
+<SUBSECTION Private>
+ClutterBoxPrivate
+clutter_box_get_type
+</SECTION>

doc/reference/clutter/clutter.types

@@ -33,3 +33,7 @@ clutter_animation_get_type
 clutter_interval_get_type
 clutter_stage_manager_get_type
 clutter_binding_pool_get_type
+clutter_box_get_type
+clutter_layout_manager_get_type
+clutter_fixed_layout_get_type
+clutter_bin_layout_get_type