GNOME.org
 

[gtkmm] Update documentation of non-HV classes that were previously just bases.

commit 5c7437d2b55f0d3e32746d6075995de649c0b75d
Author: Murray Cumming <murrayc murrayc com>
Date:   Tue Jun 14 20:46:07 2011 +0200

    Update documentation of non-HV classes that were previously just bases.
    
    * gtk/src/box.hg:
    * gtk/src/buttonbox.hg:
    * gtk/src/paned.hg:
    * gtk/src/scale.hg:
    * gtk/src/scrollbar.hg:
    * gtk/src/separator.hg: Update the overview doxygen comment based on
    the latest C documentation.

 ChangeLog            |   12 ++++++++++++
 gtk/src/box.hg       |   30 +++++++++++++++++++-----------
 gtk/src/buttonbox.hg |   21 ++++++++++++++++++---
 gtk/src/paned.hg     |   14 ++++++++++----
 gtk/src/scale.hg     |    7 ++++++-
 gtk/src/scrollbar.hg |    6 ++++--
 gtk/src/separator.hg |    8 ++++++--
 7 files changed, 75 insertions(+), 23 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 4987049..8d8d2e5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,17 @@
 2011-06-14  Murray Cumming  <murrayc murrayc com>
 
+	Update documentation of non-HV classes that were previously just bases.
+
+	* gtk/src/box.hg:
+	* gtk/src/buttonbox.hg:
+	* gtk/src/paned.hg:
+	* gtk/src/scale.hg:
+	* gtk/src/scrollbar.hg:
+	* gtk/src/separator.hg: Update the overview doxygen comment based on 
+	the latest C documentation.
+
+2011-06-14  Murray Cumming  <murrayc murrayc com>
+
 	Remove deprecation ifdefs around HBox and VBox.
 
 	* gtk/src/hvbox.hg: We can't put these in ifdefs because they are 
diff --git a/gtk/src/box.hg b/gtk/src/box.hg
index 0d9b09d..ee1f250 100644
--- a/gtk/src/box.hg
+++ b/gtk/src/box.hg
@@ -38,19 +38,18 @@ enum PackOptions
   PACK_EXPAND_WIDGET /**< Space is expanded, with extra space filled by increasing the child widget size. */
 };
 
-/** A base class for box containers.
+/** The Box widget organizes child widgets into a rectangular area.
  *
- * Base class for horizontal and vertical boxes, which organize a
- * variable number of widgets into a rectangular area.  This is an abstract
- * class and it defers choice of which way the widgets are packed to the screen
- * to the derived classes.  It provides a common interface for inserting
- * widgets to a box indepenently of how it is shown in the screen.
+ * The rectangular area of a Box is organized into either a single row
+ * or a single column of child widgets depending upon the orientation.
+ * Thus, all children of a Box are allocated one dimension in common,
+ * which is the height of a row, or the width of a column.
  *
  * Gtk::Box uses a notion of packing. Packing refers to adding widgets with
  * reference to a particular position in a Gtk::Container. There are two
- * reference positions: the start and the end of the box. For a VBox, the start
+ * reference positions: the start and the end of the box. For a vertical Box, the start
  * is defined as the top of the box and the end is defined as the bottom.  For
- * a HBox the start is defined as the left side and the end is defined as the
+ * a horizontal Box the start is defined as the left side and the end is defined as the
  * right side.  Use repeated calls to pack_start() to pack widgets into a
  * Gtk::Box from start to end. Use pack_end() to add widgets from end to start.
  * You may intersperse these calls and add widgets from both ends of the same
@@ -62,9 +61,18 @@ enum PackOptions
  * Gtk::Container::remove() to remove widgets.
  *
  * Use set_homogeneous() to specify whether or not all children of the Gtk::Box
- * occupy the same amount of space.  Use set_spacing() to determine the minimum
- * space placed between all children in the Gtk::Box.  Use reorder_child() to
- * move a child widget to a different place in the box.  Use
+ * occupy the same amount of space.
+ *
+ * Use set_spacing() to determine the minimum
+ * space placed between all children in the Gtk::Box.  Note that
+ * spacing is added between the children, while
+ * padding added by gtk_box_pack_start() or gtk_box_pack_end() is added
+ * on either side of the widget it belongs to.
+ *
+ * Use reorder_child() to
+ * move a child widget to a different place in the box.
+ *
+ * Use
  * set_child_packing() to reset the pack options and padding attributes of any
  * Gtk::Box child. Use query_child_packing() to query these fields.
  */
diff --git a/gtk/src/buttonbox.hg b/gtk/src/buttonbox.hg
index 5b6670e..a0d4aa1 100644
--- a/gtk/src/buttonbox.hg
+++ b/gtk/src/buttonbox.hg
@@ -32,11 +32,26 @@ namespace Gtk
 enum { BUTTONBOX_DEFAULT_SPACING = -1 };
 
 
