[gtk+/overlay] overlay: add docs

[Matthias Clasen <matthiasc src gnome org>]

commit 04b9752dc066650a60725e9c49935e7c21c89622
Author: Matthias Clasen <mclasen redhat com>
Date:   Sat Jun 11 09:40:02 2011 -0400

    overlay: add docs

 docs/reference/gtk/gtk-docs.sgml     |    1 +
 docs/reference/gtk/gtk3-sections.txt |   26 +++++++++++
 docs/reference/gtk/gtk3.types        |    1 +
 gtk/gtkoverlay.c                     |   80 ++++++++++++++++++++++------------
 gtk/gtkoverlay.h                     |    1 -
 5 files changed, 80 insertions(+), 29 deletions(-)
---
diff --git a/docs/reference/gtk/gtk-docs.sgml b/docs/reference/gtk/gtk-docs.sgml
index 11d14ab..f72c798 100644
--- a/docs/reference/gtk/gtk-docs.sgml
+++ b/docs/reference/gtk/gtk-docs.sgml
@@ -242,6 +242,7 @@
       <xi:include href="xml/gtknotebook.xml" />
       <xi:include href="xml/gtktable.xml" />
       <xi:include href="xml/gtkexpander.xml" />
+      <xi:include href="xml/gtkoverlay.xml" />
       <xi:include href="xml/gtkorientable.xml" />
     </chapter>
 
diff --git a/docs/reference/gtk/gtk3-sections.txt b/docs/reference/gtk/gtk3-sections.txt
index 291b219..ba5c52f 100644
--- a/docs/reference/gtk/gtk3-sections.txt
+++ b/docs/reference/gtk/gtk3-sections.txt
@@ -7075,3 +7075,29 @@ GTK_LOCK_BUTTON_GET_CLASS
 gtk_lock_button_get_type
 GtkLockButtonPrivate
 </SECTION>
+
+<SECTION>
+<FILE>gtkoverlay</FILE>
+<TITLE>GtkOverlay</TITLE>
+GtkOverlay
+
+gtk_overlay_new
+gtk_overlay_set_relative_widget
+gtk_overlay_get_relative_widget
+gtk_overlay_add
+gtk_overlay_set_offset
+gtk_overlay_get_offset
+
+<SUBSECTION Standard>
+GTK_TYPE_OVERLAY
+GTK_OVERLAY
+GTK_OVERLAY_CLASS
+GTK_IS_OVERLAY
+GTK_IS_OVERLAY_CLASS
+GTK_OVERLAY_GET_CLASS
+GtkOverlayClass
+
+<SUBSECTION Private>
+gtk_overlay_get_type
+GtkOverlayPrivate
+</SECTION>
diff --git a/docs/reference/gtk/gtk3.types b/docs/reference/gtk/gtk3.types
index 2b9cd79..d0190b7 100644
--- a/docs/reference/gtk/gtk3.types
+++ b/docs/reference/gtk/gtk3.types
@@ -105,6 +105,7 @@ gtk_notebook_get_type
 gtk_numerable_icon_get_type
 gtk_offscreen_window_get_type
 gtk_orientable_get_type
+gtk_overlay_get_type
 gtk_page_setup_get_type
 gtk_page_setup_unix_dialog_get_type
 gtk_paned_get_type
diff --git a/gtk/gtkoverlay.c b/gtk/gtkoverlay.c
index 996f4bd..064cf9a 100644
--- a/gtk/gtkoverlay.c
+++ b/gtk/gtkoverlay.c
@@ -28,6 +28,32 @@
 #include "gtkprivate.h"
 #include "gtkintl.h"
 
