2008-06-21 Stefan Kost <ensonic@users.sf.net>
+ * docs/reference/gobject/tmpl/gtypemodule.sgml:
+ * gobject/gtypemodule.c:
+ * gobject/gtypemodule.h:
+ Migrating docs.
+
+2008-06-21 Stefan Kost <ensonic@users.sf.net>
+
* gobject/gboxed.c:
* gobject/gclosure.c:
* gobject/genums.c:
+++ /dev/null
-<!-- ##### 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_module_register_type()
-@CODE: Custom code that gets inserted in the *_get_type() function.
-@Since: 2.14
-
-
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:gtypemodule
+ * @Short_description: Type loading modules
+ * @See_also:<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>
+ * @Title: GTypeModule
+ *
+ * #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.
+ *
+ * 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.
+ *
+ * #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.
+ */
#include <stdlib.h>
return type_module_type;
}
+/**
+ * g_type_module_set_name:
+ * @module: a #GTypeModule.
+ * @name: a human-readable name to use in error messages.
+ *
+ * Sets the name for a #GTypeModule
+ */
void
g_type_module_set_name (GTypeModule *module,
const gchar *name)
return NULL;
}
+/**
+ * g_type_module_use:
+ * @module: a #GTypeModule
+ *
+ * Increases the use count of a #GTypeModule by one. If the
+ * use count was zero before, the plugin will be loaded.
+ *
+ * Returns: %FALSE if the plugin needed to be loaded and
+ * loading the plugin failed.
+ */
gboolean
g_type_module_use (GTypeModule *module)
{
return TRUE;
}
+/**
+ * g_type_module_unuse:
+ * @module: a #GTypeModule
+ *
+ * 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.)
+ */
void
g_type_module_unuse (GTypeModule *module)
{
*info = module_interface_info->info;
}
+/**
+ * g_type_module_register_type:
+ * @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
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * As long as any instances of the type exist, the type plugin will
+ * not be unloaded.
+ *
+ * Returns: the new or existing type ID
+ */
GType
g_type_module_register_type (GTypeModule *module,
GType parent_type,
return module_type_info->type;
}
+/**
+ * g_type_module_add_interface:
+ * @module: a #GTypeModule
+ * @instance_type: type to which to add the interface.
+ * @interface_type: interface type to add
+ * @interface_info: type information structure
+ *
+ * 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.
+ *
+ * As long as any instances of the type exist, the type plugin will
+ * not be unloaded.
+ */
void
g_type_module_add_interface (GTypeModule *module,
GType instance_type,
module_interface_info->info = *interface_info;
}
+/**
+ * g_type_module_register_enum:
+ * @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.
+ *
+ * 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.
+ *
+ * As long as any instances of the type exist, the type plugin will
+ * not be unloaded.
+ *
+ * Since: 2.6
+ * Returns: the new or existing type ID
+ */
GType
g_type_module_register_enum (GTypeModule *module,
const gchar *name,
G_TYPE_ENUM, name, &enum_type_info, 0);
}
+/**
+ * g_type_module_register_flags:
+ * @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.
+ *
+ * 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.
+ *
+ * As long as any instances of the type exist, the type plugin will
+ * not be unloaded.
+ *
+ * Since: 2.6
+ * Returns: the new or existing type ID
+ */
GType
g_type_module_register_flags (GTypeModule *module,
const gchar *name,
#define G_IS_TYPE_MODULE_CLASS(class) (G_TYPE_CHECK_CLASS_TYPE ((class), G_TYPE_TYPE_MODULE))
#define G_TYPE_MODULE_GET_CLASS(module) (G_TYPE_INSTANCE_GET_CLASS ((module), G_TYPE_TYPE_MODULE, GTypeModuleClass))
+/**
+ * GTypeModule:
+ * @name: the name of the module
+ *
+ * The members of the <structname>GTypeModule</structname> structure should not
+ * be accessed directly, except for the @name field.
+ */
struct _GTypeModule
{
GObject parent_instance;
gchar *name;
};
+/**
+ * GTypeModuleClass:
+ * @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
+ *
+ * In order to implement dynamic loading of types based on #GTypeModule,
+ * the @load and @unload functions in #GTypeModuleClass must be implemented.
+ */
struct _GTypeModuleClass
{
GObjectClass parent_class;
void (*reserved4) (void);
};
+/**
+ * G_DEFINE_DYNAMIC_TYPE:
+ * @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.
+ *
+ * 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.
+ *
+ * Since: 2.14
+ */
#define G_DEFINE_DYNAMIC_TYPE(TN, t_n, T_P) G_DEFINE_DYNAMIC_TYPE_EXTENDED (TN, t_n, T_P, 0, {})
+/**
+ * G_DEFINE_DYNAMIC_TYPE_EXTENDED:
+ * @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_module_register_type()
+ * @CODE: Custom code that gets inserted in the *_get_type() function.
+ *
+ * A more general version of G_DEFINE_DYNAMIC_TYPE() which
+ * allows to specify #GTypeFlags and custom code.
+ *
+ * |[
+ * G_DEFINE_DYNAMIC_TYPE_EXTENDED (GtkGadget,
+ * gtk_gadget,
+ * GTK_TYPE_THING,
+ * 0,
+ * G_IMPLEMENT_INTERFACE (TYPE_GIZMO,
+ * gtk_gadget_gizmo_init));
+ * ]|
+ * expands to
+ * |[
+ * 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);
+ * }
+ * }
+ * ]|
+ *
+ * Since: 2.14
+ */
#define G_DEFINE_DYNAMIC_TYPE_EXTENDED(TypeName, type_name, TYPE_PARENT, flags, CODE) \
static void type_name##_init (TypeName *self); \
static void type_name##_class_init (TypeName##Class *klass); \
projects / platform / upstream / glib.git / commitdiff