add @since: for _add_private, _GET_PRIVATE fix example to use ->priv and

* gobject/tmpl/gtype.sgml:
add @since: for _add_private, _GET_PRIVATE
* gobject/tut_gobject.xml:
fix example to use ->priv and not ->private
* gobject/tut_howto.xml:
fix g_type_class_add_private example

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index c81f452eec2c9492e30b9486bcb60117763843d1..d4e151633bef8a8aa729880c5835d1de2708f548 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,12 @@
+2006-02-22  Stefan Kost  <ensonic@users.sf.net>
+
+       * gobject/tmpl/gtype.sgml:
+         add @since: for _add_private, _GET_PRIVATE
+       * gobject/tut_gobject.xml:
+         fix example to use ->priv and not ->private
+       * gobject/tut_howto.xml:
+         fix g_type_class_add_private example
+
 2006-02-14  Tor Lillqvist  <tml@novell.com>
 
        * glib/tmpl/iochannels.sgml: Document some Windows-specific issues.

diff --git a/docs/reference/gobject/tmpl/gtype.sgml b/docs/reference/gobject/tmpl/gtype.sgml
index 9ca599caacdc4dc426608002cf8d8a9354fdbb1b..a2cb4966da202845852bfe419ef89cf41f2644bb 100644 (file)
--- a/docs/reference/gobject/tmpl/gtype.sgml
+++ b/docs/reference/gobject/tmpl/gtype.sgml
@@ -240,10 +240,6 @@ A structure that provides information to the type system which is
 used specifically for managing interface types.
 </para>
 
-@interface_init:       Location of the function that initializes the interface.
-@interface_finalize:   Location of the function that finalizes the interface.
-@interface_data:       Location of user data passed to the @interface_init and
-                       @interface_finalize functions (optional).
 
 <!-- ##### STRUCT GTypeValueTable ##### -->
 <para>
@@ -511,6 +507,7 @@ This macro should only be used in type implementations.
 @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.
+@Since: 2.4
 
 
 <!-- ##### MACRO G_TYPE_CHECK_INSTANCE ##### -->
@@ -827,6 +824,7 @@ my_object_get_some_field (MyObject *my_object)
 
 @g_class: class structure for an instantiatable type
 @private_size: size of private structure.
+@Since: 2.4
 
 
 <!-- ##### FUNCTION g_type_interface_peek ##### -->

diff --git a/docs/reference/gobject/tut_gobject.xml b/docs/reference/gobject/tut_gobject.xml
index 7a76154e5a7e71b4555a9dbeedf966ef48f17b77..e790251b92d69a57e06b926a83bd46ab29dcbafd 100644 (file)
--- a/docs/reference/gobject/tut_gobject.xml
+++ b/docs/reference/gobject/tut_gobject.xml
@@ -547,14 +547,14 @@ maman_bar_set_property (GObject      *object,
 
   switch (property_id) {
   case MAMAN_BAR_CONSTRUCT_NAME: {
-    g_free (self->private->name);
-    self->private->name = g_value_dup_string (value);
-    g_print ("maman: %s\n",self->private->name);
+    g_free (self->priv->name);
+    self->priv->name = g_value_dup_string (value);
+    g_print ("maman: %s\n",self->priv->name);
   }
     break;
   case MAMAN_BAR_PAPA_NUMBER: {
-    self->private->papa_number = g_value_get_uchar (value);
-    g_print ("papa: %u\n",self->private->papa_number);
+    self->priv->papa_number = g_value_get_uchar (value);
+    g_print ("papa: %u\n",self->priv->papa_number);
   }
     break;
   default:
@@ -574,11 +574,11 @@ maman_bar_get_property (GObject      *object,
 
   switch (property_id) {
   case MAMAN_BAR_CONSTRUCT_NAME: {
-    g_value_set_string (value, self->private->name);
+    g_value_set_string (value, self->priv->name);
   }
     break;
   case MAMAN_BAR_PAPA_NUMBER: {
-    g_value_set_uchar (value, self->private->papa_number);
+    g_value_set_uchar (value, self->priv->papa_number);
   }
     break;
   default:

diff --git a/docs/reference/gobject/tut_howto.xml b/docs/reference/gobject/tut_howto.xml
index 03e5c2d9511877b903a5c5a76fcff16a5b9bade4..6212b2bbd71b5f9d46810279c38504de82b2d24a 100644 (file)
--- a/docs/reference/gobject/tut_howto.xml
+++ b/docs/reference/gobject/tut_howto.xml
@@ -168,15 +168,17 @@ struct _MamanBar {
               The private structure is then defined in the .c file, instantiated in the object's
               <function>init</function> function and destroyed in the object's <function>finalize</function> function.
 <programlisting>
-static void maman_bar_finalize(GObject *object) {
+static void
+maman_bar_finalize (GObject *object) {
   MamanBar *self = MAMAN_BAR (object);
   /* do stuff */
   g_free (self->priv);
 }
 
-static void maman_bar_init(GTypeInstance *instance, gpointer g_class) {
+static void
+maman_bar_init (GTypeInstance *instance, gpointer g_class) {
   MamanBar *self = MAMAN_BAR (instance);
-  self->priv = g_new0(MamanBarPrivate,1);
+  self->priv = g_new0 (MamanBarPrivate,1);
   /* do stuff */
 }
 </programlisting>
@@ -184,10 +186,14 @@ static void maman_bar_init(GTypeInstance *instance, gpointer g_class) {
 
             <listitem><para>
               A similar alternative, available since Glib version 2.4, is to define a private structure in the .c file,
-              declare it as a private structure in <function>class_init</function> using 
-              <function><link linkend="g-type-class-add-private">g_type_class_add_private</link></function> and declare a macro to allow convenient access to this structure.
+              declare it as a private structure in <function>maman_bar_class_init</function> using 
+              <function><link linkend="g-type-class-add-private">g_type_class_add_private</link></function>.
+              Instead of allocating memory in <function>maman_bar_init</function> a pointer to the private memory area is
+              stored in the instance to allow convenient access to this structure.
               A private structure will then be attached to each newly created object by the GObject system.
               You dont need to free or allocate the private structure, only the objects or pointers that it may contain.
+              Another advantage of this to the previous version is that is lessens memory fragmentation,
+              as the public and private parts of the instance memory are allocated at once.
 <programlisting>
 typedef struct _MamanBarPrivate MamanBarPrivate;
 
@@ -195,8 +201,6 @@ struct _MamanBarPrivate {
   int private_field;
 };
 
-#define MAMAN_BAR_GET_PRIVATE(o) (G_TYPE_INSTANCE_GET_PRIVATE ((o), MAMAN_BAR_TYPE, MamanBarPrivate))
-
 static void
 maman_bar_class_init (MamanBarClass *klass)
 {
@@ -205,12 +209,11 @@ maman_bar_class_init (MamanBarClass *klass)
   ...
 }
 
-static int
-maman_bar_get_private_field (MamanBar *self)
-{
-  MamanBarPrivate *priv = MAMAN_BAR_GET_PRIVATE (self);
-
-  return priv->private_field;
+static void
+maman_bar_init (GTypeInstance *instance, gpointer g_class) {
+  MamanBar *self = MAMAN_BAR (instance);
+  self->priv = G_TYPE_INSTANCE_GET_PRIVATE (self, MAMAN_BAR_TYPE, MamanBarPrivate);
+  /* do stuff */
 }
 </programlisting>
             </para></listitem>