Pileus Git - ~andy/gtk/blob - gtk/gtkbuildable.c

   1 /* gtkbuildable.c
   2  * Copyright (C) 2006-2007 Async Open Source,
   3  *                         Johan Dahlin <jdahlin@async.com.br>
   4  *
   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.
   9  *
  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.
  14  *
  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/>.
  17  */
  18
  19 /**
  20  * SECTION:gtkbuildable
  21  * @Short_description: Interface for objects that can be built by GtkBuilder
  22  * @Title: GtkBuildable
  23  *
  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.
  28  *
  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.
  34  *
  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>
  37  */
  38
  39 #include "config.h"
  40 #include "gtkbuildable.h"
  41 #include "gtkintl.h"
  42
  43
  44 typedef GtkBuildableIface GtkBuildableInterface;
  45 G_DEFINE_INTERFACE (GtkBuildable, gtk_buildable, G_TYPE_OBJECT)
  46
  47 static void
  48 gtk_buildable_default_init (GtkBuildableInterface *iface)
  49 {
  50 }
  51
  52 /**
  53  * gtk_buildable_set_name:
  54  * @buildable: a #GtkBuildable
  55  * @name: name to set
  56  *
  57  * Sets the name of the @buildable object.
  58  *
  59  * Since: 2.12
  60  **/
  61 void
  62 gtk_buildable_set_name (GtkBuildable *buildable,
  63                         const gchar  *name)
  64 {
  65   GtkBuildableIface *iface;
  66
  67   g_return_if_fail (GTK_IS_BUILDABLE (buildable));
  68   g_return_if_fail (name != NULL);
  69
  70   iface = GTK_BUILDABLE_GET_IFACE (buildable);
  71
  72   if (iface->set_name)
  73     (* iface->set_name) (buildable, name);
  74   else
  75     g_object_set_data_full (G_OBJECT (buildable),
  76                             "gtk-builder-name",
  77                             g_strdup (name),
  78                             g_free);
  79 }
  80
  81 /**
  82  * gtk_buildable_get_name:
  83  * @buildable: a #GtkBuildable
  84  *
  85  * Gets the name of the @buildable object.
  86  *
  87  * #GtkBuilder sets the name based on the
  88  * <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
  89  * used to construct the @buildable.
  90  *
  91  * Returns: the name set with gtk_buildable_set_name()
  92  *
  93  * Since: 2.12
  94  **/
  95 const gchar *
  96 gtk_buildable_get_name (GtkBuildable *buildable)
  97 {
  98   GtkBuildableIface *iface;
  99
 100   g_return_val_if_fail (GTK_IS_BUILDABLE (buildable), NULL);
 101
 102   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 103
 104   if (iface->get_name)
 105     return (* iface->get_name) (buildable);
 106   else
 107     return (const gchar*)g_object_get_data (G_OBJECT (buildable),
 108                                             "gtk-builder-name");
 109 }
 110
 111 /**
 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
 117  *
 118  * Adds a child to @buildable. @type is an optional string
 119  * describing how the child should be added.
 120  *
 121  * Since: 2.12
 122  **/
 123 void
 124 gtk_buildable_add_child (GtkBuildable *buildable,
 125                          GtkBuilder   *builder,
 126                          GObject      *child,
 127                          const gchar  *type)
 128 {
 129   GtkBuildableIface *iface;
 130
 131   g_return_if_fail (GTK_IS_BUILDABLE (buildable));
 132   g_return_if_fail (GTK_IS_BUILDER (builder));
 133
 134   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 135   g_return_if_fail (iface->add_child != NULL);
 136
 137   (* iface->add_child) (buildable, builder, child, type);
 138 }
 139
 140 /**
 141  * gtk_buildable_set_buildable_property:
 142  * @buildable: a #GtkBuildable
 143  * @builder: a #GtkBuilder
 144  * @name: name of property
 145  * @value: value of property
 146  *
 147  * Sets the property name @name to @value on the @buildable object.
 148  *
 149  * Since: 2.12
 150  **/
 151 void
 152 gtk_buildable_set_buildable_property (GtkBuildable *buildable,
 153                                       GtkBuilder   *builder,
 154                                       const gchar  *name,
 155                                       const GValue *value)
 156 {
 157   GtkBuildableIface *iface;
 158
 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);
 163
 164   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 165   if (iface->set_buildable_property)
 166     (* iface->set_buildable_property) (buildable, builder, name, value);
 167   else
 168     g_object_set_property (G_OBJECT (buildable), name, value);
 169 }
 170
 171 /**
 172  * gtk_buildable_parser_finished:
 173  * @buildable: a #GtkBuildable
 174  * @builder: a #GtkBuilder
 175  *
 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.
 181  *
 182  * Since: 2.12
 183  **/
 184 void
 185 gtk_buildable_parser_finished (GtkBuildable *buildable,
 186                                GtkBuilder   *builder)
 187 {
 188   GtkBuildableIface *iface;
 189
 190   g_return_if_fail (GTK_IS_BUILDABLE (buildable));
 191   g_return_if_fail (GTK_IS_BUILDER (builder));
 192
 193   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 194   if (iface->parser_finished)
 195     (* iface->parser_finished) (buildable, builder);
 196 }
 197
 198 /**
 199  * gtk_buildable_construct_child:
 200  * @buildable: A #GtkBuildable
 201  * @builder: #GtkBuilder used to construct this object
 202  * @name: name of child to construct
 203  *
 204  * Constructs a child of @buildable with the name @name.
 205  *
 206  * #GtkBuilder calls this function if a "constructor" has been
 207  * specified in the UI definition.
 208  *
 209  * Returns: (transfer full): the constructed child
 210  *
 211  * Since: 2.12
 212  **/
 213 GObject *
 214 gtk_buildable_construct_child (GtkBuildable *buildable,
 215                                GtkBuilder   *builder,
 216                                const gchar  *name)
 217 {
 218   GtkBuildableIface *iface;
 219
 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);
 223
 224   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 225   g_return_val_if_fail (iface->construct_child != NULL, NULL);
 226
 227   return (* iface->construct_child) (buildable, builder, name);
 228 }
 229
 230 /**
 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
 239  *
 240  * This is called for each unknown element under &lt;child&gt;.
 241  *
 242  * Returns: %TRUE if a object has a custom implementation, %FALSE
 243  *          if it doesn't.
 244  *
 245  * Since: 2.12
 246  **/
 247 gboolean
 248 gtk_buildable_custom_tag_start (GtkBuildable  *buildable,
 249                                 GtkBuilder    *builder,
 250                                 GObject       *child,
 251                                 const gchar   *tagname,
 252                                 GMarkupParser *parser,
 253                                 gpointer      *data)
 254 {
 255   GtkBuildableIface *iface;
 256
 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);
 260
 261   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 262   g_return_val_if_fail (iface->custom_tag_start != NULL, FALSE);
 263
 264   return (* iface->custom_tag_start) (buildable, builder, child,
 265                                       tagname, parser, data);
 266 }
 267
 268 /**
 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
 275  *
 276  * This is called at the end of each custom element handled by
 277  * the buildable.
 278  *
 279  * Since: 2.12
 280  **/
 281 void
 282 gtk_buildable_custom_tag_end (GtkBuildable  *buildable,
 283                               GtkBuilder    *builder,
 284                               GObject       *child,
 285                               const gchar   *tagname,
 286                               gpointer      *data)
 287 {
 288   GtkBuildableIface *iface;
 289
 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);
 293
 294   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 295   if (iface->custom_tag_end)
 296     (* iface->custom_tag_end) (buildable, builder, child, tagname, data);
 297 }
 298
 299 /**
 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
 306  *
 307  * This is similar to gtk_buildable_parser_finished() but is
 308  * called once for each custom tag handled by the @buildable.
 309  *
 310  * Since: 2.12
 311  **/
 312 void
 313 gtk_buildable_custom_finished (GtkBuildable  *buildable,
 314                                GtkBuilder    *builder,
 315                                GObject       *child,
 316                                const gchar   *tagname,
 317                                gpointer       data)
 318 {
 319   GtkBuildableIface *iface;
 320
 321   g_return_if_fail (GTK_IS_BUILDABLE (buildable));
 322   g_return_if_fail (GTK_IS_BUILDER (builder));
 323
 324   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 325   if (iface->custom_finished)
 326     (* iface->custom_finished) (buildable, builder, child, tagname, data);
 327 }
 328
 329 /**
 330  * gtk_buildable_get_internal_child:
 331  * @buildable: a #GtkBuildable
 332  * @builder: a #GtkBuilder
 333  * @childname: name of child
 334  *
 335  * Get the internal child called @childname of the @buildable object.
 336  *
 337  * Returns: (transfer none): the internal child of the buildable object
 338  *
 339  * Since: 2.12
 340  **/
 341 GObject *
 342 gtk_buildable_get_internal_child (GtkBuildable *buildable,
 343                                   GtkBuilder   *builder,
 344                                   const gchar  *childname)
 345 {
 346   GtkBuildableIface *iface;
 347
 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);
 351
 352   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 353   if (!iface->get_internal_child)
 354     return NULL;
 355
 356   return (* iface->get_internal_child) (buildable, builder, childname);
 357 }