Lerking/gtk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[docs] Move documentation to inline comments: GtkBuildable

Browse Source 
Fixes https://bugzilla.gnome.org/show_bug.cgi?id=611741

Signed-off-by: Javier Jardón <jjardon@gnome.org>
This commit is contained in:
Tadej Borovšak
2010-03-04 17:09:36 +01:00
committed by Javier Jardón
parent 8e8d302d10
commit 51e32fe67a
3 changed files with 66 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files

193
docs/reference/gtk/tmpl/gtkbuildable.sgml
View File

@@ -1,193 +0,0 @@
<!-- ##### SECTION Title ##### -->
GtkBuildable
<!-- ##### SECTION Short_Description ##### -->
Interface for objects that can be built by GtkBuilder
<!-- ##### SECTION Long_Description ##### -->
<para>
In order to allow construction from a <link linkend="BUILDER-UI">GtkBuilder
UI description</link>, an object class must implement the
GtkBuildable interface. The interface includes methods for setting
names and properties of objects, parsing custom tags, constructing
child objects.
</para>
<para>
The GtkBuildable interface is implemented by all widgets and
many of the non-widget objects that are provided by GTK+. The
main user of this interface is #GtkBuilder, there should be
very little need for applications to call any
<function>gtk_buildable_...</function> functions.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### SECTION Stability_Level ##### -->
<!-- ##### STRUCT GtkBuildable ##### -->
<para>
</para>
<!-- ##### STRUCT GtkBuildableIface ##### -->
<para>
The GtkBuildableIface interface contains method that are
necessary to allow #GtkBuilder to construct an object from
a GtkBuilder UI definition.
</para>
@g_iface: the parent class
@set_name: Stores the name attribute given in the GtkBuilder UI definition.
#GtkWidget stores the name as object data. Implement this method if your
object has some notion of "name" and it makes sense to map the XML name
attribute to it.
@get_name: The getter corresponding to @set_name. Implement this
if you implement @set_name.
@add_child: Adds a child. The @type parameter can be used to
differentiate the kind of child. #GtkContainer implements this
to add add a child widget to the container, #GtkNotebook uses
the @type to distinguish between page labels (of type "page-label")
and normal children.
@set_buildable_property: Sets a property of a buildable object.
It is normally not necessary to implement this, g_object_set_property()
is used by default. #GtkWindow implements this to delay showing itself
(i.e. setting the #GtkWidget:visible property) until the whole interface
is created.
@construct_child: Constructs a child of a buildable that has been
specified as "constructor" in the UI definition. #GtkUIManager implements
this to reference to a widget created in a &lt;ui&gt; tag which is outside
of the normal GtkBuilder UI definition hierarchy. A reference to the
constructed object is returned and becomes owned by the caller.
@custom_tag_start: Implement this if the buildable needs to parse
content below &lt;child&gt;. To handle an element, the implementation
must fill in the @parser structure and @user_data and return %TRUE.
#GtkWidget implements this to parse keyboard accelerators specified
in &lt;accelerator&gt; elements. #GtkContainer implements it to map
properties defined via &lt;packing&gt; elements to child properties.
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).
@custom_finished: Called for each custom tag handled by the buildable
when the builder finishes parsing (see @custom_tag_start)
@parser_finished: Called when a builder finishes the parsing
of a UI definition. It is normally not necessary to implement this,
unless you need to perform special cleanup actions. #GtkWindow sets
the #GtkWidget:visible property here.
@get_internal_child: Returns an internal child of a buildable.
#GtkDialog implements this to give access to its @vbox, making
it possible to add children to the vbox in a UI definition.
Implement this if the buildable has internal children that may
need to be accessed from a UI definition.
<!-- ##### FUNCTION gtk_buildable_set_name ##### -->
<para>
</para>
@buildable:
@name:
<!-- ##### FUNCTION gtk_buildable_get_name ##### -->
<para>
</para>
@buildable:
@Returns:
<!-- ##### FUNCTION gtk_buildable_add_child ##### -->
<para>
</para>
@buildable:
@builder:
@child:
@type:
<!-- ##### FUNCTION gtk_buildable_set_buildable_property ##### -->
<para>
</para>
@buildable:
@builder:
@name:
@value:
<!-- ##### FUNCTION gtk_buildable_construct_child ##### -->
<para>
</para>
@buildable:
@builder:
@name:
@Returns:
<!-- ##### FUNCTION gtk_buildable_custom_tag_start ##### -->
<para>
</para>
@buildable:
@builder:
@child:
@tagname:
@parser:
@data:
@Returns:
<!-- ##### FUNCTION gtk_buildable_custom_tag_end ##### -->
<para>
</para>
@buildable:
@builder:
@child:
@tagname:
@data:
<!-- ##### FUNCTION gtk_buildable_custom_finished ##### -->
<para>
</para>
@buildable:
@builder:
@child:
@tagname:
@data:
<!-- ##### FUNCTION gtk_buildable_parser_finished ##### -->
<para>
</para>
@buildable:
@builder:
<!-- ##### FUNCTION gtk_buildable_get_internal_child ##### -->
<para>
</para>
@buildable:
@builder:
@childname:
@Returns:

