1 /* GObject - GLib Type, Object, Parameter and Signal Library
2 * Copyright (C) 1998-1999, 2000-2001 Tim Janik and Red Hat, Inc.
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General
15 * Public License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
17 * Boston, MA 02111-1307, USA.
19 #ifndef __G_OBJECT_H__
20 #define __G_OBJECT_H__
22 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
23 #error "Only <glib-object.h> can be included directly."
26 #include <gobject/gtype.h>
27 #include <gobject/gvalue.h>
28 #include <gobject/gparam.h>
29 #include <gobject/gclosure.h>
30 #include <gobject/gsignal.h>
31 #include <gobject/gboxed.h>
35 /* --- type macros --- */
38 * @type: Type id to check
40 * Check if the passed in type id is a %G_TYPE_OBJECT or derived from it.
42 * Returns: %FALSE or %TRUE, indicating whether @type is a %G_TYPE_OBJECT.
44 #define G_TYPE_IS_OBJECT(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_OBJECT)
47 * @object: Object which is subject to casting.
49 * Casts a #GObject or derived pointer into a (GObject*) pointer.
50 * Depending on the current debugging level, this function may invoke
51 * certain runtime checks to identify invalid casts.
53 #define G_OBJECT(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_OBJECT, GObject))
56 * @class: a valid #GObjectClass
58 * Casts a derived #GObjectClass structure into a #GObjectClass structure.
60 #define G_OBJECT_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_OBJECT, GObjectClass))
63 * @object: Instance to check for being a %G_TYPE_OBJECT.
65 * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_OBJECT.
67 #define G_IS_OBJECT(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), G_TYPE_OBJECT))
70 * @class: a #GObjectClass
72 * Checks whether @class "is a" valid #GObjectClass structure of type
73 * %G_TYPE_OBJECT or derived.
75 #define G_IS_OBJECT_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_OBJECT))
78 * @object: a #GObject instance.
80 * Get the class structure associated to a #GObject instance.
82 * Returns: pointer to object class structure.
84 #define G_OBJECT_GET_CLASS(object) (G_TYPE_INSTANCE_GET_CLASS ((object), G_TYPE_OBJECT, GObjectClass))
87 * @object: Object to return the type id for.
89 * Get the type id of an object.
91 * Returns: Type id of @object.
93 #define G_OBJECT_TYPE(object) (G_TYPE_FROM_INSTANCE (object))
96 * @object: Object to return the type name for.
98 * Get the name of an object's type.
100 * Returns: Type name of @object. The string is owned by the type system and
101 * should not be freed.
103 #define G_OBJECT_TYPE_NAME(object) (g_type_name (G_OBJECT_TYPE (object)))
105 * G_OBJECT_CLASS_TYPE:
106 * @class: a valid #GObjectClass
108 * Get the type id of a class structure.
110 * Returns: Type id of @class.
112 #define G_OBJECT_CLASS_TYPE(class) (G_TYPE_FROM_CLASS (class))
114 * G_OBJECT_CLASS_NAME:
115 * @class: a valid #GObjectClass
117 * Return the name of a class structure's type.
119 * Returns: Type name of @class. The string is owned by the type system and
120 * should not be freed.
122 #define G_OBJECT_CLASS_NAME(class) (g_type_name (G_OBJECT_CLASS_TYPE (class)))
124 * G_VALUE_HOLDS_OBJECT:
125 * @value: a valid #GValue structure
127 * Checks whether the given #GValue can hold values derived from type %G_TYPE_OBJECT.
129 * Returns: %TRUE on success.
131 #define G_VALUE_HOLDS_OBJECT(value) (G_TYPE_CHECK_VALUE_TYPE ((value), G_TYPE_OBJECT))
133 /* --- type macros --- */
135 * G_TYPE_INITIALLY_UNOWNED:
137 * The type for #GInitiallyUnowned.
139 #define G_TYPE_INITIALLY_UNOWNED (g_initially_unowned_get_type())
141 * G_INITIALLY_UNOWNED:
142 * @object: Object which is subject to casting.
144 * Casts a #GInitiallyUnowned or derived pointer into a (GInitiallyUnowned*)
145 * pointer. Depending on the current debugging level, this function may invoke
146 * certain runtime checks to identify invalid casts.
148 #define G_INITIALLY_UNOWNED(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), G_TYPE_INITIALLY_UNOWNED, GInitiallyUnowned))
150 * G_INITIALLY_UNOWNED_CLASS:
151 * @class: a valid #GInitiallyUnownedClass
153 * Casts a derived #GInitiallyUnownedClass structure into a
154 * #GInitiallyUnownedClass structure.
156 #define G_INITIALLY_UNOWNED_CLASS(class) (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_INITIALLY_UNOWNED, GInitiallyUnownedClass))
158 * G_IS_INITIALLY_UNOWNED:
159 * @object: Instance to check for being a %G_TYPE_INITIALLY_UNOWNED.
161 * Checks whether a valid #GTypeInstance pointer is of type %G_TYPE_INITIALLY_UNOWNED.
163 #define G_IS_INITIALLY_UNOWNED(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), G_TYPE_INITIALLY_UNOWNED))
165 * G_IS_INITIALLY_UNOWNED_CLASS:
166 * @class: a #GInitiallyUnownedClass
168 * Checks whether @class "is a" valid #GInitiallyUnownedClass structure of type
169 * %G_TYPE_INITIALLY_UNOWNED or derived.
171 #define G_IS_INITIALLY_UNOWNED_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_INITIALLY_UNOWNED))
173 * G_INITIALLY_UNOWNED_GET_CLASS:
174 * @object: a #GInitiallyUnowned instance.
176 * Get the class structure associated to a #GInitiallyUnowned instance.
178 * Returns: pointer to object class structure.
180 #define G_INITIALLY_UNOWNED_GET_CLASS(object) (G_TYPE_INSTANCE_GET_CLASS ((object), G_TYPE_INITIALLY_UNOWNED, GInitiallyUnownedClass))
181 /* GInitiallyUnowned ia a GObject with initially floating reference count */
184 /* --- typedefs & structures --- */
185 typedef struct _GObject GObject
;
186 typedef struct _GObjectClass GObjectClass
;
187 typedef struct _GObject GInitiallyUnowned
;
188 typedef struct _GObjectClass GInitiallyUnownedClass
;
189 typedef struct _GObjectConstructParam GObjectConstructParam
;
191 * GObjectGetPropertyFunc:
192 * @object: a #GObject
193 * @property_id: the numeric id under which the property was registered with
194 * g_object_class_install_property().
195 * @value: a #GValue to return the property value in
196 * @pspec: the #GParamSpec describing the property
198 * The type of the @get_property function of #GObjectClass.
200 typedef void (*GObjectGetPropertyFunc
) (GObject
*object
,
205 * GObjectSetPropertyFunc:
206 * @object: a #GObject
207 * @property_id: the numeric id under which the property was registered with
208 * g_object_class_install_property().
209 * @value: the new value for the property
210 * @pspec: the #GParamSpec describing the property
212 * The type of the @set_property function of #GObjectClass.
214 typedef void (*GObjectSetPropertyFunc
) (GObject
*object
,
219 * GObjectFinalizeFunc:
220 * @object: the #GObject being finalized
222 * The type of the @finalize function of #GObjectClass.
224 typedef void (*GObjectFinalizeFunc
) (GObject
*object
);
227 * @data: data that was provided when the weak reference was established
228 * @where_the_object_was: the object being finalized
230 * A #GWeakNotify function can be added to an object as a callback that gets
231 * triggered when the object is finalized. Since the object is already being
232 * finalized when the #GWeakNotify is called, there's not much you could do
233 * with the object, apart from e.g. using its address as hash-index or the like.
235 typedef void (*GWeakNotify
) (gpointer data
,
236 GObject
*where_the_object_was
);
240 * All the fields in the <structname>GObject</structname> structure are private
241 * to the #GObject implementation and should never be accessed directly.
245 GTypeInstance g_type_instance
;
248 volatile guint ref_count
;
253 * @g_type_class: the parent class
254 * @constructor: the @constructor function is called by g_object_new () to
255 * complete the object initialization after all the construction properties are
256 * set. The first thing a @constructor implementation must do is chain up to the
257 * @constructor of the parent class. Overriding @constructor should be rarely
258 * needed, e.g. to handle construct properties, or to implement singletons.
259 * @set_property: the generic setter for all properties of this type. Should be
260 * overridden for every type with properties. If implementations of
261 * @set_property don't emit property change notification explicitly, this will
262 * be done implicitly by the type system. However, if the notify signal is
263 * emitted explicitly, the type system will not emit it a second time.
264 * @get_property: the generic getter for all properties of this type. Should be
265 * overridden for every type with properties.
266 * @dispose: the @dispose function is supposed to drop all references to other
267 * objects, but keep the instance otherwise intact, so that client method
268 * invocations still work. It may be run multiple times (due to reference
269 * loops). Before returning, @dispose should chain up to the @dispose method
270 * of the parent class.
271 * @finalize: instance finalization function, should finish the finalization of
272 * the instance begun in @dispose and chain up to the @finalize method of the
274 * @dispatch_properties_changed: emits property change notification for a bunch
275 * of properties. Overriding @dispatch_properties_changed should be rarely
277 * @notify: the class closure for the notify signal
278 * @constructed: the @constructed function is called by g_object_new() as the
279 * final step of the object creation process. At the point of the call, all
280 * construction properties have been set on the object. The purpose of this
281 * call is to allow for object initialisation steps that can only be performed
282 * after construction properties have been set. @constructed implementors
283 * should chain up to the @constructed call of their parent class to allow it
284 * to complete its initialisation.
286 * The class structure for the <structname>GObject</structname> type.
289 * <title>Implementing singletons using a constructor</title>
291 * static MySingleton *the_singleton = NULL;
294 * my_singleton_constructor (GType type,
295 * guint n_construct_params,
296 * GObjectConstructParam *construct_params)
300 * if (!the_singleton)
302 * object = G_OBJECT_CLASS (parent_class)->constructor (type,
303 * n_construct_params,
305 * the_singleton = MY_SINGLETON (object);
308 * object = g_object_ref (G_OBJECT (the_singleton));
312 * </programlisting></example>
316 GTypeClass g_type_class
;
319 GSList
*construct_properties
;
322 /* seldom overidden */
323 GObject
* (*constructor
) (GType type
,
324 guint n_construct_properties
,
325 GObjectConstructParam
*construct_properties
);
326 /* overridable methods */
327 void (*set_property
) (GObject
*object
,
331 void (*get_property
) (GObject
*object
,
335 void (*dispose
) (GObject
*object
);
336 void (*finalize
) (GObject
*object
);
337 /* seldom overidden */
338 void (*dispatch_properties_changed
) (GObject
*object
,
340 GParamSpec
**pspecs
);
342 void (*notify
) (GObject
*object
,
345 /* called when done constructing */
346 void (*constructed
) (GObject
*object
);
355 * GObjectConstructParam:
356 * @pspec: the #GParamSpec of the construct parameter
357 * @value: the value to set the parameter to
359 * The <structname>GObjectConstructParam</structname> struct is an auxiliary
360 * structure used to hand #GParamSpec/#GValue pairs to the @constructor of
363 struct _GObjectConstructParam
372 * All the fields in the <structname>GInitiallyUnowned</structname> structure
373 * are private to the #GInitiallyUnowned implementation and should never be
377 * GInitiallyUnownedClass:
379 * The class structure for the <structname>GInitiallyUnowned</structname> type.
383 /* --- prototypes --- */
384 GLIB_AVAILABLE_IN_ALL
385 GType
g_initially_unowned_get_type (void);
386 GLIB_AVAILABLE_IN_ALL
387 void g_object_class_install_property (GObjectClass
*oclass
,
390 GLIB_AVAILABLE_IN_ALL
391 GParamSpec
* g_object_class_find_property (GObjectClass
*oclass
,
392 const gchar
*property_name
);
393 GLIB_AVAILABLE_IN_ALL
394 GParamSpec
**g_object_class_list_properties (GObjectClass
*oclass
,
395 guint
*n_properties
);
396 GLIB_AVAILABLE_IN_ALL
397 void g_object_class_override_property (GObjectClass
*oclass
,
400 GLIB_AVAILABLE_IN_ALL
401 void g_object_class_install_properties (GObjectClass
*oclass
,
403 GParamSpec
**pspecs
);
405 GLIB_AVAILABLE_IN_ALL
406 void g_object_interface_install_property (gpointer g_iface
,
408 GLIB_AVAILABLE_IN_ALL
409 GParamSpec
* g_object_interface_find_property (gpointer g_iface
,
410 const gchar
*property_name
);
411 GLIB_AVAILABLE_IN_ALL
412 GParamSpec
**g_object_interface_list_properties (gpointer g_iface
,
413 guint
*n_properties_p
);
415 GLIB_AVAILABLE_IN_ALL
416 GType
g_object_get_type (void) G_GNUC_CONST
;
417 GLIB_AVAILABLE_IN_ALL
418 gpointer
g_object_new (GType object_type
,
419 const gchar
*first_property_name
,
421 GLIB_AVAILABLE_IN_ALL
422 gpointer
g_object_newv (GType object_type
,
424 GParameter
*parameters
);
425 GLIB_AVAILABLE_IN_ALL
426 GObject
* g_object_new_valist (GType object_type
,
427 const gchar
*first_property_name
,
429 GLIB_AVAILABLE_IN_ALL
430 void g_object_set (gpointer object
,
431 const gchar
*first_property_name
,
432 ...) G_GNUC_NULL_TERMINATED
;
433 GLIB_AVAILABLE_IN_ALL
434 void g_object_get (gpointer object
,
435 const gchar
*first_property_name
,
436 ...) G_GNUC_NULL_TERMINATED
;
437 GLIB_AVAILABLE_IN_ALL
438 gpointer
g_object_connect (gpointer object
,
439 const gchar
*signal_spec
,
440 ...) G_GNUC_NULL_TERMINATED
;
441 GLIB_AVAILABLE_IN_ALL
442 void g_object_disconnect (gpointer object
,
443 const gchar
*signal_spec
,
444 ...) G_GNUC_NULL_TERMINATED
;
445 GLIB_AVAILABLE_IN_ALL
446 void g_object_set_valist (GObject
*object
,
447 const gchar
*first_property_name
,
449 GLIB_AVAILABLE_IN_ALL
450 void g_object_get_valist (GObject
*object
,
451 const gchar
*first_property_name
,
453 GLIB_AVAILABLE_IN_ALL
454 void g_object_set_property (GObject
*object
,
455 const gchar
*property_name
,
456 const GValue
*value
);
457 GLIB_AVAILABLE_IN_ALL
458 void g_object_get_property (GObject
*object
,
459 const gchar
*property_name
,
461 GLIB_AVAILABLE_IN_ALL
462 void g_object_freeze_notify (GObject
*object
);
463 GLIB_AVAILABLE_IN_ALL
464 void g_object_notify (GObject
*object
,
465 const gchar
*property_name
);
466 GLIB_AVAILABLE_IN_ALL
467 void g_object_notify_by_pspec (GObject
*object
,
469 GLIB_AVAILABLE_IN_ALL
470 void g_object_thaw_notify (GObject
*object
);
471 GLIB_AVAILABLE_IN_ALL
472 gboolean
g_object_is_floating (gpointer object
);
473 GLIB_AVAILABLE_IN_ALL
474 gpointer
g_object_ref_sink (gpointer object
);
475 GLIB_AVAILABLE_IN_ALL
476 gpointer
g_object_ref (gpointer object
);
477 GLIB_AVAILABLE_IN_ALL
478 void g_object_unref (gpointer object
);
479 GLIB_AVAILABLE_IN_ALL
480 void g_object_weak_ref (GObject
*object
,
483 GLIB_AVAILABLE_IN_ALL
484 void g_object_weak_unref (GObject
*object
,
487 GLIB_AVAILABLE_IN_ALL
488 void g_object_add_weak_pointer (GObject
*object
,
489 gpointer
*weak_pointer_location
);
490 GLIB_AVAILABLE_IN_ALL
491 void g_object_remove_weak_pointer (GObject
*object
,
492 gpointer
*weak_pointer_location
);
496 * @data: Callback data passed to g_object_add_toggle_ref()
497 * @object: The object on which g_object_add_toggle_ref() was called.
498 * @is_last_ref: %TRUE if the toggle reference is now the
499 * last reference to the object. %FALSE if the toggle
500 * reference was the last reference and there are now other
503 * A callback function used for notification when the state
504 * of a toggle reference changes. See g_object_add_toggle_ref().
506 typedef void (*GToggleNotify
) (gpointer data
,
508 gboolean is_last_ref
);
510 GLIB_AVAILABLE_IN_ALL
511 void g_object_add_toggle_ref (GObject
*object
,
512 GToggleNotify notify
,
514 GLIB_AVAILABLE_IN_ALL
515 void g_object_remove_toggle_ref (GObject
*object
,
516 GToggleNotify notify
,
519 GLIB_AVAILABLE_IN_ALL
520 gpointer
g_object_get_qdata (GObject
*object
,
522 GLIB_AVAILABLE_IN_ALL
523 void g_object_set_qdata (GObject
*object
,
526 GLIB_AVAILABLE_IN_ALL
527 void g_object_set_qdata_full (GObject
*object
,
530 GDestroyNotify destroy
);
531 GLIB_AVAILABLE_IN_ALL
532 gpointer
g_object_steal_qdata (GObject
*object
,
535 GLIB_AVAILABLE_IN_2_34
536 gpointer
g_object_dup_qdata (GObject
*object
,
538 GDuplicateFunc dup_func
,
540 GLIB_AVAILABLE_IN_2_34
541 gboolean
g_object_replace_qdata (GObject
*object
,
545 GDestroyNotify destroy
,
546 GDestroyNotify
*old_destroy
);
548 GLIB_AVAILABLE_IN_ALL
549 gpointer
g_object_get_data (GObject
*object
,
551 GLIB_AVAILABLE_IN_ALL
552 void g_object_set_data (GObject
*object
,
555 GLIB_AVAILABLE_IN_ALL
556 void g_object_set_data_full (GObject
*object
,
559 GDestroyNotify destroy
);
560 GLIB_AVAILABLE_IN_ALL
561 gpointer
g_object_steal_data (GObject
*object
,
564 GLIB_AVAILABLE_IN_2_34
565 gpointer
g_object_dup_data (GObject
*object
,
567 GDuplicateFunc dup_func
,
569 GLIB_AVAILABLE_IN_2_34
570 gboolean
g_object_replace_data (GObject
*object
,
574 GDestroyNotify destroy
,
575 GDestroyNotify
*old_destroy
);
578 GLIB_AVAILABLE_IN_ALL
579 void g_object_watch_closure (GObject
*object
,
581 GLIB_AVAILABLE_IN_ALL
582 GClosure
* g_cclosure_new_object (GCallback callback_func
,
584 GLIB_AVAILABLE_IN_ALL
585 GClosure
* g_cclosure_new_object_swap (GCallback callback_func
,
587 GLIB_AVAILABLE_IN_ALL
588 GClosure
* g_closure_new_object (guint sizeof_closure
,
590 GLIB_AVAILABLE_IN_ALL
591 void g_value_set_object (GValue
*value
,
593 GLIB_AVAILABLE_IN_ALL
594 gpointer
g_value_get_object (const GValue
*value
);
595 GLIB_AVAILABLE_IN_ALL
596 gpointer
g_value_dup_object (const GValue
*value
);
597 GLIB_AVAILABLE_IN_ALL
598 gulong
g_signal_connect_object (gpointer instance
,
599 const gchar
*detailed_signal
,
602 GConnectFlags connect_flags
);
605 GLIB_AVAILABLE_IN_ALL
606 void g_object_force_floating (GObject
*object
);
607 GLIB_AVAILABLE_IN_ALL
608 void g_object_run_dispose (GObject
*object
);
611 GLIB_AVAILABLE_IN_ALL
612 void g_value_take_object (GValue
*value
,
614 GLIB_DEPRECATED_FOR(g_value_take_object
)
615 void g_value_set_object_take_ownership (GValue
*value
,
619 gsize
g_object_compat_control (gsize what
,
622 /* --- implementation macros --- */
623 #define G_OBJECT_WARN_INVALID_PSPEC(object, pname, property_id, pspec) \
625 GObject *_glib__object = (GObject*) (object); \
626 GParamSpec *_glib__pspec = (GParamSpec*) (pspec); \
627 guint _glib__property_id = (property_id); \
628 g_warning ("%s: invalid %s id %u for \"%s\" of type '%s' in '%s'", \
631 _glib__property_id, \
632 _glib__pspec->name, \
633 g_type_name (G_PARAM_SPEC_TYPE (_glib__pspec)), \
634 G_OBJECT_TYPE_NAME (_glib__object)); \
637 * G_OBJECT_WARN_INVALID_PROPERTY_ID:
638 * @object: the #GObject on which set_property() or get_property() was called
639 * @property_id: the numeric id of the property
640 * @pspec: the #GParamSpec of the property
642 * This macro should be used to emit a standard warning about unexpected
643 * properties in set_property() and get_property() implementations.
645 #define G_OBJECT_WARN_INVALID_PROPERTY_ID(object, property_id, pspec) \
646 G_OBJECT_WARN_INVALID_PSPEC ((object), "property", (property_id), (pspec))
648 GLIB_AVAILABLE_IN_ALL
649 void g_clear_object (volatile GObject
**object_ptr
);
650 #define g_clear_object(object_ptr) g_clear_pointer ((object_ptr), g_object_unref)
654 union { gpointer p
; } priv
;
657 GLIB_AVAILABLE_IN_ALL
658 void g_weak_ref_init (GWeakRef
*weak_ref
,
660 GLIB_AVAILABLE_IN_ALL
661 void g_weak_ref_clear (GWeakRef
*weak_ref
);
662 GLIB_AVAILABLE_IN_ALL
663 gpointer
g_weak_ref_get (GWeakRef
*weak_ref
);
664 GLIB_AVAILABLE_IN_ALL
665 void g_weak_ref_set (GWeakRef
*weak_ref
,
670 #endif /* __G_OBJECT_H__ */