+/**
+ * SECTION:gtkoverlay
+ * @short_description: A container which overlays widgets on top of each other
+ * @title: GtkOverlay
+ *
+ * GtkOverlay is a container which contains a single main child, on top
+ * of which it can place <firstterm>overlay</firstterm> widgets. The
+ * position of each overlay widget is determined by its #GtkWidget::halign
+ * and #GtkWidget::valign properties. E.g. a widget with both alignments
+ * set to %GTK_ALIGN_START will be placed at the top left corner of the
+ * main widget, whereas an overlay with halign set to %GTK_ALIGN_CENTER
+ * and valign set to %GTK_ALIGN_END will be placed a the bottom edge of
+ * the main widget, horizontally centered. The position can be adjusted
+ * by setting the #GtkOverlay::x-offset and #GtkOverlay::y-offset child
+ * properties to non-zero values.
+ *
+ * <refsect2 id="GtkOverlay-BUILDER-UI">
+ * <title>GtkOverlay as GtkBuildable</title>
+ * <para>
+ * The GtkOverlay implementation of the GtkBuildable interface
+ * supports placing a child as an overlay by specifying "overlay" as
+ * the "type" attribute of a <tag class="starttag">child</tag> element.
+ * </para>
+ * </refsect2>
+ */
+
 struct _GtkOverlayPrivate
 {
   GtkWidget *relative_widget;
@@ -63,24 +89,6 @@ G_DEFINE_TYPE_WITH_CODE (GtkOverlay, gtk_overlay, GTK_TYPE_BIN,
                          G_IMPLEMENT_INTERFACE (GTK_TYPE_BUILDABLE,
                                                 gtk_overlay_buildable_init))
 
-/* the reason for this is that the main widget doesn't need
- * to set an offset and it doesn't need an extra window
- */
-static void
-add_child (GtkOverlay *overlay,
-           GtkWidget  *widget)
-{
-  GtkOverlayPrivate *priv = overlay->priv;
-  GtkOverlayChild *child;
-
-  child = g_slice_new0 (GtkOverlayChild);
-  child->widget = widget;
-
-  gtk_widget_set_parent (widget, GTK_WIDGET (overlay));
-
-  priv->children = g_slist_append (priv->children, child);
-}
-
 static GtkOverlayChild *
 get_child (GtkOverlay *overlay,
            GtkWidget  *widget)
@@ -89,7 +97,7 @@ get_child (GtkOverlay *overlay,
   GtkOverlayChild *child;
   GSList *children;
 
-  for (children = priv->children; children; children = g_slist_next (children))
+  for (children = priv->children; children; children = children->next)
     {
       child = children->data;
 
@@ -751,10 +759,12 @@ gtk_overlay_new (void)
 /**
  * gtk_overlay_set_relative_widget:
  * @overlay: a #GtkOverlay
- * @relative_widget: (allow-none): a child of the main widget
+ * @relative_widget: (allow-none): a child of the main widget, or %NULL
+ *
+ * Sets the relative widget where static widgets will be placed.
  *
- * Sets the relative widget where static widgets will be placed. This
- * widget must be a child of the widget added by gtk_container_add()
+ * This widget must be a child of the widget added by
+ * gtk_container_add().
  *
  * Since: 3.2
  */
@@ -780,7 +790,8 @@ gtk_overlay_set_relative_widget (GtkOverlay *overlay,
  * gtk_overlay_get_relative_widget:
  * @overlay: a #GtkOverlay
  *
- * Gets the relative widget to the main widget added by gtk_container_add()
+ * Gets the relative widget to the main widget added
+ * by gtk_container_add().
  *
  * Since: 3.2
  */
@@ -799,20 +810,29 @@ gtk_overlay_get_relative_widget (GtkOverlay *overlay)
  *
  * Adds @widget to @overlay.
  *
+ * The widget will be stacked on top of the main widget
+ * added with gtk_container_add(). The position at which
+ * @widget is placed is determined from its #GtkWidget::halign
+ * and #GtkWidget::valign properties.
+ *
  * Since: 3.2
  */
 void
 gtk_overlay_add (GtkOverlay *overlay,
                  GtkWidget  *widget)
 {
+  GtkOverlayPrivate *priv = overlay->priv;
   GtkOverlayChild *child;
 
   g_return_if_fail (GTK_IS_OVERLAY (overlay));
   g_return_if_fail (GTK_IS_WIDGET (widget));
 
-  add_child (overlay, widget);
+  child = g_slice_new0 (GtkOverlayChild);
+  child->widget = widget;
 
-  child = get_child (overlay, widget);
+  gtk_widget_set_parent (widget, GTK_WIDGET (overlay));
+
+  priv->children = g_slist_append (priv->children, child);
 
   if (gtk_widget_get_realized (GTK_WIDGET (overlay)))
     child->window = gtk_overlay_create_child_window (overlay, widget);
@@ -825,7 +845,7 @@ gtk_overlay_add (GtkOverlay *overlay,
  * @x_offset: the new x offset for @widget
  * @y_offset: the new y offset for @widget
  *
- * Sets the offset for @widget
+ * Sets the offset for @widget.
  *
  * Since: 3.2
  */
@@ -835,9 +855,13 @@ gtk_overlay_set_offset (GtkOverlay *overlay,
                         gint        x_offset,
                         gint        y_offset)
 {
+  GtkOverlayChild *child;
+
   g_return_if_fail (GTK_IS_OVERLAY (overlay));
 
-  gtk_overlay_set_offset_internal (overlay, get_child (overlay, widget), x_offset, y_offset);
+  child = get_child (overlay, widget);
+
+  gtk_overlay_set_offset_internal (overlay, child, x_offset, y_offset);
 }
 
 /**
@@ -847,7 +871,7 @@ gtk_overlay_set_offset (GtkOverlay *overlay,
  * @x_offset: (out) (allow-none): returns the x offset of @widget
  * @y_offset: (out) (allow-none): returns the y offset of @widget
  *
- * Gets the offset for @widget
+ * Gets the offset for @widget.
  *
  * Since: 3.2
  */
diff --git a/gtk/gtkoverlay.h b/gtk/gtkoverlay.h
index 33c9681..604b844 100644
--- a/gtk/gtkoverlay.h
+++ b/gtk/gtkoverlay.h
@@ -33,7 +33,6 @@ G_BEGIN_DECLS
 
 #define GTK_TYPE_OVERLAY             (gtk_overlay_get_type ())
 #define GTK_OVERLAY(obj)             (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_OVERLAY, GtkOverlay))
-#define GTK_OVERLAY_CONST(obj)       (G_TYPE_CHECK_INSTANCE_CAST ((obj), GTK_TYPE_OVERLAY, GtkOverlay const))
 #define GTK_OVERLAY_CLASS(klass)     (G_TYPE_CHECK_CLASS_CAST ((klass), GTK_TYPE_OVERLAY, GtkOverlayClass))
 #define GTK_IS_OVERLAY(obj)          (G_TYPE_CHECK_INSTANCE_TYPE ((obj), GTK_TYPE_OVERLAY))
 #define GTK_IS_OVERLAY_CLASS(klass)  (G_TYPE_CHECK_CLASS_TYPE ((klass), GTK_TYPE_OVERLAY))