diff --git a/gtk/gtkbuildable.c b/gtk/gtkbuildable.c index dd0e33040d..659a0ff3bd 100644 --- a/gtk/gtkbuildable.c +++ b/gtk/gtkbuildable.c @@ -48,16 +48,16 @@ gtk_buildable_default_init (GtkBuildableInterface *iface) { } -/** +/*< private > * gtk_buildable_set_buildable_id: * @buildable: a #GtkBuildable * @id: name to set * * Sets the ID of the @buildable object. - **/ + */ void gtk_buildable_set_buildable_id (GtkBuildable *buildable, - const char *id) + const char *id) { GtkBuildableIface *iface; @@ -103,16 +103,16 @@ gtk_buildable_get_buildable_id (GtkBuildable *buildable) "gtk-builder-id"); } -/** +/*< private > * gtk_buildable_add_child: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder * @child: child to add - * @type: (allow-none): kind of child or %NULL + * @type: (nullable): kind of child or %NULL * * Adds a child to @buildable. @type is an optional string * describing how the child should be added. - **/ + */ void gtk_buildable_add_child (GtkBuildable *buildable, GtkBuilder *builder, @@ -130,7 +130,7 @@ gtk_buildable_add_child (GtkBuildable *buildable, (* iface->add_child) (buildable, builder, child, type); } -/** +/*< private > * gtk_buildable_set_buildable_property: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder @@ -138,7 +138,7 @@ gtk_buildable_add_child (GtkBuildable *buildable, * @value: value of property * * Sets the property name @name to @value on the @buildable object. - **/ + */ void gtk_buildable_set_buildable_property (GtkBuildable *buildable, GtkBuilder *builder, @@ -159,7 +159,7 @@ gtk_buildable_set_buildable_property (GtkBuildable *buildable, g_object_set_property (G_OBJECT (buildable), name, value); } -/** +/*< private > * gtk_buildable_parser_finished: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder @@ -169,7 +169,7 @@ gtk_buildable_set_buildable_property (GtkBuildable *buildable, * Note that this will be called once for each time * gtk_builder_add_from_file() or gtk_builder_add_from_string() * is called on a builder. - **/ + */ void gtk_buildable_parser_finished (GtkBuildable *buildable, GtkBuilder *builder) @@ -184,7 +184,7 @@ gtk_buildable_parser_finished (GtkBuildable *buildable, (* iface->parser_finished) (buildable, builder); } -/** +/*< private > * gtk_buildable_construct_child: * @buildable: A #GtkBuildable * @builder: #GtkBuilder used to construct this object @@ -196,7 +196,7 @@ gtk_buildable_parser_finished (GtkBuildable *buildable, * specified in the UI definition. * * Returns: (transfer full): the constructed child - **/ + */ GObject * gtk_buildable_construct_child (GtkBuildable *buildable, GtkBuilder *builder, @@ -214,7 +214,7 @@ gtk_buildable_construct_child (GtkBuildable *buildable, return (* iface->construct_child) (buildable, builder, name); } -/** +/*< private > * gtk_buildable_custom_tag_start: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder used to construct this object @@ -228,7 +228,7 @@ gtk_buildable_construct_child (GtkBuildable *buildable, * * Returns: %TRUE if an object has a custom implementation, %FALSE * if it doesn't. - **/ + */ gboolean gtk_buildable_custom_tag_start (GtkBuildable *buildable, GtkBuilder *builder, @@ -250,7 +250,7 @@ gtk_buildable_custom_tag_start (GtkBuildable *buildable, tagname, parser, data); } -/** +/*< private > * gtk_buildable_custom_tag_end: * @buildable: A #GtkBuildable * @builder: #GtkBuilder used to construct this object @@ -260,7 +260,7 @@ gtk_buildable_custom_tag_start (GtkBuildable *buildable, * * This is called at the end of each custom element handled by * the buildable. - **/ + */ void gtk_buildable_custom_tag_end (GtkBuildable *buildable, GtkBuilder *builder, @@ -279,7 +279,7 @@ gtk_buildable_custom_tag_end (GtkBuildable *buildable, (* iface->custom_tag_end) (buildable, builder, child, tagname, data); } -/** +/*< private > * gtk_buildable_custom_finished: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder @@ -289,7 +289,7 @@ gtk_buildable_custom_tag_end (GtkBuildable *buildable, * * This is similar to gtk_buildable_parser_finished() but is * called once for each custom tag handled by the @buildable. - **/ + */ void gtk_buildable_custom_finished (GtkBuildable *buildable, GtkBuilder *builder, @@ -307,7 +307,7 @@ gtk_buildable_custom_finished (GtkBuildable *buildable, (* iface->custom_finished) (buildable, builder, child, tagname, data); } -/** +/*< private > * gtk_buildable_get_internal_child: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder @@ -316,7 +316,7 @@ gtk_buildable_custom_finished (GtkBuildable *buildable, * Get the internal child called @childname of the @buildable object. * * Returns: (transfer none): the internal child of the buildable object - **/ + */ GObject * gtk_buildable_get_internal_child (GtkBuildable *buildable, GtkBuilder *builder, diff --git a/gtk/gtkbuildable.h b/gtk/gtkbuildable.h index ed0dbdd25a..84008c9ff5 100644 --- a/gtk/gtkbuildable.h +++ b/gtk/gtkbuildable.h @@ -101,7 +101,7 @@ struct _GtkBuildableParser * content below . To handle an element, the implementation * must fill in the @parser and @user_data and return %TRUE. * #GtkWidget implements this to parse keyboard accelerators specified - * in elements. + * in elements. * Note that @user_data must be freed in @custom_tag_end or @custom_finished. * @custom_tag_end: Called for the end tag of each custom element that is * handled by the buildable (see @custom_tag_start). @@ -128,7 +128,18 @@ struct _GtkBuildableIface /* virtual table */ void (* set_id) (GtkBuildable *buildable, const char *id); - const char * (* get_id) (GtkBuildable *buildable); + const char * (* get_id) (GtkBuildable *buildable); + + /** + * GtkBuildableIface::add_child: + * @buildable: a #GtkBuildable + * @builder: a #GtkBuilder + * @child: child to add + * @type: (nullable): kind of child or %NULL + * + * Adds a child to @buildable. @type is an optional string + * describing how the child should be added. + */ void (* add_child) (GtkBuildable *buildable, GtkBuilder *builder, GObject *child, @@ -140,17 +151,55 @@ struct _GtkBuildableIface GObject * (* construct_child) (GtkBuildable *buildable, GtkBuilder *builder, const char *name); + + /** + * GtkBuildableIface::custom_tag_start: + * @buildable: a #GtkBuildable + * @builder: a #GtkBuilder used to construct this object + * @child: (nullable): child object or %NULL for non-child tags + * @tagname: name of tag + * @parser: (out): a #GMarkupParser to fill in + * @data: (out): return location for user data that will be passed in + * to parser functions + * + * Called for each unknown element under ``. + * + * Returns: %TRUE if an object has a custom implementation, %FALSE + * if it doesn't. + */ gboolean (* custom_tag_start) (GtkBuildable *buildable, GtkBuilder *builder, GObject *child, const char *tagname, GtkBuildableParser *parser, gpointer *data); + /** + * GtkBuildableIface::custom_tag_end: + * @buildable: A #GtkBuildable + * @builder: #GtkBuilder used to construct this object + * @child: (nullable): child object or %NULL for non-child tags + * @tagname: name of tag + * @data: user data that will be passed in to parser functions + * + * Called at the end of each custom element handled by + * the buildable. + */ void (* custom_tag_end) (GtkBuildable *buildable, GtkBuilder *builder, GObject *child, const char *tagname, gpointer data); + /** + * GtkBuildableIface::custom_finished: + * @buildable: a #GtkBuildable + * @builder: a #GtkBuilder + * @child: (nullable): child object or %NULL for non-child tags + * @tagname: the name of the tag + * @data: user data created in custom_tag_start + * + * Similar to gtk_buildable_parser_finished() but is + * called once for each custom tag handled by the @buildable. + */ void (* custom_finished) (GtkBuildable *buildable, GtkBuilder *builder, GObject *child, @@ -159,6 +208,16 @@ struct _GtkBuildableIface void (* parser_finished) (GtkBuildable *buildable, GtkBuilder *builder); + /** + * GtkBuildableIface::get_internal_child: + * @buildable: a #GtkBuildable + * @builder: a #GtkBuilder + * @childname: name of child + * + * Retrieves the internal child called @childname of the @buildable object. + * + * Returns: (transfer none): the internal child of the buildable object + */ GObject * (* get_internal_child) (GtkBuildable *buildable, GtkBuilder *builder, const char *childname);