Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtkobject.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GtkObject
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 The base class of the Gtk type hierarchy.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <refsect2>
   9 <title>Description</title>
  10 <para>
  11 #GtkObject is the base class for all widgets, and for a few
  12 non-widget objects such as #GtkAdjustment. #GtkObject predates
  13 #GObject; non-widgets that derive from #GtkObject rather than
  14 #GObject do so for backward compatibility reasons.
  15 </para>
  16 <para>
  17 The most interesting difference between #GtkObject and #GObject is the
  18 "floating" reference count. A #GObject is created with a reference count of 1,
  19 owned by the creator of the #GObject. (The owner of a reference is the code
  20 section that has the right to call g_object_unref() in order to remove that
  21 reference.)  A #GtkObject is created with a reference count of 1 also, but it
  22 isn't owned by anyone; calling g_object_unref() on the newly-created #GtkObject
  23 is incorrect. Instead, the initial reference count of a #GtkObject is "floating".
  24 The floating reference can be removed by anyone at any time, by calling
  25 gtk_object_sink(). gtk_object_sink() does nothing if an object is already
  26 sunk (has no floating reference).
  27 </para>
  28 <para>
  29 When you add a widget to its parent container, the parent container
  30 will do this:
  31 <programlisting>
  32   g_object_ref (G_OBJECT (child_widget));
  33   gtk_object_sink (GTK_OBJECT (child_widget));
  34 </programlisting>
  35 This means that the container now owns a reference to the child widget (since
  36 it called g_object_ref()), and the child widget has no floating reference.
  37 </para>
  38 <para>
  39 The purpose of the floating reference is to keep the child widget alive
  40 until you add it to a parent container:
  41 <programlisting>
  42    button = gtk_button_new ();
  43    /* button has one floating reference to keep it alive */
  44    gtk_container_add (GTK_CONTAINER (container), button);
  45    /* button has one non-floating reference owned by the container */
  46 </programlisting>
  47 </para>
  48 <para>
  49 #GtkWindow is a special case, because GTK+ itself will ref/sink it on creation.
  50 That is, after calling gtk_window_new(), the #GtkWindow will have one
  51 reference which is owned by GTK+, and no floating references.
  52 </para>
  53
  54 <para>
  55 One more factor comes into play: the "destroy" signal, emitted by the
  56 gtk_object_destroy() method. The "destroy" signal asks all code owning a
  57 reference to an object to release said reference. So, for example, if you call
  58 gtk_object_destroy() on a #GtkWindow, GTK+ will release the reference count that
  59 it owns; if you call gtk_object_destroy() on a #GtkButton, then the button will
  60 be removed from its parent container and the parent container will release its
  61 reference to the button.  Because these references are released, calling
  62 gtk_object_destroy() should result in freeing all memory associated with an
  63 object, unless some buggy code fails to release its references in response to
  64 the "destroy" signal. Freeing memory (referred to as
  65 <firstterm>finalization</firstterm> only happens if the reference count reaches
  66 zero.
  67 </para>
  68
  69 <para>
  70 Some simple rules for handling #GtkObject:
  71 <itemizedlist>
  72 <listitem><para>
  73 Never call g_object_unref() unless you have previously called g_object_ref(),
  74 even if you created the #GtkObject. (Note: this is <emphasis>not</emphasis>
  75 true for #GObject; for #GObject, the creator of the object owns a reference.)
  76 </para></listitem>
  77 <listitem><para>
  78 Call gtk_object_destroy() to get rid of most objects in most cases.
  79 In particular, widgets are almost always destroyed in this way.
  80 </para></listitem>
  81 <listitem><para> Because of the floating reference count, you don't need to
  82 worry about reference counting for widgets and toplevel windows, unless you
  83 explicitly call g_object_ref() yourself.  </para></listitem>
  84 </itemizedlist>
  85 </para>
  86
  87 </refsect2>
  88
  89 <!-- ##### SECTION See_Also ##### -->
  90 <para>
  91 #GObject
  92 </para>
  93
  94 <!-- ##### STRUCT GtkObject ##### -->
  95 <para>
  96 The object itself.  You should never use these members directly -
  97  use the accessing macros instead.
  98 </para>
  99
 100
 101 <!-- ##### MACRO GTK_OBJECT_TYPE ##### -->
 102 <para>
 103 Gets the type of an object.
 104 </para>
 105
 106 @object: a #GtkObject.
 107
 108
 109 <!-- ##### MACRO GTK_OBJECT_TYPE_NAME ##### -->
 110 <para>
 111 Gets the name of an objects type.
 112 </para>
 113
 114 @object: a #GtkObject.
 115
 116
 117 <!-- ##### ENUM GtkObjectFlags ##### -->
 118 <para>
 119 Tells about the state of the object.
 120 </para>
 121
 122 @GTK_IN_DESTRUCTION:
 123 @GTK_FLOATING: whether the object is orphaned.  Objects that take
 124 strong hold of an object may gtk_object_sink() it, after obtaining
 125 there own references, if they believe they are nearly primary
 126 ownership of the object.
 127 GTK_CONNECTED: refers to whether are signals are connected to this
 128 object.
 129 @GTK_RESERVED_1: reserved for future use
 130 @GTK_RESERVED_2: reserved for future use
 131
 132 <!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
 133 <para>
 134 Gets the #GtkObjectFlags for an object without directly
 135 accessing its members.
 136 </para>
 137
 138 @obj: the object whose flags are returned.
 139
 140
 141 <!-- ##### MACRO GTK_OBJECT_FLOATING ##### -->
 142 <para>
 143 Evaluates to %TRUE if the object still has its floating reference count.
 144 See the overview documentation for #GtkObject.
 145 </para>
 146
 147 @obj: the object to examine.
 148
 149
 150 <!-- ##### MACRO GTK_OBJECT_CONNECTED ##### -->
 151 <para>
 152 Tests whether a #GtkObject has had a signal connected to it.
 153 </para>
 154
 155 @obj: the object to examine.
 156
 157
 158 <!-- ##### MACRO GTK_OBJECT_SET_FLAGS ##### -->
 159 <para>
 160 Turns on certain object flags.  (Private)
 161 </para>
 162
 163 @obj: the object to affect.
 164 @flag: the flags to set.
 165
 166
 167 <!-- ##### MACRO GTK_OBJECT_UNSET_FLAGS ##### -->
 168 <para>
 169 Turns off certain object flags.  (Private)
 170 </para>
 171
 172 @obj: the object to affect.
 173 @flag: the flags to unset.
 174
 175
 176 <!-- ##### ENUM GtkArgFlags ##### -->
 177 <para>
 178 Possible flags indicating how an argument should be treated.
 179 Deprecated in favor of #GParamSpec features.
 180 </para>
 181
 182 @GTK_ARG_READABLE: the argument is readable. (i.e. can be queried)
 183 @GTK_ARG_WRITABLE: the argument is writable. (i.e. settable)
 184 @GTK_ARG_CONSTRUCT: the argument needs construction.
 185 @GTK_ARG_CONSTRUCT_ONLY: the argument needs construction (and will
 186 be set once during object creation), but is otherwise cannot be
 187 set.  Hence this flag is not allowed with #GTK_ARG_WRITABLE,
 188 and is redundant with #GTK_ARG_CONSTRUCT.
 189 @GTK_ARG_CHILD_ARG: an argument type that applies to (and may be different for)
 190 each child.  Used by #GtkContainer.
 191
 192 <!-- ##### FUNCTION gtk_object_new ##### -->
 193 <para>
 194 Constructs an object given its arguments, enumerated in the call to the
 195 function. Deprecated in favor of g_object_new().
 196 </para>
 197
 198 @type: the type identifying this object.  Returned by gtk_type_unique()
 199 (although for a properly-written object it should be accessible through
 200 a #GTK_TYPE_FOO macro.)
 201 @first_property_name: name of the first property to set when constructing
 202    the object.
 203 @Varargs: the first argument's value, followed by any number of
 204 name/argument-value pairs, terminated with %NULL.
 205 @Returns: the new #GtkObject.
 206
 207
 208 <!-- ##### FUNCTION gtk_object_sink ##### -->
 209 <para>
 210 Removes the floating reference from a #GtkObject, if it exists;
 211 otherwise does nothing. See the #GtkObject overview documentation at
 212 the top of the page.
 213 </para>
 214
 215 @object: the object to sink.
 216
 217
 218 <!-- ##### FUNCTION gtk_object_ref ##### -->
 219 <para>
 220 Increases the reference count of the object.
 221 Deprecated in favor of g_object_ref().
 222 </para>
 223
 224 @object: the object to reference.
 225 @Returns: @object.
 226
 227
 228 <!-- ##### FUNCTION gtk_object_unref ##### -->
 229 <para>
 230 Decreases the reference count of an object.  When its reference count drops
 231 to 0, the object is finalized (i.e. its memory is freed).  Deprecated in
 232 favor of g_object_unref().
 233 </para>
 234
 235 @object: the object to dereference.
 236
 237
 238 <!-- ##### FUNCTION gtk_object_weakref ##### -->
 239 <para>
 240 Adds a weak reference callback to an object. Deprecated in favor of
 241 g_object_weak_ref(). Weak references are used for notification when an object is
 242 finalized. They are called "weak references" because they allow you to safely
 243 hold a pointer to an object without calling g_object_ref() (g_object_ref() adds
 244 a strong reference, that is, forces the object to stay alive).
 245 </para>
 246
 247 @object: object to weakly reference.
 248 @notify: callback to invoke before the object is freed.
 249 @data: extra data to pass to #notify.
 250
 251
 252 <!-- ##### FUNCTION gtk_object_weakunref ##### -->
 253 <para>
 254 Removes a weak reference callback to an object.
 255 </para>
 256
 257 @object: object stop weakly referencing.
 258 @notify: callback to search for.
 259 @data: data to search for.
 260
 261
 262 <!-- ##### FUNCTION gtk_object_destroy ##### -->
 263 <para>
 264 Emits the "destroy" signal notifying all reference holders that they should
 265 release the #GtkObject. See the overview documentation at the top of the
 266 page for more details.
 267 </para>
 268 <para>
 269 The memory for the object itself won't be deleted until
 270 its reference count actually drops to 0; gtk_object_destroy() merely asks
 271 reference holders to release their references, it does not free the object.
 272 </para>
 273
 274 @object: the object to destroy.
 275
 276
 277 <!-- ##### FUNCTION gtk_object_get ##### -->
 278 <para>
 279 Gets properties of an object. Deprecated in favor of g_object_get().
 280 </para>
 281
 282 @object: a #GtkObject.
 283 @first_property_name: name of first property to get the value for.
 284 @Varargs: %NULL-terminated list of name-return location pairs.
 285
 286
 287 <!-- ##### FUNCTION gtk_object_set ##### -->
 288 <para>
 289 Sets properties on an object. Deprecated in favor of g_object_set().
 290 </para>
 291 <para>
 292 <informalexample>
 293 <programlisting>
 294 void set_box_properties(GtkBox* box)
 295 {
 296   gtk_object_set(GTK_OBJECT(box), "homogeneous", TRUE,
 297                                   "spacing", 8,
 298                                   NULL);
 299 }
 300 </programlisting>
 301 </informalexample>
 302 </para>
 303
 304 @object: a #GtkObject.
 305 @first_property_name: name of the first property to set
 306 @Varargs: the value of the first argument, followed optionally
 307 by more name/value pairs, followed by %NULL.
 308
 309
 310 <!-- ##### FUNCTION gtk_object_set_data ##### -->
 311 <para>
 312 Deprecated in favor of g_object_set_data().
 313 Each object carries around a table of associations from
 314 strings to pointers.  This function lets you set an association.
 315 </para>
 316 <para>
 317 If the object already had an association with that name,
 318 the old association will be destroyed.
 319 </para>
 320
 321 @object: object containing the associations.
 322 @key: name of the key.
 323 @data: data to associate with that key.
 324
 325
 326 <!-- ##### FUNCTION gtk_object_set_data_full ##### -->
 327 <para>
 328 Deprecated in favor of g_object_set_data_full().
 329 Like gtk_object_set_data() except it adds notification
 330 for when the association is destroyed, either by
 331 gtk_object_remove_data() or when the object is destroyed.
 332 </para>
 333
 334 @object: object containing the associations.
 335 @key: name of the key.
 336 @data: data to associate with that key.
 337 @destroy: function to call when the association is destroyed.
 338
 339
 340 <!-- ##### FUNCTION gtk_object_remove_data ##### -->
 341 <para>
 342 Deprecated in favor of setting object data to %NULL using g_object_set_data().
 343 Removes a specified datum from the object's data associations (the object_data).
 344 Subsequent calls to gtk_object_get_data() will return %NULL.
 345 </para>
 346 <para>
 347 If you specified a destroy handler with gtk_object_set_data_full(),
 348 it will be invoked.
 349 </para>
 350
 351 @object: the object maintaining the association.
 352 @key: name of the key for that association.
 353
 354
 355 <!-- ##### FUNCTION gtk_object_get_data ##### -->
 356 <para>
 357 Deprecated in favor of g_object_get_data().
 358 Get a named field from the object's table of associations (the object_data).
 359 </para>
 360
 361 @object: the object maintaining the associations.
 362 @key: name of the key for that association.
 363 @Returns: the data if found, or %NULL if no such data exists.
 364
 365
 366 <!-- ##### FUNCTION gtk_object_remove_no_notify ##### -->
 367 <para>
 368 Deprecated in favor of g_object_steal_data().
 369 Remove a specified datum from the object's data associations (the object_data),
 370 without invoking the association's destroy handler.
 371 </para>
 372 <para>
 373 Just like gtk_object_remove_data() except that any destroy handler
 374 will be ignored.
 375 Therefore this only affects data set using gtk_object_set_data_full().
 376 </para>
 377
 378 @object: the object maintaining the association.
 379 @key: name of the key for that association.
 380
 381
 382 <!-- ##### FUNCTION gtk_object_set_user_data ##### -->
 383 <para>
 384 Deprecated in favor of g_object_set_data().
 385 For convenience, every object offers a generic user data
 386 pointer.  This function sets it.
 387 </para>
 388 <para>
 389 This function is equivalent to:
 390 <informalexample>
 391 <programlisting>
 392         gtk_object_set_data(object, "user_data", data);
 393 </programlisting>
 394 </informalexample>
 395 </para>
 396
 397 @object: the object whose user data should be set.
 398 @data: the new value for the user data.
 399
 400
 401 <!-- ##### FUNCTION gtk_object_get_user_data ##### -->
 402 <para>
 403 Deprecated in favor of g_object_get_data().
 404 Get the object's user data pointer.
 405 </para>
 406 <para>
 407 This is intended to be a pointer for your convenience in
 408 writing applications.
 409 </para>
 410
 411 @object: the object.
 412 @Returns: the user data field for object.
 413
 414
 415 <!-- ##### FUNCTION gtk_object_add_arg_type ##### -->
 416 <para>
 417 Deprecated in favor of the #GObject property system including #GParamSpec.
 418 Add a new type of argument to an object class.
 419 Usually this is called when registering a new type of object.
 420 </para>
 421
 422 @arg_name: fully qualify object name, for example GtkObject::user_data.
 423 @arg_type: type of the argument.
 424 @arg_flags: bitwise-OR of the #GtkArgFlags enum.  (Whether the argument is
 425 settable or gettable, whether it is set when the object is constructed.)
 426 @arg_id: an internal number, passed in from here to the "set_arg" and
 427 "get_arg" handlers of the object.
 428
 429
 430 <!-- ##### FUNCTION gtk_object_set_data_by_id ##### -->
 431 <para>
 432 Deprecated in favor of g_object_set_qdata().
 433 Just like gtk_object_set_data() except that it takes
 434 a #GQuark instead of a string, so it is slightly faster.
 435 </para>
 436 <para>
 437 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 438 to get an id from a string.
 439 </para>
 440
 441 @object: object containing the associations.
 442 @data_id: quark of the key.
 443 @data: data to associate with that key.
 444
 445
 446 <!-- ##### FUNCTION gtk_object_set_data_by_id_full ##### -->
 447 <para>
 448 Deprecated in favor of g_object_set_qdata_full().
 449 Just like gtk_object_set_data_full() except that it takes
 450 a #GQuark instead of a string, so it is slightly faster.
 451 </para>
 452 <para>
 453 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 454 to get an id from a string.
 455 </para>
 456
 457 @object: object containing the associations.
 458 @data_id: quark of the key.
 459 @data: data to associate with that key.
 460 @destroy: function to call when the association is destroyed.
 461
 462
 463 <!-- ##### FUNCTION gtk_object_get_data_by_id ##### -->
 464 <para>
 465 Deprecated in favor of g_object_get_qdata().
 466 Just like gtk_object_get_data() except that it takes
 467 a #GQuark instead of a string, so it is slightly faster.
 468 </para>
 469 <para>
 470 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 471 to get an id from a string.
 472 </para>
 473
 474 @object: object containing the associations.
 475 @data_id: quark of the key.
 476 @Returns: the data if found, or %NULL if no such data exists.
 477
 478
 479 <!-- ##### FUNCTION gtk_object_remove_data_by_id ##### -->
 480 <para>
 481 Deprecated in favor of g_object_set_qdata() called with data of %NULL.
 482 Just like gtk_object_remove_data() except that it takes
 483 a #GQuark instead of a string, so it is slightly faster.
 484 </para>
 485 <para>
 486 Remove a specified datum from the object's data associations.
 487 Subsequent calls to gtk_object_get_data() will return %NULL.
 488 </para>
 489 <para>
 490 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 491 to get an id from a string.
 492 </para>
 493
 494 @object: object containing the associations.
 495 @data_id: quark of the key.
 496
 497
 498 <!-- ##### FUNCTION gtk_object_remove_no_notify_by_id ##### -->
 499 <para>
 500 Deprecated in favor of g_object_steal_qdata().
 501 Just like gtk_object_remove_no_notify() except that it takes
 502 a #GQuark instead of a string, so it is slightly faster.
 503 </para>
 504 <para>
 505 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 506 to get an id from a string.
 507 </para>
 508
 509 @object: object containing the associations.
 510 @key_id: quark of the key.
 511 <!-- # Unused Parameters # -->
 512 @data_id:
 513
 514
 515 <!-- ##### MACRO gtk_object_data_try_key ##### -->
 516 <para>
 517 Useless deprecated macro. Ignore it.
 518 </para>
 519
 520
 521
 522 <!-- ##### MACRO gtk_object_data_force_id ##### -->
 523 <para>
 524 Useless deprecated macro. Ignore it.
 525 </para>
 526
 527
 528
 529 <!-- ##### SIGNAL GtkObject::destroy ##### -->
 530 <para>
 531 Signals that all holders of a reference to the #GtkObject should release
 532 the reference that they hold. May result in finalization of the object
 533 if all references are released.
 534 </para>
 535
 536 @object: the object which received the signal.
 537
 538 <!-- ##### ARG GtkObject:user-data ##### -->
 539 <para>
 540 A pointer for convenience when programming applications.
 541 Deprecated.
 542 </para>
 543