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 GObject is the fundamental type providing the common attributes and methods
  10 for all object types in GTK+, Pango and other libraries based on GObject.
  11 The GObject class provides methods for object construction and destruction,
  12 property access methods, and signal support.
  13 Signals are described in detail in <xref linkend="gobject-Signals"/>.
  14 </para>
  15 <para id="floating-ref">
  16 #GInitiallyUnowned is derived from #GObject. The only difference between
  17 the two is that the initial reference of a #GInitiallyUnowned is flagged
  18 as a <firstterm>floating</firstterm> reference.
  19 This means that it is not specifically claimed to be "owned" by
  20 any code portion. The main motivation for providing floating references is
  21 C convenience. In particular, it allows code to be written as:
  22 <example><programlisting>
  23   container = create_container();
  24   container_add_child (container, create_child());
  25 </programlisting></example>
  26 If <function>container_add_child()</function> will g_object_ref_sink() the
  27 passed in child, no reference of the newly created child is leaked.
  28 Without floating references, <function>container_add_child()</function>
  29 can only g_object_ref() the new child, so to implement this code without
  30 reference leaks, it would have to be written as:
  31 <example><programlisting>
  32   Child *child;
  33   container = create_container();
  34   child = create_child();
  35   container_add_child (container, child);
  36   g_object_unref (child);
  37 </programlisting></example>
  38 The floating reference can be converted into
  39 an ordinary reference by calling g_object_ref_sink().
  40 For already sunken objects (objects that don't have a floating reference
  41 anymore), g_object_ref_sink() is equivalent to g_object_ref() and returns
  42 a new reference.
  43 Since floating references are useful almost exclusively for C convenience,
  44 language bindings that provide automated reference and memory ownership
  45 maintenance (such as smart pointers or garbage collection) therefore don't
  46 need to expose floating references in their API.
  47 </para>
  48 <para>
  49 Some object implementations may need to save an objects floating state
  50 across certain code portions (an example is #GtkMenu), to achive this, the
  51 following sequence can be used:
  52 </para>
  53
  54 <example><programlisting>
  55   /* save floating state */
  56   gboolean was_floating = g_object_is_floating (object);
  57   g_object_ref_sink (object);
  58   /* protected code portion */
  59   ...;
  60   /* restore floating state */
  61   if (was_floating)
  62     g_object_force_floating (object);
  63   g_obejct_unref (object); /* release previously acquired reference */
  64 </programlisting></example>
  65
  66 <!-- ##### SECTION See_Also ##### -->
  67 <para>
  68 #GParamSpecObject, g_param_spec_object()
  69 </para>
  70
  71 <!-- ##### SECTION Stability_Level ##### -->
  72
  73
  74 <!-- ##### STRUCT GObject ##### -->
  75 <para>
  76 All the fields in the <structname>GObject</structname> structure are private
  77 to the #GObject implementation and should never be accessed directly.
  78 </para>
  79
  80
  81 <!-- ##### SIGNAL GObject::notify ##### -->
  82 <para>
  83 The notify signal is emitted on an object when one of its properties
  84 has been changed. Note that getting this signal doesn't guarantee that the
  85 value of the property has actually changed, it may also be emitted when
  86 the setter for the property is called to reinstate the previous value.
  87 </para>
  88
  89 @pspec: the #GParamSpec of the property which changed
  90 @gobject: the object which received the signal.
  91
  92 <!-- ##### STRUCT GObjectClass ##### -->
  93 <para>
  94 The class structure for the <structname>GObject</structname> type.
  95 </para>
  96 <example>
  97 <title>Implementing singletons using a constructor</title>
  98 <programlisting>
  99 static MySingleton *the_singleton = NULL;
 100
 101 static GObject*
 102 my_singleton_constructor (GType                  type,
 103                           guint                  n_construct_params,
 104                           GObjectConstructParam *construct_params)
 105 {
 106   GObject *object;
 107
 108   if (!the_singleton)
 109     {
 110       object = G_OBJECT_CLASS (parent_class)->constructor (type,
 111                                                            n_construct_params,
 112                                                            construct_params);
 113       the_singleton = MY_SINGLETON (object);
 114     }
 115   else
 116     object = g_object_ref (G_OBJECT (the_singleton));
 117
 118   return object;
 119 }
 120 </programlisting></example>
 121
 122 @g_type_class: the parent class
 123 @constructor:  the @constructor function is called by g_object_new () to
 124   complete the object initialization after all the construction properties are
 125   set. The first thing a @constructor implementation must do is chain up to the
 126   @constructor of the parent class. Overriding @constructor should be rarely
 127   needed, e.g. to handle construct properties, or to implement singletons.
 128 @set_property: the generic setter for all properties of this type. Should be
 129   overridden for every type with properties. Implementations of @set_property
 130   don't need to emit property change notification explicitly, this is handled
 131   by the type system.
 132 @get_property: the generic getter for all properties of this type. Should be
 133   overridden for every type with properties.
 134 @dispose: the @dispose function is supposed to drop all references to other
 135   objects, but keep the instance otherwise intact, so that client method
 136   invocations still work. It may be run multiple times (due to reference
 137   loops). Before returning, @dispose should chain up to the @dispose method
 138   of the parent class.
 139 @finalize: instance finalization function, should finish the finalization of
 140   the instance begun in @dispose and chain up to the @finalize method of the
 141   parent class.
 142 @dispatch_properties_changed: emits property change notification for a bunch
 143   of properties. Overriding @dispatch_properties_changed should be rarely
 144   needed.
 145 @notify: the class closure for the notify signal
 146
 147 <!-- ##### STRUCT GObjectConstructParam ##### -->
 148 <para>
 149 The <structname>GObjectConstructParam</structname> struct is an auxiliary
 150 structure used to hand #GParamSpec/#GValue pairs to the @constructor of
 151 a #GObjectClass.
 152 </para>
 153
 154 @pspec: the #GParamSpec of the construct parameter
 155 @value: the value to set the parameter to
 156
 157 <!-- ##### USER_FUNCTION GObjectGetPropertyFunc ##### -->
 158 <para>
 159 The type of the @get_property function of #GObjectClass.
 160 </para>
 161
 162 @object: a #GObject
 163 @property_id: the numeric id under which the property was registered with
 164    g_object_class_install_property().
 165 @value: a #GValue to return the property value in
 166 @pspec: the #GParamSpec describing the property
 167
 168
 169 <!-- ##### USER_FUNCTION GObjectSetPropertyFunc ##### -->
 170 <para>
 171 The type of the @set_property function of #GObjectClass.
 172 </para>
 173
 174 @object: a #GObject
 175 @property_id: the numeric id under which the property was registered with
 176    g_object_class_install_property().
 177 @value: the new value for the property
 178 @pspec: the #GParamSpec describing the property
 179
 180
 181 <!-- ##### USER_FUNCTION GObjectFinalizeFunc ##### -->
 182 <para>
 183 The type of the @finalize function of #GObjectClass.
 184 </para>
 185
 186 @object: the #GObject being finalized
 187
 188
 189 <!-- ##### MACRO G_TYPE_IS_OBJECT ##### -->
 190 <para>
 191 Returns a boolean value of %FALSE or %TRUE indicating whether
 192 the passed in type id is a %G_TYPE_OBJECT or derived from it.
 193 </para>
 194
 195 @type: Type id to check for is a %G_TYPE_OBJECT relationship.
 196 @Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT.
 197
 198
 199 <!-- ##### MACRO G_OBJECT ##### -->
 200 <para>
 201 Casts a #GObject or derived pointer into a (GObject*) pointer.
 202 Depending on the current debugging level, this function may invoke
 203 certain runtime checks to identify invalid casts.
 204 </para>
 205
 206 @object: Object which is subject to casting.
 207
 208
 209 <!-- ##### MACRO G_IS_OBJECT ##### -->
 210 <para>
 211 Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
 212 </para>
 213
 214 @object: Instance to check for being a %G_TYPE_OBJECT.
 215
 216
 217 <!-- ##### MACRO G_OBJECT_CLASS ##### -->
 218 <para>
 219 Casts a derived #GObjectClass structure into a #GObjectClass structure.
 220 </para>
 221
 222 @class: a valid #GObjectClass
 223
 224
 225 <!-- ##### MACRO G_IS_OBJECT_CLASS ##### -->
 226 <para>
 227 Checks whether @class "is a" valid #GObjectClass structure of type
 228 %G_TYPE_OBJECT or derived.
 229 </para>
 230
 231 @class: a #GObjectClass
 232
 233
 234 <!-- ##### MACRO G_OBJECT_GET_CLASS ##### -->
 235 <para>
 236 Returns the class structure associated to a #GObject instance.
 237 </para>
 238
 239 @object: a #GObject instance.
 240
 241
 242 <!-- ##### MACRO G_OBJECT_TYPE ##### -->
 243 <para>
 244 Return the type id of an object.
 245 </para>
 246
 247 @object: Object to return the type id for.
 248 @Returns: Type id of @object.
 249
 250
 251 <!-- ##### MACRO G_OBJECT_TYPE_NAME ##### -->
 252 <para>
 253 Returns the name of an object's type.
 254 </para>
 255
 256 @object: Object to return the type name for.
 257 @Returns: Type name of @object. The string is owned by the type system and
 258 should not be freed.
 259
 260
 261 <!-- ##### MACRO G_OBJECT_CLASS_TYPE ##### -->
 262 <para>
 263 Return the type id of a class structure.
 264 </para>
 265
 266 @class: a valid #GObjectClass
 267 @Returns: Type id of @class.
 268
 269
 270 <!-- ##### MACRO G_OBJECT_CLASS_NAME ##### -->
 271 <para>
 272 Return the name of a class structure's type.
 273 </para>
 274
 275 @class: a valid #GObjectClass
 276 @Returns: Type name of @class. The string is owned by the type system and
 277 should not be freed.
 278
 279
 280 <!-- ##### FUNCTION g_object_class_install_property ##### -->
 281 <para>
 282 Installs a new property. This is usually done in the class initializer.
 283 </para>
 284
 285 @oclass: a #GObjectClass
 286 @property_id: the id for the new property
 287 @pspec: the #GParamSpec for the new property
 288
 289
 290 <!-- ##### FUNCTION g_object_class_find_property ##### -->
 291 <para>
 292 Looks up the #GParamSpec for a property of a class.
 293 </para>
 294
 295 @oclass: a #GObjectClass
 296 @property_name: the name of the property to look up
 297 @Returns: the #GParamSpec for the property, or %NULL if the class doesn't have
 298 a property of that name
 299
 300
 301 <!-- ##### FUNCTION g_object_class_list_properties ##### -->
 302 <para>
 303 Returns an array of #GParamSpec* for all properties of a class.
 304 </para>
 305
 306 @oclass: a #GObjectClass
 307 @n_properties: return location for the length of the returned array
 308 @Returns: an array of #GParamSpec* which should be freed after use
 309
 310
 311 <!-- ##### FUNCTION g_object_class_override_property ##### -->
 312 <para>
 313 Registers @property_id as referring to a property with the
 314 name @name in a parent class or in an interface implemented
 315 by @oclass. This allows this class to <firstterm>override</firstterm>
 316 a property implementation in a parent class or to provide
 317 the implementation of a property from an interface.
 318 </para>
 319 <note>
 320 <para>
 321 Internally, overriding is implemented by creating a property of type
 322 #GParamSpecOverride; generally operations that query the properties of
 323 the object class, such as g_object_class_find_property() or
 324 g_object_class_list_properties() will return the overridden
 325 property. However, in one case, the @construct_properties argument of
 326 the @constructor virtual function, the #GParamSpecOverride is passed
 327 instead, so that the @param_id field of the #GParamSpec will be
 328 correct.  For virtually all uses, this makes no difference. If you
 329 need to get the overridden property, you can call
 330 g_param_spec_get_redirect_target().
 331 </para>
 332 </note>
 333
 334 @oclass: a #GObjectClass
 335 @property_id: the new property ID
 336 @name: the name of a property registered in a parent class or
 337        in an interface of this class.
 338
 339
 340 <!-- ##### FUNCTION g_object_interface_install_property ##### -->
 341 <para>
 342 Add a property to an interface; this is only useful for interfaces
 343 that are added to GObject-derived types. Adding a property to an
 344 interface forces all objects classes with that interface to have a
 345 compatible property. The compatible property could be a newly
 346 created #GParamSpec, but normally
 347 g_object_class_override_property() will be used so that the object
 348 class only needs to provide an implementation and inherits the
 349 property description, default value, bounds, and so forth from the
 350 interface property.
 351 </para>
 352 <para>
 353 This function is meant to be called from the interface's default
 354 vtable initialization function (the @class_init member of
 355 #GTypeInfo.) It must not be called after after @class_init has
 356 been called for any object types implementing this interface.
 357 </para>
 358
 359 @g_iface: any interface vtable for the interface, or the default
 360  vtable for the interface.
 361 @pspec: the #GParamSpec for the new property
 362 @Since: 2.4
 363
 364
 365 <!-- ##### FUNCTION g_object_interface_find_property ##### -->
 366 <para>
 367 Find the #GParamSpec with the given name for an
 368 interface. Generally, the interface vtable passed in as @g_iface
 369 will be the default vtable from g_type_default_interface_ref(), or,
 370 if you know the interface has already been loaded,
 371 g_type_default_interface_peek().
 372 </para>
 373
 374 @g_iface: any interface vtable for the interface, or the default
 375   vtable for the interface
 376 @property_name: name of a property to lookup.
 377 @Returns: the #GParamSpec for the property of the
 378   interface with the name @property_name, or %NULL
 379   if no such property exists.
 380 @Since: 2.4
 381
 382
 383 <!-- ##### FUNCTION g_object_interface_list_properties ##### -->
 384 <para>
 385 Lists the properties of an interface.Generally, the interface
 386 vtable passed in as @g_iface will be the default vtable from
 387 g_type_default_interface_ref(), or, if you know the interface has
 388 already been loaded, g_type_default_interface_peek().
 389 </para>
 390
 391 @g_iface: any interface vtable for the interface, or the default
 392  vtable for the interface
 393 @n_properties_p: location to store number of properties returned.
 394 @Returns: a pointer to an array of pointers to #GParamSpec structures.
 395   The paramspecs are owned by GLib, but the array should
 396   be freed with g_free() when you are done with it.
 397 @Since: 2.4
 398
 399
 400 <!-- ##### FUNCTION g_object_new ##### -->
 401 <para>
 402 Creates a new instance of a #GObject subtype and sets its properties.
 403 </para>
 404 <para>
 405 Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
 406 which are not explicitly specified are set to their default values.
 407 </para>
 408
 409 @object_type: the type id of the #GObject subtype to instantiate
 410 @first_property_name: the name of the first property
 411 @Varargs: the value of the first property, followed optionally by more
 412      name/value pairs, followed by %NULL
 413 @Returns: a new instance of @object_type
 414
 415
 416 <!-- ##### FUNCTION g_object_newv ##### -->
 417 <para>
 418 Creates a new instance of a #GObject subtype and sets its properties.
 419 </para>
 420 <para>
 421 Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
 422 which are not explicitly specified are set to their default values.
 423 </para>
 424
 425 @object_type: the type id of the #GObject subtype to instantiate
 426 @n_parameters: the length of the @parameters array
 427 @parameters: an array of #GParameter
 428 @Returns: a new instance of @object_type
 429
 430
 431 <!-- ##### STRUCT GParameter ##### -->
 432 <para>
 433 The <structname>GParameter</structname> struct is an auxiliary structure used
 434 to hand parameter name/value pairs to g_object_newv().
 435 </para>
 436
 437 @name: the parameter name
 438 @value: the parameter value
 439
 440 <!-- ##### FUNCTION g_object_ref ##### -->
 441 <para>
 442 Increases the reference count of @object.
 443 </para>
 444
 445 @object: a #GObject
 446 @Returns: the same @object
 447
 448
 449 <!-- ##### FUNCTION g_object_unref ##### -->
 450 <para>
 451 Decreases the reference count of @object.
 452 When its reference count drops to 0, the object is finalized
 453 (i.e. its memory is freed).
 454 </para>
 455
 456 @object: a #GObject
 457
 458
 459 <!-- ##### FUNCTION g_object_ref_sink ##### -->
 460 <para>
 461 Increase the reference count of @object, and possibly remove the
 462 <link linkend="floating-ref">floating</link> reference, if @object
 463 has a floating reference.
 464 </para>
 465 <para>
 466 In other words, if the object is floating, then this call "assumes
 467 ownership" of the floating reference, converting it to a normal reference
 468 by clearing the floating flag while leaving the reference count unchanged.
 469 If the object is not floating, then this call adds a new normal reference
 470 increasing the reference count by one.
 471 </para>
 472
 473 @object: a #GObject
 474 @Returns: @object
 475 @Since: 2.10
 476
 477
 478 <!-- ##### TYPEDEF GInitiallyUnowned ##### -->
 479 <para>
 480 All the fields in the <structname>GInitiallyUnowned</structname> structure
 481 are private to the #GInitiallyUnowned implementation and should never be
 482 accessed directly.
 483 </para>
 484
 485
 486 <!-- ##### TYPEDEF GInitiallyUnownedClass ##### -->
 487 <para>
 488 The class structure for the <structname>GInitiallyUnowned</structname> type.
 489 </para>
 490
 491
 492 <!-- ##### MACRO G_TYPE_INITIALLY_UNOWNED ##### -->
 493 <para>
 494 The type for #GInitiallyUnowned.
 495 </para>
 496
 497
 498
 499 <!-- ##### FUNCTION g_object_is_floating ##### -->
 500 <para>
 501 Checks wether @object has a <link linkend="floating-ref">floating</link>
 502 reference.
 503 </para>
 504
 505 @object: a #GObject
 506 @Returns: %TRUE if @object has a floating reference
 507 @Since: 2.10
 508
 509
 510 <!-- ##### FUNCTION g_object_force_floating ##### -->
 511 <para>
 512 This function is intended for #GObject implementations to re-enforce a
 513 <link linkend="floating-ref">floating</link> object reference.
 514 Doing this is seldomly required, all
 515 #GInitiallyUnowned<!-- -->s are created with a floating reference which
 516 usually just needs to be sunken by calling g_object_ref_sink().
 517 </para>
 518
 519 @object: a #GObject
 520 @Since: 2.10
 521
 522
 523 <!-- ##### USER_FUNCTION GWeakNotify ##### -->
 524 <para>
 525 A #GWeakNotify function can be added to an object as a callback that gets
 526 triggered when the object is finalized. Since the object is already being
 527 finalized when the #GWeakNotify is called, there's not much you could do
 528 with the object, apart from e.g. using its adress as hash-index or the like.
 529 </para>
 530
 531 @data: data that was provided when the weak reference was established
 532 @where_the_object_was: the object being finalized
 533
 534
 535 <!-- ##### FUNCTION g_object_weak_ref ##### -->
 536 <para>
 537 Adds a weak reference callback to an object. Weak references are used for
 538 notification when an object is finalized. They are called "weak references"
 539 because they allow you to safely hold a pointer to an object without calling
 540 g_object_ref() (g_object_ref() adds a strong reference, that is, forces the
 541 object to stay alive).
 542 </para>
 543
 544 @object: #GObject to reference weakly
 545 @notify: callback to invoke before the object is freed
 546 @data: extra data to pass to notify
 547
 548
 549 <!-- ##### FUNCTION g_object_weak_unref ##### -->
 550 <para>
 551 Removes a weak reference callback to an object.
 552 </para>
 553
 554 @object: #GObject to remove a weak reference from
 555 @notify: callback to search for
 556 @data: data to search for
 557
 558
 559 <!-- ##### FUNCTION g_object_add_weak_pointer ##### -->
 560 <para>
 561 Adds a weak reference from weak_pointer to @object to indicate that
 562 the pointer located at @weak_pointer_location is only valid during the
 563 lifetime of @object. When the @object is finalized, @weak_pointer will
 564 be set to %NULL.
 565 </para>
 566
 567 @object: The object that should be weak referenced.
 568 @weak_pointer_location: The memory address of a pointer.
 569
 570
 571 <!-- ##### FUNCTION g_object_remove_weak_pointer ##### -->
 572 <para>
 573 Removes a weak reference from @object that was previously added
 574 using g_object_add_weak_pointer(). The @weak_pointer_location has
 575 to match the one used with g_object_add_weak_pointer().
 576 </para>
 577
 578 @object: The object that is weak referenced.
 579 @weak_pointer_location: The memory address of a pointer.
 580
 581
 582 <!-- ##### USER_FUNCTION GToggleNotify ##### -->
 583 <para>
 584 A callback function used for notification when the state
 585 of a toggle reference changes. See g_object_add_toggle_ref().
 586 </para>
 587
 588 @data: Callback data passed to g_object_add_toggle_ref()
 589 @object: The object on which g_object_add_toggle_ref() was called.
 590 @is_last_ref: %TRUE if the toggle reference is now the
 591   last reference to the object. %FALSE if the toggle
 592   reference was the last reference and there are now other
 593   references.
 594
 595
 596 <!-- ##### FUNCTION g_object_add_toggle_ref ##### -->
 597 <para>
 598 Increases the reference count of the object by one and sets a
 599 callback to be called when all other references to the object are
 600 dropped, or when this is already the last reference to the object
 601 and another reference is established.
 602 </para>
 603 <para>
 604 This functionality is intended for binding @object to a proxy
 605 object managed by another memory manager. This is done with two
 606 paired references: the strong reference added by
 607 g_object_add_toggle_ref() and a reverse reference to the proxy
 608 object which is either a strong reference or weak reference.
 609 </para>
 610 <para>
 611 The setup is that when there are no other references to @object,
 612 only a weak reference is held in the reverse direction from @object
 613 to the proxy object, but when there are other references held to
 614 @object, a strong reference is held. The @notify callback is called
 615 when the reference from @object to the proxy object should be
 616 <firstterm>toggled</firstterm> from strong to weak (@is_last_ref
 617 true) or weak to strong (@is_last_ref false).
 618 </para>
 619 <para>
 620 Since a (normal) reference must be held to the object before
 621 calling g_object_toggle_ref(), the initial state of the reverse
 622 link is always strong.
 623 </para>
 624 <para>
 625 Multiple toggle references may be added to the same gobject,
 626 however if there are multiple toggle references to an object, none
 627 of them will ever be notified until all but one are removed.  For
 628 this reason, you should only ever use a toggle reference if there
 629 is important state in the proxy object.
 630 </para>
 631
 632 @object: a #GObject
 633 @notify: a function to call when this reference is the
 634   last reference to the object, or is no longer
 635   the last reference.
 636 @data: data to pass to @notify
 637 @Since: 2.8
 638
 639
 640 <!-- ##### FUNCTION g_object_remove_toggle_ref ##### -->
 641 <para>
 642 Removes a reference added with g_object_add_toggle_ref(). The
 643 reference count of the object is decreased by one.
 644 </para>
 645
 646 @object: a #GObject
 647 @notify: a function to call when this reference is the
 648   last reference to the object, or is no longer
 649   the last reference.
 650 @data: data to pass to @notify
 651 @Since: 2.8
 652
 653
 654 <!-- ##### FUNCTION g_object_connect ##### -->
 655 <para>
 656 A convenience function to connect multiple signals at once.
 657 </para>
 658 <para>
 659 The signal specs expected by this function have the form
 660 "modifier::signal_name", where modifier can be one of the following:
 661 <variablelist>
 662 <varlistentry>
 663 <term>signal</term>
 664 <listitem><para>
 665 equivalent to <literal>g_signal_connect_data (...)</literal>
 666 </para></listitem>
 667 </varlistentry>
 668 <varlistentry>
 669 <term>object_signal</term>
 670 <term>object-signal</term>
 671 <listitem><para>
 672 equivalent to <literal>g_signal_connect_object (...)</literal>
 673 </para></listitem>
 674 </varlistentry>
 675 <varlistentry>
 676 <term>swapped_signal</term>
 677 <term>swapped-signal</term>
 678 <listitem><para>
 679 equivalent to <literal>g_signal_connect_data (..., G_CONNECT_SWAPPED)</literal>
 680 </para></listitem>
 681 </varlistentry>
 682 <varlistentry>
 683 <term>swapped_object_signal</term>
 684 <term>swapped-object-signal</term>
 685 <listitem><para>
 686 equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED)</literal>
 687 </para></listitem>
 688 </varlistentry>
 689 <varlistentry>
 690 <term>signal_after</term>
 691 <term>signal-after</term>
 692 <listitem><para>
 693 equivalent to <literal>g_signal_connect_data (..., G_CONNECT_AFTER)</literal>
 694 </para></listitem>
 695 </varlistentry>
 696 <varlistentry>
 697 <term>object_signal_after</term>
 698 <term>object-signal-after</term>
 699 <listitem><para>
 700 equivalent to <literal>g_signal_connect_object (..., G_CONNECT_AFTER)</literal>
 701 </para></listitem>
 702 </varlistentry>
 703 <varlistentry>
 704 <term>swapped_signal_after</term>
 705 <term>swapped-signal-after</term>
 706 <listitem><para>
 707 equivalent to <literal>g_signal_connect_data (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal>
 708 </para></listitem>
 709 </varlistentry>
 710 <varlistentry>
 711 <term>swapped_object_signal_after</term>
 712 <term>swapped-object-signal-after</term>
 713 <listitem><para>
 714 equivalent to <literal>g_signal_connect_object (..., G_CONNECT_SWAPPED | G_CONNECT_AFTER)</literal>
 715 </para></listitem>
 716 </varlistentry>
 717 </variablelist>
 718 </para>
 719 <informalexample>
 720 <programlisting>
 721   menu->toplevel = g_object_connect (g_object_new (GTK_TYPE_WINDOW,
 722                                                    "type", GTK_WINDOW_POPUP,
 723                                                    "child", menu,
 724                                                    NULL),
 725                                      "signal::event", gtk_menu_window_event, menu,
 726                                      "signal::size_request", gtk_menu_window_size_request, menu,
 727                                      "signal::destroy", gtk_widget_destroyed, &amp;menu-&gt;toplevel,
 728                                      NULL);
 729 </programlisting>
 730 </informalexample>
 731
 732 @object: a #GObject
 733 @signal_spec: the spec for the first signal
 734 @Varargs: #GCallback for the first signal, followed by data for the first signal,
 735           followed optionally by more signal spec/callback/data triples,
 736           followed by %NULL
 737 @Returns: @object
 738
 739
 740 <!-- ##### FUNCTION g_object_disconnect ##### -->
 741 <para>
 742 A convenience function to disconnect multiple signals at once.
 743 </para>
 744 <para>
 745 The signal specs expected by this function have the form "any_signal", which
 746 means to disconnect any signal with matching callback and data, or
 747 "any_signal::signal_name", which only disconnects the signal named "signal_name".
 748 </para>
 749
 750 @object: a #GObject
 751 @signal_spec: the spec for the first signal
 752 @Varargs: #GCallback for the first signal, followed by data for the first signal,
 753           followed optionally by more signal spec/callback/data triples,
 754           followed by %NULL
 755
 756
 757 <!-- ##### FUNCTION g_object_set ##### -->
 758 <para>
 759 Sets properties on an object.
 760 </para>
 761
 762 @object: a #GObject
 763 @first_property_name: name of the first property to set
 764 @Varargs: value for the first property, followed optionally by more
 765           name/value pairs, followed by %NULL
 766
 767
 768 <!-- ##### FUNCTION g_object_get ##### -->
 769 <para>
 770 Gets properties of an object.
 771 </para>
 772 <para>
 773 In general, a copy is made of the property contents and the caller is
 774 responsible for freeing the memory in the appropriate manner for the type,
 775 for instance by calling g_free() or g_object_unref().
 776 </para>
 777 <example>
 778 <title>Using g_object_get(<!-- -->)</title>
 779 <para>
 780 An example of using g_object_get() to get the contents
 781 of three properties - one of type #G_TYPE_INT,
 782 one of type #G_TYPE_STRING, and one of type #G_TYPE_OBJECT:
 783 </para>
 784 <programlisting>
 785  gint intval;
 786  gchar *strval;
 787  GObject *objval;
 788
 789  g_object_get (my_object,
 790                "intproperty", &amp;intval,
 791                "strproperty", &amp;strval,
 792                "objproperty", &amp;objval,
 793                NULL);
 794
 795  /* Do something with intval, strval, objval */
 796
 797  g_free (strval);
 798  g_object_unref (objval);
 799 </programlisting>
 800 </example>
 801
 802 @object: a #GObject
 803 @first_property_name: name of the first property to get
 804 @Varargs: return location for the first property, followed optionally by more
 805           name/return location pairs, followed by %NULL
 806
 807
 808 <!-- ##### FUNCTION g_object_notify ##### -->
 809 <para>
 810 Emits a "notify" signal for the property @property_name on @object.
 811 </para>
 812
 813 @object: a #GObject
 814 @property_name: the name of a property installed on the class of @object.
 815
 816
 817 <!-- ##### FUNCTION g_object_freeze_notify ##### -->
 818 <para>
 819 Stops emission of "notify" signals on @object. The signals are
 820 queued until g_object_thaw_notify() is called on @object.
 821 </para>
 822 <para>
 823 This is necessary for accessors that modify multiple properties to prevent
 824 premature notification while the object is still being modified.
 825 </para>
 826
 827 @object: a #GObject
 828
 829
 830 <!-- ##### FUNCTION g_object_thaw_notify ##### -->
 831 <para>
 832 Reverts the effect of a previous call to g_object_freeze_notify().
 833 This causes all queued "notify" signals on @object to be emitted.
 834 </para>
 835
 836 @object: a #GObject
 837
 838
 839 <!-- ##### FUNCTION g_object_get_data ##### -->
 840 <para>
 841 Gets a named field from the objects table of associations (see g_object_set_data()).
 842 </para>
 843
 844 @object: #GObject containing the associations
 845 @key: name of the key for that association
 846 @Returns: the data if found, or %NULL if no such data exists.
 847
 848
 849 <!-- ##### FUNCTION g_object_set_data ##### -->
 850 <para>
 851 Each object carries around a table of associations from
 852 strings to pointers.  This function lets you set an association.
 853 </para>
 854 <para>
 855 If the object already had an association with that name,
 856 the old association will be destroyed.
 857 </para>
 858
 859 @object: #GObject containing the associations.
 860 @key: name of the key
 861 @data: data to associate with that key
 862
 863
 864 <!-- ##### FUNCTION g_object_set_data_full ##### -->
 865 <para>
 866 Like g_object_set_data() except it adds notification
 867 for when the association is destroyed, either by setting it
 868 to a different value or when the object is destroyed.
 869 </para>
 870
 871 @object: #GObject containing the associations
 872 @key: name of the key
 873 @data: data to associate with that key
 874 @destroy: function to call when the association is destroyed
 875
 876
 877 <!-- ##### FUNCTION g_object_steal_data ##### -->
 878 <para>
 879 Remove a specified datum from the object's data associations,
 880 without invoking the association's destroy handler.
 881 </para>
 882
 883 @object: #GObject containing the associations
 884 @key: name of the key
 885 @Returns: the data if found, or %NULL if no such data exists.
 886
 887
 888 <!-- ##### FUNCTION g_object_get_qdata ##### -->
 889 <para>
 890 This function gets back user data pointers stored via
 891 g_object_set_qdata().
 892 </para>
 893
 894 @object:  The GObject to get a stored user data pointer from
 895 @quark:   A #GQuark, naming the user data pointer
 896 @Returns: The user data pointer set, or %NULL
 897
 898
 899 <!-- ##### FUNCTION g_object_set_qdata ##### -->
 900 <para>
 901 This sets an opaque, named pointer on an object.
 902 The name is specified through a #GQuark (retrived e.g. via
 903 g_quark_from_static_string()), and the pointer
 904 can be gotten back from the @object with g_object_get_qdata()
 905 until the @object is finalized.
 906 Setting a previously set user data pointer, overrides (frees)
 907 the old pointer set, using #NULL as pointer essentially
 908 removes the data stored.
 909 </para>
 910
 911 @object: The GObject to set store a user data pointer
 912 @quark:  A #GQuark, naming the user data pointer
 913 @data:   An opaque user data pointer
 914
 915
 916 <!-- ##### FUNCTION g_object_set_qdata_full ##### -->
 917 <para>
 918 This function works like g_object_set_qdata(), but in addition,
 919 a void (*destroy) (gpointer) function may be specified which is
 920 called with @data as argument when the @object is finalized, or
 921 the data is being overwritten by a call to g_object_set_qdata()
 922 with the same @quark.
 923 </para>
 924
 925 @object:  The GObject to set store a user data pointer
 926 @quark:   A #GQuark, naming the user data pointer
 927 @data:    An opaque user data pointer
 928 @destroy: Function to invoke with @data as argument, when @data needs to be freed
 929
 930
 931 <!-- ##### FUNCTION g_object_steal_qdata ##### -->
 932 <para>
 933 This function gets back user data pointers stored via
 934 g_object_set_qdata() and removes the @data from object
 935 without invoking it's destroy() function (if any was
 936 set).
 937 Usually, calling this function is only required to update
 938 user data pointers with a destroy notifier, for example:
 939 <programlisting>
 940 void
 941 object_add_to_user_list (GObject     *object,
 942                          const gchar *new_string)
 943 {
 944   /* the quark, naming the object data */
 945   GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
 946   /* retrive the old string list */
 947   GList *list = g_object_steal_qdata (object, quark_string_list);
 948
 949   /* prepend new string */
 950   list = g_list_prepend (list, g_strdup (new_string));
 951   /* this changed 'list', so we need to set it again */
 952   g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
 953 }
 954 static void
 955 free_string_list (gpointer data)
 956 {
 957   GList *node, *list = data;
 958
 959   for (node = list; node; node = node->next)
 960     g_free (node->data);
 961   g_list_free (list);
 962 }
 963 </programlisting>
 964 Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata()
 965 would have left the destroy function set, and thus the partial string list would
 966 have been freed upon g_object_set_qdata_full().
 967 </para>
 968
 969 @object:  The GObject to get a stored user data pointer from
 970 @quark:   A #GQuark, naming the user data pointer
 971 @Returns: The user data pointer set, or %NULL
 972
 973
 974 <!-- ##### FUNCTION g_object_set_property ##### -->
 975 <para>
 976 Sets a property on an object.
 977 </para>
 978
 979 @object: a #GObject
 980 @property_name: the name of the property to set
 981 @value: the value
 982
 983
 984 <!-- ##### FUNCTION g_object_get_property ##### -->
 985 <para>
 986 Gets a property of an object.
 987 </para>
 988 <para>
 989 In general, a copy is made of the property contents and the caller is
 990 responsible for freeing the memory by calling g_value_unset().
 991 </para>
 992 <para>
 993 Note that g_object_get_property() is really intended for language
 994 bindings, g_object_get() is much more convenient for C programming.
 995 </para>
 996
 997 @object: a #GObject
 998 @property_name: the name of the property to get
 999 @value: return location for the property value
