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