Documentation updates.
[glib.git] / gobject / gtype.h
blobc9b93b2fb2cac1a924c82ebe48bfe1baa5da340c
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."
21 #endif
23 #ifndef __G_TYPE_H__
24 #define __G_TYPE_H__
26 #include <glib.h>
28 G_BEGIN_DECLS
30 /* Basic Type Macros
32 #define G_TYPE_FUNDAMENTAL(type) (g_type_fundamental (type))
33 #define G_TYPE_FUNDAMENTAL_MAX (255 << G_TYPE_FUNDAMENTAL_SHIFT)
35 /* Constant fundamental types,
36 * introduced by g_type_init().
38 #define G_TYPE_INVALID G_TYPE_MAKE_FUNDAMENTAL (0)
39 #define G_TYPE_NONE G_TYPE_MAKE_FUNDAMENTAL (1)
40 #define G_TYPE_INTERFACE G_TYPE_MAKE_FUNDAMENTAL (2)
41 #define G_TYPE_CHAR G_TYPE_MAKE_FUNDAMENTAL (3)
42 #define G_TYPE_UCHAR G_TYPE_MAKE_FUNDAMENTAL (4)
43 #define G_TYPE_BOOLEAN G_TYPE_MAKE_FUNDAMENTAL (5)
44 #define G_TYPE_INT G_TYPE_MAKE_FUNDAMENTAL (6)
45 #define G_TYPE_UINT G_TYPE_MAKE_FUNDAMENTAL (7)
46 #define G_TYPE_LONG G_TYPE_MAKE_FUNDAMENTAL (8)
47 #define G_TYPE_ULONG G_TYPE_MAKE_FUNDAMENTAL (9)
48 #define G_TYPE_INT64 G_TYPE_MAKE_FUNDAMENTAL (10)
49 #define G_TYPE_UINT64 G_TYPE_MAKE_FUNDAMENTAL (11)
50 #define G_TYPE_ENUM G_TYPE_MAKE_FUNDAMENTAL (12)
51 #define G_TYPE_FLAGS G_TYPE_MAKE_FUNDAMENTAL (13)
52 #define G_TYPE_FLOAT G_TYPE_MAKE_FUNDAMENTAL (14)
53 #define G_TYPE_DOUBLE G_TYPE_MAKE_FUNDAMENTAL (15)
54 #define G_TYPE_STRING G_TYPE_MAKE_FUNDAMENTAL (16)
55 #define G_TYPE_POINTER G_TYPE_MAKE_FUNDAMENTAL (17)
56 #define G_TYPE_BOXED G_TYPE_MAKE_FUNDAMENTAL (18)
57 #define G_TYPE_PARAM G_TYPE_MAKE_FUNDAMENTAL (19)
58 #define G_TYPE_OBJECT G_TYPE_MAKE_FUNDAMENTAL (20)
61 /* Reserved fundamental type numbers to create new fundamental
62 * type IDs with G_TYPE_MAKE_FUNDAMENTAL().
63 * Send email to gtk-devel-list@redhat.com for reservations.
65 #define G_TYPE_FUNDAMENTAL_SHIFT (2)
66 #define G_TYPE_MAKE_FUNDAMENTAL(x) ((GType) ((x) << G_TYPE_FUNDAMENTAL_SHIFT))
67 #define G_TYPE_RESERVED_GLIB_FIRST (21)
68 #define G_TYPE_RESERVED_GLIB_LAST (31)
69 #define G_TYPE_RESERVED_BSE_FIRST (32)
70 #define G_TYPE_RESERVED_BSE_LAST (48)
71 #define G_TYPE_RESERVED_USER_FIRST (49)
74 /* Type Checking Macros
76 #define G_TYPE_IS_FUNDAMENTAL(type) ((type) <= G_TYPE_FUNDAMENTAL_MAX)
77 #define G_TYPE_IS_DERIVED(type) ((type) > G_TYPE_FUNDAMENTAL_MAX)
78 #define G_TYPE_IS_INTERFACE(type) (G_TYPE_FUNDAMENTAL (type) == G_TYPE_INTERFACE)
79 #define G_TYPE_IS_CLASSED(type) (g_type_test_flags ((type), G_TYPE_FLAG_CLASSED))
80 #define G_TYPE_IS_INSTANTIATABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_INSTANTIATABLE))
81 #define G_TYPE_IS_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DERIVABLE))
82 #define G_TYPE_IS_DEEP_DERIVABLE(type) (g_type_test_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE))
83 #define G_TYPE_IS_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_ABSTRACT))
84 #define G_TYPE_IS_VALUE_ABSTRACT(type) (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT))
85 #define G_TYPE_IS_VALUE_TYPE(type) (g_type_check_is_value_type (type))
86 #define G_TYPE_HAS_VALUE_TABLE(type) (g_type_value_table_peek (type) != NULL)
89 /* Typedefs
91 #if GLIB_SIZEOF_LONG == GLIB_SIZEOF_SIZE_T
92 typedef gulong GType;
93 #else /* hm, shouldn't happen? */
94 typedef gsize GType;
95 #endif
96 typedef struct _GValue GValue;
97 typedef union _GTypeCValue GTypeCValue;
98 typedef struct _GTypePlugin GTypePlugin;
99 typedef struct _GTypeClass GTypeClass;
100 typedef struct _GTypeInterface GTypeInterface;
101 typedef struct _GTypeInstance GTypeInstance;
102 typedef struct _GTypeInfo GTypeInfo;
103 typedef struct _GTypeFundamentalInfo GTypeFundamentalInfo;
104 typedef struct _GInterfaceInfo GInterfaceInfo;
105 typedef struct _GTypeValueTable GTypeValueTable;
106 typedef struct _GTypeQuery GTypeQuery;
109 /* Basic Type Structures
111 struct _GTypeClass
113 /*< private >*/
114 GType g_type;
116 struct _GTypeInstance
118 /*< private >*/
119 GTypeClass *g_class;
121 struct _GTypeInterface
123 /*< private >*/
124 GType g_type; /* iface type */
125 GType g_instance_type;
127 struct _GTypeQuery
129 GType type;
130 const gchar *type_name;
131 guint class_size;
132 guint instance_size;
136 /* Casts, checks and accessors for structured types
137 * usage of these macros is reserved to type implementations only
139 /*< protected >*/
140 #define G_TYPE_CHECK_INSTANCE(instance) (_G_TYPE_CHI ((GTypeInstance*) (instance)))
141 #define G_TYPE_CHECK_INSTANCE_CAST(instance, g_type, c_type) (_G_TYPE_CIC ((instance), (g_type), c_type))
142 #define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type) (_G_TYPE_CIT ((instance), (g_type)))
143 #define G_TYPE_INSTANCE_GET_CLASS(instance, g_type, c_type) (_G_TYPE_IGC ((instance), (g_type), c_type))
144 #define G_TYPE_INSTANCE_GET_INTERFACE(instance, g_type, c_type) (_G_TYPE_IGI ((instance), (g_type), c_type))
145 #define G_TYPE_CHECK_CLASS_CAST(g_class, g_type, c_type) (_G_TYPE_CCC ((g_class), (g_type), c_type))
146 #define G_TYPE_CHECK_CLASS_TYPE(g_class, g_type) (_G_TYPE_CCT ((g_class), (g_type)))
147 #define G_TYPE_CHECK_VALUE(value) (_G_TYPE_CHV ((value)))
148 #define G_TYPE_CHECK_VALUE_TYPE(value, g_type) (_G_TYPE_CVH ((value), (g_type)))
149 #define G_TYPE_FROM_INSTANCE(instance) (G_TYPE_FROM_CLASS (((GTypeInstance*) (instance))->g_class))
150 #define G_TYPE_FROM_CLASS(g_class) (((GTypeClass*) (g_class))->g_type)
151 #define G_TYPE_FROM_INTERFACE(g_iface) (((GTypeInterface*) (g_iface))->g_type)
153 #define G_TYPE_INSTANCE_GET_PRIVATE(instance, g_type, c_type) ((c_type*) g_type_instance_get_private ((GTypeInstance*) (instance), (g_type)))
156 /* debug flags for g_type_init_with_debug_flags() */
157 typedef enum /*< skip >*/
159 G_TYPE_DEBUG_NONE = 0,
160 G_TYPE_DEBUG_OBJECTS = 1 << 0,
161 G_TYPE_DEBUG_SIGNALS = 1 << 1,
162 G_TYPE_DEBUG_MASK = 0x03
163 } GTypeDebugFlags;
166 /* --- prototypes --- */
167 void g_type_init (void);
168 void g_type_init_with_debug_flags (GTypeDebugFlags debug_flags);
169 G_CONST_RETURN gchar* g_type_name (GType type);
170 GQuark g_type_qname (GType type);
171 GType g_type_from_name (const gchar *name);
172 GType g_type_parent (GType type);
173 guint g_type_depth (GType type);
174 GType g_type_next_base (GType leaf_type,
175 GType root_type);
176 gboolean g_type_is_a (GType type,
177 GType is_a_type);
178 gpointer g_type_class_ref (GType type);
179 gpointer g_type_class_peek (GType type);
180 gpointer g_type_class_peek_static (GType type);
181 void g_type_class_unref (gpointer g_class);
182 gpointer g_type_class_peek_parent (gpointer g_class);
183 gpointer g_type_interface_peek (gpointer instance_class,
184 GType iface_type);
185 gpointer g_type_interface_peek_parent (gpointer g_iface);
187 gpointer g_type_default_interface_ref (GType g_type);
188 gpointer g_type_default_interface_peek (GType g_type);
189 void g_type_default_interface_unref (gpointer g_iface);
191 /* g_free() the returned arrays */
192 GType* g_type_children (GType type,
193 guint *n_children);
194 GType* g_type_interfaces (GType type,
195 guint *n_interfaces);
197 /* per-type _static_ data */
198 void g_type_set_qdata (GType type,
199 GQuark quark,
200 gpointer data);
201 gpointer g_type_get_qdata (GType type,
202 GQuark quark);
203 void g_type_query (GType type,
204 GTypeQuery *query);
207 /* --- type registration --- */
208 typedef void (*GBaseInitFunc) (gpointer g_class);
209 typedef void (*GBaseFinalizeFunc) (gpointer g_class);
210 typedef void (*GClassInitFunc) (gpointer g_class,
211 gpointer class_data);
212 typedef void (*GClassFinalizeFunc) (gpointer g_class,
213 gpointer class_data);
214 typedef void (*GInstanceInitFunc) (GTypeInstance *instance,
215 gpointer g_class);
216 typedef void (*GInterfaceInitFunc) (gpointer g_iface,
217 gpointer iface_data);
218 typedef void (*GInterfaceFinalizeFunc) (gpointer g_iface,
219 gpointer iface_data);
220 typedef gboolean (*GTypeClassCacheFunc) (gpointer cache_data,
221 GTypeClass *g_class);
222 typedef void (*GTypeInterfaceCheckFunc) (gpointer func_data,
223 gpointer g_iface);
224 typedef enum /*< skip >*/
226 G_TYPE_FLAG_CLASSED = (1 << 0),
227 G_TYPE_FLAG_INSTANTIATABLE = (1 << 1),
228 G_TYPE_FLAG_DERIVABLE = (1 << 2),
229 G_TYPE_FLAG_DEEP_DERIVABLE = (1 << 3)
230 } GTypeFundamentalFlags;
231 typedef enum /*< skip >*/
233 G_TYPE_FLAG_ABSTRACT = (1 << 4),
234 G_TYPE_FLAG_VALUE_ABSTRACT = (1 << 5)
235 } GTypeFlags;
236 struct _GTypeInfo
238 /* interface types, classed types, instantiated types */
239 guint16 class_size;
241 GBaseInitFunc base_init;
242 GBaseFinalizeFunc base_finalize;
244 /* interface types, classed types, instantiated types */
245 GClassInitFunc class_init;
246 GClassFinalizeFunc class_finalize;
247 gconstpointer class_data;
249 /* instantiated types */
250 guint16 instance_size;
251 guint16 n_preallocs;
252 GInstanceInitFunc instance_init;
254 /* value handling */
255 const GTypeValueTable *value_table;
257 struct _GTypeFundamentalInfo
259 GTypeFundamentalFlags type_flags;
261 struct _GInterfaceInfo
263 GInterfaceInitFunc interface_init;
264 GInterfaceFinalizeFunc interface_finalize;
265 gpointer interface_data;
267 struct _GTypeValueTable
269 void (*value_init) (GValue *value);
270 void (*value_free) (GValue *value);
271 void (*value_copy) (const GValue *src_value,
272 GValue *dest_value);
273 /* varargs functionality (optional) */
274 gpointer (*value_peek_pointer) (const GValue *value);
275 gchar *collect_format;
276 gchar* (*collect_value) (GValue *value,
277 guint n_collect_values,
278 GTypeCValue *collect_values,
279 guint collect_flags);
280 gchar *lcopy_format;
281 gchar* (*lcopy_value) (const GValue *value,
282 guint n_collect_values,
283 GTypeCValue *collect_values,
284 guint collect_flags);
286 GType g_type_register_static (GType parent_type,
287 const gchar *type_name,
288 const GTypeInfo *info,
289 GTypeFlags flags);
290 GType g_type_register_dynamic (GType parent_type,
291 const gchar *type_name,
292 GTypePlugin *plugin,
293 GTypeFlags flags);
294 GType g_type_register_fundamental (GType type_id,
295 const gchar *type_name,
296 const GTypeInfo *info,
297 const GTypeFundamentalInfo *finfo,
298 GTypeFlags flags);
299 void g_type_add_interface_static (GType instance_type,
300 GType interface_type,
301 const GInterfaceInfo *info);
302 void g_type_add_interface_dynamic (GType instance_type,
303 GType interface_type,
304 GTypePlugin *plugin);
305 void g_type_interface_add_prerequisite (GType interface_type,
306 GType prerequisite_type);
307 GType*g_type_interface_prerequisites (GType interface_type,
308 guint *n_prerequisites);
309 void g_type_class_add_private (gpointer g_class,
310 gsize private_size);
311 gpointer g_type_instance_get_private (GTypeInstance *instance,
312 GType private_type);
315 /* --- GType boilerplate --- */
316 /* convenience macros for type implementations, which for a type GtkGadget will:
317 * - prototype: static void gtk_gadget_class_init (GtkGadgetClass *klass);
318 * - prototype: static void gtk_gadget_init (GtkGadget *self);
319 * - define: static gpointer gtk_gadget_parent_class = NULL;
320 * gtk_gadget_parent_class is initialized prior to calling gtk_gadget_class_init()
321 * - implement: GType gtk_gadget_get_type (void) { ... }
322 * - support custom code in gtk_gadget_get_type() after the type is registered.
324 * macro arguments: TypeName, type_name, TYPE_PARENT, CODE
325 * example: G_DEFINE_TYPE_WITH_CODE (GtkGadget, gtk_gadget, GTK_TYPE_WIDGET,
326 * g_print ("GtkGadget-id: %lu\n", g_define_type_id));
328 #define G_DEFINE_TYPE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
329 #define G_DEFINE_TYPE_WITH_CODE(TN, t_n, T_P, _C_) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, 0, _C_)
330 #define G_DEFINE_ABSTRACT_TYPE(TN, t_n, T_P) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, {})
331 #define G_DEFINE_ABSTRACT_TYPE_WITH_CODE(TN, t_n, T_P, _C_) G_DEFINE_TYPE_EXTENDED (TN, t_n, T_P, G_TYPE_FLAG_ABSTRACT, _C_)
333 /* convenience macro to ease interface addition in the CODE
334 * section of G_DEFINE_TYPE_WITH_CODE() (this macro relies on
335 * the g_define_type_id present within G_DEFINE_TYPE_WITH_CODE()).
336 * usage example:
337 * G_DEFINE_TYPE_WITH_CODE (GtkTreeStore, gtk_tree_store, G_TYPE_OBJECT,
338 * G_IMPLEMENT_INTERFACE (GTK_TYPE_TREE_MODEL,
339 * gtk_tree_store_tree_model_init));
341 #define G_IMPLEMENT_INTERFACE(TYPE_IFACE, iface_init) { \
342 static const GInterfaceInfo g_implement_interface_info = { \
343 (GInterfaceInitFunc) iface_init \
344 }; \
345 g_type_add_interface_static (g_define_type_id, TYPE_IFACE, &g_implement_interface_info); \
348 #define G_DEFINE_TYPE_EXTENDED(TypeName, type_name, TYPE_PARENT, flags, CODE) \
350 static void type_name##_init (TypeName *self); \
351 static void type_name##_class_init (TypeName##Class *klass); \
352 static gpointer type_name##_parent_class = NULL; \
353 static void type_name##_class_intern_init (gpointer klass) \
355 type_name##_parent_class = g_type_class_peek_parent (klass); \
356 type_name##_class_init ((TypeName##Class*) klass); \
359 GType \
360 type_name##_get_type (void) \
362 static GType g_define_type_id = 0; \
363 if (G_UNLIKELY (g_define_type_id == 0)) \
365 static const GTypeInfo g_define_type_info = { \
366 sizeof (TypeName##Class), \
367 (GBaseInitFunc) NULL, \
368 (GBaseFinalizeFunc) NULL, \
369 (GClassInitFunc) type_name##_class_intern_init, \
370 (GClassFinalizeFunc) NULL, \
371 NULL, /* class_data */ \
372 sizeof (TypeName), \
373 0, /* n_preallocs */ \
374 (GInstanceInitFunc) type_name##_init, \
375 }; \
376 g_define_type_id = g_type_register_static (TYPE_PARENT, #TypeName, &g_define_type_info, (GTypeFlags) flags); \
377 { CODE ; } \
379 return g_define_type_id; \
383 /* --- protected (for fundamental type implementations) --- */
384 GTypePlugin* g_type_get_plugin (GType type);
385 GTypePlugin* g_type_interface_get_plugin (GType instance_type,
386 GType interface_type);
387 GType g_type_fundamental_next (void);
388 GType g_type_fundamental (GType type_id);
389 GTypeInstance* g_type_create_instance (GType type);
390 void g_type_free_instance (GTypeInstance *instance);
392 void g_type_add_class_cache_func (gpointer cache_data,
393 GTypeClassCacheFunc cache_func);
394 void g_type_remove_class_cache_func (gpointer cache_data,
395 GTypeClassCacheFunc cache_func);
396 void g_type_class_unref_uncached (gpointer g_class);
398 void g_type_add_interface_check (gpointer check_data,
399 GTypeInterfaceCheckFunc check_func);
400 void g_type_remove_interface_check (gpointer check_data,
401 GTypeInterfaceCheckFunc chec_func);
403 GTypeValueTable* g_type_value_table_peek (GType type);
406 /*< private >*/
407 gboolean g_type_check_instance (GTypeInstance *instance);
408 GTypeInstance* g_type_check_instance_cast (GTypeInstance *instance,
409 GType iface_type);
410 gboolean g_type_check_instance_is_a (GTypeInstance *instance,
411 GType iface_type);
412 GTypeClass* g_type_check_class_cast (GTypeClass *g_class,
413 GType is_a_type);
414 gboolean g_type_check_class_is_a (GTypeClass *g_class,
415 GType is_a_type);
416 gboolean g_type_check_is_value_type (GType type);
417 gboolean g_type_check_value (GValue *value);
418 gboolean g_type_check_value_holds (GValue *value,
419 GType type);
420 gboolean g_type_test_flags (GType type,
421 guint flags);
424 /* --- debugging functions --- */
425 G_CONST_RETURN gchar* g_type_name_from_instance (GTypeInstance *instance);
426 G_CONST_RETURN gchar* g_type_name_from_class (GTypeClass *g_class);
429 /* --- implementation bits --- */
430 #ifndef G_DISABLE_CAST_CHECKS
431 # define _G_TYPE_CIC(ip, gt, ct) \
432 ((ct*) g_type_check_instance_cast ((GTypeInstance*) ip, gt))
433 # define _G_TYPE_CCC(cp, gt, ct) \
434 ((ct*) g_type_check_class_cast ((GTypeClass*) cp, gt))
435 #else /* G_DISABLE_CAST_CHECKS */
436 # define _G_TYPE_CIC(ip, gt, ct) ((ct*) ip)
437 # define _G_TYPE_CCC(cp, gt, ct) ((ct*) cp)
438 #endif /* G_DISABLE_CAST_CHECKS */
439 #define _G_TYPE_CHI(ip) (g_type_check_instance ((GTypeInstance*) ip))
440 #define _G_TYPE_CHV(vl) (g_type_check_value ((GValue*) vl))
441 #define _G_TYPE_IGC(ip, gt, ct) ((ct*) (((GTypeInstance*) ip)->g_class))
442 #define _G_TYPE_IGI(ip, gt, ct) ((ct*) g_type_interface_peek (((GTypeInstance*) ip)->g_class, gt))
443 #ifdef __GNUC__
444 # define _G_TYPE_CIT(ip, gt) (G_GNUC_EXTENSION ({ \
445 GTypeInstance *__inst = (GTypeInstance*) ip; GType __t = gt; gboolean __r; \
446 if (__inst && __inst->g_class && __inst->g_class->g_type == __t) \
447 __r = TRUE; \
448 else \
449 __r = g_type_check_instance_is_a (__inst, __t); \
450 __r; \
452 # define _G_TYPE_CCT(cp, gt) (G_GNUC_EXTENSION ({ \
453 GTypeClass *__class = (GTypeClass*) cp; GType __t = gt; gboolean __r; \
454 if (__class && __class->g_type == __t) \
455 __r = TRUE; \
456 else \
457 __r = g_type_check_class_is_a (__class, __t); \
458 __r; \
460 # define _G_TYPE_CVH(vl, gt) (G_GNUC_EXTENSION ({ \
461 GValue *__val = (GValue*) vl; GType __t = gt; gboolean __r; \
462 if (__val && __val->g_type == __t) \
463 __r = TRUE; \
464 else \
465 __r = g_type_check_value_holds (__val, __t); \
466 __r; \
468 #else /* !__GNUC__ */
469 # define _G_TYPE_CIT(ip, gt) (g_type_check_instance_is_a ((GTypeInstance*) ip, gt))
470 # define _G_TYPE_CCT(cp, gt) (g_type_check_class_is_a ((GTypeClass*) cp, gt))
471 # define _G_TYPE_CVH(vl, gt) (g_type_check_value_holds ((GValue*) vl, gt))
472 #endif /* !__GNUC__ */
473 #define G_TYPE_FLAG_RESERVED_ID_BIT ((GType) (1 << 0))
474 extern GTypeDebugFlags _g_type_debug_flags;
476 G_END_DECLS
478 #endif /* __G_TYPE_H__ */