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