17
gtk/gtkbuildable.c
View File

@@ -18,6 +18,23 @@
* Boston, MA 02111-1307, USA.
*/
/**
* SECTION:gtkbuildable
* @Short_description: Interface for objects that can be built by GtkBuilder
* @Title: GtkBuildable
*
* In order to allow construction from a <link linkend="BUILDER-UI">GtkBuilder
* UI description</link>, an object class must implement the
* GtkBuildable interface. The interface includes methods for setting
* names and properties of objects, parsing custom tags, constructing
* child objects.
*
* The GtkBuildable interface is implemented by all widgets and
* many of the non-widget objects that are provided by GTK+. The
* main user of this interface is #GtkBuilder, there should be
* very little need for applications to call any
* <function>gtk_buildable_...</function> functions.
*/
#include "config.h"
#include "gtkbuildable.h"

49
gtk/gtkbuildable.h
View File

@@ -40,6 +40,55 @@ G_BEGIN_DECLS
typedef struct _GtkBuildable GtkBuildable; /* Dummy typedef */
typedef struct _GtkBuildableIface GtkBuildableIface;
/**
* GtkBuildableIface:
* @g_iface: the parent class
* @set_name: Stores the name attribute given in the GtkBuilder UI definition.
* #GtkWidget stores the name as object data. Implement this method if your
* object has some notion of "name" and it makes sense to map the XML name
* attribute to it.
* @get_name: The getter corresponding to @set_name. Implement this
* if you implement @set_name.
* @add_child: Adds a child. The @type parameter can be used to
* differentiate the kind of child. #GtkContainer implements this
* to add add a child widget to the container, #GtkNotebook uses
* the @type to distinguish between page labels (of type "page-label")
* and normal children.
* @set_buildable_property: Sets a property of a buildable object.
* It is normally not necessary to implement this, g_object_set_property()
* is used by default. #GtkWindow implements this to delay showing itself
* (i.e. setting the #GtkWidget:visible property) until the whole interface
* is created.
* @construct_child: Constructs a child of a buildable that has been
* specified as "constructor" in the UI definition. #GtkUIManager implements
* this to reference to a widget created in a &lt;ui&gt; tag which is outside
* of the normal GtkBuilder UI definition hierarchy. A reference to the
* constructed object is returned and becomes owned by the caller.
* @custom_tag_start: Implement this if the buildable needs to parse
* content below &lt;child&gt;. To handle an element, the implementation
* must fill in the @parser structure and @user_data and return %TRUE.
* #GtkWidget implements this to parse keyboard accelerators specified
* in &lt;accelerator&gt; elements. #GtkContainer implements it to map
* properties defined via &lt;packing&gt; elements to child properties.
* 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).
* @custom_finished: Called for each custom tag handled by the buildable
* when the builder finishes parsing (see @custom_tag_start)
* @parser_finished: Called when a builder finishes the parsing
* of a UI definition. It is normally not necessary to implement this,
* unless you need to perform special cleanup actions. #GtkWindow sets
* the #GtkWidget:visible property here.
* @get_internal_child: Returns an internal child of a buildable.
* #GtkDialog implements this to give access to its @vbox, making
* it possible to add children to the vbox in a UI definition.
* Implement this if the buildable has internal children that may
* need to be accessed from a UI definition.
*
* The GtkBuildableIface interface contains method that are
* necessary to allow #GtkBuilder to construct an object from
* a GtkBuilder UI definition.
*/
struct _GtkBuildableIface
{
GTypeInterface g_iface;