| <!-- ##### SECTION Title ##### --> |
| GTypeModule |
| |
| <!-- ##### SECTION Short_Description ##### --> |
| Type loading modules |
| |
| <!-- ##### SECTION Long_Description ##### --> |
| <para> |
| #GTypeModule provides a simple implementation of the #GTypePlugin |
| interface. The model of #GTypeModule is a dynamically loaded module |
| which implements some number of types and interface |
| implementations. When the module is loaded, it registers its types |
| and interfaces using g_type_module_register_type() and |
| g_type_module_add_interface(). As long as any instances of these |
| types and interface implementations are in use, the module is kept |
| loaded. When the types and interfaces are gone, the module may be |
| unloaded. If the types and interfaces become used again, the module |
| will be reloaded. Note that the last unref can not happen in module |
| code, since that would lead to the caller's code being unloaded before |
| g_object_unref() returns to it. |
| </para> |
| <para> |
| Keeping track of whether the module should be loaded or not is done by |
| using a use count - it starts at zero, and whenever it is greater than |
| zero, the module is loaded. The use count is maintained internally by |
| the type system, but also can be explicitly controlled by |
| g_type_module_use() and g_type_module_unuse(). Typically, when loading |
| a module for the first type, g_type_module_use() will be used to load |
| it so that it can initialize its types. At some later point, when the |
| module no longer needs to be loaded except for the type |
| implementations it contains, g_type_module_unuse() is called. |
| </para> |
| <para> |
| #GTypeModule does not actually provide any implementation of module |
| loading and unloading. To create a particular module type you must |
| derive from #GTypeModule and implement the load and unload functions |
| in #GTypeModuleClass. |
| </para> |
| |
| <!-- ##### SECTION See_Also ##### --> |
| <para> |
| <variablelist> |
| |
| <varlistentry> |
| <term>#GTypePlugin</term> |
| <listitem><para>The abstract type loader interface.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term>#GModule</term> |
| <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </para> |
| |
| <!-- ##### SECTION Stability_Level ##### --> |
| |
| |
| <!-- ##### STRUCT GTypeModule ##### --> |
| <para> |
| The members of the <structname>GTypeModule</structname> structure should not |
| be accessed directly, except for the @name field. |
| </para> |
| |
| @name: the name of the module |
| |
| <!-- ##### STRUCT GTypeModuleClass ##### --> |
| <para> |
| In order to implement dynamic loading of types based on #GTypeModule, |
| the @load and @unload functions in #GTypeModuleClass must be implemented. |
| </para> |
| |
| @parent_class: the parent class |
| @load: loads the module and registers one or more types using |
| g_type_module_register_type(). |
| @unload: unloads the module |
| |
| <!-- ##### FUNCTION g_type_module_use ##### --> |
| <para> |
| Increases the use count of a #GTypeModule by one. If the |
| use count was zero before, the plugin will be loaded. |
| </para> |
| |
| @module: a #GTypeModule |
| @Returns: %FALSE if the plugin needed to be loaded and |
| loading the plugin failed. |
| |
| |
| <!-- ##### FUNCTION g_type_module_unuse ##### --> |
| <para> |
| Decreases the use count of a #GTypeModule by one. If the |
| result is zero, the module will be unloaded. (However, the |
| #GTypeModule will not be freed, and types associated with the |
| #GTypeModule are not unregistered. Once a #GTypeModule is |
| initialized, it must exist forever.) |
| </para> |
| |
| @module: a #GTypeModule |
| |
| |
| <!-- ##### FUNCTION g_type_module_set_name ##### --> |
| <para> |
| Sets the name for a #GTypeModule |
| </para> |
| |
| @module: a #GTypeModule. |
| @name: a human-readable name to use in error messages. |
| |
| |
| <!-- ##### FUNCTION g_type_module_register_type ##### --> |
| <para> |
| Looks up or registers a type that is implemented with a particular |
| type plugin. If a type with name @type_name was previously registered, |
| the #GType identifier for the type is returned, otherwise the type |
| is newly registered, and the resulting #GType identifier returned. |
| </para> |
| <para> |
| When reregistering a type (typically because a module is unloaded |
| then reloaded, and reinitialized), @module and @parent_type must |
| be the same as they were previously. |
| </para> |
| <para> |
| As long as any instances of the type exist, the type plugin will |
| not be unloaded. |
| </para> |
| |
| @module: a #GTypeModule |
| @parent_type: the type for the parent class |
| @type_name: name for the type |
| @type_info: type information structure |
| @flags: flags field providing details about the type |
| @Returns: the new or existing type ID |
| |
| |
| <!-- ##### FUNCTION g_type_module_add_interface ##### --> |
| <para> |
| Registers an additional interface for a type, whose interface |
| lives in the given type plugin. If the interface was already registered |
| for the type in this plugin, nothing will be done. |
| </para> |
| <para> |
| As long as any instances of the type exist, the type plugin will |
| not be unloaded. |
| </para> |
| |
| @module: a #GTypeModule |
| @instance_type: type to which to add the interface. |
| @interface_type: interface type to add |
| @interface_info: type information structure |
| |
| |
| <!-- ##### FUNCTION g_type_module_register_enum ##### --> |
| <para> |
| Looks up or registers an enumeration that is implemented with a particular |
| type plugin. If a type with name @type_name was previously registered, |
| the #GType identifier for the type is returned, otherwise the type |
| is newly registered, and the resulting #GType identifier returned. |
| </para> |
| <para> |
| As long as any instances of the type exist, the type plugin will |
| not be unloaded. |
| </para> |
| |
| @module: a #GTypeModule |
| @name: name for the type |
| @const_static_values: an array of #GEnumValue structs for the possible |
| enumeration values. The array is terminated by a struct with all |
| members being 0. |
| @Returns: the new or existing type ID |
| @Since: 2.6 |
| |
| |
| <!-- ##### FUNCTION g_type_module_register_flags ##### --> |
| <para> |
| Looks up or registers a flags type that is implemented with a particular |
| type plugin. If a type with name @type_name was previously registered, |
| the #GType identifier for the type is returned, otherwise the type |
| is newly registered, and the resulting #GType identifier returned. |
| </para> |
| <para> |
| As long as any instances of the type exist, the type plugin will |
| not be unloaded. |
| </para> |
| |
| @module: a #GTypeModule |
| @name: name for the type |
| @const_static_values: an array of #GFlagsValue structs for the possible |
| flags values. The array is terminated by a struct with all |
| members being 0. |
| @Returns: the new or existing type ID |
| @Since: 2.6 |
| |
| |
| <!-- ##### MACRO G_DEFINE_DYNAMIC_TYPE ##### --> |
| <para> |
| A convenience macro for dynamic type implementations, which declares a |
| class initialization function, an instance initialization function (see |
| #GTypeInfo for information about these) and a static variable named |
| @t_n<!-- -->_parent_class pointing to the parent class. Furthermore, |
| it defines a <function>*_get_type()</function> and a static |
| <function>*_register_type()</function> function for use in your |
| <function>module_init()</function>. |
| See G_DEFINE_DYNAMIC_TYPE_EXTENDED() for an example. |
| </para> |
| |
| @TN: The name of the new type, in Camel case. |
| @t_n: The name of the new type, in lowercase, with words |
| separated by '_'. |
| @T_P: The #GType of the parent type. |
| @Since: 2.14 |
| |
| |
| <!-- ##### MACRO G_DEFINE_DYNAMIC_TYPE_EXTENDED ##### --> |
| <para> |
| A more general version of G_DEFINE_DYNAMIC_TYPE() which |
| allows to specify #GTypeFlags and custom code. |
| </para> |
| <informalexample><programlisting> |
| G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget, |
| gtk_gadget, |
| GTK_TYPE_THING, |
| 0, |
| G_IMPLEMENT_INTERFACE (TYPE_GIZMO, |
| gtk_gadget_gizmo_init)); |
| </programlisting> |
| expands to |
| <programlisting> |
| static void gtk_gadget_init (GtkGadget *self); |
| static void gtk_gadget_class_init (GtkGadgetClass *klass); |
| static void gtk_gadget_class_finalize (GtkGadgetClass *klass); |
| <!-- --> |
| static gpointer gtk_gadget_parent_class = NULL; |
| static GType gtk_gadget_type_id = 0; |
| <!-- --> |
| static void gtk_gadget_class_intern_init (gpointer klass) |
| { |
| gtk_gadget_parent_class = g_type_class_peek_parent (klass); |
| gtk_gadget_class_init ((GtkGadgetClass*) klass); |
| } |
| <!-- --> |
| GType |
| gtk_gadget_get_type (void) |
| { |
| return gtk_gadget_type_id; |
| } |
| <!-- --> |
| static void |
| gtk_gadget_register_type (GTypeModule *type_module) |
| { |
| const GTypeInfo g_define_type_info = { |
| sizeof (GtkGadgetClass), |
| (GBaseInitFunc) NULL, |
| (GBaseFinalizeFunc) NULL, |
| (GClassInitFunc) gtk_gadget_class_intern_init, |
| (GClassFinalizeFunc) gtk_gadget_class_finalize, |
| NULL, /* class_data */ |
| sizeof (GtkGadget), |
| 0, /* n_preallocs */ |
| (GInstanceInitFunc) gtk_gadget_init, |
| NULL /* value_table */ |
| }; |
| gtk_gadget_type_id = g_type_module_register_type (type_module, |
| GTK_TYPE_THING, |
| GtkGadget, |
| &g_define_type_info, |
| (GTypeFlags) flags); |
| { |
| const GInterfaceInfo g_implement_interface_info = { |
| (GInterfaceInitFunc) gtk_gadget_gizmo_init |
| }; |
| g_type_add_interface_static (g_define_type_id, TYPE_GIZMO, &g_implement_interface_info); |
| } |
| } |
| </programlisting> |
| </informalexample> |
| |
| @TypeName: The name of the new type, in Camel case. |
| @type_name: The name of the new type, in lowercase, with words |
| separated by '_'. |
| @TYPE_PARENT: The #GType of the parent type. |
| @flags: #GTypeFlags to pass to g_type_register_static() |
| @CODE: Custom code that gets inserted in the *_get_type() function. |
| @Since: 2.14 |
| |
| |