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