2 * Copyright (C) 2006-2007 Async Open Source,
3 * Johan Dahlin <jdahlin@async.com.br>
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Library General Public License for more details.
15 * You should have received a copy of the GNU Library General Public
16 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
20 * SECTION:gtkbuildable
21 * @Short_description: Interface for objects that can be built by GtkBuilder
22 * @Title: GtkBuildable
24 * GtkBuildable allows objects to extend and customize their deserialization
25 * from <link linkend="BUILDER-UI">GtkBuilder UI descriptions</link>.
26 * The interface includes methods for setting names and properties of objects,
27 * parsing custom tags and constructing child objects.
29 * The GtkBuildable interface is implemented by all widgets and
30 * many of the non-widget objects that are provided by GTK+. The
31 * main user of this interface is #GtkBuilder. There should be
32 * very little need for applications to call any
33 * <function>gtk_buildable_...</function> functions.
35 * <note><para>An object only needs to implement this interface if it needs
36 * to extend the #GtkBuilder format or run any extra routines at deserialization time</para></note>
40 #include "gtkbuildable.h"
44 typedef GtkBuildableIface GtkBuildableInterface;
45 G_DEFINE_INTERFACE (GtkBuildable, gtk_buildable, G_TYPE_OBJECT)
48 gtk_buildable_default_init (GtkBuildableInterface *iface)
53 * gtk_buildable_set_name:
54 * @buildable: a #GtkBuildable
57 * Sets the name of the @buildable object.
62 gtk_buildable_set_name (GtkBuildable *buildable,
65 GtkBuildableIface *iface;
67 g_return_if_fail (GTK_IS_BUILDABLE (buildable));
68 g_return_if_fail (name != NULL);
70 iface = GTK_BUILDABLE_GET_IFACE (buildable);
73 (* iface->set_name) (buildable, name);
75 g_object_set_data_full (G_OBJECT (buildable),
82 * gtk_buildable_get_name:
83 * @buildable: a #GtkBuildable
85 * Gets the name of the @buildable object.
87 * #GtkBuilder sets the name based on the
88 * <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
89 * used to construct the @buildable.
91 * Returns: the name set with gtk_buildable_set_name()
96 gtk_buildable_get_name (GtkBuildable *buildable)
98 GtkBuildableIface *iface;
100 g_return_val_if_fail (GTK_IS_BUILDABLE (buildable), NULL);
102 iface = GTK_BUILDABLE_GET_IFACE (buildable);
105 return (* iface->get_name) (buildable);
107 return (const gchar*)g_object_get_data (G_OBJECT (buildable),
112 * gtk_buildable_add_child:
113 * @buildable: a #GtkBuildable
114 * @builder: a #GtkBuilder
115 * @child: child to add
116 * @type: (allow-none): kind of child or %NULL
118 * Adds a child to @buildable. @type is an optional string
119 * describing how the child should be added.
124 gtk_buildable_add_child (GtkBuildable *buildable,
129 GtkBuildableIface *iface;
131 g_return_if_fail (GTK_IS_BUILDABLE (buildable));
132 g_return_if_fail (GTK_IS_BUILDER (builder));
134 iface = GTK_BUILDABLE_GET_IFACE (buildable);
135 g_return_if_fail (iface->add_child != NULL);
137 (* iface->add_child) (buildable, builder, child, type);
141 * gtk_buildable_set_buildable_property:
142 * @buildable: a #GtkBuildable
143 * @builder: a #GtkBuilder
144 * @name: name of property
145 * @value: value of property
147 * Sets the property name @name to @value on the @buildable object.
152 gtk_buildable_set_buildable_property (GtkBuildable *buildable,
157 GtkBuildableIface *iface;
159 g_return_if_fail (GTK_IS_BUILDABLE (buildable));
160 g_return_if_fail (GTK_IS_BUILDER (builder));
161 g_return_if_fail (name != NULL);
162 g_return_if_fail (value != NULL);
164 iface = GTK_BUILDABLE_GET_IFACE (buildable);
165 if (iface->set_buildable_property)
166 (* iface->set_buildable_property) (buildable, builder, name, value);
168 g_object_set_property (G_OBJECT (buildable), name, value);
172 * gtk_buildable_parser_finished:
173 * @buildable: a #GtkBuildable
174 * @builder: a #GtkBuilder
176 * Called when the builder finishes the parsing of a
177 * <link linkend="BUILDER-UI">GtkBuilder UI definition</link>.
178 * Note that this will be called once for each time
179 * gtk_builder_add_from_file() or gtk_builder_add_from_string()
180 * is called on a builder.
185 gtk_buildable_parser_finished (GtkBuildable *buildable,
188 GtkBuildableIface *iface;
190 g_return_if_fail (GTK_IS_BUILDABLE (buildable));
191 g_return_if_fail (GTK_IS_BUILDER (builder));
193 iface = GTK_BUILDABLE_GET_IFACE (buildable);
194 if (iface->parser_finished)
195 (* iface->parser_finished) (buildable, builder);
199 * gtk_buildable_construct_child:
200 * @buildable: A #GtkBuildable
201 * @builder: #GtkBuilder used to construct this object
202 * @name: name of child to construct
204 * Constructs a child of @buildable with the name @name.
206 * #GtkBuilder calls this function if a "constructor" has been
207 * specified in the UI definition.
209 * Returns: (transfer full): the constructed child
214 gtk_buildable_construct_child (GtkBuildable *buildable,
218 GtkBuildableIface *iface;
220 g_return_val_if_fail (GTK_IS_BUILDABLE (buildable), NULL);
221 g_return_val_if_fail (GTK_IS_BUILDER (builder), NULL);
222 g_return_val_if_fail (name != NULL, NULL);
224 iface = GTK_BUILDABLE_GET_IFACE (buildable);
225 g_return_val_if_fail (iface->construct_child != NULL, NULL);
227 return (* iface->construct_child) (buildable, builder, name);
231 * gtk_buildable_custom_tag_start:
232 * @buildable: a #GtkBuildable
233 * @builder: a #GtkBuilder used to construct this object
234 * @child: (allow-none): child object or %NULL for non-child tags
235 * @tagname: name of tag
236 * @parser: (out): a #GMarkupParser structure to fill in
237 * @data: (out): return location for user data that will be passed in
238 * to parser functions
240 * This is called for each unknown element under <child>.
242 * Returns: %TRUE if a object has a custom implementation, %FALSE
248 gtk_buildable_custom_tag_start (GtkBuildable *buildable,
251 const gchar *tagname,
252 GMarkupParser *parser,
255 GtkBuildableIface *iface;
257 g_return_val_if_fail (GTK_IS_BUILDABLE (buildable), FALSE);
258 g_return_val_if_fail (GTK_IS_BUILDER (builder), FALSE);
259 g_return_val_if_fail (tagname != NULL, FALSE);
261 iface = GTK_BUILDABLE_GET_IFACE (buildable);
262 g_return_val_if_fail (iface->custom_tag_start != NULL, FALSE);
264 return (* iface->custom_tag_start) (buildable, builder, child,
265 tagname, parser, data);
269 * gtk_buildable_custom_tag_end:
270 * @buildable: A #GtkBuildable
271 * @builder: #GtkBuilder used to construct this object
272 * @child: (allow-none): child object or %NULL for non-child tags
273 * @tagname: name of tag
274 * @data: (type gpointer): user data that will be passed in to parser functions
276 * This is called at the end of each custom element handled by
282 gtk_buildable_custom_tag_end (GtkBuildable *buildable,
285 const gchar *tagname,
288 GtkBuildableIface *iface;
290 g_return_if_fail (GTK_IS_BUILDABLE (buildable));
291 g_return_if_fail (GTK_IS_BUILDER (builder));
292 g_return_if_fail (tagname != NULL);
294 iface = GTK_BUILDABLE_GET_IFACE (buildable);
295 if (iface->custom_tag_end)
296 (* iface->custom_tag_end) (buildable, builder, child, tagname, data);
300 * gtk_buildable_custom_finished:
301 * @buildable: a #GtkBuildable
302 * @builder: a #GtkBuilder
303 * @child: (allow-none): child object or %NULL for non-child tags
304 * @tagname: the name of the tag
305 * @data: user data created in custom_tag_start
307 * This is similar to gtk_buildable_parser_finished() but is
308 * called once for each custom tag handled by the @buildable.
313 gtk_buildable_custom_finished (GtkBuildable *buildable,
316 const gchar *tagname,
319 GtkBuildableIface *iface;
321 g_return_if_fail (GTK_IS_BUILDABLE (buildable));
322 g_return_if_fail (GTK_IS_BUILDER (builder));
324 iface = GTK_BUILDABLE_GET_IFACE (buildable);
325 if (iface->custom_finished)
326 (* iface->custom_finished) (buildable, builder, child, tagname, data);
330 * gtk_buildable_get_internal_child:
331 * @buildable: a #GtkBuildable
332 * @builder: a #GtkBuilder
333 * @childname: name of child
335 * Get the internal child called @childname of the @buildable object.
337 * Returns: (transfer none): the internal child of the buildable object
342 gtk_buildable_get_internal_child (GtkBuildable *buildable,
344 const gchar *childname)
346 GtkBuildableIface *iface;
348 g_return_val_if_fail (GTK_IS_BUILDABLE (buildable), NULL);
349 g_return_val_if_fail (GTK_IS_BUILDER (builder), NULL);
350 g_return_val_if_fail (childname != NULL, NULL);
352 iface = GTK_BUILDABLE_GET_IFACE (buildable);
353 if (!iface->get_internal_child)
356 return (* iface->get_internal_child) (buildable, builder, childname);