gobject/gtype.h

   1 /* GObject - GLib Type, Object, Parameter and Signal Library
   2  * Copyright (C) 1998-1999, 2000-2001 Tim Janik and Red Hat, Inc.
   3  *
   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.
   8  *
   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.
  13  *
  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.
  18  */
  19 #ifndef __G_TYPE_H__
  20 #define __G_TYPE_H__
  21
  22 #if !defined (__GLIB_GOBJECT_H_INSIDE__) && !defined (GOBJECT_COMPILATION)
  23 #error "Only <glib-object.h> can be included directly."
  24 #endif
  25
  26 #include        <glib.h>
  27
  28 G_BEGIN_DECLS
  29
  30 /* Basic Type Macros
  31  */
  32 #define G_TYPE_FUNDAMENTAL(type)                ((type) & 0xff)
  33 #define G_TYPE_FUNDAMENTAL_MAX                  (0xff)
  34 #define G_TYPE_DERIVE_ID(ptype, branch_seqno)   (G_TYPE_FUNDAMENTAL (ptype) | ((branch_seqno) << 8))
  35 #define G_TYPE_BRANCH_SEQNO(type)               ((type) >> 8)
  36 #define G_TYPE_FUNDAMENTAL_LAST                 ((GType) g_type_fundamental_last ())
  37
  38
  39 /* predefined fundamental and derived types
  40  */
  41 typedef enum    /*< skip >*/
  42 {
  43   /* standard types, introduced by g_type_init() */
  44   G_TYPE_INVALID,
  45   G_TYPE_NONE,
  46   G_TYPE_INTERFACE,
  47
  48   /* GLib type ids */
  49   G_TYPE_CHAR,
  50   G_TYPE_UCHAR,
  51   G_TYPE_BOOLEAN,
  52   G_TYPE_INT,
  53   G_TYPE_UINT,
  54   G_TYPE_LONG,
  55   G_TYPE_ULONG,
  56   G_TYPE_INT64,
  57   G_TYPE_UINT64,
  58   G_TYPE_ENUM,
  59   G_TYPE_FLAGS,
  60   G_TYPE_FLOAT,
  61   G_TYPE_DOUBLE,
  62   G_TYPE_STRING,
  63   G_TYPE_POINTER,
  64   G_TYPE_BOXED,
  65   G_TYPE_PARAM,
  66   G_TYPE_OBJECT,
  67
  68   /* reserved fundamental type ids,
  69    * mail gtk-devel-list@redhat.com for reservations
  70    */
  71   G_TYPE_RESERVED_BSE_FIRST,
  72   G_TYPE_RESERVED_BSE_LAST      = G_TYPE_RESERVED_BSE_FIRST + 15,
  73   G_TYPE_RESERVED_LAST_FUNDAMENTAL,
  74
  75   /* derived type ids */
  76   G_TYPE_CLOSURE                = G_TYPE_DERIVE_ID (G_TYPE_BOXED, 1),
  77   G_TYPE_VALUE                  = G_TYPE_DERIVE_ID (G_TYPE_BOXED, 2),
  78   G_TYPE_VALUE_ARRAY            = G_TYPE_DERIVE_ID (G_TYPE_BOXED, 3),
  79   G_TYPE_GSTRING                = G_TYPE_DERIVE_ID (G_TYPE_BOXED, 4),
  80   G_TYPE_PARAM_CHAR             = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 1),
  81   G_TYPE_PARAM_UCHAR            = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 2),
  82   G_TYPE_PARAM_BOOLEAN          = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 3),
  83   G_TYPE_PARAM_INT              = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 4),
  84   G_TYPE_PARAM_UINT             = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 5),
  85   G_TYPE_PARAM_LONG             = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 6),
  86   G_TYPE_PARAM_ULONG            = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 7),
  87   G_TYPE_PARAM_INT64            = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 8),
  88   G_TYPE_PARAM_UINT64           = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 9),
  89   G_TYPE_PARAM_UNICHAR          = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 10),
  90   G_TYPE_PARAM_ENUM             = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 11),
  91   G_TYPE_PARAM_FLAGS            = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 12),
  92   G_TYPE_PARAM_FLOAT            = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 13),
  93   G_TYPE_PARAM_DOUBLE           = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 14),
  94   G_TYPE_PARAM_STRING           = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 15),
  95   G_TYPE_PARAM_PARAM            = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 16),
  96   G_TYPE_PARAM_BOXED            = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 17),
  97   G_TYPE_PARAM_POINTER          = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 18),
  98   G_TYPE_PARAM_VALUE_ARRAY      = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 19),
  99   G_TYPE_PARAM_OBJECT           = G_TYPE_DERIVE_ID (G_TYPE_PARAM, 20)
 100
 101 } GTypeFundamentals;
 102
 103
 104 /* Type Checking Macros
 105  */
 106 #define G_TYPE_IS_FUNDAMENTAL(type)             (G_TYPE_BRANCH_SEQNO (type) == 0)
 107 #define G_TYPE_IS_DERIVED(type)                 (G_TYPE_BRANCH_SEQNO (type) > 0)
 108 #define G_TYPE_IS_INTERFACE(type)               (G_TYPE_FUNDAMENTAL (type) == G_TYPE_INTERFACE)
 109 #define G_TYPE_IS_CLASSED(type)                 (g_type_test_flags ((type), G_TYPE_FLAG_CLASSED))
 110 #define G_TYPE_IS_INSTANTIATABLE(type)          (g_type_test_flags ((type), G_TYPE_FLAG_INSTANTIATABLE))
 111 #define G_TYPE_IS_DERIVABLE(type)               (g_type_test_flags ((type), G_TYPE_FLAG_DERIVABLE))
 112 #define G_TYPE_IS_DEEP_DERIVABLE(type)          (g_type_test_flags ((type), G_TYPE_FLAG_DEEP_DERIVABLE))
 113 #define G_TYPE_IS_ABSTRACT(type)                (g_type_test_flags ((type), G_TYPE_FLAG_ABSTRACT))
 114 #define G_TYPE_IS_VALUE_ABSTRACT(type)          (g_type_test_flags ((type), G_TYPE_FLAG_VALUE_ABSTRACT))
 115 #define G_TYPE_IS_PARAM(type)                   (G_TYPE_FUNDAMENTAL (type) == G_TYPE_PARAM)
 116 #define G_TYPE_IS_VALUE_TYPE(type)              (g_type_check_is_value_type (type))
 117 #define G_TYPE_HAS_VALUE_TABLE(type)            (g_type_value_table_peek (type) != NULL)
 118
 119
 120 /* Typedefs
 121  */
 122 typedef guint32                         GType;
 123 typedef struct _GValue                  GValue;
 124 typedef union  _GTypeCValue             GTypeCValue;
 125 typedef struct _GTypePlugin             GTypePlugin;
 126 typedef struct _GTypeClass              GTypeClass;
 127 typedef struct _GTypeInterface          GTypeInterface;
 128 typedef struct _GTypeInstance           GTypeInstance;
 129 typedef struct _GTypeInfo               GTypeInfo;
 130 typedef struct _GTypeFundamentalInfo    GTypeFundamentalInfo;
 131 typedef struct _GInterfaceInfo          GInterfaceInfo;
 132 typedef struct _GTypeValueTable         GTypeValueTable;
 133 typedef struct _GTypeQuery              GTypeQuery;
 134
 135
 136 /* Basic Type Structures
 137  */
 138 struct _GTypeClass
 139 {
 140   /*< private >*/
 141   GType g_type;
 142 };
 143 struct _GTypeInstance
 144 {
 145   /*< private >*/
 146   GTypeClass *g_class;
 147 };
 148 struct _GTypeInterface
 149 {
 150   /*< private >*/
 151   GType g_type;         /* iface type */
 152   GType g_instance_type;
 153 };
 154 struct _GTypeQuery
 155 {
 156   GType         type;
 157   const gchar  *type_name;
 158   guint         class_size;
 159   guint         instance_size;
 160 };
 161
 162
 163 /* Casts, checks and accessors for structured types
 164  * usage of these macros is reserved to type implementations only
 165  */
 166 /*< protected >*/
 167 #define G_TYPE_CHECK_INSTANCE(instance)                         (_G_TYPE_CHI ((GTypeInstance*) (instance)))
 168 #define G_TYPE_CHECK_INSTANCE_CAST(instance, g_type, c_type)    (_G_TYPE_CIC ((instance), (g_type), c_type))
 169 #define G_TYPE_CHECK_INSTANCE_TYPE(instance, g_type)            (_G_TYPE_CIT ((instance), (g_type)))
 170 #define G_TYPE_INSTANCE_GET_CLASS(instance, g_type, c_type)     (_G_TYPE_IGC ((instance), (g_type), c_type))
 171 #define G_TYPE_INSTANCE_GET_INTERFACE(instance, g_type, c_type) (_G_TYPE_IGI ((instance), (g_type), c_type))
 172 #define G_TYPE_CHECK_CLASS_CAST(g_class, g_type, c_type)        (_G_TYPE_CCC ((g_class), (g_type), c_type))
 173 #define G_TYPE_CHECK_CLASS_TYPE(g_class, g_type)                (_G_TYPE_CCT ((g_class), (g_type)))
 174 #define G_TYPE_CHECK_VALUE(value)                               (_G_TYPE_CHV ((value)))
 175 #define G_TYPE_CHECK_VALUE_TYPE(value, g_type)                  (_G_TYPE_CVH ((value), (g_type)))
 176 #define G_TYPE_FROM_INSTANCE(instance)                          (G_TYPE_FROM_CLASS (((GTypeInstance*) (instance))->g_class))
 177 #define G_TYPE_FROM_CLASS(g_class)                              (((GTypeClass*) (g_class))->g_type)
 178 #define G_TYPE_FROM_INTERFACE(g_iface)                          (((GTypeInterface*) (g_iface))->g_type)
 179
 180
 181 /* debug flags for g_type_init_with_debug_flags() */
 182 typedef enum    /*< skip >*/
 183 {
 184   G_TYPE_DEBUG_NONE     = 0,
 185   G_TYPE_DEBUG_OBJECTS  = 1 << 0,
 186   G_TYPE_DEBUG_SIGNALS  = 1 << 1,
 187   G_TYPE_DEBUG_MASK     = 0x03
 188 } GTypeDebugFlags;
 189
 190
 191 /* --- prototypes --- */
 192 void                  g_type_init                    (void);
 193 void                  g_type_init_with_debug_flags   (GTypeDebugFlags  debug_flags);
 194 G_CONST_RETURN gchar* g_type_name                    (GType            type);
 195 GQuark                g_type_qname                   (GType            type);
 196 GType                 g_type_from_name               (const gchar     *name);
 197 GType                 g_type_parent                  (GType            type);
 198 guint                 g_type_depth                   (GType            type);
 199 GType                 g_type_next_base               (GType            leaf_type,
 200                                                       GType            root_type);
 201 gboolean              g_type_is_a                    (GType            type,
 202                                                       GType            is_a_type);
 203 guint                 g_type_fundamental_branch_last (GType            type);
 204 gpointer              g_type_class_ref               (GType            type);
 205 gpointer              g_type_class_peek              (GType            type);
 206 void                  g_type_class_unref             (gpointer         g_class);
 207 gpointer              g_type_class_peek_parent       (gpointer         g_class);
 208 gpointer              g_type_interface_peek          (gpointer         instance_class,
 209                                                       GType            iface_type);
 210 gpointer              g_type_interface_peek_parent   (gpointer         g_iface);
 211
 212 /* g_free() the returned arrays */
 213 GType*                g_type_children                (GType            type,
 214                                                       guint           *n_children);
 215 GType*                g_type_interfaces              (GType            type,
 216                                                       guint           *n_interfaces);
 217
 218 /* per-type _static_ data */
 219 void                  g_type_set_qdata               (GType            type,
 220                                                       GQuark           quark,
 221                                                       gpointer         data);
 222 gpointer              g_type_get_qdata               (GType            type,
 223                                                       GQuark           quark);
 224 void                  g_type_query                   (GType            type,
 225                                                       GTypeQuery      *query);
 226
 227
 228 /* --- type registration --- */
 229 typedef void   (*GBaseInitFunc)              (gpointer         g_class);
 230 typedef void   (*GBaseFinalizeFunc)          (gpointer         g_class);
 231 typedef void   (*GClassInitFunc)             (gpointer         g_class,
 232                                               gpointer         class_data);
 233 typedef void   (*GClassFinalizeFunc)         (gpointer         g_class,
 234                                               gpointer         class_data);
 235 typedef void   (*GInstanceInitFunc)          (GTypeInstance   *instance,
 236                                               gpointer         g_class);
 237 typedef void   (*GInterfaceInitFunc)         (gpointer         g_iface,
 238                                               gpointer         iface_data);
 239 typedef void   (*GInterfaceFinalizeFunc)     (gpointer         g_iface,
 240                                               gpointer         iface_data);
 241 typedef gboolean (*GTypeClassCacheFunc)      (gpointer         cache_data,
 242                                               GTypeClass      *g_class);
 243 typedef enum    /*< skip >*/
 244 {
 245   G_TYPE_FLAG_CLASSED           = (1 << 0),
 246   G_TYPE_FLAG_INSTANTIATABLE    = (1 << 1),
 247   G_TYPE_FLAG_DERIVABLE         = (1 << 2),
 248   G_TYPE_FLAG_DEEP_DERIVABLE    = (1 << 3)
 249 } GTypeFundamentalFlags;
 250 typedef enum    /*< skip >*/
 251 {
 252   G_TYPE_FLAG_ABSTRACT          = (1 << 4),
 253   G_TYPE_FLAG_VALUE_ABSTRACT    = (1 << 5)
 254 } GTypeFlags;
 255 struct _GTypeInfo
 256 {
 257   /* interface types, classed types, instantiated types */
 258   guint16                class_size;
 259
 260   GBaseInitFunc          base_init;
 261   GBaseFinalizeFunc      base_finalize;
 262
 263   /* classed types, instantiated types */
 264   GClassInitFunc         class_init;
 265   GClassFinalizeFunc     class_finalize;
 266   gconstpointer          class_data;
 267
 268   /* instantiated types */
 269   guint16                instance_size;
 270   guint16                n_preallocs;
 271   GInstanceInitFunc      instance_init;
 272
 273   /* value handling */
 274   const GTypeValueTable *value_table;
 275 };
 276 struct _GTypeFundamentalInfo
 277 {
 278   GTypeFundamentalFlags  type_flags;
 279 };
 280 struct _GInterfaceInfo
 281 {
 282   GInterfaceInitFunc     interface_init;
 283   GInterfaceFinalizeFunc interface_finalize;
 284   gpointer               interface_data;
 285 };
 286 struct _GTypeValueTable
 287 {
 288   void     (*value_init)         (GValue       *value);
 289   void     (*value_free)         (GValue       *value);
 290   void     (*value_copy)         (const GValue *src_value,
 291                                   GValue       *dest_value);
 292   /* varargs functionality (optional) */
 293   gpointer (*value_peek_pointer) (const GValue *value);
 294   gchar     *collect_format;
 295   gchar*   (*collect_value)      (GValue       *value,
 296                                   guint         n_collect_values,
 297                                   GTypeCValue  *collect_values,
 298                                   guint         collect_flags);
 299   gchar     *lcopy_format;
 300   gchar*   (*lcopy_value)        (const GValue *value,
 301                                   guint         n_collect_values,
 302                                   GTypeCValue  *collect_values,
 303                                   guint         collect_flags);
 304 };
 305 GType g_type_register_static            (GType                       parent_type,
 306                                          const gchar                *type_name,
 307                                          const GTypeInfo            *info,
 308                                          GTypeFlags                  flags);
 309 GType g_type_register_dynamic           (GType                       parent_type,
 310                                          const gchar                *type_name,
 311                                          GTypePlugin                *plugin,
 312                                          GTypeFlags                  flags);
 313 GType g_type_register_fundamental       (GType                       type_id,
 314                                          const gchar                *type_name,
 315                                          const GTypeInfo            *info,
 316                                          const GTypeFundamentalInfo *finfo,
 317                                          GTypeFlags                  flags);
 318 void  g_type_add_interface_static       (GType                       instance_type,
 319                                          GType                       interface_type,
 320                                          const GInterfaceInfo       *info);
 321 void  g_type_add_interface_dynamic      (GType                       instance_type,
 322                                          GType                       interface_type,
 323                                          GTypePlugin                *plugin);
 324 void  g_type_interface_add_prerequisite (GType                       interface_type,
 325                                          GType                       prerequisite_type);
 326
 327
 328 /* --- protected (for fundamental type implementations) --- */
 329 GTypePlugin*     g_type_get_plugin              (GType               type);
 330 GTypePlugin*     g_type_interface_get_plugin    (GType               instance_type,
 331                                                  GType               implementation_type);
 332
 333 GType            g_type_fundamental_last        (void);
 334 GTypeInstance*   g_type_create_instance         (GType               type);
 335 void             g_type_free_instance           (GTypeInstance      *instance);
 336 void             g_type_add_class_cache_func    (gpointer            cache_data,
 337                                                  GTypeClassCacheFunc cache_func);
 338 void             g_type_remove_class_cache_func (gpointer            cache_data,
 339                                                  GTypeClassCacheFunc cache_func);
 340 void             g_type_class_unref_uncached    (gpointer            g_class);
 341 GTypeValueTable* g_type_value_table_peek        (GType               type);
 342
 343
 344 /*< private >*/
 345 gboolean         g_type_check_instance          (GTypeInstance      *instance);
 346 GTypeInstance*   g_type_check_instance_cast     (GTypeInstance      *instance,
 347                                                  GType               iface_type);
 348 gboolean         g_type_check_instance_is_a     (GTypeInstance      *instance,
 349                                                  GType               iface_type);
 350 GTypeClass*      g_type_check_class_cast        (GTypeClass         *g_class,
 351                                                  GType               is_a_type);
 352 gboolean         g_type_check_class_is_a        (GTypeClass         *g_class,
 353                                                  GType               is_a_type);
 354 gboolean         g_type_check_is_value_type     (GType               type);
 355 gboolean         g_type_check_value             (GValue             *value);
 356 gboolean         g_type_check_value_holds       (GValue             *value,
 357                                                  GType               type);
 358 gboolean         g_type_test_flags              (GType               type,
 359                                                  guint               flags);
 360
 361
 362 /* --- debugging functions --- */
 363 G_CONST_RETURN gchar* g_type_name_from_instance (GTypeInstance  *instance);
 364 G_CONST_RETURN gchar* g_type_name_from_class    (GTypeClass     *g_class);
 365
 366
 367 /* --- implementation bits --- */
 368 #ifndef G_DISABLE_CAST_CHECKS
 369 #  define _G_TYPE_CIC(ip, gt, ct) \
 370     ((ct*) g_type_check_instance_cast ((GTypeInstance*) ip, gt))
 371 #  define _G_TYPE_CCC(cp, gt, ct) \
 372     ((ct*) g_type_check_class_cast ((GTypeClass*) cp, gt))
 373 #else /* G_DISABLE_CAST_CHECKS */
 374 #  define _G_TYPE_CIC(ip, gt, ct)       ((ct*) ip)
 375 #  define _G_TYPE_CCC(cp, gt, ct)       ((ct*) cp)
 376 #endif /* G_DISABLE_CAST_CHECKS */
 377 #define _G_TYPE_CHI(ip)                 (g_type_check_instance ((GTypeInstance*) ip))
 378 #define _G_TYPE_CVH(vl, gt)             (g_type_check_value_holds ((GValue*) vl, gt))
 379 #define _G_TYPE_CHV(vl)                 (g_type_check_value ((GValue*) vl))
 380 #define _G_TYPE_IGC(ip, gt, ct)         ((ct*) (((GTypeInstance*) ip)->g_class))
 381 #define _G_TYPE_IGI(ip, gt, ct)         ((ct*) g_type_interface_peek (((GTypeInstance*) ip)->g_class, gt))
 382 #ifdef  __GNUC__
 383 #  define _G_TYPE_CIT(ip, gt)             ({ \
 384   GTypeInstance *__inst = (GTypeInstance*) ip; GType __t = gt; gboolean __r; \
 385   if (__inst && __inst->g_class && __inst->g_class->g_type == __t) \
 386     __r = TRUE; \
 387   else \
 388     __r = g_type_check_instance_is_a (__inst, __t); \
 389   __r; \
 390 })
 391 #  define _G_TYPE_CCT(cp, gt)             ({ \
 392   GTypeClass *__class = (GTypeClass*) cp; GType __t = gt; gboolean __r; \
 393   if (__class && __class->g_type == __t) \
 394     __r = TRUE; \
 395   else \
 396     __r = g_type_check_class_is_a (__class, __t); \
 397   __r; \
 398 })
 399 #else  /* !__GNUC__ */
 400 #  define _G_TYPE_CIT(ip, gt)             (g_type_check_instance_is_a ((GTypeInstance*) ip, gt))
 401 #  define _G_TYPE_CCT(cp, gt)             (g_type_check_class_is_a ((GTypeClass*) cp, gt))
 402 #endif /* !__GNUC__ */
 403 #define G_TYPE_FLAG_RESERVED_ID_BIT     (1 << 30)
 404 extern GTypeDebugFlags                  _g_type_debug_flags;
 405
 406 G_END_DECLS
 407
 408 #endif /* __G_TYPE_H__ */