X-Git-Url: http://pileus.org/git/?a=blobdiff_plain;f=gtk%2Fgtkbuildable.c;h=8867cfd333d41d5eba01ceb227595ab776b41af6;hb=e1edc998a2e9c557030d207533932b3120e13fe5;hp=e5dbf569955afb045009883b050030fe24da15f6;hpb=60a409785facbef5ba61c0bb1e396ec027e02bbc;p=~andy%2Fgtk diff --git a/gtk/gtkbuildable.c b/gtk/gtkbuildable.c index e5dbf5699..8867cfd33 100644 --- a/gtk/gtkbuildable.c +++ b/gtk/gtkbuildable.c @@ -13,30 +13,40 @@ * Library General Public License for more details. * * You should have received a copy of the GNU Library General Public - * License along with this library; if not, write to the - * Free Software Foundation, Inc., 59 Temple Place - Suite 330, - * Boston, MA 02111-1307, USA. + * License along with this library. If not, see . */ +/** + * SECTION:gtkbuildable + * @Short_description: Interface for objects that can be built by GtkBuilder + * @Title: GtkBuildable + * + * GtkBuildable allows objects to extend and customize their deserialization + * from GtkBuilder UI descriptions. + * The interface includes methods for setting names and properties of objects, + * parsing custom tags and 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 + * gtk_buildable_... functions. + * + * An object only needs to implement this interface if it needs + * to extend the #GtkBuilder format or run any extra routines at deserialization time + */ -#include +#include "config.h" #include "gtkbuildable.h" -#include "gtktypeutils.h" #include "gtkintl.h" -#include "gtkalias.h" -GType -gtk_buildable_get_type (void) -{ - static GType buildable_type = 0; - if (!buildable_type) - buildable_type = - g_type_register_static_simple (G_TYPE_INTERFACE, I_("GtkBuildable"), - sizeof (GtkBuildableIface), - NULL, 0, NULL, 0); +typedef GtkBuildableIface GtkBuildableInterface; +G_DEFINE_INTERFACE (GtkBuildable, gtk_buildable, G_TYPE_OBJECT) - return buildable_type; +static void +gtk_buildable_default_init (GtkBuildableInterface *iface) +{ } /** @@ -44,10 +54,7 @@ gtk_buildable_get_type (void) * @buildable: a #GtkBuildable * @name: name to set * - * Sets the name of the buildable object, it's used to synchronize the name - * if the object already has it's own concept of name. - * - * #GtkWidget implements this to map the buildable name to the widget name + * Sets the name of the @buildable object. * * Since: 2.12 **/ @@ -75,12 +82,11 @@ gtk_buildable_set_name (GtkBuildable *buildable, * gtk_buildable_get_name: * @buildable: a #GtkBuildable * - * - * Returns the buildable name. #GtkBuilder sets the name based on the - * the GtkBuilder UI definition used - * to construct the @buildable. - * - * #GtkWidget implements this to map the buildable name to the widget name + * Gets the name of the @buildable object. + * + * #GtkBuilder sets the name based on the + * GtkBuilder UI definition + * used to construct the @buildable. * * Returns: the name set with gtk_buildable_set_name() * @@ -107,15 +113,11 @@ gtk_buildable_get_name (GtkBuildable *buildable) * @buildable: a #GtkBuildable * @builder: a #GtkBuilder * @child: child to add - * @type: kind of child or %NULL + * @type: (allow-none): kind of child or %NULL * - * Add a child to a buildable. type is an optional string + * Adds a child to @buildable. @type is an optional string * describing how the child should be added. * - * #GtkContainer implements this to be able to add a child widget - * to the container. #GtkNotebook uses the @type to distinguish between - * page labels (@type = "page-label") and normal children. - * * Since: 2.12 **/ void @@ -142,14 +144,7 @@ gtk_buildable_add_child (GtkBuildable *buildable, * @name: name of property * @value: value of property * - * Sets the property name @name to @value on the buildable object @buildable - * which is created by the @builder. - * - * This is optional to implement and is normally not needed. - * g_object_set_property() is used as a fallback. - * - * #GtkWindow implements this to delay showing (::visible) itself until - * the whole interface is fully created. + * Sets the property name @name to @value on the @buildable object. * * Since: 2.12 **/ @@ -178,12 +173,11 @@ gtk_buildable_set_buildable_property (GtkBuildable *buildable, * @buildable: a #GtkBuildable * @builder: a #GtkBuilder * - * Finish the parsing of a GtkBuilder UI definition - * snippet. 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. - * - * #GtkWindow implements this to delay showing (::visible) itself until - * the whole interface is fully created. + * Called when the builder finishes the parsing of a + * GtkBuilder UI definition. + * 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. * * Since: 2.12 **/ @@ -202,19 +196,17 @@ gtk_buildable_parser_finished (GtkBuildable *buildable, } /** - * gtk_buildable_construct_child + * gtk_buildable_construct_child: * @buildable: A #GtkBuildable * @builder: #GtkBuilder used to construct this object * @name: name of child to construct * - * Construct a child of @buildable with the name @name. + * Constructs a child of @buildable with the name @name. * - * #GtkUIManager implements this to reference to a widget created in a - * <ui> tag which is outside of the normal - * GtkBuilder UI definition - * hierarchy. + * #GtkBuilder calls this function if a "constructor" has been + * specified in the UI definition. * - * Returns: the child with name @name + * Returns: (transfer full): the constructed child * * Since: 2.12 **/ @@ -236,27 +228,17 @@ gtk_buildable_construct_child (GtkBuildable *buildable, } /** - * gtk_buildable_custom_tag_start + * gtk_buildable_custom_tag_start: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder used to construct this object - * @child: child object or %NULL for non-child tags + * @child: (allow-none): child object or %NULL for non-child tags * @tagname: name of tag - * @parser: a #GMarkupParser structure - * @data: user data that will be passed in to parser functions + * @parser: (out): a #GMarkupParser structure to fill in + * @data: (out): return location for user data that will be passed in + * to parser functions * - * This is called when an unknown tag under <child> tag is found. + * This is called for each unknown element under <child>. * - * Called when an unknown tag is present under a <child> tag. - * If the buildable implementation wishes to handle the tag it should - * return %TRUE and fill in the @parser structure. Remember to either - * implement custom_tag_end or custom_tag_finish to free - * the user data allocated here. - * - * #GtkWidget implements this and parsers all <accelerator> tags to - * keyboard accelerators. - * #GtkContainer implements this to map properties defined under - * <packing> tag to child properties. - * * Returns: %TRUE if a object has a custom implementation, %FALSE * if it doesn't. * @@ -284,15 +266,15 @@ gtk_buildable_custom_tag_start (GtkBuildable *buildable, } /** - * gtk_buildable_custom_tag_end + * gtk_buildable_custom_tag_end: * @buildable: A #GtkBuildable * @builder: #GtkBuilder used to construct this object - * @child: child object or %NULL for non-child tags + * @child: (allow-none): child object or %NULL for non-child tags * @tagname: name of tag - * @data: user data that will be passed in to parser functions + * @data: (type gpointer): user data that will be passed in to parser functions * - * This is called for each custom tag handled by the buildable. - * It will be called when the end of the tag is reached. + * This is called at the end of each custom element handled by + * the buildable. * * Since: 2.12 **/ @@ -318,7 +300,7 @@ gtk_buildable_custom_tag_end (GtkBuildable *buildable, * gtk_buildable_custom_finished: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder - * @child: child object or %NULL for non-child tags + * @child: (allow-none): child object or %NULL for non-child tags * @tagname: the name of the tag * @data: user data created in custom_tag_start * @@ -345,14 +327,14 @@ gtk_buildable_custom_finished (GtkBuildable *buildable, } /** - * gtk_buildable_get_internal_child + * gtk_buildable_get_internal_child: * @buildable: a #GtkBuildable * @builder: a #GtkBuilder * @childname: name of child * * Get the internal child called @childname of the @buildable object. * - * Returns: the internal child of the buildable object + * Returns: (transfer none): the internal child of the buildable object * * Since: 2.12 **/ @@ -373,6 +355,3 @@ gtk_buildable_get_internal_child (GtkBuildable *buildable, return (* iface->get_internal_child) (buildable, builder, childname); } - -#define __GTK_BUILDABLE_C__ -#include "gtkaliasdef.c"