-/** Base class for Gtk::HButtonBox and Gtk::VButtonBox
+/** A container for arranging buttons.
  *
  * A button box should be used to provide a consistent layout of buttons
- * throughout your application.  There is one default layout and a default
- * spacing value that are persistant across all ButtonBox widgets.
+ * throughout your application. The layout/spacing can be altered by the
+ * programmer, or if desired, by the user to alter the 'feel' of a
+ * program to a small degree.
+ *
+ * get_layout() et_layout() retrieve and
+ * alter the method used to spread the buttons in a button box across the
+ * container, respectively.
+ *
+ * The main purpose of ButtonBox is to make sure the children have all the
+ * same size. ButtonBox gives all children the same size, but it does allow
+ * 'outliers' to keep their own larger size. To force all children to be
+ * strictly the same size without exceptions, you can set the
+ * homogeneous property to true.
+ *
+ * To excempt individual children from homogeneous sizing regardless of their
+ * 'outlier' status, you can set the non-homogeneous child
+ * property.
  */
 class ButtonBox
   : public Box
diff --git a/gtk/src/paned.hg b/gtk/src/paned.hg
index 3268747..861fe45 100644
--- a/gtk/src/paned.hg
+++ b/gtk/src/paned.hg
@@ -30,18 +30,24 @@ _PINCLUDE(gtkmm/private/container_p.h)
 namespace Gtk
 {
 
-/** This is the base class for widgets with two panes, arranged either
- * horizontally (Gtk::HPaned) or vertically (Gtk::VPaned).
+/** A widget with two adjustable panes.
  *
+ * Gtk::Paned has two panes, arranged either
+ * horizontally or vertically. The division between
+ * the two panes is adjustable by the user by dragging
+ * a handle.
+
  * Child widgets are added to the panes of the widget with pack1() and pack2().
  * The division beween 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. Often, it is useful to
+ * 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 Gtk::Frame with the shadow type set to Gtk::SHADOW_IN
- * so that the gutter appears as a ridge.
+ * 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
diff --git a/gtk/src/scale.hg b/gtk/src/scale.hg
index c577c4d..593bacd 100644
--- a/gtk/src/scale.hg
+++ b/gtk/src/scale.hg
@@ -27,7 +27,7 @@ _PINCLUDE(gtkmm/private/range_p.h)
 namespace Gtk
 {
 
-/** Base clase for Gtk::HScale and Gtk::VScale.
+/** A slider widget for selecting a value from a range.
  *
  * A Gtk::Scale is a slider control used to select a numeric value. To use it,
  * you'll probably want to investigate the methods on its base class,
@@ -35,6 +35,11 @@ namespace Gtk
  * value of a scale, you would normally use set_value(). To detect
  * changes to the value, you would normally use signal_value_changed().
  *
+ * Note that using the same upper and lower bounds for the Scale (through
+ * the Range methods) will hide the slider itself. This is useful for
+ * applications that want to show an undeterminate value on the scale, without
+ * changing the layout of the application (such as movie or music players).
+ *
  * @ingroup Widgets
  */
 class Scale : public Range
diff --git a/gtk/src/scrollbar.hg b/gtk/src/scrollbar.hg
index 5a8c933..bb586c0 100644
--- a/gtk/src/scrollbar.hg
+++ b/gtk/src/scrollbar.hg
@@ -32,8 +32,10 @@ _PINCLUDE(gtkmm/private/range_p.h)
 namespace Gtk
 {
 
-/**  The Gtk::Scrollbar widget is a base class for Gtk::HScrollbar
- * and Gtk::VScrollbar. It is not very useful in itself. 
+/** A Scrollbar.
+ *
+ * The #Scrollbar widget is a horizontal or vertical scrollbar,
+ * depending on the value of the orientation property.
  *
  * The position of the thumb in a scrollbar is controlled by the scroll
  * adjustments. See Gtk::Adjustment for the fields in an adjustment - for
diff --git a/gtk/src/separator.hg b/gtk/src/separator.hg
index c41d276..4010425 100644
--- a/gtk/src/separator.hg
+++ b/gtk/src/separator.hg
@@ -29,8 +29,12 @@ _PINCLUDE(gtkmm/private/widget_p.h)
 namespace Gtk
 {
 
-/** Separator base class.
- * Base class for Gtk::VSeparator and Gtk::HSeparator.
+/** A separator widget.
+ *
+ * Gtk::Separator is a horizontal or vertical separator widget, depending on the 
+ * value of the orientation property, used to group the widgets within a
+ * window. It displays a line with a shadow to make it appear sunken into the 
+ * interface.
  */
 class Separator
  : public Widget,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]