* 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 <http://www.gnu.org/licenses/>.
*/
+/**
+ * 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 <link linkend="BUILDER-UI">GtkBuilder UI descriptions</link>.
+ * 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
+ * <function>gtk_buildable_...</function> functions.
+ *
+ * <note><para>An object only needs to implement this interface if it needs
+ * to extend the #GtkBuilder format or run any extra routines at deserialization time</para></note>
+ */
-#include <config.h>
+#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)
+{
}
/**
* @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
**/
* gtk_buildable_get_name:
* @buildable: a #GtkBuildable
*
- * Returns: the buildable name, the name which was set in
- * the <link linkend="BUILDER-UI">GtkBuilder UI definition</link> used to
- * construct the @buildable.
+ * Gets the name of the @buildable object.
+ *
+ * #GtkBuilder sets the name based on the
+ * <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
+ * used to construct the @buildable.
*
- * #GtkWidget implements this to map the buildable name to the widget name
+ * Returns: the name set with gtk_buildable_set_name()
*
* Since: 2.12
**/
}
/**
- * gtk_buildable_add:
+ * gtk_buildable_add_child:
* @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
-gtk_buildable_add (GtkBuildable *buildable,
- GtkBuilder *builder,
- GObject *child,
- const gchar *type)
+gtk_buildable_add_child (GtkBuildable *buildable,
+ GtkBuilder *builder,
+ GObject *child,
+ const gchar *type)
{
GtkBuildableIface *iface;
g_return_if_fail (GTK_IS_BUILDER (builder));
iface = GTK_BUILDABLE_GET_IFACE (buildable);
- g_return_if_fail (iface->add != NULL);
+ g_return_if_fail (iface->add_child != NULL);
- (* iface->add) (buildable, builder, child, type);
+ (* iface->add_child) (buildable, builder, child, type);
}
/**
- * gtk_buildable_set_property:
+ * gtk_buildable_set_buildable_property:
* @buildable: a #GtkBuildable
* @builder: a #GtkBuilder
* @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
**/
void
-gtk_buildable_set_property (GtkBuildable *buildable,
- GtkBuilder *builder,
- const gchar *name,
- const GValue *value)
+gtk_buildable_set_buildable_property (GtkBuildable *buildable,
+ GtkBuilder *builder,
+ const gchar *name,
+ const GValue *value)
{
GtkBuildableIface *iface;
g_return_if_fail (value != NULL);
iface = GTK_BUILDABLE_GET_IFACE (buildable);
- if (iface->set_property)
- (* iface->set_property) (buildable, builder, name, value);
+ if (iface->set_buildable_property)
+ (* iface->set_buildable_property) (buildable, builder, name, value);
else
g_object_set_property (G_OBJECT (buildable), name, value);
}
* @buildable: a #GtkBuildable
* @builder: a #GtkBuilder
*
- * Finish the parsing of a <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
- * 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
+ * <link linkend="BUILDER-UI">GtkBuilder UI definition</link>.
+ * 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
**/
}
/**
- * 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.
+ *
+ * #GtkBuilder calls this function if a "constructor" has been
+ * specified in the UI definition.
*
- * #GtkUIManager implements this to reference to a widget created in a <ui> tag
- * which is outside of the normal <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
- * object hierarchy.
+ * Returns: (transfer full): the constructed child
*
* Since: 2.12
**/
}
/**
- * 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.
*
}
/**
- * 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
**/
* 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
*
}
/**
- * 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 @child of the @buildable object.
+ * Get the internal child called @childname of the @buildable object.
*
- * Return: the internal child of the buildable object
+ * Returns: (transfer none): the internal child of the buildable object
*
* Since: 2.12
**/
return (* iface->get_internal_child) (buildable, builder, childname);
}
-
-#define __GTK_BUILDABLE_C__
-#include "gtkaliasdef.c"
projects / ~andy / gtk / blobdiff