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