From 899db6f226864614350d6aa07d8313dccf7d652f Mon Sep 17 00:00:00 2001 From: Emmanuele Bassi Date: Tue, 15 Sep 2009 16:24:47 +0100 Subject: [PATCH] [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 | 6 +- clutter/clutter-bin-layout.h | 4 +- clutter/clutter-layout-manager.c | 145 ++++++++++++++++++++- clutter/clutter-layout-manager.h | 16 ++- doc/reference/clutter/clutter-docs.xml.in | 9 ++ doc/reference/clutter/clutter-sections.txt | 94 +++++++++++++ doc/reference/clutter/clutter.types | 4 + 7 files changed, 269 insertions(+), 9 deletions(-) diff --git a/clutter/clutter-bin-layout.c b/clutter/clutter-bin-layout.c index 8b92db69e..bca6f9e39 100644 --- a/clutter/clutter-bin-layout.c +++ b/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 - * @child: a #ClutterActor child of @container + * @container: a #ClutterContainer using the #ClutterBinLayout + * @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 diff --git a/clutter/clutter-bin-layout.h b/clutter/clutter-bin-layout.h index 5eb4617d6..032d73794 100644 --- a/clutter/clutter-bin-layout.h +++ b/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, - ClutterBinAlignment align_y); +ClutterLayoutManager *clutter_bin_layout_new (ClutterBinAlignment x_align, + ClutterBinAlignment y_align); void clutter_bin_layout_set_alignment (ClutterBinLayout *self, ClutterContainer *container, diff --git a/clutter/clutter-layout-manager.c b/clutter/clutter-layout-manager.c index 7d6e7dd6d..c62c0567e 100644 --- a/clutter/clutter-layout-manager.c +++ b/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, diff --git a/clutter/clutter-layout-manager.h b/clutter/clutter-layout-manager.h index 4acd26447..429be2006 100644 --- a/clutter/clutter-layout-manager.h +++ b/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 - * instance associated to a #ClutterContainer and a child #ClutterActor, - * used to maintain layout manager specific properties + * @create_child_meta: virtual function; override to create a + * #ClutterChildMeta instance associated to a #ClutterContainer and a + * 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, diff --git a/doc/reference/clutter/clutter-docs.xml.in b/doc/reference/clutter/clutter-docs.xml.in index 1a6409105..7b1be959f 100644 --- a/doc/reference/clutter/clutter-docs.xml.in +++ b/doc/reference/clutter/clutter-docs.xml.in @@ -55,6 +55,7 @@ + @@ -71,6 +72,14 @@ + + + + + Layout managers + + + diff --git a/doc/reference/clutter/clutter-sections.txt b/doc/reference/clutter/clutter-sections.txt index 1ba2c6868..34bcae8d2 100644 --- a/doc/reference/clutter/clutter-sections.txt +++ b/doc/reference/clutter/clutter-sections.txt @@ -1725,3 +1725,97 @@ CLUTTER_STAGE_MANAGER_GET_CLASS clutter_stage_manager_get_type + +
+Layout Managers +clutter-layout-manager +ClutterLayoutManager +ClutterLayoutManagerClass +clutter_layout_manager_get_preferred_width +clutter_layout_manager_get_preferred_height +clutter_layout_manager_allocate +clutter_layout_manager_layout_changed + + +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 + + +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 + + +clutter_layout_manager_get_type +
+ +
+ClutterFixedLayout +clutter-fixed-layout +ClutterFixedLayout +ClutterFixedLayoutClass +clutter_fixed_layout_new + + +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 + + +clutter_fixed_layout_get_type +
+ +
+ClutterBinLayout +clutter-bin-layout +ClutterBinAlignment +ClutterBinLayout +ClutterBinLayoutClass +clutter_bin_layout_new +clutter_bin_layout_set_alignment +clutter_bin_layout_get_alignment + + +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 + + +ClutterBinLayoutPrivate +clutter_bin_layout_get_type +
+ +
+ClutterBox +clutter-box +ClutterBox +ClutterBoxClass +clutter_box_new +clutter_box_get_layout_manager + + +CLUTTER_TYPE_BOX +CLUTTER_BOX +CLUTTER_BOX_CLASS +CLUTTER_IS_BOX +CLUTTER_IS_BOX_CLASS +CLUTTER_BOX_GET_CLASS + + +ClutterBoxPrivate +clutter_box_get_type +
diff --git a/doc/reference/clutter/clutter.types b/doc/reference/clutter/clutter.types index 5a243947f..f4d0ac375 100644 --- a/doc/reference/clutter/clutter.types +++ b/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