Document private instance data.

Mon Mar 10 11:33:10 2003  Owen Taylor  <otaylor@redhat.com>

        * gobject/tmpl/gtype.sgml gobject/gobject-sections.txt:
        Document private instance data.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 3b143fe..bf0d1d1 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+Mon Mar 10 11:33:10 2003  Owen Taylor  <otaylor@redhat.com>
+
+       * gobject/tmpl/gtype.sgml gobject/gobject-sections.txt: 
+       Document private instance data.
+
 2003-02-11  Matthias Clasen  <maclas@gmx.de>
 
        * glib/tmpl/string_utils.sgml: Fix an off-by-one error in the

diff --git a/docs/reference/gobject/gobject-sections.txt b/docs/reference/gobject/gobject-sections.txt
index 2f629bd..3215304 100644 (file)
--- a/docs/reference/gobject/gobject-sections.txt
+++ b/docs/reference/gobject/gobject-sections.txt
@@ -30,6 +30,7 @@ G_TYPE_FROM_CLASS
 G_TYPE_FROM_INTERFACE
 G_TYPE_INSTANCE_GET_CLASS
 G_TYPE_INSTANCE_GET_INTERFACE
+G_TYPE_INSTANCE_GET_PRIVATE
 G_TYPE_CHECK_INSTANCE
 G_TYPE_CHECK_INSTANCE_CAST
 G_TYPE_CHECK_INSTANCE_TYPE
@@ -52,6 +53,7 @@ g_type_class_ref
 g_type_class_peek
 g_type_class_unref
 g_type_class_peek_parent
+g_type_class_add_private
 g_type_interface_peek
 g_type_interface_peek_parent
 g_type_children
@@ -97,6 +99,7 @@ g_type_check_class_is_a
 g_type_check_is_value_type
 g_type_check_value
 g_type_check_value_holds
+g_type_instance_get_private
 g_type_test_flags
 g_type_name_from_instance
 g_type_name_from_class

diff --git a/docs/reference/gobject/tmpl/enumerations_flags.sgml b/docs/reference/gobject/tmpl/enumerations_flags.sgml
index b429f8e..e650b1a 100644 (file)
--- a/docs/reference/gobject/tmpl/enumerations_flags.sgml
+++ b/docs/reference/gobject/tmpl/enumerations_flags.sgml
@@ -18,12 +18,21 @@ Enumeration and flags types
 
 </para>
 
+@g_type_class: 
+@minimum: 
+@maximum: 
+@n_values: 
+@values: 
 
 <!-- ##### STRUCT GFlagsClass ##### -->
 <para>
 
 </para>
 
+@g_type_class: 
+@mask: 
+@n_values: 
+@values: 
 
 <!-- ##### MACRO G_ENUM_CLASS_TYPE ##### -->
 <para>

diff --git a/docs/reference/gobject/tmpl/gparamspec.sgml b/docs/reference/gobject/tmpl/gparamspec.sgml
index 1490fc0..708bd92 100644 (file)
--- a/docs/reference/gobject/tmpl/gparamspec.sgml
+++ b/docs/reference/gobject/tmpl/gparamspec.sgml
@@ -107,6 +107,13 @@ Retrieve the #GType to intiialize a #GValue for this parameter.
 
 </para>
 
+@g_type_class: 
+@value_type: 
+@finalize: 
+@value_set_default: 
+@value_validate: 
+@values_cmp: 
+@dummy: 
 
 <!-- ##### ENUM GParamFlags ##### -->
 <para>

diff --git a/docs/reference/gobject/tmpl/gtype.sgml b/docs/reference/gobject/tmpl/gtype.sgml
index 2304a66..eddb371 100644 (file)
--- a/docs/reference/gobject/tmpl/gtype.sgml
+++ b/docs/reference/gobject/tmpl/gtype.sgml
@@ -462,6 +462,17 @@ Returns the interface structure for interface @g_type of a given @instance.
 @c_type: The corresponding C type of @g_type.
 
 
+<!-- ##### MACRO G_TYPE_INSTANCE_GET_PRIVATE ##### -->
+<para>
+Gets the private structure for a particular type.
+The private structure must have been registered in the
+class_init function with g_type_class_add_private().
+</para>
+
+@instance: the instance of a type deriving from @private_type.
+@g_type: the type identifying which private data to retrieve.
+@c_type: The C type for the private structure.
+
 <!-- ##### MACRO G_TYPE_CHECK_INSTANCE ##### -->
 <para>
 
@@ -693,6 +704,48 @@ g_type_class_peek (g_type_parent (G_TYPE_FROM_CLASS (g_class)));
 @Returns: The parent class of @g_class.
 
 
