1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 The base class of the GTK+ type hierarchy
7 <!-- ##### SECTION Long_Description ##### -->
9 <title>Description</title>
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.
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).
26 When you add a widget to its parent container, the parent container
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.
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>
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.
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
66 Some simple rules for handling #GtkObject:
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.)
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.
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>
85 <!-- ##### SECTION See_Also ##### -->
90 <!-- ##### SECTION Stability_Level ##### -->
93 <!-- ##### STRUCT GtkObject ##### -->
95 The object itself. You should never use these members directly -
96 use the accessing macros instead.
100 <!-- ##### SIGNAL GtkObject::destroy ##### -->
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.
107 @object: the object which received the signal.
109 <!-- ##### ARG GtkObject:user-data ##### -->
114 <!-- ##### MACRO GTK_OBJECT_TYPE ##### -->
116 Gets the type of an object.
119 @object: a #GtkObject.
122 <!-- ##### MACRO GTK_OBJECT_TYPE_NAME ##### -->
124 Gets the name of an objects type.
127 @object: a #GtkObject.
130 <!-- ##### ENUM GtkObjectFlags ##### -->
132 Tells about the state of the object.
135 @GTK_IN_DESTRUCTION: the object is currently being destroyed. This is used
136 internally by GTK+ to prevent reinvokations during destruction.
139 @GTK_RESERVED_2: reserved for future use
141 <!-- ##### MACRO GTK_OBJECT_FLAGS ##### -->
143 Gets the #GtkObjectFlags for an object without directly
144 accessing its members.
147 @obj: the object whose flags are returned.
150 <!-- ##### MACRO GTK_OBJECT_FLOATING ##### -->
152 Evaluates to %TRUE if the object still has its floating reference count.
153 See the overview documentation for #GtkObject.
156 @obj: the object to examine.
159 <!-- ##### ENUM GtkArgFlags ##### -->
161 Possible flags indicating how an argument should be treated.
164 @GTK_ARG_READABLE: the argument is readable. (i.e. can be queried)
165 @GTK_ARG_WRITABLE: the argument is writable. (i.e. settable)
166 @GTK_ARG_CONSTRUCT: the argument needs construction.
167 @GTK_ARG_CONSTRUCT_ONLY: the argument needs construction (and will
168 be set once during object creation), but is otherwise cannot be
169 set. Hence this flag is not allowed with #GTK_ARG_WRITABLE,
170 and is redundant with #GTK_ARG_CONSTRUCT.
171 @GTK_ARG_CHILD_ARG: an argument type that applies to (and may be different for)
172 each child. Used by #GtkContainer.
173 @Deprecated: Use corresponding #GParamSpec features instead
175 <!-- ##### FUNCTION gtk_object_new ##### -->
177 Constructs an object given its arguments, enumerated in the call to the
181 @type: the type identifying this object. Returned by gtk_type_unique()
182 (although for a properly-written object it should be accessible through
183 a #GTK_TYPE_FOO macro.)
184 @first_property_name: name of the first property to set when constructing
186 @Varargs: the first argument's value, followed by any number of
187 name/argument-value pairs, terminated with %NULL.
188 @Returns: the new #GtkObject.
189 @Deprecated: Use g_object_new() instead.
192 <!-- ##### FUNCTION gtk_object_sink ##### -->
194 Removes the floating reference from a #GtkObject, if it exists;
195 otherwise does nothing. See the #GtkObject overview documentation at
199 @object: the object to sink.
200 @Deprecated: 2.10: Use g_object_ref_sink() instead
203 <!-- ##### FUNCTION gtk_object_ref ##### -->
205 Increases the reference count of the object.
208 @object: the object to reference.
210 @Deprecated: Use g_object_ref() instead.
213 <!-- ##### FUNCTION gtk_object_unref ##### -->
215 Decreases the reference count of an object. When its reference count drops
216 to 0, the object is finalized (i.e. its memory is freed).
219 @object: the object to dereference.
220 @Deprecated: Use g_object_unref() instead.
223 <!-- ##### FUNCTION gtk_object_weakref ##### -->
225 Adds a weak reference callback to an object. Weak references are used for notification when an object is
226 finalized. They are called "weak references" because they allow you to safely
227 hold a pointer to an object without calling g_object_ref() (g_object_ref() adds
228 a strong reference, that is, forces the object to stay alive).
231 @object: object to weakly reference.
232 @notify: callback to invoke before the object is freed.
233 @data: extra data to pass to #notify.
234 @Deprecated: Use g_object_weak_ref() instead.
237 <!-- ##### FUNCTION gtk_object_weakunref ##### -->
239 Removes a weak reference callback to an object.
242 @object: object stop weakly referencing.
243 @notify: callback to search for.
244 @data: data to search for.
245 @Deprecated: Use g_object_weak_unref() instead.
248 <!-- ##### FUNCTION gtk_object_destroy ##### -->
250 Emits the "destroy" signal notifying all reference holders that they should
251 release the #GtkObject. See the overview documentation at the top of the
252 page for more details.
255 The memory for the object itself won't be deleted until
256 its reference count actually drops to 0; gtk_object_destroy() merely asks
257 reference holders to release their references, it does not free the object.
260 @object: the object to destroy.
263 <!-- ##### FUNCTION gtk_object_get ##### -->
265 Gets properties of an object.
268 @object: a #GtkObject.
269 @first_property_name: name of first property to get the value for.
270 @Varargs: %NULL-terminated list of name-return location pairs.
271 @Deprecated: Use g_object_get() instead.
274 <!-- ##### FUNCTION gtk_object_set ##### -->
276 Sets properties on an object.
281 void set_box_properties (GtkBox* box)
283 gtk_object_set (GTK_OBJECT (box), "homogeneous", TRUE,
291 @object: a #GtkObject.
292 @first_property_name: name of the first property to set
293 @Varargs: the value of the first argument, followed optionally
294 by more name/value pairs, followed by %NULL.
295 @Deprecated: Use g_object_set() instead.
298 <!-- ##### FUNCTION gtk_object_set_data ##### -->
300 Each object carries around a table of associations from
301 strings to pointers. This function lets you set an association.
304 If the object already had an association with that name,
305 the old association will be destroyed.
308 @object: object containing the associations.
309 @key: name of the key.
310 @data: data to associate with that key.
311 @Deprecated: Use g_object_set_data() instead.
314 <!-- ##### FUNCTION gtk_object_set_data_full ##### -->
316 Like gtk_object_set_data() except it adds notification
317 for when the association is destroyed, either by
318 gtk_object_remove_data() or when the object is destroyed.
321 @object: object containing the associations.
322 @key: name of the key.
323 @data: data to associate with that key.
324 @destroy: function to call when the association is destroyed.
325 @Deprecated: Use g_object_set_data_full() instead.
328 <!-- ##### FUNCTION gtk_object_remove_data ##### -->
330 Removes a specified datum from the object's data associations (the object_data).
331 Subsequent calls to gtk_object_get_data() will return %NULL.
334 If you specified a destroy handler with gtk_object_set_data_full(),
338 @object: the object maintaining the association.
339 @key: name of the key for that association.
340 @Deprecated: Use g_object_set_data() to set the object data to %NULL instead.
343 <!-- ##### FUNCTION gtk_object_get_data ##### -->
345 Get a named field from the object's table of associations (the object_data).
348 @object: the object maintaining the associations.
349 @key: name of the key for that association.
350 @Returns: the data if found, or %NULL if no such data exists.
351 @Deprecated: Use g_object_get_data() instead.
354 <!-- ##### FUNCTION gtk_object_remove_no_notify ##### -->
356 Remove a specified datum from the object's data associations (the object_data),
357 without invoking the association's destroy handler.
360 Just like gtk_object_remove_data() except that any destroy handler
362 Therefore this only affects data set using gtk_object_set_data_full().
365 @object: the object maintaining the association.
366 @key: name of the key for that association.
367 @Deprecated: Use g_object_steal_data() instead.
370 <!-- ##### FUNCTION gtk_object_set_user_data ##### -->
372 For convenience, every object offers a generic user data
373 pointer. This function sets it.
376 @object: the object whose user data should be set.
377 @data: the new value for the user data.
378 @Deprecated: Use g_object_set_data() instead.
381 <!-- ##### FUNCTION gtk_object_get_user_data ##### -->
383 Get the object's user data pointer.
386 This is intended to be a pointer for your convenience in
387 writing applications.
391 @Returns: the user data field for object.
392 @Deprecated: Use g_object_get_data() instead.
395 <!-- ##### FUNCTION gtk_object_add_arg_type ##### -->
397 Deprecated in favor of the #GObject property system including #GParamSpec.
398 Add a new type of argument to an object class.
399 Usually this is called when registering a new type of object.
402 @arg_name: fully qualify object name, for example GtkObject::user_data.
403 @arg_type: type of the argument.
404 @arg_flags: bitwise-OR of the #GtkArgFlags enum. (Whether the argument is
405 settable or gettable, whether it is set when the object is constructed.)
406 @arg_id: an internal number, passed in from here to the "set_arg" and
407 "get_arg" handlers of the object.
410 <!-- ##### FUNCTION gtk_object_set_data_by_id ##### -->
412 Just like gtk_object_set_data() except that it takes
413 a #GQuark instead of a string, so it is slightly faster.
416 Use gtk_object_data_try_key() and gtk_object_data_force_id()
417 to get an id from a string.
420 @object: object containing the associations.
421 @data_id: quark of the key.
422 @data: data to associate with that key.
423 @Deprecated: Use g_object_set_qdata() instead.
426 <!-- ##### FUNCTION gtk_object_set_data_by_id_full ##### -->
428 Just like gtk_object_set_data_full() except that it takes
429 a #GQuark instead of a string, so it is slightly faster.
432 Use gtk_object_data_try_key() and gtk_object_data_force_id()
433 to get an id from a string.
436 @object: object containing the associations.
437 @data_id: quark of the key.
438 @data: data to associate with that key.
439 @destroy: function to call when the association is destroyed.
440 @Deprecated: Use g_object_set_qdata_full() instead.
443 <!-- ##### FUNCTION gtk_object_get_data_by_id ##### -->
445 Just like gtk_object_get_data() except that it takes
446 a #GQuark instead of a string, so it is slightly faster.
449 Use gtk_object_data_try_key() and gtk_object_data_force_id()
450 to get an id from a string.
453 @object: object containing the associations.
454 @data_id: quark of the key.
455 @Returns: the data if found, or %NULL if no such data exists.
456 @Deprecated: Use g_object_get_qdata() instead.
459 <!-- ##### FUNCTION gtk_object_remove_data_by_id ##### -->
461 Just like gtk_object_remove_data() except that it takes
462 a #GQuark instead of a string, so it is slightly faster.
465 Remove a specified datum from the object's data associations.
466 Subsequent calls to gtk_object_get_data() will return %NULL.
469 Use gtk_object_data_try_key() and gtk_object_data_force_id()
470 to get an id from a string.
473 @object: object containing the associations.
474 @data_id: quark of the key.
475 @Deprecated: Use g_object_set_qdata() with data of %NULL instead.
478 <!-- ##### FUNCTION gtk_object_remove_no_notify_by_id ##### -->
480 Just like gtk_object_remove_no_notify() except that it takes
481 a #GQuark instead of a string, so it is slightly faster.
484 Use gtk_object_data_try_key() and gtk_object_data_force_id()
485 to get an id from a string.
488 @object: object containing the associations.
489 @key_id: quark of the key.
490 @Deprecated: Use g_object_steal_qdata() instead.
493 <!-- ##### MACRO gtk_object_data_try_key ##### -->
495 Useless deprecated macro. Ignore it.
500 <!-- ##### MACRO gtk_object_data_force_id ##### -->
502 Useless deprecated macro. Ignore it.