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, write to the
  17  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18  * Boston, MA 02111-1307, USA.
  19  */
  20
  21 /**
  22  * SECTION:gtkbuildable
  23  * @Short_description: Interface for objects that can be built by GtkBuilder
  24  * @Title: GtkBuildable
  25  *
  26  * GtkBuildable allows objects to extend and customize thier deserialization
  27  * from <link linkend="BUILDER-UI">GtkBuilder UI descriptions</link>.
  28  * The interface includes methods for setting names and properties of objects,
  29  * parsing custom tags and constructing child objects.
  30  *
  31  * The GtkBuildable interface is implemented by all widgets and
  32  * many of the non-widget objects that are provided by GTK+. The
  33  * main user of this interface is #GtkBuilder, there should be
  34  * very little need for applications to call any
  35  * <function>gtk_buildable_...</function> functions.
  36  *
  37  * <note><para>An object only needs to implement this interface if it needs
  38  * to extend the #GtkBuilder format or run any extra routines at deserialization time</para></note>
  39  */
  40
  41 #include "config.h"
  42 #include "gtkbuildable.h"
  43 #include "gtktypeutils.h"
  44 #include "gtkintl.h"
  45
  46
  47 typedef GtkBuildableIface GtkBuildableInterface;
  48 G_DEFINE_INTERFACE (GtkBuildable, gtk_buildable, G_TYPE_OBJECT)
  49
  50 static void
  51 gtk_buildable_default_init (GtkBuildableInterface *iface)
  52 {
  53 }
  54
  55 /**
  56  * gtk_buildable_set_name:
  57  * @buildable: a #GtkBuildable
  58  * @name: name to set
  59  *
  60  * Sets the name of the @buildable object.
  61  *
  62  * Since: 2.12
  63  **/
  64 void
  65 gtk_buildable_set_name (GtkBuildable *buildable,
  66                         const gchar  *name)
  67 {
  68   GtkBuildableIface *iface;
  69
  70   g_return_if_fail (GTK_IS_BUILDABLE (buildable));
  71   g_return_if_fail (name != NULL);
  72
  73   iface = GTK_BUILDABLE_GET_IFACE (buildable);
  74
  75   if (iface->set_name)
  76     (* iface->set_name) (buildable, name);
  77   else
  78     g_object_set_data_full (G_OBJECT (buildable),
  79                             "gtk-builder-name",
  80                             g_strdup (name),
  81                             g_free);
  82 }
  83
  84 /**
  85  * gtk_buildable_get_name:
  86  * @buildable: a #GtkBuildable
  87  *
  88  * Gets the name of the @buildable object.
  89  *
  90  * #GtkBuilder sets the name based on the the
  91  * <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
  92  * used to construct the @buildable.
  93  *
  94  * Returns: the name set with gtk_buildable_set_name()
  95  *
  96  * Since: 2.12
  97  **/
  98 const gchar *
  99 gtk_buildable_get_name (GtkBuildable *buildable)
 100 {
 101   GtkBuildableIface *iface;
 102
 103   g_return_val_if_fail (GTK_IS_BUILDABLE (buildable), NULL);
 104
 105   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 106
 107   if (iface->get_name)
 108     return (* iface->get_name) (buildable);
 109   else
 110     return (const gchar*)g_object_get_data (G_OBJECT (buildable),
 111                                             "gtk-builder-name");
 112 }
 113
 114 /**
 115  * gtk_buildable_add_child:
 116  * @buildable: a #GtkBuildable
 117  * @builder: a #GtkBuilder
 118  * @child: child to add
 119  * @type: (allow-none): kind of child or %NULL
 120  *
 121  * Adds a child to @buildable. @type is an optional string
 122  * describing how the child should be added.
 123  *
 124  * Since: 2.12
 125  **/
 126 void
 127 gtk_buildable_add_child (GtkBuildable *buildable,
 128                          GtkBuilder   *builder,
 129                          GObject      *child,
 130                          const gchar  *type)
 131 {
 132   GtkBuildableIface *iface;
 133
 134   g_return_if_fail (GTK_IS_BUILDABLE (buildable));
 135   g_return_if_fail (GTK_IS_BUILDER (builder));
 136
 137   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 138   g_return_if_fail (iface->add_child != NULL);
 139
 140   (* iface->add_child) (buildable, builder, child, type);
 141 }
 142
 143 /**
 144  * gtk_buildable_set_buildable_property:
 145  * @buildable: a #GtkBuildable
 146  * @builder: a #GtkBuilder
 147  * @name: name of property
 148  * @value: value of property
 149  *
 150  * Sets the property name @name to @value on the @buildable object.
 151  *
 152  * Since: 2.12
 153  **/
 154 void
 155 gtk_buildable_set_buildable_property (GtkBuildable *buildable,
 156                                       GtkBuilder   *builder,
 157                                       const gchar  *name,
 158                                       const GValue *value)
 159 {
 160   GtkBuildableIface *iface;
 161
 162   g_return_if_fail (GTK_IS_BUILDABLE (buildable));
 163   g_return_if_fail (GTK_IS_BUILDER (builder));
 164   g_return_if_fail (name != NULL);
 165   g_return_if_fail (value != NULL);
 166
 167   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 168   if (iface->set_buildable_property)
 169     (* iface->set_buildable_property) (buildable, builder, name, value);
 170   else
 171     g_object_set_property (G_OBJECT (buildable), name, value);
 172 }
 173
 174 /**
 175  * gtk_buildable_parser_finished:
 176  * @buildable: a #GtkBuildable
 177  * @builder: a #GtkBuilder
 178  *
 179  * Called when the builder finishes the parsing of a
 180  * <link linkend="BUILDER-UI">GtkBuilder UI definition</link>.
 181  * Note that this will be called once for each time
 182  * gtk_builder_add_from_file() or gtk_builder_add_from_string()
 183  * is called on a builder.
 184  *
 185  * Since: 2.12
 186  **/
 187 void
 188 gtk_buildable_parser_finished (GtkBuildable *buildable,
 189                                GtkBuilder   *builder)
 190 {
 191   GtkBuildableIface *iface;
 192
 193   g_return_if_fail (GTK_IS_BUILDABLE (buildable));
 194   g_return_if_fail (GTK_IS_BUILDER (builder));
 195
 196   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 197   if (iface->parser_finished)
 198     (* iface->parser_finished) (buildable, builder);
 199 }
 200
 201 /**
 202  * gtk_buildable_construct_child:
 203  * @buildable: A #GtkBuildable
 204  * @builder: #GtkBuilder used to construct this object
 205  * @name: name of child to construct
 206  *
 207  * Constructs a child of @buildable with the name @name.
 208  *
 209  * #GtkBuilder calls this function if a "constructor" has been
 210  * specified in the UI definition.
 211  *
 212  * Returns: (transfer full): the constructed child
 213  *
 214  * Since: 2.12
 215  **/
 216 GObject *
 217 gtk_buildable_construct_child (GtkBuildable *buildable,
 218                                GtkBuilder   *builder,
 219                                const gchar  *name)
 220 {
 221   GtkBuildableIface *iface;
 222
 223   g_return_val_if_fail (GTK_IS_BUILDABLE (buildable), NULL);
 224   g_return_val_if_fail (GTK_IS_BUILDER (builder), NULL);
 225   g_return_val_if_fail (name != NULL, NULL);
 226
 227   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 228   g_return_val_if_fail (iface->construct_child != NULL, NULL);
 229
 230   return (* iface->construct_child) (buildable, builder, name);
 231 }
 232
 233 /**
 234  * gtk_buildable_custom_tag_start:
 235  * @buildable: a #GtkBuildable
 236  * @builder: a #GtkBuilder used to construct this object
 237  * @child: (allow-none): child object or %NULL for non-child tags
 238  * @tagname: name of tag
 239  * @parser: a #GMarkupParser structure to fill in
 240  * @data: return location for user data that will be passed in
 241  *   to parser functions
 242  *
 243  * This is called for each unknown element under &lt;child&gt;.
 244  *
 245  * Returns: %TRUE if a object has a custom implementation, %FALSE
 246  *          if it doesn't.
 247  *
 248  * Since: 2.12
 249  **/
 250 gboolean
 251 gtk_buildable_custom_tag_start (GtkBuildable  *buildable,
 252                                 GtkBuilder    *builder,
 253                                 GObject       *child,
 254                                 const gchar   *tagname,
 255                                 GMarkupParser *parser,
 256                                 gpointer      *data)
 257 {
 258   GtkBuildableIface *iface;
 259
 260   g_return_val_if_fail (GTK_IS_BUILDABLE (buildable), FALSE);
 261   g_return_val_if_fail (GTK_IS_BUILDER (builder), FALSE);
 262   g_return_val_if_fail (tagname != NULL, FALSE);
 263
 264   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 265   g_return_val_if_fail (iface->custom_tag_start != NULL, FALSE);
 266
 267   return (* iface->custom_tag_start) (buildable, builder, child,
 268                                       tagname, parser, data);
 269 }
 270
 271 /**
 272  * gtk_buildable_custom_tag_end:
 273  * @buildable: A #GtkBuildable
 274  * @builder: #GtkBuilder used to construct this object
 275  * @child: (allow-none): child object or %NULL for non-child tags
 276  * @tagname: name of tag
 277  * @data: user data that will be passed in to parser functions
 278  *
 279  * This is called at the end of each custom element handled by
 280  * the buildable.
 281  *
 282  * Since: 2.12
 283  **/
 284 void
 285 gtk_buildable_custom_tag_end (GtkBuildable  *buildable,
 286                               GtkBuilder    *builder,
 287                               GObject       *child,
 288                               const gchar   *tagname,
 289                               gpointer      *data)
 290 {
 291   GtkBuildableIface *iface;
 292
 293   g_return_if_fail (GTK_IS_BUILDABLE (buildable));
 294   g_return_if_fail (GTK_IS_BUILDER (builder));
 295   g_return_if_fail (tagname != NULL);
 296
 297   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 298   if (iface->custom_tag_end)
 299     (* iface->custom_tag_end) (buildable, builder, child, tagname, data);
 300 }
 301
 302 /**
 303  * gtk_buildable_custom_finished:
 304  * @buildable: a #GtkBuildable
 305  * @builder: a #GtkBuilder
 306  * @child: (allow-none): child object or %NULL for non-child tags
 307  * @tagname: the name of the tag
 308  * @data: user data created in custom_tag_start
 309  *
 310  * This is similar to gtk_buildable_parser_finished() but is
 311  * called once for each custom tag handled by the @buildable.
 312  *
 313  * Since: 2.12
 314  **/
 315 void
 316 gtk_buildable_custom_finished (GtkBuildable  *buildable,
 317                                GtkBuilder    *builder,
 318                                GObject       *child,
 319                                const gchar   *tagname,
 320                                gpointer       data)
 321 {
 322   GtkBuildableIface *iface;
 323
 324   g_return_if_fail (GTK_IS_BUILDABLE (buildable));
 325   g_return_if_fail (GTK_IS_BUILDER (builder));
 326
 327   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 328   if (iface->custom_finished)
 329     (* iface->custom_finished) (buildable, builder, child, tagname, data);
 330 }
 331
 332 /**
 333  * gtk_buildable_get_internal_child:
 334  * @buildable: a #GtkBuildable
 335  * @builder: a #GtkBuilder
 336  * @childname: name of child
 337  *
 338  * Get the internal child called @childname of the @buildable object.
 339  *
 340  * Returns: (transfer none): the internal child of the buildable object
 341  *
 342  * Since: 2.12
 343  **/
 344 GObject *
 345 gtk_buildable_get_internal_child (GtkBuildable *buildable,
 346                                   GtkBuilder   *builder,
 347                                   const gchar  *childname)
 348 {
 349   GtkBuildableIface *iface;
 350
 351   g_return_val_if_fail (GTK_IS_BUILDABLE (buildable), NULL);
 352   g_return_val_if_fail (GTK_IS_BUILDER (builder), NULL);
 353   g_return_val_if_fail (childname != NULL, NULL);
 354
 355   iface = GTK_BUILDABLE_GET_IFACE (buildable);
 356   if (!iface->get_internal_child)
 357     return NULL;
 358
 359   return (* iface->get_internal_child) (buildable, builder, childname);
 360 }