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 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
20 #error "Only <glib-object.h> can be included directly."
23 #ifndef __G_OBJECT_H__
24 #define __G_OBJECT_H__
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. Implementations of @set_property
261 * don't need to emit property change notification explicitly, this is handled
262 * by the type system.
263 * @get_property: the generic getter for all properties of this type. Should be
264 * overridden for every type with properties.
265 * @dispose: the @dispose function is supposed to drop all references to other
266 * objects, but keep the instance otherwise intact, so that client method
267 * invocations still work. It may be run multiple times (due to reference
268 * loops). Before returning, @dispose should chain up to the @dispose method
269 * of the parent class.
270 * @finalize: instance finalization function, should finish the finalization of
271 * the instance begun in @dispose and chain up to the @finalize method of the
273 * @dispatch_properties_changed: emits property change notification for a bunch
274 * of properties. Overriding @dispatch_properties_changed should be rarely
276 * @notify: the class closure for the notify signal
277 * @constructed: the @constructed function is called by g_object_new() as the
278 * final step of the object creation process. At the point of the call, all
279 * construction properties have been set on the object. The purpose of this
280 * call is to allow for object initialisation steps that can only be performed
281 * after construction properties have been set. @constructed implementors
282 * should chain up to the @constructed call of their parent class to allow it
283 * to complete its initialisation.
285 * The class structure for the <structname>GObject</structname> type.
288 * <title>Implementing singletons using a constructor</title>
290 * static MySingleton *the_singleton = NULL;
293 * my_singleton_constructor (GType type,
294 * guint n_construct_params,
295 * GObjectConstructParam *construct_params)
299 * if (!the_singleton)
301 * object = G_OBJECT_CLASS (parent_class)->constructor (type,
302 * n_construct_params,
304 * the_singleton = MY_SINGLETON (object);
307 * object = g_object_ref (G_OBJECT (the_singleton));
311 * </programlisting></example>
315 GTypeClass g_type_class;
318 GSList *construct_properties;
321 /* seldom overidden */
322 GObject* (*constructor) (GType type,
323 guint n_construct_properties,
324 GObjectConstructParam *construct_properties);
325 /* overridable methods */
326 void (*set_property) (GObject *object,
330 void (*get_property) (GObject *object,
334 void (*dispose) (GObject *object);
335 void (*finalize) (GObject *object);
336 /* seldom overidden */
337 void (*dispatch_properties_changed) (GObject *object,
339 GParamSpec **pspecs);
341 void (*notify) (GObject *object,
344 /* called when done constructing */
345 void (*constructed) (GObject *object);
354 * GObjectConstructParam:
355 * @pspec: the #GParamSpec of the construct parameter
356 * @value: the value to set the parameter to
358 * The <structname>GObjectConstructParam</structname> struct is an auxiliary
359 * structure used to hand #GParamSpec/#GValue pairs to the @constructor of
362 struct _GObjectConstructParam
371 * All the fields in the <structname>GInitiallyUnowned</structname> structure
372 * are private to the #GInitiallyUnowned implementation and should never be
376 * GInitiallyUnownedClass:
378 * The class structure for the <structname>GInitiallyUnowned</structname> type.
382 /* --- prototypes --- */
383 GType g_initially_unowned_get_type (void);
384 void g_object_class_install_property (GObjectClass *oclass,
387 GParamSpec* g_object_class_find_property (GObjectClass *oclass,
388 const gchar *property_name);
389 GParamSpec**g_object_class_list_properties (GObjectClass *oclass,
390 guint *n_properties);
391 void g_object_class_override_property (GObjectClass *oclass,
394 void g_object_class_install_properties (GObjectClass *oclass,
396 GParamSpec **pspecs);
398 void g_object_interface_install_property (gpointer g_iface,
400 GParamSpec* g_object_interface_find_property (gpointer g_iface,
401 const gchar *property_name);
402 GParamSpec**g_object_interface_list_properties (gpointer g_iface,
403 guint *n_properties_p);
405 GType g_object_get_type (void) G_GNUC_CONST;
406 gpointer g_object_new (GType object_type,
407 const gchar *first_property_name,
409 gpointer g_object_newv (GType object_type,
411 GParameter *parameters);
412 GObject* g_object_new_valist (GType object_type,
413 const gchar *first_property_name,
415 void g_object_set (gpointer object,
416 const gchar *first_property_name,
417 ...) G_GNUC_NULL_TERMINATED;
418 void g_object_get (gpointer object,
419 const gchar *first_property_name,
420 ...) G_GNUC_NULL_TERMINATED;
421 gpointer g_object_connect (gpointer object,
422 const gchar *signal_spec,
423 ...) G_GNUC_NULL_TERMINATED;
424 void g_object_disconnect (gpointer object,
425 const gchar *signal_spec,
426 ...) G_GNUC_NULL_TERMINATED;
427 void g_object_set_valist (GObject *object,
428 const gchar *first_property_name,
430 void g_object_get_valist (GObject *object,
431 const gchar *first_property_name,
433 void g_object_set_property (GObject *object,
434 const gchar *property_name,
435 const GValue *value);
436 void g_object_get_property (GObject *object,
437 const gchar *property_name,
439 void g_object_freeze_notify (GObject *object);
440 void g_object_notify (GObject *object,
441 const gchar *property_name);
442 void g_object_notify_by_pspec (GObject *object,
444 void g_object_thaw_notify (GObject *object);
445 gboolean g_object_is_floating (gpointer object);
446 gpointer g_object_ref_sink (gpointer object);
447 gpointer g_object_ref (gpointer object);
448 void g_object_unref (gpointer object);
449 void g_object_weak_ref (GObject *object,
452 void g_object_weak_unref (GObject *object,
455 void g_object_add_weak_pointer (GObject *object,
456 gpointer *weak_pointer_location);
457 void g_object_remove_weak_pointer (GObject *object,
458 gpointer *weak_pointer_location);
462 * @data: Callback data passed to g_object_add_toggle_ref()
463 * @object: The object on which g_object_add_toggle_ref() was called.
464 * @is_last_ref: %TRUE if the toggle reference is now the
465 * last reference to the object. %FALSE if the toggle
466 * reference was the last reference and there are now other
469 * A callback function used for notification when the state
470 * of a toggle reference changes. See g_object_add_toggle_ref().
472 typedef void (*GToggleNotify) (gpointer data,
474 gboolean is_last_ref);
476 void g_object_add_toggle_ref (GObject *object,
477 GToggleNotify notify,
479 void g_object_remove_toggle_ref (GObject *object,
480 GToggleNotify notify,
483 gpointer g_object_get_qdata (GObject *object,
485 void g_object_set_qdata (GObject *object,
488 void g_object_set_qdata_full (GObject *object,
491 GDestroyNotify destroy);
492 gpointer g_object_steal_qdata (GObject *object,
495 GLIB_AVAILABLE_IN_2_34
496 gpointer g_object_dup_qdata (GObject *object,
498 GDuplicateFunc dup_func,
500 GLIB_AVAILABLE_IN_2_34
501 gboolean g_object_replace_qdata (GObject *object,
505 GDestroyNotify destroy,
506 GDestroyNotify *old_destroy);
508 gpointer g_object_get_data (GObject *object,
510 void g_object_set_data (GObject *object,
513 void g_object_set_data_full (GObject *object,
516 GDestroyNotify destroy);
517 gpointer g_object_steal_data (GObject *object,
520 GLIB_AVAILABLE_IN_2_34
521 gpointer g_object_dup_data (GObject *object,
523 GDuplicateFunc dup_func,
525 GLIB_AVAILABLE_IN_2_34
526 gboolean g_object_replace_data (GObject *object,
530 GDestroyNotify destroy,
531 GDestroyNotify *old_destroy);
534 void g_object_watch_closure (GObject *object,
536 GClosure* g_cclosure_new_object (GCallback callback_func,
538 GClosure* g_cclosure_new_object_swap (GCallback callback_func,
540 GClosure* g_closure_new_object (guint sizeof_closure,
542 void g_value_set_object (GValue *value,
544 gpointer g_value_get_object (const GValue *value);
545 gpointer g_value_dup_object (const GValue *value);
546 gulong g_signal_connect_object (gpointer instance,
547 const gchar *detailed_signal,
550 GConnectFlags connect_flags);
553 void g_object_force_floating (GObject *object);
554 void g_object_run_dispose (GObject *object);
557 void g_value_take_object (GValue *value,
559 GLIB_DEPRECATED_FOR(g_value_take_object)
560 void g_value_set_object_take_ownership (GValue *value,
564 gsize g_object_compat_control (gsize what,
567 /* --- implementation macros --- */
568 #define G_OBJECT_WARN_INVALID_PSPEC(object, pname, property_id, pspec) \
570 GObject *_object = (GObject*) (object); \
571 GParamSpec *_pspec = (GParamSpec*) (pspec); \
572 guint _property_id = (property_id); \
573 g_warning ("%s: invalid %s id %u for \"%s\" of type `%s' in `%s'", \
578 g_type_name (G_PARAM_SPEC_TYPE (_pspec)), \
579 G_OBJECT_TYPE_NAME (_object)); \
582 * G_OBJECT_WARN_INVALID_PROPERTY_ID:
583 * @object: the #GObject on which set_property() or get_property() was called
584 * @property_id: the numeric id of the property
585 * @pspec: the #GParamSpec of the property
587 * This macro should be used to emit a standard warning about unexpected
588 * properties in set_property() and get_property() implementations.
590 #define G_OBJECT_WARN_INVALID_PROPERTY_ID(object, property_id, pspec) \
591 G_OBJECT_WARN_INVALID_PSPEC ((object), "property", (property_id), (pspec))
593 void g_clear_object (volatile GObject **object_ptr);
594 #define g_clear_object(object_ptr) g_clear_pointer ((object_ptr), g_object_unref)
598 union { gpointer p; } priv;
601 void g_weak_ref_init (GWeakRef *weak_ref,
603 void g_weak_ref_clear (GWeakRef *weak_ref);
604 gpointer g_weak_ref_get (GWeakRef *weak_ref);
605 void g_weak_ref_set (GWeakRef *weak_ref,
610 #endif /* __G_OBJECT_H__ */