From 0cbbe0bcdfc00d4c245f36d27808eae09ab55e71 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 17 Oct 2003 23:33:03 +0000 Subject: [PATCH] Add /*< public >*/ and /*< private >*/ markers for documentation purposes. Sat Oct 18 01:30:47 2003 Matthias Clasen * gtypeplugin.h (struct _GTypePluginClass): Add /*< public >*/ and /*< private >*/ markers for documentation purposes. * gobject/tmpl/gboxed.sgml: * gobject/tmpl/gtypeplugin.sgml: * gobject/tmpl/enumerations_flags.sgml: Additions. --- docs/reference/ChangeLog | 6 + .../reference/gobject/tmpl/enumerations_flags.sgml | 71 +++++++--- docs/reference/gobject/tmpl/gboxed.sgml | 47 ++++++- docs/reference/gobject/tmpl/gtypeplugin.sgml | 145 ++++++++++++++++----- gobject/ChangeLog | 5 + gobject/gtypeplugin.h | 2 + 6 files changed, 218 insertions(+), 58 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index afd8929..0e6a60c 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,9 @@ +Sat Oct 18 01:30:47 2003 Matthias Clasen + + * gobject/tmpl/gboxed.sgml: + * gobject/tmpl/gtypeplugin.sgml: + * gobject/tmpl/enumerations_flags.sgml: Additions. + Sat Oct 18 00:04:22 2003 Matthias Clasen * 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 6f9462f..87f276e 100644 --- a/docs/reference/gobject/tmpl/enumerations_flags.sgml +++ b/docs/reference/gobject/tmpl/enumerations_flags.sgml @@ -202,41 +202,80 @@ with that nickname - +Registers a new static enumeration type with the name @name. + + +It is normally more convenient to let +glib-mkenums generate a +my_enum_get_type() function from a usual C enumeration definition +than to write one yourself using g_enum_register_static(). -@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. - +Registers a new static flags type with the name @name. + + +It is normally more convenient to let +glib-mkenums generate a +my_flags_get_type() function from a usual C enumeration definition +than to write one yourself using g_flags_register_static(). -@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. - +This function is meant to be called from the complete_type_info() function +of a #GTypePlugin implementation, as in the following example: + + +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); +} + + -@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. - +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. -@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 7ca54ec..e6b36e9 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. - -@boxed_init: -@is_refcounted: - +Creates a new %G_TYPE_POINTER derived type id for a new +pointer type with name @name. -@name: -@Returns: +@name: the name of the new pointer type. +@Returns: a new %G_TYPE_POINTER derived type id for @name. @@ -84,3 +82,40 @@ The #GType for #GString. + + +The #GType for a boxed type holding a %NULL-terminated array of strings. + + +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(). + + +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); + + + + + + + + + + diff --git a/docs/reference/gobject/tmpl/gtypeplugin.sgml b/docs/reference/gobject/tmpl/gtypeplugin.sgml index 8ba0550..eeaf40e 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 - +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: + + + + + 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: +new_type_id = g_type_register_dynamic (parent_type_id, + "TypeName", + new_type_plugin, + type_flags); + + where new_type_plugin is an implementation of the + #GTypePlugin interface. + + + 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 new_type_id. + + + 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 + new_type_plugin. + + + 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). + + + 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 new_type_plugin. + + + Things may repeat from the second step. + + + + +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. + + +#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. - +#GTypeModule and g_type_register_dynamic(). @@ -22,88 +78,105 @@ An interface for dynamically loadable types - +The #GTypePlugin interface is used by the type system in order to handle +the lifecycle of dynamically loaded types. -@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 memset(s, 0, sizeof (s)) before calling + this function. +@complete_interface_info: Fills in missing parts of the #GInterfaceInfo + for the interface. The structs is initialized with + memset(s, 0, sizeof (s)) before calling + this function. - +The type of the @use_plugin function of #GTypePluginClass, which gets called +to increase the use count of @plugin. -@plugin: +@plugin: the #GTypePlugin whose use count should be increased - +The type of the @unuse_plugin function of #GTypePluginClass. -@plugin: +@plugin: the #GTypePlugin whose use count should be decreased - +The type of the @complete_type_info function of #GTypePluginClass. -@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 - +The type of the @complete_interface_info function of #GTypePluginClass. -@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 - +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. -@plugin: +@plugin: a #GTypePlugin - +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. -@plugin: +@plugin: a #GTypePlugin - +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. -@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 - +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. -@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 74ec287..c975e80 100644 --- a/gobject/ChangeLog +++ b/gobject/ChangeLog @@ -1,3 +1,8 @@ +Sat Oct 18 01:24:14 2003 Matthias Clasen + + * gtypeplugin.h (struct _GTypePluginClass): Add /*< public >*/ + and /*< private >*/ markers for documentation purposes. + Thu Oct 2 07:37:12 2003 Tim Janik * gtype.c: fix post class_init interface initialization logic diff --git a/gobject/gtypeplugin.h b/gobject/gtypeplugin.h index 415259a..a8e9803 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; -- 2.7.4