docs/reference/gobject/tmpl/objects.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GObject
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 The base object type
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9
  10 </para>
  11
  12 <!-- ##### SECTION See_Also ##### -->
  13 <para>
  14
  15 </para>
  16
  17 <!-- ##### STRUCT GObject ##### -->
  18 <para>
  19 All the fields in the <structname>GObject</structname> structure are private
  20 to the #GObject implementation and should never be accessed directly.
  21 </para>
  22
  23
  24 <!-- ##### STRUCT GObjectClass ##### -->
  25 <para>
  26
  27 </para>
  28
  29 @g_type_class:
  30 @constructor:
  31 @set_property:
  32 @get_property:
  33 @dispose:
  34 @finalize:
  35 @dispatch_properties_changed:
  36 @notify:
  37
  38 <!-- ##### STRUCT GObjectConstructParam ##### -->
  39 <para>
  40 The <structname>GObjectConstructParam</structname> struct is an auxiliary
  41 structure used to hand #GParamSpec/#GValue pairs to the @constructor of
  42 a #GObjectClass.
  43 </para>
  44
  45 @pspec: the #GParamSpec of the construct parameter
  46 @value: the value to set the parameter to
  47
  48 <!-- ##### USER_FUNCTION GObjectGetPropertyFunc ##### -->
  49 <para>
  50 The type of the @get_property function of #GObjectClass.
  51 </para>
  52
  53 @object: a #GObject
  54 @property_id: the numeric id under which the property was registered with
  55    g_object_class_install_property().
  56 @value: a #GValue to return the property value in
  57 @pspec: the #GParamSpec describing the property
  58
  59
  60 <!-- ##### USER_FUNCTION GObjectSetPropertyFunc ##### -->
  61 <para>
  62 The type of the @set_property function of #GObjectClass.
  63 </para>
  64
  65 @object: a #GObject
  66 @property_id: the numeric id under which the property was registered with
  67    g_object_class_install_property().
  68 @value: the new value for the property
  69 @pspec: the #GParamSpec describing the property
  70
  71
  72 <!-- ##### USER_FUNCTION GObjectFinalizeFunc ##### -->
  73 <para>
  74 The type of the @finalize function of #GObjectClass.
  75 </para>
  76
  77 @object: the #GObject being finalized
  78
  79
  80 <!-- ##### MACRO G_TYPE_IS_OBJECT ##### -->
  81 <para>
  82 Returns a boolean value of %FALSE or %TRUE indicating whether
  83 the passed in type id is a %G_TYPE_OBJECT or derived from it.
  84 </para>
  85
  86 @type: Type id to check for is a %G_TYPE_OBJECT relationship.
  87 @Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT.
  88
  89
  90 <!-- ##### MACRO G_OBJECT ##### -->
  91 <para>
  92 Casts a #GObject or derived pointer into a (GObject*) pointer.
  93 Depending on the current debugging level, this function may invoke
  94 certain runtime checks to identify invalid casts.
  95 </para>
  96
  97 @object: Object which is subject to casting.
  98
  99
 100 <!-- ##### MACRO G_IS_OBJECT ##### -->
 101 <para>
 102 Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
 103 </para>
 104
 105 @object: Instance to check for being a %G_TYPE_OBJECT.
 106
 107
 108 <!-- ##### MACRO G_OBJECT_CLASS ##### -->
 109 <para>
 110 Casts a derived #GObjectClass structure into a #GObjectClass structure.
 111 </para>
 112
 113 @class: a valid #GObjectClass
 114
 115
 116 <!-- ##### MACRO G_IS_OBJECT_CLASS ##### -->
 117 <para>
 118 Checks whether @class "is a" valid #GObjectClass structure of type
 119 %G_TYPE_OBJECT or derived.
 120 </para>
 121
 122 @class: a #GObjectClass
 123
 124
 125 <!-- ##### MACRO G_OBJECT_GET_CLASS ##### -->
 126 <para>
 127 Returns the class structure associated to a #GObject instance.
 128 </para>
 129
 130 @object: a #GObject instance.
 131
 132
 133 <!-- ##### MACRO G_OBJECT_TYPE ##### -->
 134 <para>
 135 Return the type id of an object.
 136 </para>
 137
 138 @object: Object to return the type id for.
 139 @Returns: Type id of @object.
 140
 141
 142 <!-- ##### MACRO G_OBJECT_TYPE_NAME ##### -->
 143 <para>
 144 Returns the name of an object's type.
 145 </para>
 146
 147 @object: Object to return the type name for.
 148 @Returns: Type name of @object. The string is owned by the type system and
 149 should not be freed.
 150
 151
 152 <!-- ##### MACRO G_OBJECT_CLASS_TYPE ##### -->
 153 <para>
 154 Return the type id of a class structure.
 155 </para>
 156
 157 @class: a valid #GObjectClass
 158 @Returns: Type id of @class.
 159
 160
 161 <!-- ##### MACRO G_OBJECT_CLASS_NAME ##### -->
 162 <para>
 163 Return the name of a class structure's type.
 164 </para>
 165
 166 @class: a valid #GObjectClass
 167 @Returns: Type name of @class. The string is owned by the type system and
 168 should not be freed.
 169
 170
 171 <!-- ##### FUNCTION g_object_class_install_property ##### -->
 172 <para>
 173 Installs a new property. This is usually done in the class initializer.
 174 </para>
 175
 176 @oclass: a #GObjectClass
 177 @property_id: the id for the new property
 178 @pspec: the #GParamSpec for the new property
 179
 180
 181 <!-- ##### FUNCTION g_object_class_find_property ##### -->
 182 <para>
 183 Looks up the #GParamSpec for a property of a class.
 184 </para>
 185
 186 @oclass: a #GObjectClass
 187 @property_name: the name of the property to look up
 188 @Returns: the #GParamSpec for the property, or %NULL if the class doesn't have
 189 a property of that name
 190
 191
 192 <!-- ##### FUNCTION g_object_class_list_properties ##### -->
 193 <para>
 194 Returns an array of #GParamSpec* for all properties of a class.
 195 </para>
 196
 197 @oclass: a #GObjectClass
 198 @n_properties: return location for the length of the returned array
 199 @Returns: an array of #GParamSpec* which should be freed after use
 200
 201
 202 <!-- ##### FUNCTION g_object_class_override_property ##### -->
 203 <para>
 204 Registers @property_id as referring to a property with the
 205 name @name in a parent class or in an interface implemented
 206 by @oclass. This allows this class to <firstterm>override</firstterm>
 207 a property implementation in a parent class or to provide
 208 the implementation of a property from an interface.
 209 </para>
 210 <note>
 211 <para>
 212 Internally, overriding is implemented by creating a property of type
 213 #GParamSpecOverride; generally operations that query the properties of
 214 the object class, such as g_object_class_find_property() or
 215 g_object_class_list_properties() will return the overridden
 216 property. However, in one case, the @construct_properties argument of
 217 the @constructor virtual function, the #GParamSpecOverride is passed
 218 instead, so that the @param_id field of the #GParamSpec will be
 219 correct.  For virtually all uses, this makes no difference. If you
 220 need to get the overridden property, you can call
 221 g_param_spec_get_redirect_target().
 222 </para>
 223 </note>
 224
 225 @oclass: a #GObjectClass
 226 @property_id: the new property ID
 227 @name: the name of a property registered in a parent class or
 228        in an interface of this class.
 229
 230
 231 <!-- ##### FUNCTION g_object_interface_install_property ##### -->
 232 <para>
 233 Add a property to an interface; this is only useful for interfaces
 234 that are added to GObject-derived types. Adding a property to an
 235 interface forces all objects classes with that interface to have a
 236 compatible property. The compatible property could be a newly
 237 created #GParamSpec, but normally
 238 g_object_class_override_property() will be used so that the object
 239 class only needs to provide an implementation and inherits the
 240 property description, default value, bounds, and so forth from the
 241 interface property.
 242 </para>
 243 <para>
 244 This function is meant to be called from the interface's default
 245 vtable initialization function (the @class_init member of
 246 #GTypeInfo.) It must not be called after after @class_init has
 247 been called for any object types implementing this interface.
 248 </para>
 249
 250 @g_iface: any interface vtable for the interface, or the default
 251  vtable for the interface.
 252 @pspec: the #GParamSpec for the new property
 253 @Since: 2.4
 254
 255
 256 <!-- ##### FUNCTION g_object_interface_find_property ##### -->
 257 <para>
 258 Find the #GParamSpec with the given name for an
 259 interface. Generally, the interface vtable passed in as @g_iface
 260 will be the default vtable from g_type_default_interface_ref(), or,
 261 if you know the interface has already been loaded,
 262 g_type_default_interface_peek().
 263 </para>
 264
 265 @g_iface: any interface vtable for the interface, or the default
 266   vtable for the interface
 267 @property_name: name of a property to lookup.
 268 @Returns: the #GParamSpec for the property of the
 269   interface with the name @property_name, or %NULL
 270   if no such property exists.
 271 @Since: 2.4
 272
 273
 274 <!-- ##### FUNCTION g_object_interface_list_properties ##### -->
 275 <para>
 276 Lists the properties of an interface.Generally, the interface
 277 vtable passed in as @g_iface will be the default vtable from
 278 g_type_default_interface_ref(), or, if you know the interface has
 279 already been loaded, g_type_default_interface_peek().
 280 </para>
 281
 282 @g_iface: any interface vtable for the interface, or the default
 283  vtable for the interface
 284 @n_properties_p: location to store number of properties returned.
 285 @Returns: a pointer to an array of pointers to #GParamSpec structures.
 286   The paramspecs are owned by GLib, but the array should
 287   be freed with g_free() when you are done with it.
 288 @Since: 2.4
 289
 290
 291 <!-- ##### FUNCTION g_object_new ##### -->
 292 <para>
 293 Creates a new instance of a #GObject subtype and sets its properties.
 294 </para>
 295 <para>
 296 Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
 297 which are not explicitly specified are set to their default values.
 298 </para>
 299
 300 @object_type: the type id of the #GObject subtype to instantiate
 301 @first_property_name: the name of the first property
 302 @Varargs: the value of the first property, followed optionally by more
 303      name/value pairs, followed by %NULL
 304 @Returns: a new instance of @object_type
 305
 306
 307 <!-- ##### FUNCTION g_object_newv ##### -->
 308 <para>
 309 Creates a new instance of a #GObject subtype and sets its properties.
 310 </para>
 311 <para>
 312 Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
 313 which are not explicitly specified are set to their default values.
 314 </para>
 315
 316 @object_type: the type id of the #GObject subtype to instantiate
 317 @n_parameters: the length of the @parameters array
 318 @parameters: an array of #GParameter
 319 @Returns: a new instance of @object_type
 320
 321
 322 <!-- ##### STRUCT GParameter ##### -->
 323 <para>
 324 The <structname>GParameter</structname> struct is an auxiliary structure used
 325 to hand parameter name/value pairs to g_object_newv().
 326 </para>
 327
 328 @name: the parameter name
 329 @value: the parameter value
 330
 331 <!-- ##### FUNCTION g_object_ref ##### -->
 332 <para>
 333 Increases the reference count of @object.
 334 </para>
 335
 336 @object: a #GObject
 337 @Returns: @object
 338
 339
 340 <!-- ##### FUNCTION g_object_unref ##### -->
 341 <para>
 342 Decreases the reference count if @object.
 343 When its reference count drops to 0, the object is finalized (i.e. its memory is freed).
 344 </para>
 345
 346 @object: a #GObject
 347
 348
 349 <!-- ##### USER_FUNCTION GWeakNotify ##### -->
 350 <para>
 351 A #GWeakNotify function can be added to an object as a callback that gets
 352 triggered when the object is finalized. Since the object is already being
 353 finalized when the #GWeakNotify is called, there's not much you could do
 354 with the object, apart from e.g. using its adress as hash-index or the like.
 355 </para>
 356
 357 @data: data that was provided when the weak reference was established
 358 @where_the_object_was: the object being finalized
 359
 360
 361 <!-- ##### FUNCTION g_object_weak_ref ##### -->
 362 <para>
 363 Adds a weak reference callback to an object. Weak references are used for
 364 notification when an object is finalized. They are called "weak references"
 365 because they allow you to safely hold a pointer to an object without calling
 366 g_object_ref() (g_object_ref() adds a strong reference, that is, forces the
 367 object to stay alive).
 368 </para>
 369
 370 @object: #GObject to reference weakly
 371 @notify: callback to invoke before the object is freed
 372 @data: extra data to pass to notify
 373
 374
 375 <!-- ##### FUNCTION g_object_weak_unref ##### -->
 376 <para>
 377 Removes a weak reference callback to an object.
 378 </para>
 379
 380 @object: #GObject to remove a weak reference from
 381 @notify: callback to search for
 382 @data: data to search for
 383
 384
 385 <!-- ##### FUNCTION g_object_add_weak_pointer ##### -->
 386 <para>
 387 Adds a weak reference from weak_pointer to @object to indicate that
 388 the pointer located at @weak_pointer_location is only valid during the
 389 lifetime of @object. When the @object is finalized, @weak_pointer will
 390 be set to %NULL.
 391 </para>
 392
 393 @object: The object that should be weak referenced.
 394 @weak_pointer_location: The memory address of a pointer.
 395
 396
 397 <!-- ##### FUNCTION g_object_remove_weak_pointer ##### -->
 398 <para>
 399 Removes a weak reference from @object that was previously added
 400 using g_object_add_weak_pointer(). The @weak_pointer_location has
 401 to match the one used with g_object_add_weak_pointer().
 402 </para>
 403
 404 @object: The object that is weak referenced.
 405 @weak_pointer_location: The memory address of a pointer.
 406
 407
 408 <!-- ##### FUNCTION g_object_connect ##### -->
 409 <para>
 410 A convenience function to connect multiple signals at once.
 411 </para>
 412 <para>
 413 The signal specs expected by this function have the form
 414 "modifier::signal_name", where modifier can be one of the following:
 415 <variablelist>
 416 <varlistentry>
 417 <term>signal</term>
 418 <listitem><para>
 419 equivalent to <literal>g_signal_connect_data (...)</literal>
 420 </para></listitem>
 421 </varlistentry>
 422 <varlistentry>
 423 <term>object_signal</term>
 424 <listitem><para>
 425 equivalent to <literal>g_signal_connect_object (...)</literal>
 426 </para></listitem>
 427 </varlistentry>
 428 <varlistentry>
 429 <term>swapped_signal</term>
 430 <listitem><para>
 431 equivalent to <literal>g_signal_connect_data (..., G_CONNECT_SWAPPED)</literal>
 432 </para></listitem>
 433 </varlistentry>
 434 <varlistentry>
 435 <term>swapped_object_signal</term>
 436 <listitem><para>
 437 equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED)</literal>
 438 </para></listitem>
 439 </varlistentry>
 440 <varlistentry>
 441 <term>signal_after</term>
 442 <listitem><para>
 443 equivalent to <literal>g_signal_connect_data (..., G_CONNECT_AFTER)</literal>
 444 </para></listitem>
 445 </varlistentry>
 446 <varlistentry>
 447 <term>object_signal_after</term>
 448 <listitem><para>
 449 equivalent to <literal>g_signal_connect_object (..., G_CONNECT_AFTER)</literal>
 450 </para></listitem>
 451 </varlistentry>
 452 <varlistentry>
 453 <term>swapped_signal_after</term>
 454 <listitem><para>
 455 equivalent to <literal>g_signal_connect_data (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal>
 456 </para></listitem>
 457 </varlistentry>
 458 <varlistentry>
 459 <term>swapped_object_signal_after</term>
 460 <listitem><para>
 461 equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal>
 462 </para></listitem>
 463 </varlistentry>
 464 </variablelist>
 465 </para>
 466 <informalexample>
 467 <programlisting>
 468   menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
 469                                                    "type", GTK_WINDOW_POPUP,
 470                                                    "child", menu,
 471                                                    NULL),
 472                                      "signal::event", gtk_menu_window_event, menu,
 473                                      "signal::size_request", gtk_menu_window_size_request, menu,
 474                                      "signal::destroy", gtk_widget_destroyed, &amp;menu-&gt;toplevel,
 475                                      NULL);
 476 </programlisting>
 477 </informalexample>
 478
 479 @object: a #GObject
 480 @signal_spec: the spec for the first signal
 481 @Varargs: #GCallback for the first signal, followed by data for the first signal,
 482           followed optionally by more signal spec/callback/data triples,
 483           followed by %NULL
 484 @Returns: @object
 485
 486
 487 <!-- ##### FUNCTION g_object_disconnect ##### -->
 488 <para>
 489 A convenience function to disconnect multiple signals at once.
 490 </para>
 491 <para>
 492 The signal specs expected by this function have the form "any_signal", which
 493 means to disconnect any signal with matching callback and data, or
 494 "any_signal::signal_name", which only disconnects the signal named "signal_name".
 495 </para>
 496
 497 @object: a #GObject
 498 @signal_spec: the spec for the first signal
 499 @Varargs: #GCallback for the first signal, followed by data for the first signal,
 500           followed optionally by more signal spec/callback/data triples,
 501           followed by %NULL
 502
 503
 504 <!-- ##### FUNCTION g_object_set ##### -->
 505 <para>
 506 Sets properties on an object.
 507 </para>
 508
 509 @object: a #GObject
 510 @first_property_name: name of the first property to set
 511 @Varargs: value for the first property, followed optionally by more
 512           name/value pairs, followed by %NULL
 513
 514
 515 <!-- ##### FUNCTION g_object_get ##### -->
 516 <para>
 517 Gets properties of an object.
 518 </para>
 519 <para>
 520 In general, a copy is made of the property contents and the caller is
 521 responsible for freeing the memory in the appropriate manner for the type,
 522 for instance by calling g_free() or g_object_unref().
 523 </para>
 524 <example>
 525 <title>Using g_object_get(<!-- -->)</title>
 526 <para>
 527 An example of using g_object_get() to get the contents
 528 of three properties - one of type #G_TYPE_INT,
 529 one of type #G_TYPE_STRING, and one of type #G_TYPE_OBJECT:
 530 </para>
 531 <programlisting>
 532  gint intval;
 533  gchar *strval;
 534  GObject *objval;
 535
 536  g_object_get (my_object,
 537                "intproperty", &amp;intval,
 538                "strproperty", &amp;strval,
 539                "objproperty", &amp;objval,
 540                NULL);
 541
 542  /* Do something with intval, strval, objval */
 543
 544  g_free (strval);
 545  g_object_unref (objval);
 546 </programlisting>
 547 </example>
 548
 549 @object: a #GObject
 550 @first_property_name: name of the first property to get
 551 @Varargs: return location for the first property, followed optionally by more
 552           name/return location pairs, followed by %NULL
 553
 554
 555 <!-- ##### FUNCTION g_object_notify ##### -->
 556 <para>
 557 Emits a "notify" signal for the property @property_name on @object.
 558 </para>
 559
 560 @object: a #GObject
 561 @property_name: the name of a property installed on the class of @object.
 562
 563
 564 <!-- ##### FUNCTION g_object_freeze_notify ##### -->
 565 <para>
 566 Stops emission of "notify" signals on @object. The signals are
 567 queued until g_object_thaw_notify() is called on @object.
 568 </para>
 569 <para>
 570 This is necessary for accessors that modify multiple properties to prevent
 571 premature notification while the object is still being modified.
 572 </para>
 573
 574 @object: a #GObject
 575
 576
 577 <!-- ##### FUNCTION g_object_thaw_notify ##### -->
 578 <para>
 579 Reverts the effect of a previous call to g_object_freeze_notify().
 580 This causes all queued "notify" signals on @object to be emitted.
 581 </para>
 582
 583 @object: a #GObject
 584
 585
 586 <!-- ##### FUNCTION g_object_get_data ##### -->
 587 <para>
 588 Gets a named field from the objects table of associations (see g_object_set_data()).
 589 </para>
 590
 591 @object: #GObject containing the associations
 592 @key: name of the key for that association
 593 @Returns: the data if found, or %NULL if no such data exists.
 594
 595
 596 <!-- ##### FUNCTION g_object_set_data ##### -->
 597 <para>
 598 Each object carries around a table of associations from
 599 strings to pointers.  This function lets you set an association.
 600 </para>
 601 <para>
 602 If the object already had an association with that name,
 603 the old association will be destroyed.
 604 </para>
 605
 606 @object: #GObject containing the associations.
 607 @key: name of the key
 608 @data: data to associate with that key
 609
 610
 611 <!-- ##### FUNCTION g_object_set_data_full ##### -->
 612 <para>
 613 Like g_object_set_data() except it adds notification
 614 for when the association is destroyed, either by setting it
 615 to a different value or when the object is destroyed.
 616 </para>
 617
 618 @object: #GObject containing the associations
 619 @key: name of the key
 620 @data: data to associate with that key
 621 @destroy: function to call when the association is destroyed
 622
 623
 624 <!-- ##### FUNCTION g_object_steal_data ##### -->
 625 <para>
 626 Remove a specified datum from the object's data associations,
 627 without invoking the association's destroy handler.
 628 </para>
 629
 630 @object: #GObject containing the associations
 631 @key: name of the key
 632 @Returns: the data if found, or %NULL if no such data exists.
 633
 634
 635 <!-- ##### FUNCTION g_object_get_qdata ##### -->
 636 <para>
 637 This function gets back user data pointers stored via
 638 g_object_set_qdata().
 639 </para>
 640
 641 @object:  The GObject to get a stored user data pointer from
 642 @quark:   A #GQuark, naming the user data pointer
 643 @Returns: The user data pointer set, or %NULL
 644
 645
 646 <!-- ##### FUNCTION g_object_set_qdata ##### -->
 647 <para>
 648 This sets an opaque, named pointer on an object.
 649 The name is specified through a #GQuark (retrived e.g. via
 650 g_quark_from_static_string()), and the pointer
 651 can be gotten back from the @object with g_object_get_qdata()
 652 until the @object is finalized.
 653 Setting a previously set user data pointer, overrides (frees)
 654 the old pointer set, using #NULL as pointer essentially
 655 removes the data stored.
 656 </para>
 657
 658 @object: The GObject to set store a user data pointer
 659 @quark:  A #GQuark, naming the user data pointer
 660 @data:   An opaque user data pointer
 661
 662
 663 <!-- ##### FUNCTION g_object_set_qdata_full ##### -->
 664 <para>
 665 This function works like g_object_set_qdata(), but in addition,
 666 a void (*destroy) (gpointer) function may be specified which is
 667 called with @data as argument when the @object is finalized, or
 668 the data is being overwritten by a call to g_object_set_qdata()
 669 with the same @quark.
 670 </para>
 671
 672 @object:  The GObject to set store a user data pointer
 673 @quark:   A #GQuark, naming the user data pointer
 674 @data:    An opaque user data pointer
 675 @destroy: Function to invoke with @data as argument, when @data needs to be freed
 676
 677
 678 <!-- ##### FUNCTION g_object_steal_qdata ##### -->
 679 <para>
 680 This function gets back user data pointers stored via
 681 g_object_set_qdata() and removes the @data from object
 682 without invoking it's destroy() function (if any was
 683 set).
 684 Usually, calling this function is only required to update
 685 user data pointers with a destroy notifier, for example:
 686 <programlisting>
 687 void
 688 object_add_to_user_list (GObject     *object,
 689                          const gchar *new_string)
 690 {
 691   /* the quark, naming the object data */
 692   GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
 693   /* retrive the old string list */
 694   GList *list = g_object_steal_qdata (object, quark_string_list);
 695
 696   /* prepend new string */
 697   list = g_list_prepend (list, g_strdup (new_string));
 698   /* this changed 'list', so we need to set it again */
 699   g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
 700 }
 701 static void
 702 free_string_list (gpointer data)
 703 {
 704   GList *node, *list = data;
 705
 706   for (node = list; node; node = node->next)
 707     g_free (node->data);
 708   g_list_free (list);
 709 }
 710 </programlisting>
 711 Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata()
 712 would have left the destroy function set, and thus the partial string list would
 713 have been freed upon g_object_set_qdata_full().
 714 </para>
 715
 716 @object:  The GObject to get a stored user data pointer from
 717 @quark:   A #GQuark, naming the user data pointer
 718 @Returns: The user data pointer set, or %NULL
 719
 720
 721 <!-- ##### FUNCTION g_object_set_property ##### -->
 722 <para>
 723 Sets a property on an object.
 724 </para>
 725
 726 @object: a #GObject
 727 @property_name: the name of the property to set
 728 @value: the value
 729
 730
 731 <!-- ##### FUNCTION g_object_get_property ##### -->
 732 <para>
 733 Gets a property of an object.
 734 </para>
 735 <para>
 736 In general, a copy is made of the property contents and the caller is
 737 responsible for freeing the memory in the appropriate manner for the type,
 738 for instance by calling g_free() or g_object_unref().
 739 </para>
 740 <para>
 741 See g_object_get().
 742 </para>
 743
 744 @object: a #GObject
 745 @property_name: the name of the property to get
 746 @value: return location for the property value
 747
 748
 749 <!-- ##### FUNCTION g_object_new_valist ##### -->
 750 <para>
 751 Creates a new instance of a #GObject subtype and sets its properties.
 752 </para>
 753 <para>
 754 Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
 755 which are not explicitly specified are set to their default values.
 756 </para>
 757
 758 @object_type: the type id of the #GObject subtype to instantiate
 759 @first_property_name: the name of the first property
 760 @var_args: the value of the first property, followed optionally by more
 761      name/value pairs, followed by %NULL
 762 @Returns: a new instance of @object_type
 763
 764
 765 <!-- ##### FUNCTION g_object_set_valist ##### -->
 766 <para>
 767 Sets properties on an object.
 768 </para>
 769
 770 @object: a #GObject
 771 @first_property_name: name of the first property to set
 772 @var_args: value for the first property, followed optionally by more
 773            name/value pairs, followed by %NULL
 774
 775
 776 <!-- ##### FUNCTION g_object_get_valist ##### -->
 777 <para>
 778 Gets properties of an object.
 779 </para>
 780 <para>
 781 In general, a copy is made of the property contents and the caller is
 782 responsible for freeing the memory in the appropriate manner for the type,
 783 for instance by calling g_free() or g_object_unref().
 784 </para>
 785 <para>
 786 See g_object_get().
 787 </para>
 788
 789 @object: a #GObject
 790 @first_property_name: name of the first property to get
 791 @var_args: return location for the first property, followed optionally by more
 792            name/return location pairs, followed by %NULL
 793
 794
 795 <!-- ##### FUNCTION g_object_watch_closure ##### -->
 796 <para>
 797 This function essentially limits the life time of the @closure
 798 to the life time of the object. That is, when the object is finalized,
 799 the @closure is invalidated by calling g_closure_invalidate() on it,
 800 in order to prevent invocations of the closure with a finalized
 801 (nonexisting) object. Also, g_object_ref() and g_object_unref() are added
 802 as marshal guards to the @closure, to ensure that an extra reference
 803 count is held on @object during invocation of the @closure.
 804 Usually, this function will be called on closures that use this @object
 805 as closure data.
 806 </para>
 807
 808 @object:  GObject restricting lifetime of @closure
 809 @closure: GClosure to watch
 810
 811
 812 <!-- ##### FUNCTION g_object_run_dispose ##### -->
 813 <para>
 814 Releases all references to other objects. This can be used to break
 815 reference cycles.
 816 </para>
 817 <note><para>
 818 This functions should only be called from object system implementations.
 819 </para></note>
 820
 821 @object: a #GObject
 822
 823
 824 <!-- ##### MACRO G_OBJECT_WARN_INVALID_PROPERTY_ID ##### -->
 825 <para>
 826 This macros should be used to emit a standard warning about unexpected
 827 properties in set_property() and get_property() implementations.
 828 </para>
 829
 830 @object: the #GObject on which set_property() or get_property() was called
 831 @property_id: the numeric id of the property
 832 @pspec: the #GParamSpec of the property
 833
 834
 835 <!-- ##### SIGNAL GObject::notify ##### -->
 836 <para>
 837 The notify signal is emitted on an object when one of its properties
 838 has been changed. Note that getting this signal doesn't guarantee that the
 839 value of the property has actually changed, it may also be emitted when
 840 the setter for the property is called to reinstate the previous value.
 841 </para>
 842
 843 @gobject: the object which received the signal.
 844 @pspec: the #GParamSpec of the property which changed
 845