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>
+The initial reference a #GObject is created with is flagged as a
+<firstterm>floating</firstterm> reference.
+This means that it is not specifically claimed to be "owned" by
+any code portion. The main motivation for providing floating references is
+C convenience. In particular, it allowes code to be written as:
+<example><programlisting>
+ container = create_container();
+ container_add_child (container, create_child());
+</programlisting></example>
+If <function>container_add_child()</function> will g_object_ref_sink() the
+passed in child, no reference of the newly created child is leaked.
+Without floating references, <function>container_add_child()</function>
+can only g_object_ref() the new child, so to implement this code without
+reference leaks, it would have to be written as:
+<example><programlisting>
+ Child *child;
+ container = create_container();
+ child = create_child();
+ container_add_child (container, child);
+ g_object_unref (child);
+</programlisting></example>
+The floating reference can be converted into
+an ordinary reference by calling g_object_ref_sink().
+For already sunken objects (objects that don't have a floating reference
+anymore), g_object_ref_sink() is equivalent to g_object_ref() and returns
+a new reference.
+Since floating references are useful allmost exclusively for C convenience,
+language bindings that provide automated reference and memory ownership
+maintenance (such as smart pointers or garbage collection) therefore don't
+need to expose floating references in their API.
+</para>
+<para>
+Some object implementations may need to save an objects floating state
+across certain code portions (an example is #GtkMenu), to achive this, the
+following sequence can be used:
+</para>
+
+<example><programlisting>
+ /* save floating state */
+ gboolean was_floating = g_object_is_floating (object);
+ g_object_ref_sink (object);
+ /* protected code portion */
+ ...;
+ /* restore floating state */
+ if (was_floating)
+ g_object_force_floating (object);
+ g_obejct_unref (object); /* release previously acquired reference */
+</programlisting></example>
<!-- ##### SECTION See_Also ##### -->
<para>
<!-- ##### FUNCTION g_object_ref_sink ##### -->
<para>
-Increase the reference count of @object, and remove the
+Increase the reference count of @object, and possibly remove the
<link linkend="floating-ref">floating</link> reference, if @object
has a floating reference.
</para>
<!-- ##### 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.
+This function is intended for #GObject implementations to re-enforce a
+<link linkend="floating-ref">floating</link> object reference.
+Doing this is seldomly required, all
+#GObject<!-- -->s are created with a floating reference which usually
+just needs to be sunken by calling g_object_ref_sink().
</para>
@object: a #GObject