gobject/gtypemodule.h

   1 /* GObject - GLib Type, Object, Parameter and Signal Library
   2  * Copyright (C) 2000 Red Hat, Inc.
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-or-later
   5  *
   6  * This library is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * This library is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with this library; if not, see <http://www.gnu.org/licenses/>.
  18  */
  19 #ifndef __G_TYPE_MODULE_H__
  20 #define __G_TYPE_MODULE_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 <gobject/gobject.h>
  27 #include <gobject/genums.h>
  28
  29 G_BEGIN_DECLS
  30
  31 typedef struct _GTypeModule      GTypeModule;
  32 typedef struct _GTypeModuleClass GTypeModuleClass;
  33
  34 #define G_TYPE_TYPE_MODULE              (g_type_module_get_type ())
  35 #define G_TYPE_MODULE(module)           (G_TYPE_CHECK_INSTANCE_CAST ((module), G_TYPE_TYPE_MODULE, GTypeModule))
  36 #define G_TYPE_MODULE_CLASS(class)      (G_TYPE_CHECK_CLASS_CAST ((class), G_TYPE_TYPE_MODULE, GTypeModuleClass))
  37 #define G_IS_TYPE_MODULE(module)        (G_TYPE_CHECK_INSTANCE_TYPE ((module), G_TYPE_TYPE_MODULE))
  38 #define G_IS_TYPE_MODULE_CLASS(class)   (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_TYPE_MODULE))
  39 #define G_TYPE_MODULE_GET_CLASS(module) (G_TYPE_INSTANCE_GET_CLASS ((module), G_TYPE_TYPE_MODULE, GTypeModuleClass))
  40
  41 G_DEFINE_AUTOPTR_CLEANUP_FUNC(GTypeModule, g_object_unref)
  42
  43 /**
  44  * GTypeModule:
  45  * @name: the name of the module
  46  *
  47  * The members of the GTypeModule structure should not
  48  * be accessed directly, except for the @name field.
  49  */
  50 struct _GTypeModule
  51 {
  52   GObject parent_instance;
  53
  54   guint use_count;
  55   GSList *type_infos;
  56   GSList *interface_infos;
  57
  58   /*< public >*/
  59   gchar *name;
  60 };
  61
  62 /**
  63  * GTypeModuleClass:
  64  * @parent_class: the parent class
  65  * @load: loads the module and registers one or more types using
  66  *  g_type_module_register_type().
  67  * @unload: unloads the module
  68  *
  69  * In order to implement dynamic loading of types based on #GTypeModule,
  70  * the @load and @unload functions in #GTypeModuleClass must be implemented.
  71  */
  72 struct _GTypeModuleClass
  73 {
  74   GObjectClass parent_class;
  75
  76   /*< public >*/
  77   gboolean (* load)   (GTypeModule *module);
  78   void     (* unload) (GTypeModule *module);
  79
  80   /*< private >*/
  81   /* Padding for future expansion */
  82   void (*reserved1) (void);
  83   void (*reserved2) (void);
  84   void (*reserved3) (void);
  85   void (*reserved4) (void);
  86 };
  87
  88 /**
  89  * G_DEFINE_DYNAMIC_TYPE:
  90  * @TN: The name of the new type, in Camel case.
  91  * @t_n: The name of the new type, in lowercase, with words
  92  *  separated by '_'.
  93  * @T_P: The #GType of the parent type.
  94  *
  95  * A convenience macro for dynamic type implementations, which declares a
  96  * class initialization function, an instance initialization function (see
  97  * #GTypeInfo for information about these) and a static variable named
  98  * `t_n`_parent_class pointing to the parent class.
  99  *
 100  * Furthermore, it defines a `*_get_type()` and a static `*_register_type()`
 101  * functions for use in your `module_init()`.
 102  *
 103  * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example.
 104  *
 105  * Since: 2.14
 106  */
 107 #define G_DEFINE_DYNAMIC_TYPE(TN, t_n, T_P)          G_DEFINE_DYNAMIC_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
 108 /**
 109  * G_DEFINE_DYNAMIC_TYPE_EXTENDED:
 110  * @TypeName: The name of the new type, in Camel case.
 111  * @type_name: The name of the new type, in lowercase, with words
 112  *  separated by '_'.
 113  * @TYPE_PARENT: The #GType of the parent type.
 114  * @flags: #GTypeFlags to pass to g_type_module_register_type()
 115  * @CODE: Custom code that gets inserted in the *_get_type() function.
 116  *
 117  * A more general version of G_DEFINE_DYNAMIC_TYPE() which
 118  * allows to specify #GTypeFlags and custom code.
 119  *
 120  * |[<!-- language="C" -->
 121  * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
 122  *                                 gtk_gadget,
 123  *                                 GTK_TYPE_THING,
 124  *                                 0,
 125  *                                 G_IMPLEMENT_INTERFACE_DYNAMIC (TYPE_GIZMO,
 126  *                                                                gtk_gadget_gizmo_init));
 127  * ]|
 128  *
 129  * expands to
 130  *
 131  * |[<!-- language="C" -->
 132  * static void     gtk_gadget_init              (GtkGadget      *self);
 133  * static void     gtk_gadget_class_init        (GtkGadgetClass *klass);
 134  * static void     gtk_gadget_class_finalize    (GtkGadgetClass *klass);
 135  *
 136  * static gpointer gtk_gadget_parent_class = NULL;
 137  * static GType    gtk_gadget_type_id = 0;
 138  *
 139  * static void     gtk_gadget_class_intern_init (gpointer klass)
 140  * {
 141  *   gtk_gadget_parent_class = g_type_class_peek_parent (klass);
 142  *   gtk_gadget_class_init ((GtkGadgetClass*) klass);
 143  * }
 144  *
 145  * GType
 146  * gtk_gadget_get_type (void)
 147  * {
 148  *   return gtk_gadget_type_id;
 149  * }
 150  *
 151  * static void
 152  * gtk_gadget_register_type (GTypeModule *type_module)
 153  * {
 154  *   const GTypeInfo g_define_type_info = {
 155  *     sizeof (GtkGadgetClass),
 156  *     (GBaseInitFunc) NULL,
 157  *     (GBaseFinalizeFunc) NULL,
 158  *     (GClassInitFunc) gtk_gadget_class_intern_init,
 159  *     (GClassFinalizeFunc) gtk_gadget_class_finalize,
 160  *     NULL,   // class_data
 161  *     sizeof (GtkGadget),
 162  *     0,      // n_preallocs
 163  *     (GInstanceInitFunc) gtk_gadget_init,
 164  *     NULL    // value_table
 165  *   };
 166  *   gtk_gadget_type_id = g_type_module_register_type (type_module,
 167  *                                                     GTK_TYPE_THING,
 168  *                                                     "GtkGadget",
 169  *                                                     &g_define_type_info,
 170  *                                                     (GTypeFlags) flags);
 171  *   {
 172  *     const GInterfaceInfo g_implement_interface_info = {
 173  *       (GInterfaceInitFunc) gtk_gadget_gizmo_init
 174  *     };
 175  *     g_type_module_add_interface (type_module, g_define_type_id, TYPE_GIZMO, &g_implement_interface_info);
 176  *   }
 177  * }
 178  * ]|
 179  *
 180  * Since: 2.14
 181  */
 182 #define G_DEFINE_DYNAMIC_TYPE_EXTENDED(TypeName, type_name, TYPE_PARENT, flags, CODE) \
 183 static void     type_name##_init              (TypeName        *self); \
 184 static void     type_name##_class_init        (TypeName##Class *klass); \
 185 static void     type_name##_class_finalize    (TypeName##Class *klass); \
 186 static gpointer type_name##_parent_class = NULL; \
 187 static GType    type_name##_type_id = 0; \
 188 static gint     TypeName##_private_offset; \
 189 \
 190 _G_DEFINE_TYPE_EXTENDED_CLASS_INIT(TypeName, type_name) \
 191 \
 192 G_GNUC_UNUSED \
 193 static inline gpointer \
 194 type_name##_get_instance_private (TypeName *self) \
 195 { \
 196   return (G_STRUCT_MEMBER_P (self, TypeName##_private_offset)); \
 197 } \
 198 \
 199 GType \
 200 type_name##_get_type (void) \
 201 { \
 202   return type_name##_type_id; \
 203 } \
 204 static void \
 205 type_name##_register_type (GTypeModule *type_module) \
 206 { \
 207   GType g_define_type_id G_GNUC_UNUSED; \
 208   const GTypeInfo g_define_type_info = { \
 209     sizeof (TypeName##Class), \
 210     (GBaseInitFunc) NULL, \
 211     (GBaseFinalizeFunc) NULL, \
 212     (GClassInitFunc)(void (*)(void)) type_name##_class_intern_init, \
 213     (GClassFinalizeFunc)(void (*)(void)) type_name##_class_finalize, \
 214     NULL,   /* class_data */ \
 215     sizeof (TypeName), \
 216     0,      /* n_preallocs */ \
 217     (GInstanceInitFunc)(void (*)(void)) type_name##_init, \
 218     NULL    /* value_table */ \
 219   }; \
 220   type_name##_type_id = g_type_module_register_type (type_module, \
 221                                                      TYPE_PARENT, \
 222                                                      #TypeName, \
 223                                                      &g_define_type_info, \
 224                                                      (GTypeFlags) flags); \
 225   g_define_type_id = type_name##_type_id; \
 226   { CODE ; } \
 227 }
 228
 229 /**
 230  * G_IMPLEMENT_INTERFACE_DYNAMIC:
 231  * @TYPE_IFACE: The #GType of the interface to add
 232  * @iface_init: The interface init function
 233  *
 234  * A convenience macro to ease interface addition in the @_C_ section
 235  * of G_DEFINE_DYNAMIC_TYPE_EXTENDED().
 236  *
 237  * See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example.
 238  *
 239  * Note that this macro can only be used together with the
 240  * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable
 241  * names from that macro.
 242  *
 243  * Since: 2.24
 244  */
 245 #define G_IMPLEMENT_INTERFACE_DYNAMIC(TYPE_IFACE, iface_init)       { \
 246   const GInterfaceInfo g_implement_interface_info = { \
 247     (GInterfaceInitFunc)(void (*)(void)) iface_init, NULL, NULL      \
 248   }; \
 249   g_type_module_add_interface (type_module, g_define_type_id, TYPE_IFACE, &g_implement_interface_info); \
 250 }
 251
 252 /**
 253  * G_ADD_PRIVATE_DYNAMIC:
 254  * @TypeName: the name of the type in CamelCase
 255  *
 256  * A convenience macro to ease adding private data to instances of a new dynamic
 257  * type in the @_C_ section of G_DEFINE_DYNAMIC_TYPE_EXTENDED().
 258  *
 259  * See G_ADD_PRIVATE() for details, it is similar but for static types.
 260  *
 261  * Note that this macro can only be used together with the
 262  * G_DEFINE_DYNAMIC_TYPE_EXTENDED macros, since it depends on variable
 263  * names from that macro.
 264  *
 265  * Since: 2.38
 266  */
 267 #define G_ADD_PRIVATE_DYNAMIC(TypeName)         { \
 268   TypeName##_private_offset = sizeof (TypeName##Private); \
 269 }
 270
 271 GOBJECT_AVAILABLE_IN_ALL
 272 GType    g_type_module_get_type       (void) G_GNUC_CONST;
 273 GOBJECT_AVAILABLE_IN_ALL
 274 gboolean g_type_module_use            (GTypeModule          *module);
 275 GOBJECT_AVAILABLE_IN_ALL
 276 void     g_type_module_unuse          (GTypeModule          *module);
 277 GOBJECT_AVAILABLE_IN_ALL
 278 void     g_type_module_set_name       (GTypeModule          *module,
 279                                        const gchar          *name);
 280 GOBJECT_AVAILABLE_IN_ALL
 281 GType    g_type_module_register_type  (GTypeModule          *module,
 282                                        GType                 parent_type,
 283                                        const gchar          *type_name,
 284                                        const GTypeInfo      *type_info,
 285                                        GTypeFlags            flags);
 286 GOBJECT_AVAILABLE_IN_ALL
 287 void     g_type_module_add_interface  (GTypeModule          *module,
 288                                        GType                 instance_type,
 289                                        GType                 interface_type,
 290                                        const GInterfaceInfo *interface_info);
 291 GOBJECT_AVAILABLE_IN_ALL
 292 GType    g_type_module_register_enum  (GTypeModule          *module,
 293                                        const gchar          *name,
 294                                        const GEnumValue     *const_static_values);
 295 GOBJECT_AVAILABLE_IN_ALL
 296 GType    g_type_module_register_flags (GTypeModule          *module,
 297                                        const gchar          *name,
 298                                        const GFlagsValue    *const_static_values);
 299
 300 G_END_DECLS
 301
 302 #endif /* __G_TYPE_MODULE_H__ */