diff options
| -rw-r--r-- | docs/reference/ChangeLog | 6 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/enumerations_flags.sgml | 71 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/gboxed.sgml | 47 | ||||
| -rw-r--r-- | docs/reference/gobject/tmpl/gtypeplugin.sgml | 145 | ||||
| -rw-r--r-- | gobject/ChangeLog | 5 | ||||
| -rw-r--r-- | gobject/gtypeplugin.h | 2 |
6 files changed, 218 insertions, 58 deletions
diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index afd8929af..0e6a60cac 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,9 @@ +Sat Oct 18 01:30:47 2003 Matthias Clasen <maclas@gmx.de> + + * gobject/tmpl/gboxed.sgml: + * gobject/tmpl/gtypeplugin.sgml: + * gobject/tmpl/enumerations_flags.sgml: Additions. + Sat Oct 18 00:04:22 2003 Matthias Clasen <maclas@gmx.de> * gobject/gobject.types: List GObject here, since the diff --git a/docs/reference/gobject/tmpl/enumerations_flags.sgml b/docs/reference/gobject/tmpl/enumerations_flags.sgml index 6f9462ff2..87f276eba 100644 --- a/docs/reference/gobject/tmpl/enumerations_flags.sgml +++ b/docs/reference/gobject/tmpl/enumerations_flags.sgml @@ -202,41 +202,80 @@ with that nickname <!-- ##### 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. diff --git a/docs/reference/gobject/tmpl/gboxed.sgml b/docs/reference/gobject/tmpl/gboxed.sgml index 7ca54ec10..e6b36e9d6 100644 --- a/docs/reference/gobject/tmpl/gboxed.sgml +++ b/docs/reference/gobject/tmpl/gboxed.sgml @@ -63,18 +63,16 @@ provided to copy and free opaque boxed structures of this type. @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 ##### --> @@ -84,3 +82,40 @@ The #GType for #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> + + diff --git a/docs/reference/gobject/tmpl/gtypeplugin.sgml b/docs/reference/gobject/tmpl/gtypeplugin.sgml index 8ba0550a5..eeaf40ee5 100644 --- a/docs/reference/gobject/tmpl/gtypeplugin.sgml +++ b/docs/reference/gobject/tmpl/gtypeplugin.sgml @@ -6,12 +6,68 @@ An interface for dynamically loadable types <!-- ##### 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 ##### --> @@ -22,88 +78,105 @@ An interface for dynamically loadable types <!-- ##### 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 diff --git a/gobject/ChangeLog b/gobject/ChangeLog index 74ec2870c..c975e80c5 100644 --- a/gobject/ChangeLog +++ b/gobject/ChangeLog @@ -1,3 +1,8 @@ +Sat Oct 18 01:24:14 2003 Matthias Clasen <maclas@gmx.de> + + * gtypeplugin.h (struct _GTypePluginClass): Add /*< public >*/ + and /*< private >*/ markers for documentation purposes. + Thu Oct 2 07:37:12 2003 Tim Janik <timj@gtk.org> * gtype.c: fix post class_init interface initialization logic diff --git a/gobject/gtypeplugin.h b/gobject/gtypeplugin.h index 415259ad2..a8e9803d6 100644 --- a/gobject/gtypeplugin.h +++ b/gobject/gtypeplugin.h @@ -50,8 +50,10 @@ typedef void (*GTypePluginCompleteInterfaceInfo) (GTypePlugin *plugin, GInterfaceInfo *info); struct _GTypePluginClass { + /*< private >*/ GTypeInterface base_iface; + /*< public >*/ GTypePluginUse use_plugin; GTypePluginUnuse unuse_plugin; GTypePluginCompleteTypeInfo complete_type_info; |