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 instead you the accessing macros.
  98 </para>
  99
 100
 101 <!-- ##### MACRO GTK_OBJECT_TYPE ##### -->
 102 <para>
 103 Get the type of an object.
 104 </para>
 105
 106 @object:
 107 <!-- # Unused Parameters # -->
 108 @obj: the object whose type we wish to get.
 109
 110
 111 <!-- ##### MACRO GTK_OBJECT_TYPE_NAME ##### -->
 112 <para>
 113
 114 </para>
 115
 116 @object:
 117
 118
 119 <!-- ##### ENUM GtkObjectFlags ##### -->
 120 <para>
 121 Tells about the state of the object.
 122 </para>
 123
 124 @GTK_IN_DESTRUCTION:
 125 @GTK_FLOATING: whether the object is orphaned.  Objects that take
 126 strong hold of an object may gtk_object_sink() it, after obtaining
 127 there own references, if they believe they are nearly primary
 128 ownership of the object.
 129 GTK_CONNECTED: refers to whether are signals are connected to this
 130 object.
 131 @GTK_RESERVED_1: reserved for future use
 132 @GTK_RESERVED_2: reserved for future use
 133
 134 <!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
 135 <para>
 136 Get the #GtkObjectFlags for an object without directly
 137 accessing its members.
 138 </para>
 139
 140 @obj: the object whose flags are returned.
 141
 142
 143 <!-- ##### MACRO GTK_OBJECT_FLOATING ##### -->
 144 <para>
 145 Evaluates to %TRUE if the object still has its floating reference count.
 146 See the overview documentation for #GtkObject.
 147 </para>
 148
 149 @obj: the object to examine.
 150
 151
 152 <!-- ##### MACRO GTK_OBJECT_CONNECTED ##### -->
 153 <para>
 154 Test whether a GtkObject has had a signal connected to it.
 155 </para>
 156
 157 @obj: the object to examine.
 158
 159
 160 <!-- ##### MACRO GTK_OBJECT_SET_FLAGS ##### -->
 161 <para>
 162 Turn on certain object flags.  (Private)
 163 </para>
 164
 165 @obj: the object to affect.
 166 @flag: the flags to set.
 167
 168
 169 <!-- ##### MACRO GTK_OBJECT_UNSET_FLAGS ##### -->
 170 <para>
 171 Turn off certain object flags.  (Private)
 172 </para>
 173
 174 @obj: the object to affect.
 175 @flag: the flags to unset.
 176
 177
 178 <!-- ##### ENUM GtkArgFlags ##### -->
 179 <para>
 180 Possible flags indicating how an argument should be treated.
 181 Deprecated in favor of #GParamSpec features.
 182 </para>
 183
 184 @GTK_ARG_READABLE: the argument is readable. (i.e. can be queried)
 185 @GTK_ARG_WRITABLE: the argument is writable. (i.e. settable)
 186 @GTK_ARG_CONSTRUCT: the argument needs construction.
 187 @GTK_ARG_CONSTRUCT_ONLY: the argument needs construction (and will
 188 be set once during object creation), but is otherwise cannot be
 189 set.  Hence this flag is not allowed with #GTK_ARG_WRITABLE,
 190 and is redundant with #GTK_ARG_CONSTRUCT.
 191 @GTK_ARG_CHILD_ARG: an argument type that applies to (and may be different for)
 192 each child.  Used by #GtkContainer.
 193
 194 <!-- ##### FUNCTION gtk_object_new ##### -->
 195 <para>
 196 Construct an object given its arguments, enumerated in the call to the
 197 function. Deprecated in favor of g_object_new().
 198 </para>
 199
 200 @type: the type identifying this object.  Returned by gtk_type_unique()
 201 although (for a properly-written object it should be accessible through
 202 #GTK_TYPE_FOO.)
 203 @first_property_name:
 204 @Varargs: the first argument's value, followed by any number of
 205 name/argument-value pairs, terminated with NULL.
 206 @Returns: the new GtkObject.
 207 <!-- # Unused Parameters # -->
 208 @first_arg_name: name of the first argument to set when constructing
 209 the object.
 210
 211
 212 <!-- ##### FUNCTION gtk_object_sink ##### -->
 213 <para>
 214 Removes the floating reference from a #GtkObject, if it exists;
 215 otherwise does nothing. See the #GtkObject overview documentation at
 216 the top of the page.
 217 </para>
 218
 219 @object: the object to sink.
 220
 221
 222 <!-- ##### FUNCTION gtk_object_ref ##### -->
 223 <para>
 224 Increase the reference count of the object, simply calls
 225 g_object_ref() internally.
 226 Deprecated in favor of g_object_ref().
 227 </para>
 228
 229 @object: the object to reference.
 230 @Returns: the object which was referenced
 231
 232
 233 <!-- ##### FUNCTION gtk_object_unref ##### -->
 234 <para>
 235 Decrease the reference count of an object.  When its reference count drops to 0,
 236 the object is finalized (i.e. its memory is freed).  Deprecated in favor of
 237 g_object_unref(). Simply calls g_object_unref() internally.
 238 </para>
 239
 240 @object: the object to dereference.
 241
 242
 243 <!-- ##### FUNCTION gtk_object_weakref ##### -->
 244 <para>
 245 Adds a weak reference callback to an object. Deprecated in favor of
 246 g_object_weak_ref(). Weak references are used for notification when an object is
 247 finalized. They are called "weak references" because they allow you to safely
 248 hold a pointer to an object without calling g_object_ref() (g_object_ref() adds
 249 a strong reference, that is, forces the object to stay alive).
 250 </para>
 251
 252 @object: object to weakly reference.
 253 @notify: callback to invoke before the object is freed.
 254 @data: extra data to pass to #notify.
 255
 256
 257 <!-- ##### FUNCTION gtk_object_weakunref ##### -->
 258 <para>
 259 Removes a weak reference callback to an object.
 260 </para>
 261
 262 @object: object stop weakly referencing.
 263 @notify: callback to search for.
 264 @data: data to search for.
 265
 266
 267 <!-- ##### FUNCTION gtk_object_destroy ##### -->
 268 <para>
 269 Emits the "destroy" signal notifying all reference holders that they should
 270 release the #GtkObject. See the overview documentation at the top of the
 271 page for more details.
 272 </para>
 273 <para>
 274 The memory for the object itself won't be deleted until
 275 its reference count actually drops to 0; gtk_object_destroy() merely asks
 276 reference holders to release their references, it does not free the object.
 277 </para>
 278
 279 @object: the object to destroy.
 280
 281
 282 <!-- ##### FUNCTION gtk_object_get ##### -->
 283 <para>
 284 Get properties of an object. Deprecated in favor of g_object_get().  It takes an
 285 object, then a list of name/return location pairs in a list, followed by NULL.
 286 </para>
 287
 288 @object: a #GtkObject
 289 @first_property_name: name of first property to get the value for
 290 @Varargs: list of name-return location pairs.
 291
 292
 293 <!-- ##### FUNCTION gtk_object_set ##### -->
 294 <para>
 295 Set properties on an object. Deprecated in favor of g_object_set().
 296 </para>
 297 <para>
 298 It takes an object, then a list of name/value pairs
 299 in a list, followed by NULL.
 300 </para>
 301 <para>
 302 <informalexample>
 303 <programlisting>
 304 void set_box_properties(GtkBox* box)
 305 {
 306   gtk_object_set(GTK_OBJECT(box), "homogeneous", TRUE,
 307                                   "spacing", 8,
 308                                   NULL);
 309 }
 310 </programlisting>
 311 </informalexample>
 312 </para>
 313
 314 @object: the object whose arguments should be set.
 315 @first_property_name: name of the first property to set
 316 @Varargs: the value of the first argument, followed optionally
 317 by more name/value pairs, followed by NULL.
 318
 319
 320 <!-- ##### FUNCTION gtk_object_set_data ##### -->
 321 <para>
 322 Deprecated in favor of g_object_set_data().
 323 Each object carries around a table of associations from
 324 strings to pointers.  This function lets you set an association.
 325 </para>
 326 <para>
 327 If the object already had an association with that name,
 328 the old association will be destroyed.
 329 </para>
 330
 331 @object: object containing the associations.
 332 @key: name of the key.
 333 @data: data to associate with that key.
 334
 335
 336 <!-- ##### FUNCTION gtk_object_set_data_full ##### -->
 337 <para>
 338 Deprecated in favor of g_object_set_data_full().
 339 Like gtk_object_set_data() except it adds notification
 340 for when the association is destroyed, either by
 341 gtk_object_remove_data() or when the object is destroyed.
 342 </para>
 343
 344 @object: object containing the associations.
 345 @key: name of the key.
 346 @data: data to associate with that key.
 347 @destroy: function to call when the association is destroyed.
 348
 349
 350 <!-- ##### FUNCTION gtk_object_remove_data ##### -->
 351 <para>
 352 Deprecated in favor of setting object data to %NULL using g_object_set_data().
 353 Removes a specified datum from the object's data associations (the object_data).
 354 Subsequent calls to gtk_object_get_data() will return NULL.
 355 </para>
 356 <para>
 357 If you specified a destroy handler with gtk_object_set_data_full(),
 358 it will be invoked.
 359 </para>
 360
 361 @object: the object maintaining the association.
 362 @key: name of the key for that association.
 363
 364
 365 <!-- ##### FUNCTION gtk_object_get_data ##### -->
 366 <para>
 367 Deprecated in favor of g_object_get_data().
 368 Get a named field from the object's table of associations (the object_data).
 369 </para>
 370
 371 @object: the object maintaining the associations.
 372 @key: name of the key for that association.
 373 @Returns: the data if found, or NULL if no such data exists.
 374
 375
 376 <!-- ##### FUNCTION gtk_object_remove_no_notify ##### -->
 377 <para>
 378 Deprecated in favor of g_object_steal_data().
 379 Remove a specified datum from the object's data associations (the object_data),
 380 without invoking the association's destroy handler.
 381 </para>
 382 <para>
 383 Just like gtk_object_remove_data() except that any destroy handler
 384 will be ignored.
 385 Therefore this only affects data set using gtk_object_set_data_full().
 386 </para>
 387
 388 @object: the object maintaining the association.
 389 @key: name of the key for that association.
 390
 391
 392 <!-- ##### FUNCTION gtk_object_set_user_data ##### -->
 393 <para>
 394 Deprecated in favor of g_object_set_data().
 395 For convenience, every object offers a generic user data
 396 pointer.  The function set it.
 397 </para>
 398 <para>
 399 This function is equivalent to:
 400 <informalexample>
 401 <programlisting>
 402         gtk_object_set_data(object, "user_data", data);
 403 </programlisting>
 404 </informalexample>
 405 </para>
 406
 407 @object: the object whose user data should be set.
 408 @data: the new value for the user data.
 409
 410
 411 <!-- ##### FUNCTION gtk_object_get_user_data ##### -->
 412 <para>
 413 Deprecated in favor of g_object_get_data().
 414 Get the object's user data pointer.
 415 </para>
 416 <para>
 417 This is intended to be a pointer for your convenience in
 418 writing applications.
 419 </para>
 420
 421 @object: the object.
 422 @Returns: the user data field for object.
 423
 424
 425 <!-- ##### FUNCTION gtk_object_add_arg_type ##### -->
 426 <para>
 427 Deprecated in favor of the #GObject property system including #GParamSpec.
 428 Add a new type of argument to an object class.
 429 Usually this is called when registering a new type of object.
 430 </para>
 431
 432 @arg_name: fully qualify object name, for example GtkObject::user_data.
 433 @arg_type: type of the argument.
 434 @arg_flags: bitwise-OR of the #GtkArgFlags enum.  (Whether the argument is
 435 settable or gettable, whether it is set when the object is constructed.)
 436 @arg_id: an internal number, passed in from here to the "set_arg" and
 437 "get_arg" handlers of the object.
 438
 439
 440 <!-- ##### FUNCTION gtk_object_set_data_by_id ##### -->
 441 <para>
 442 Deprecated in favor of g_object_set_qdata().
 443 Just like gtk_object_set_data() except that it takes
 444 a #GQuark instead of a string, so it is slightly faster.
 445 </para>
 446 <para>
 447 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 448 to get an id from a string.
 449 </para>
 450
 451 @object: object containing the associations.
 452 @data_id: quark of the key.
 453 @data: data to associate with that key.
 454
 455
 456 <!-- ##### FUNCTION gtk_object_set_data_by_id_full ##### -->
 457 <para>
 458 Deprecated in favor of g_object_set_qdata_full().
 459 Just like gtk_object_set_data_full() except that it takes
 460 a #GQuark instead of a string, so it is slightly faster.
 461 </para>
 462 <para>
 463 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 464 to get an id from a string.
 465 </para>
 466
 467 @object: object containing the associations.
 468 @data_id: quark of the key.
 469 @data: data to associate with that key.
 470 @destroy: function to call when the association is destroyed.
 471
 472
 473 <!-- ##### FUNCTION gtk_object_get_data_by_id ##### -->
 474 <para>
 475 Deprecated in favor of g_object_get_qdata().
 476 Just like gtk_object_get_data() except that it takes
 477 a #GQuark instead of a string, so it is slightly faster.
 478 </para>
 479 <para>
 480 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 481 to get an id from a string.
 482 </para>
 483
 484 @object: object containing the associations.
 485 @data_id: quark of the key.
 486 @Returns: the data if found, or NULL if no such data exists.
 487
 488
 489 <!-- ##### FUNCTION gtk_object_remove_data_by_id ##### -->
 490 <para>
 491 Deprecated in favor of g_object_set_qdata() called with data of %NULL.
 492 Just like gtk_object_remove_data() except that it takes
 493 a #GQuark instead of a string, so it is slightly faster.
 494 </para>
 495 <para>
 496 Remove a specified datum from the object's data associations.
 497 Subsequent calls to gtk_object_get_data() will return NULL.
 498 </para>
 499 <para>
 500 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 501 to get an id from a string.
 502 </para>
 503
 504 @object: object containing the associations.
 505 @data_id: quark of the key.
 506
 507
 508 <!-- ##### FUNCTION gtk_object_remove_no_notify_by_id ##### -->
 509 <para>
 510 Deprecated in favor of g_object_steal_qdata().
 511 Just like gtk_object_remove_no_notify() except that it takes
 512 a #GQuark instead of a string, so it is slightly faster.
 513 </para>
 514 <para>
 515 Use gtk_object_data_try_key() and gtk_object_data_force_id()
 516 to get an id from a string.
 517 </para>
 518
 519 @object: object containing the associations.
 520 @key_id:
 521 <!-- # Unused Parameters # -->
 522 @data_id: quark of the key.
 523
 524
 525 <!-- ##### MACRO gtk_object_data_try_key ##### -->
 526 <para>
 527 Useless deprecated macro. Ignore it.
 528 </para>
 529
 530
 531
 532 <!-- ##### MACRO gtk_object_data_force_id ##### -->
 533 <para>
 534 Useless deprecated macro. Ignore it.
 535 </para>
 536
 537
 538
 539 <!-- ##### SIGNAL GtkObject::destroy ##### -->
 540 <para>
 541 Signals that all holders of a reference to the #GtkObject should release
 542 the reference that they hold. May result in finalization of the object
 543 if all references are released.
 544 </para>
 545
 546 @object: the object which received the signal.
 547
 548 <!-- ##### ARG GtkObject:user-data ##### -->
 549 <para>
 550 A pointer for convenience when programming applications.
 551 Deprecated.
 552 </para>
 553