+<!-- ##### FUNCTION g_type_class_add_private ##### -->
+<para>
+Registers a private structure for a instantiatable type;
+when an object is allocated, the private structures for
+the type and and all of its parent types are allocated
+sequentially in the same memory block as the public
+structures. This function should be called in the
+type's class_init() function. The private structure can
+be retrieved using the G_TYPE_INSTANCE_GET_PRIVATE() macro.
+The following example shows attaching a private structure
+<structname>MyObjectPrivate</structname> to an object
+<structname>MyObject</structname> defined in the standard GObject
+fashion.
+</para>
+<programlisting>
+typedef struct _MyObjectPrivate MyObjectPrivate;
+
+struct _MyObjectPrivate {
+  int some_field;
+};
+
+&num;define MY_OBJECT_GET_PRIVATE(o)  \
+   (G_TYPE_INSTANCE_GET_PRIVATE ((o), MY_TYPE_OBJECT, MyObjectPrivate))
+
+static void
+my_object_class_init (MyObjectClass *klass)
+{
+  g_type_class_add_private (klass, sizeof (MyObjectPrivate));
+}
+
+static int
+my_object_get_some_field (MyObject *my_object)
+{
+  MyObjectPrivate *priv = MY_OBJECT_GET_PRIVATE (my_object);
+
+  return priv->some_field;
+}
+</programlisting>
+
+@g_class: class structure for an instantiatable type
+@private_size: size of private structure.
+
 <!-- ##### FUNCTION g_type_interface_peek ##### -->
 <para>
 Returns the #GTypeInterface structure of an interface to which the passed in 
@@ -751,7 +804,6 @@ Returns the prerequisites of an interfaces type.
 @n_prerequisites: location to return the number of prerequisites, or %NULL
 @Returns: a newly-allocated zero-terminated array of #GType containing 
    the prerequisites of @interface_type
-<!-- # Unused Parameters # -->
 @Since: 2.2
 
 
@@ -1411,5 +1463,9 @@ The fundamental type for #GObject.
 
 </para>
 
-
-
+<!--
+Local variables:
+mode: sgml
+sgml-parent-document: ("../gobject-docs.sgml" "book" "refsect2" "")
+End:
+-->

diff --git a/docs/reference/gobject/tmpl/gtypemodule.sgml b/docs/reference/gobject/tmpl/gtypemodule.sgml
index cdc021e..b3828a5 100644 (file)
--- a/docs/reference/gobject/tmpl/gtypemodule.sgml
+++ b/docs/reference/gobject/tmpl/gtypemodule.sgml
@@ -68,6 +68,13 @@ in #GTypeModuleClass.
 
 </para>
 
+@parent_class: 
+@load: 
+@unload: 
+@reserved1: 
+@reserved2: 
+@reserved3: 
+@reserved4: 
 
 <!-- ##### FUNCTION g_type_module_use ##### -->
 <para>

diff --git a/docs/reference/gobject/tmpl/gtypeplugin.sgml b/docs/reference/gobject/tmpl/gtypeplugin.sgml
index 6bed0af..8ba0550 100644 (file)
--- a/docs/reference/gobject/tmpl/gtypeplugin.sgml
+++ b/docs/reference/gobject/tmpl/gtypeplugin.sgml
@@ -25,6 +25,11 @@ An interface for dynamically loadable types
 
 </para>
 
+@base_iface: 
+@use_plugin: 
+@unuse_plugin: 
+@complete_type_info: 
+@complete_interface_info: 
 
 <!-- ##### USER_FUNCTION GTypePluginUse ##### -->
 <para>

diff --git a/docs/reference/gobject/tmpl/objects.sgml b/docs/reference/gobject/tmpl/objects.sgml
index 870d464..fc14fc6 100644 (file)
--- a/docs/reference/gobject/tmpl/objects.sgml
+++ b/docs/reference/gobject/tmpl/objects.sgml
@@ -27,6 +27,7 @@ to the #GObject implementation and should never be accessed directly.
 
 </para>
 
+@g_type_class: 
 
 <!-- ##### USER_FUNCTION GObjectGetPropertyFunc ##### -->
 <para>

diff --git a/docs/reference/gobject/tmpl/param_value_types.sgml b/docs/reference/gobject/tmpl/param_value_types.sgml
index 3cbb303..022f48d 100644 (file)
--- a/docs/reference/gobject/tmpl/param_value_types.sgml
+++ b/docs/reference/gobject/tmpl/param_value_types.sgml
@@ -840,7 +840,7 @@ See g_param_spec_internal() for details on property names.
 @maximum:       maximum value for the property specified
 @default_value: default value for the property specified
 @flags:         flags for the property specified
-@Returns:  a newly created parameter specification 
+@Returns:  a newly created parameter specification
 
 
 <!-- ##### FUNCTION g_value_set_double ##### -->
@@ -1557,6 +1557,6 @@ See g_param_spec_internal() for details on property names.
 @element_spec:  a #GParamSpec describing the elements contained in 
                 arrays of this property, may be %NULL
 @flags:         flags for the property specified
-@Returns: a newly created parameter specification 
+@Returns: a newly created parameter specification