1000
1001
1002 <!-- ##### FUNCTION g_object_new_valist ##### -->
1003 <para>
1004 Creates a new instance of a #GObject subtype and sets its properties.
1005 </para>
1006 <para>
1007 Construction parameters (see #G_PARAM_CONSTRUCT, #G_PARAM_CONSTRUCT_ONLY)
1008 which are not explicitly specified are set to their default values.
1009 </para>
1010
1011 @object_type: the type id of the #GObject subtype to instantiate
1012 @first_property_name: the name of the first property
1013 @var_args: the value of the first property, followed optionally by more
1014      name/value pairs, followed by %NULL
1015 @Returns: a new instance of @object_type
1016
1017
1018 <!-- ##### FUNCTION g_object_set_valist ##### -->
1019 <para>
1020 Sets properties on an object.
1021 </para>
1022
1023 @object: a #GObject
1024 @first_property_name: name of the first property to set
1025 @var_args: value for the first property, followed optionally by more
1026            name/value pairs, followed by %NULL
1027
1028
1029 <!-- ##### FUNCTION g_object_get_valist ##### -->
1030 <para>
1031 Gets properties of an object.
1032 </para>
1033 <para>
1034 In general, a copy is made of the property contents and the caller is
1035 responsible for freeing the memory in the appropriate manner for the type,
1036 for instance by calling g_free() or g_object_unref().
1037 </para>
1038 <para>
1039 See g_object_get().
1040 </para>
1041
1042 @object: a #GObject
1043 @first_property_name: name of the first property to get
1044 @var_args: return location for the first property, followed optionally by more
1045            name/return location pairs, followed by %NULL
1046
1047
1048 <!-- ##### FUNCTION g_object_watch_closure ##### -->
1049 <para>
1050 This function essentially limits the life time of the @closure
1051 to the life time of the object. That is, when the object is finalized,
1052 the @closure is invalidated by calling g_closure_invalidate() on it,
1053 in order to prevent invocations of the closure with a finalized
1054 (nonexisting) object. Also, g_object_ref() and g_object_unref() are added
1055 as marshal guards to the @closure, to ensure that an extra reference
1056 count is held on @object during invocation of the @closure.
1057 Usually, this function will be called on closures that use this @object
1058 as closure data.
1059 </para>
1060
1061 @object:  GObject restricting lifetime of @closure
1062 @closure: GClosure to watch
1063
1064
1065 <!-- ##### FUNCTION g_object_run_dispose ##### -->
1066 <para>
1067 Releases all references to other objects. This can be used to break
1068 reference cycles.
1069 </para>
1070 <note><para>
1071 This functions should only be called from object system implementations.
1072 </para></note>
1073
1074 @object: a #GObject
1075
1076
1077 <!-- ##### MACRO G_OBJECT_WARN_INVALID_PROPERTY_ID ##### -->
1078 <para>
1079 This macros should be used to emit a standard warning about unexpected
1080 properties in set_property() and get_property() implementations.
1081 </para>
1082
1083 @object: the #GObject on which set_property() or get_property() was called
1084 @property_id: the numeric id of the property
1085 @pspec: the #GParamSpec of the property
1086
1087