From 8eb71819796899285c1d358cacf3e48ee242f4c7 Mon Sep 17 00:00:00 2001
From: Patrick Bernaud <patrickb@chez.com>
Date: Mon, 8 Nov 2010 18:36:39 +0100
Subject: docs: Move documentation to inline comments: GtkPaned
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fixes https://bugzilla.gnome.org/show_bug.cgi?id=634338

Signed-off-by: Javier Jardón <jjardon@gnome.org>
---
 gtk/gtkpaned.c | 86 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

(limited to 'gtk/gtkpaned.c')

diff --git a/gtk/gtkpaned.c b/gtk/gtkpaned.c
index d608d066af..7c0958f5d8 100644
--- a/gtk/gtkpaned.c
+++ b/gtk/gtkpaned.c
@@ -39,6 +39,56 @@
 #include "gtkintl.h"
 
 
+/**
+ * SECTION:gtkpaned
+ * @Short_description: Base class for widgets with two adjustable panes
+ * @Title: GtkPaned
+ *
+ * #GtkPaned is the base class for widgets with two panes, arranged either
+ * horizontally (#GtkHPaned) or vertically (#GtkVPaned). Child widgets are
+ * added to the panes of the widget with gtk_paned_pack1() and
+ * gtk_paned_pack2(). The division between the two children is set by default
+ * from the size requests of the children, but it can be adjusted by the
+ * user.
+ *
+ * A paned widget draws a separator between the two child widgets and a
+ * small handle that the user can drag to adjust the division. It does not
+ * draw any relief around the children or around the separator. (The space
+ * in which the separator is called the gutter.) Often, it is useful to put
+ * each child inside a #GtkFrame with the shadow type set to %GTK_SHADOW_IN
+ * so that the gutter appears as a ridge. No separator is drawn if one of
+ * the children is missing.
+ *
+ * Each child has two options that can be set, @resize and @shrink. If
+ * @resize is true, then when the #GtkPaned is resized, that child will
+ * expand or shrink along with the paned widget. If @shrink is true, then
+ * that child can be made smaller than its requisition by the user.
+ * Setting @shrink to %FALSE allows the application to set a minimum size.
+ * If @resize is false for both children, then this is treated as if
+ * @resize is true for both children.
+ *
+ * The application can set the position of the slider as if it were set
+ * by the user, by calling gtk_paned_set_position().
+ *
+ * <example>
+ * <title>Creating a paned widget with minimum sizes.</title>
+ * <programlisting>
+ * GtkWidget *hpaned = gtk_paned_new (GTK_ORIENTATION_HORIZONTAL);
+ * GtkWidget *frame1 = gtk_frame_new (NULL);
+ * GtkWidget *frame2 = gtk_frame_new (NULL);
+ * gtk_frame_set_shadow_type (GTK_FRAME (frame1), GTK_SHADOW_IN);
+ * gtk_frame_set_shadow_type (GTK_FRAME (frame2), GTK_SHADOW_IN);
+ *
+ * gtk_widget_set_size_request (hpaned, 200, -1);
+ *
+ * gtk_paned_pack1 (GTK_PANED (hpaned), frame1, TRUE, FALSE);
+ * gtk_widget_set_size_request (frame1, 50, -1);
+ *
+ * gtk_paned_pack2 (GTK_PANED (hpaned), frame2, FALSE, FALSE);
+ * gtk_widget_set_size_request (frame2, 50, -1);
+ * </programlisting>
+ * </example>
+ */
 
 struct _GtkPanedPrivate
 {
@@ -1444,6 +1494,15 @@ gtk_paned_new (GtkOrientation orientation)
                        NULL);
 }
 
+/**
+ * gtk_paned_add1:
+ * @paned: a paned widget
+ * @child: the child to add
+ *
+ * Adds a child to the top or left pane with default parameters. This is
+ * equivalent to
+ * <literal>gtk_paned_pack1 (paned, child, FALSE, TRUE)</literal>.
+ */
 void
 gtk_paned_add1 (GtkPaned  *paned,
 		GtkWidget *widget)
@@ -1451,6 +1510,15 @@ gtk_paned_add1 (GtkPaned  *paned,
   gtk_paned_pack1 (paned, widget, FALSE, TRUE);
 }
 
+/**
+ * gtk_paned_add2:
+ * @paned: a paned widget
+ * @child: the child to add
+ *
+ * Adds a child to the bottom or right pane with default parameters. This
+ * is equivalent to
+ * <literal>gtk_paned_pack2 (paned, child, TRUE, TRUE)</literal>.
+ */
 void
 gtk_paned_add2 (GtkPaned  *paned,
 		GtkWidget *widget)
@@ -1458,6 +1526,15 @@ gtk_paned_add2 (GtkPaned  *paned,
   gtk_paned_pack2 (paned, widget, TRUE, TRUE);
 }
 
+/**
+ * gtk_paned_pack1:
+ * @paned: a paned widget
+ * @child: the child to add
+ * @resize: should this child expand when the paned widget is resized.
+ * @shrink: can this child be made smaller than its requisition.
+ *
+ * Adds a child to the top or left pane.
+ */
 void
 gtk_paned_pack1 (GtkPaned  *paned,
 		 GtkWidget *child,
@@ -1481,6 +1558,15 @@ gtk_paned_pack1 (GtkPaned  *paned,
     }
 }
 
+/**
+ * gtk_paned_pack2:
+ * @paned: a paned widget
+ * @child: the child to add
+ * @resize: should this child expand when the paned widget is resized.
+ * @shrink: can this child be made smaller than its requisition.
+ *
+ * Adds a child to the bottom or right pane.
+ */
 void
 gtk_paned_pack2 (GtkPaned  *paned,
 		 GtkWidget *child,
-- 
cgit v1.2.1