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