<!-- ##### FUNCTION g_enum_register_static ##### -->
<para>
-
+Registers a new static enumeration type with the name @name.
+</para>
+<para>
+It is normally more convenient to let
+<link linkend="glib-mkenums">glib-mkenums</link> generate a
+my_enum_get_type() function from a usual C enumeration definition
+than to write one yourself using g_enum_register_static().
</para>
-@name:
-@const_static_values:
-@Returns:
+@name: A nul-terminated string used as the name of the new 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 type identifier.
<!-- ##### FUNCTION g_flags_register_static ##### -->
<para>
-
+Registers a new static flags type with the name @name.
+</para>
+<para>
+It is normally more convenient to let
+<link linkend="glib-mkenums">glib-mkenums</link> generate a
+my_flags_get_type() function from a usual C enumeration definition
+than to write one yourself using g_flags_register_static().
</para>
-@name:
-@const_static_values:
-@Returns:
+@name: A nul-terminated string used as the name of the new 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 type identifier.
<!-- ##### FUNCTION g_enum_complete_type_info ##### -->
<para>
-
+This function is meant to be called from the complete_type_info() function
+of a #GTypePlugin implementation, as in the following example:
+<informalexample>
+<programlisting>
+static void
+my_enum_complete_type_info (GTypePlugin *plugin,
+ GType g_type,
+ GTypeInfo *info,
+ GTypeValueTable *value_table)
+{
+ static const GEnumValue values[] = {
+ { MY_ENUM_FOO, "MY_ENUM_FOO", "foo" },
+ { MY_ENUM_BAR, "MY_ENUM_BAR", "bar" }
+ };
+
+ g_enum_complete_type_info (type, info, values);
+}
+</programlisting>
+</informalexample>
</para>
-@g_enum_type:
-@info:
-@const_values:
+@g_enum_type: the type identifier of the type being completed
+@info: the #GTypeInfo struct to be filled in
+@const_values: An array of #GEnumValue structs for the possible
+ enumeration values. The array is terminated by a struct with all
+ members being 0.
<!-- ##### FUNCTION g_flags_complete_type_info ##### -->
<para>
-
+This function is meant to be called from the complete_type_info() function
+of a #GTypePlugin implementation, see the example for
+g_enumeration_complete_type_info() above.
</para>
-@g_flags_type:
-@info:
-@const_values:
+@g_flags_type: the type identifier of the type being completed
+@info: the #GTypeInfo struct to be filled in
+@const_values: An array of #GFlagsValue structs for the possible
+ enumeration values. The array is terminated by a struct with all
+ members being 0.
@boxed_copy: Boxed structure copy function.
@boxed_free: Boxed structure free function.
@Returns: New %G_TYPE_BOXED derived type id for @name.
-<!-- # Unused Parameters # -->
-@boxed_init:
-@is_refcounted:
<!-- ##### FUNCTION g_pointer_type_register_static ##### -->
<para>
-
+Creates a new %G_TYPE_POINTER derived type id for a new
+pointer type with name @name.
</para>
-@name:
-@Returns:
+@name: the name of the new pointer type.
+@Returns: a new %G_TYPE_POINTER derived type id for @name.
<!-- ##### MACRO G_TYPE_GSTRING ##### -->
+<!-- ##### MACRO G_TYPE_STRV ##### -->
+<para>
+The #GType for a boxed type holding a %NULL-terminated array of strings.
+</para>
+<para>
+The code fragments in the following example show the use of a property of
+type #G_TYPE_STRV with g_object_class_install_property(), g_object_set()
+and g_object_get().
+</para>
+<informalexample><programlisting>
+g_object_class_install_property (object_class,
+ PROP_AUTHORS,
+ g_param_spec_boxed ("authors",
+ _("Authors"),
+ _("List of authors"),
+ G_TYPE_STRV,
+ G_PARAM_READWRITE));
+
+
+gchar *authors[] = { "Owen", "Tim", NULL };
+g_object_set (obj, "authors", authors, NULL);
+
+
+gchar *writers[];
+g_object_get (obj, "authors", &writers, NULL);
+/* do something with writers */
+g_strfreev (writers);
+</programlisting></informalexample>
+
+
+
+<!-- ##### TYPEDEF GStrv ##### -->
+<para>
+
+</para>
+
+
<!-- ##### SECTION Long_Description ##### -->
<para>
-
+The GObject type system supports dynamic loading of types. The #GTypePlugin
+interface is used to handle the lifecycle of dynamically loaded types.
+It goes as follows:
+</para>
+<para>
+<orderedlist>
+<listitem><para>
+ The type is initially introduced (usually upon loading the module
+ the first time, or by your main application that knows what modules
+ introduces what types), like this:
+<literal>new_type_id = g_type_register_dynamic (parent_type_id,
+ "TypeName",
+ new_type_plugin,
+ type_flags);
+</literal>
+ where <literal>new_type_plugin</literal> is an implementation of the
+ #GTypePlugin interface.
+</para></listitem>
+<listitem><para>
+ The type's implementation is referenced, e.g. through
+ g_type_class_ref() or through g_type_create_instance() (this is
+ being called by g_object_new()) or through one of the above done on
+ a type derived from <literal>new_type_id</literal>.
+</para></listitem>
+<listitem><para>
+ This causes the type system to load the type's implementation by calling
+ g_type_plugin_use() and g_type_plugin_complete_type_info() on
+ <literal>new_type_plugin</literal>.
+</para></listitem>
+<listitem><para>
+ At some point the type's implementation isn't required anymore, e.g. after
+ g_type_class_unref() or g_type_free_instance() (called when the reference
+ count of an instance drops to zero).
+</para></listitem>
+<listitem><para>
+ This causes the type system to throw away the information retrieved from
+ g_type_plugin_complete_type_info() and then it calls
+ g_type_plugin_unuse() on <literal>new_type_plugin</literal>.
+</para></listitem>
+<listitem><para>
+ Things may repeat from the second step.
+</para></listitem>
+</orderedlist>
+</para>
+<para>
+So basically, you need to implement a #GTypePlugin type that carries a
+use_count, once use_count goes from zero to one, you need to load the
+implementation to successfully handle the upcoming
+g_type_plugin_complete_type_info() call. Later, maybe after succeeding
+use/unuse calls, once use_count drops to zero, you can unload the
+implementation again. The type system makes sure to call g_type_plugin_use()
+and g_type_plugin_complete_type_info() again when the type is needed again.
+</para>
+<para>
+#GTypeModule is an implementation of #GTypePlugin that already implements
+most of this except for the actual module loading and unloading. It even
+handles multiple registered types per module.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-
+#GTypeModule and g_type_register_dynamic().
</para>
<!-- ##### STRUCT GTypePlugin ##### -->
<!-- ##### STRUCT GTypePluginClass ##### -->
<para>
-
+The #GTypePlugin interface is used by the type system in order to handle
+the lifecycle of dynamically loaded types.
</para>
-@base_iface:
-@use_plugin:
-@unuse_plugin:
-@complete_type_info:
-@complete_interface_info:
+@use_plugin: Increases the use count of the plugin.
+@unuse_plugin: Decreases the use count of the plugin.
+@complete_type_info: Fills in the #GTypeInfo and
+ #GTypeValueTable structs for the type. The structs are initialized
+ with <literal>memset(s, 0, sizeof (s))</literal> before calling
+ this function.
+@complete_interface_info: Fills in missing parts of the #GInterfaceInfo
+ for the interface. The structs is initialized with
+ <literal>memset(s, 0, sizeof (s))</literal> before calling
+ this function.
<!-- ##### USER_FUNCTION GTypePluginUse ##### -->
<para>
-
+The type of the @use_plugin function of #GTypePluginClass, which gets called
+to increase the use count of @plugin.
</para>
-@plugin:
+@plugin: the #GTypePlugin whose use count should be increased
<!-- ##### USER_FUNCTION GTypePluginUnuse ##### -->
<para>
-
+The type of the @unuse_plugin function of #GTypePluginClass.
</para>
-@plugin:
+@plugin: the #GTypePlugin whose use count should be decreased
<!-- ##### USER_FUNCTION GTypePluginCompleteTypeInfo ##### -->
<para>
-
+The type of the @complete_type_info function of #GTypePluginClass.
</para>
-@plugin:
-@g_type:
-@info:
-@value_table:
+@plugin: the #GTypePlugin
+@g_type: the #GType whose info is completed
+@info: the #GTypeInfo struct to fill in
+@value_table: the #GTypeValueTable to fill in
<!-- ##### USER_FUNCTION GTypePluginCompleteInterfaceInfo ##### -->
<para>
-
+The type of the @complete_interface_info function of #GTypePluginClass.
</para>
-@plugin:
-@instance_type:
-@interface_type:
-@info:
+@plugin: the #GTypePlugin
+@instance_type: the #GType of an instantiable type to which the interface
+ is added
+@interface_type: the #GType of the interface whose info is completed
+@info: the #GInterfaceInfo to fill in
<!-- ##### FUNCTION g_type_plugin_use ##### -->
<para>
-
+Calls the @use_plugin function from the #GTypePluginClass of @plugin.
+There should be no need to use this function outside of the GObject
+type system itself.
</para>
-@plugin:
+@plugin: a #GTypePlugin
<!-- ##### FUNCTION g_type_plugin_unuse ##### -->
<para>
-
+Calls the @unuse_plugin function from the #GTypePluginClass of @plugin.
+There should be no need to use this function outside of the GObject
+type system itself.
</para>
-@plugin:
+@plugin: a #GTypePlugin
<!-- ##### FUNCTION g_type_plugin_complete_type_info ##### -->
<para>
-
+Calls the @complete_type_info function from the #GTypePluginClass of @plugin.
+There should be no need to use this function outside of the GObject
+type system itself.
</para>
-@plugin:
-@g_type:
-@info:
-@value_table:
+@plugin: a #GTypePlugin
+@g_type: the #GType whose info is completed
+@info: the #GTypeInfo struct to fill in
+@value_table: the #GTypeValueTable to fill in
<!-- ##### FUNCTION g_type_plugin_complete_interface_info ##### -->
<para>
-
+Calls the @complete_interface_info function from the #GTypePluginClass
+of @plugin. There should be no need to use this function outside of the
+GObject type system itself.
</para>
-@plugin:
-@instance_type:
-@interface_type:
-@info:
+@plugin: the #GTypePlugin
+@instance_type: the #GType of an instantiable type to which the interface
+ is added
+@interface_type: the #GType of the interface whose info is completed
+@info: the #GInterfaceInfo to fill in
projects / platform / upstream / glib.git / commitdiff