From: Matthias Clasen <matthiasc@src.gnome.org>
Date: Sun, 27 Nov 2005 20:09:13 +0000 (+0000)
Subject: Document GObject API additions
X-Git-Url: http://git.openbox.org/?a=commitdiff_plain;h=9adc9c942d8250262dc76ac2225134fcc744ef20;p=dana%2Fcg-glib.git

Document GObject API additions
---

diff --git a/docs/reference/gobject/tmpl/gparamspec.sgml b/docs/reference/gobject/tmpl/gparamspec.sgml
index 75399b80..c1b793ba 100644
--- a/docs/reference/gobject/tmpl/gparamspec.sgml
+++ b/docs/reference/gobject/tmpl/gparamspec.sgml
@@ -205,6 +205,16 @@ not flagged "floating" anymore).
 @pspec: a valid #GParamSpec
 
 
+<!-- ##### FUNCTION g_param_spec_ref_sink ##### -->
+<para>
+Convenience function to ref and sink a #GParamSpec.
+</para>
+
+@pspec: a valid #GParamSpec
+@Returns: the #GParamSpec that was passed into this function
+@Since: 2.10
+
+
 <!-- ##### FUNCTION g_param_value_set_default ##### -->
 <para>
 Sets @value to its default value as specified in @pspec.
diff --git a/docs/reference/gobject/tmpl/objects.sgml b/docs/reference/gobject/tmpl/objects.sgml
index 81da0dea..e331dff6 100644
--- a/docs/reference/gobject/tmpl/objects.sgml
+++ b/docs/reference/gobject/tmpl/objects.sgml
@@ -6,11 +6,25 @@ The base object type
 
 <!-- ##### SECTION Long_Description ##### -->
 <para>
-GObject is the fundamental type providing the common attributes and methods for all object
-types in GTK+, Pango and other libraries based on GObject. The GObject class provides methods 
-for object construction and destruction, property access methods, and signal support. 
+GObject is the fundamental type providing the common attributes and methods 
+for all object types in GTK+, Pango and other libraries based on GObject. 
+The GObject class provides methods for object construction and destruction, 
+property access methods, and signal support. 
 Signals are described in detail in <xref linkend="gobject-Signals"/>.
 </para>
+<para id="floating-ref">
+The initial reference to a #GObject which is returned by g_object_new() can
+optionally be "floating", which means that it is not specifically owned
+by the creator of the object. The floating reference can be converted into 
+an ordinary reference by anyone at any time, by calling g_object_ref_sink(). 
+If the object is already sunk (has no floating reference), g_object_ref_sink() 
+returns a new reference.
+</para>
+<para>
+To create #GObject<!-- -->s with a floating reference, call 
+g_object_force_floating() from the object's init function.
+</para>
+
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
@@ -395,6 +409,42 @@ Increases the reference count of @object.
 @Returns: @object
 
 
+<!-- ##### FUNCTION g_object_ref_sink ##### -->
+<para>
+Increase the reference count of @object, and remove the 
+<link linkend="floating-ref">floating</link> reference, if @object
+has a floating reference.
+</para>
+
+@object: a #GObject
+@Returns: @object
+@Since: 2.10
+
+
+<!-- ##### FUNCTION g_object_is_floating ##### -->
+<para>
+Checks wether @object has a <link linkend="floating-ref">floating</link>
+reference.
+</para>
+
+@object: a #GObject
+@Returns: %TRUE if @object has a floating reference
+@Since: 2.10
+
+
+<!-- ##### FUNCTION g_object_force_floating ##### -->
+<para>
+This function is intended for #GObject implementations to mark the
+initial reference to the object as 
+<link linkend="floating-ref">floating</link>. It must only be called  
+from an object's init function.
+</para>
+
+@object: a #GObject
+@Since: 2.10
+
+
+
 <!-- ##### FUNCTION g_object_unref ##### -->
 <para>
 Decreases the reference count if @object.
diff --git a/gobject/ChangeLog b/gobject/ChangeLog
index bcbd710d..3b49bac2 100644
--- a/gobject/ChangeLog
+++ b/gobject/ChangeLog
@@ -1,3 +1,7 @@
+2005-11-27  Matthias Clasen  <mclasen@redhat.com>
+
+	* gboxed.h: Declare g_hash_table_get_type.
+
 Wed Nov 23 18:01:46 2005  Tim Janik  <timj@imendio.com>
 
 	* gobject.[hc]: added floating reference count.
diff --git a/gobject/gboxed.h b/gobject/gboxed.h
index eadb12e5..6370cae3 100644
--- a/gobject/gboxed.h
+++ b/gobject/gboxed.h
@@ -78,6 +78,7 @@ GType	g_value_array_get_type	(void)	G_GNUC_CONST;
 GType	g_date_get_type	        (void)	G_GNUC_CONST;
 GType	g_strv_get_type	        (void)	G_GNUC_CONST;
 GType	g_gstring_get_type      (void)	G_GNUC_CONST;
+GType   g_hash_table_get_type   (void)  G_GNUC_CONST;
 
 typedef gchar** GStrv;