1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
7 <!-- ##### SECTION Long_Description ##### -->
12 <!-- ##### SECTION See_Also ##### -->
17 <!-- ##### STRUCT GObject ##### -->
19 All the fields in the GObject structure are private to the #GObject implementation
20 and should never be accessed directly.
25 <!-- ##### STRUCT GObjectClass ##### -->
31 <!-- ##### USER_FUNCTION GObjectGetPropertyFunc ##### -->
40 <!-- # Unused Parameters # -->
44 <!-- ##### USER_FUNCTION GObjectSetPropertyFunc ##### -->
53 <!-- # Unused Parameters # -->
57 <!-- ##### USER_FUNCTION GObjectFinalizeFunc ##### -->
65 <!-- ##### MACRO G_TYPE_IS_OBJECT ##### -->
67 Return a boolean value of %FALSE or %TRUE indicating whether
68 the passed in type id is a %G_TYPE_OBJECT or derived from it.
71 @type: Type id to check for is a %G_TYPE_OBJECT relationship.
72 @Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT.
75 <!-- ##### MACRO G_OBJECT ##### -->
77 Cast a #GObject or derived pointer into a (GObject*) pointer.
78 Depending on the current debugging level, this function may invoke
79 certain runtime checks to identify invalid casts.
82 @object: Object which is subject to casting.
85 <!-- ##### MACRO G_IS_OBJECT ##### -->
87 Check whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
90 @object: Instance to check for being a %G_TYPE_OBJECT.
93 <!-- ##### MACRO G_OBJECT_CLASS ##### -->
101 <!-- ##### MACRO G_IS_OBJECT_CLASS ##### -->
109 <!-- ##### MACRO G_OBJECT_GET_CLASS ##### -->
117 <!-- ##### MACRO G_OBJECT_TYPE ##### -->
119 Return the type id of an object.
122 @object: Object to return the type id for.
123 @Returns: Type id of @object.
126 <!-- ##### MACRO G_OBJECT_TYPE_NAME ##### -->
134 <!-- ##### MACRO G_OBJECT_CLASS_TYPE ##### -->
142 <!-- ##### MACRO G_OBJECT_CLASS_NAME ##### -->
150 <!-- ##### FUNCTION g_object_class_install_property ##### -->
160 <!-- ##### FUNCTION g_object_class_find_property ##### -->
170 <!-- ##### FUNCTION g_object_class_list_properties ##### -->
180 <!-- ##### FUNCTION g_object_new ##### -->
186 @first_property_name:
189 <!-- # Unused Parameters # -->
193 <!-- ##### FUNCTION g_object_newv ##### -->
204 <!-- ##### STRUCT GParameter ##### -->
212 <!-- ##### FUNCTION g_object_ref ##### -->
221 <!-- ##### FUNCTION g_object_unref ##### -->
229 <!-- ##### USER_FUNCTION GWeakNotify ##### -->
235 @where_the_object_was:
238 <!-- ##### FUNCTION g_object_weak_ref ##### -->
248 <!-- ##### FUNCTION g_object_weak_unref ##### -->
258 <!-- ##### FUNCTION g_object_add_weak_pointer ##### -->
260 Adds a weak reference from weak_pointer to @object to indicate that
261 the pointer located at @weak_pointer_location is only valid during the
262 lifetime of @object. When the @object is finalized, @weak_pointer will
266 @object: The object that should be weak referenced.
267 @weak_pointer_location: The memory address of a pointer.
270 <!-- ##### FUNCTION g_object_remove_weak_pointer ##### -->
272 Removes a weak reference from @object that was previously added
273 using g_object_add_weak_pointer(). The @weak_pointer_location has
274 to match the one used with g_object_add_weak_pointer().
277 @object: The object that is weak referenced.
278 @weak_pointer_location: The memory address of a pointer.
281 <!-- ##### FUNCTION g_object_connect ##### -->
292 <!-- ##### FUNCTION g_object_disconnect ##### -->
300 <!-- # Unused Parameters # -->
304 <!-- ##### FUNCTION g_object_set ##### -->
310 @first_property_name:
312 <!-- # Unused Parameters # -->
316 <!-- ##### FUNCTION g_object_get ##### -->
322 @first_property_name:
326 <!-- ##### FUNCTION g_object_notify ##### -->
335 <!-- ##### FUNCTION g_object_freeze_notify ##### -->
343 <!-- ##### FUNCTION g_object_thaw_notify ##### -->
351 <!-- ##### FUNCTION g_object_get_data ##### -->
361 <!-- ##### FUNCTION g_object_set_data ##### -->
371 <!-- ##### FUNCTION g_object_set_data_full ##### -->
382 <!-- ##### FUNCTION g_object_steal_data ##### -->
392 <!-- ##### FUNCTION g_object_get_qdata ##### -->
394 This function gets back user data pointers stored via
395 g_object_set_qdata().
398 @object: The GObject to get a stored user data pointer from
399 @quark: A #GQuark, naming the user data pointer
400 @Returns: The user data pointer set, or %NULL
403 <!-- ##### FUNCTION g_object_set_qdata ##### -->
405 This sets an opaque, named pointer on an object.
406 The name is specified through a #GQuark (retrived e.g. via
407 g_quark_from_static_string()), and the pointer
408 can be gotten back from the @object with g_object_get_qdata()
409 until the @object is finalized.
410 Setting a previously set user data pointer, overrides (frees)
411 the old pointer set, using #NULL as pointer essentially
412 removes the data stored.
415 @object: The GObject to set store a user data pointer
416 @quark: A #GQuark, naming the user data pointer
417 @data: An opaque user data pointer
420 <!-- ##### FUNCTION g_object_set_qdata_full ##### -->
422 This function works like g_object_set_qdata(), but in addition,
423 a void (*destroy) (gpointer) function may be specified which is
424 called with @data as argument when the @object is finalized, or
425 the data is being overwritten by a call to g_object_set_qdata()
426 with the same @quark.
429 @object: The GObject to set store a user data pointer
430 @quark: A #GQuark, naming the user data pointer
431 @data: An opaque user data pointer
432 @destroy: Function to invoke with @data as argument, when @data needs to be freed
435 <!-- ##### FUNCTION g_object_steal_qdata ##### -->
437 This function gets back user data pointers stored via
438 g_object_set_qdata() and removes the @data from object
439 without invoking it's destroy() function (if any was
441 Usually, calling this function is only required to update
442 user data pointers with a destroy notifier, for example:
443 <msgtext><programlisting>
445 object_add_to_user_list (GObject *object,
446 const gchar *new_string)
448 /* the quark, naming the object data */
449 GQuark quark_string_list = g_quark_from_static_string ("my-string-list");
450 /* retrive the old string list */
451 GList *list = g_object_steal_qdata (object, quark_string_list);
453 /* prepend new string */
454 list = g_list_prepend (list, g_strdup (new_string));
455 /* this changed 'list', so we need to set it again */
456 g_object_set_qdata_full (object, quark_string_list, list, free_string_list);
459 free_string_list (gpointer data)
461 GList *node, *list = data;
463 for (node = list; node; node = node->next)
467 </programlisting></msgtext>
468 Using g_object_get_qdata() in the above example, instead of g_object_steal_qdata()
469 would have left the destroy function set, and thus the partial string list would
470 have been freed upon g_object_set_qdata_full().
473 @object: The GObject to get a stored user data pointer from
474 @quark: A #GQuark, naming the user data pointer
475 @Returns: The user data pointer set, or %NULL
478 <!-- ##### FUNCTION g_object_set_property ##### -->
488 <!-- ##### FUNCTION g_object_get_property ##### -->
498 <!-- ##### FUNCTION g_object_new_valist ##### -->
504 @first_property_name:
509 <!-- ##### FUNCTION g_object_set_valist ##### -->
515 @first_property_name:
519 <!-- ##### FUNCTION g_object_get_valist ##### -->
525 @first_property_name:
529 <!-- ##### FUNCTION g_object_watch_closure ##### -->
531 This function essentially limits the life time of the @closure
532 to the life time of the object. That is, when the object is finalized,
533 the @closure is invalidated by calling g_closure_invalidate() on it,
534 in order to prevent invocations of the closure with a finalized (non
535 existing) object. Also, g_object_ref() and g_object_unref() are added
536 as marshal guards to the @closure, to ensure that an extra reference
537 count is held on @object during invocation of the @closure.
538 Usually, this function will be called on closures that use this @object
542 @object: GObject restricting lifetime of @closure
543 @closure: GClosure to watch
546 <!-- ##### FUNCTION g_object_run_dispose ##### -->
554 <!-- ##### MACRO G_OBJECT_WARN_INVALID_PSPEC ##### -->
565 <!-- ##### MACRO G_OBJECT_WARN_INVALID_PROPERTY_ID ##### -->