gtk2hs-commit

[Duncan C. <dun...@us...>]

Update of /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Abstract
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv24163/gtk/Graphics/UI/Gtk/Abstract

Modified Files:
	Bin.chs Box.chs ButtonBox.chs.pp Container.chs Misc.chs 
	Object.chs.pp Paned.chs.pp Range.chs Scale.chs Widget.chs 
Log Message:
Add more module level documentation and tidy up exiting documentation.
Also add/modify section headers.
Also LGPL'ify remaining modules with permission from Matthew Walton.


Index: Range.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Abstract/Range.chs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Range.chs	12 Feb 2005 17:19:21 -0000	1.2
+++ Range.chs	25 Feb 2005 01:11:31 -0000	1.3
@@ -30,9 +30,23 @@
 --   'Adjustment' which is contained in the 'Range' object.
 --
 module Graphics.UI.Gtk.Abstract.Range (
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----'Object'
+-- |         +----'Widget'
+-- |               +----Range
+-- |                     +----'Scale'
+-- |                     +----'Scrollbar'
+-- @
+
+-- * Types
   Range,
   RangeClass,
   castToRange,
+
+-- * Methods
   rangeGetAdjustment,
   rangeSetAdjustment,
   UpdateType(..),
@@ -63,7 +77,8 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
--- methods
+--------------------
+-- Methods
 
 -- | Extract the 'Adjustment' object.
 --
@@ -140,7 +155,8 @@
 rangeSetRange r min max =
  {#call range_set_range#} (toRange r) (realToFrac min) (realToFrac max)
 
--- signals
+--------------------
+-- Signals
 
 -- | The slide has moved. The arguments give
 -- detailed information what happend.

Index: Object.chs.pp
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Abstract/Object.chs.pp,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Object.chs.pp	12 Feb 2005 17:19:21 -0000	1.2
+++ Object.chs.pp	25 Feb 2005 01:11:31 -0000	1.3
@@ -24,16 +24,41 @@
 -- Stability   : provisional
 -- Portability : portable (depends on GHC)
 --
--- Widget representation
+-- The base class of the Gtk+ type hierarchy.
 --
 -- * Each widget is a represented as a purely abstract data type. It can only 
 --   be accessed through and the special access functions that are defined
 --   in each widget file.
 --
 module Graphics.UI.Gtk.Abstract.Object (
+-- * Description
+-- 
+-- | 'Object' is the base class for all widgets, and for a few non-widget
+-- objects such as 'Adjustment'. 'Object' predates 'GObject'; non-widgets that
+-- derive from 'Object' rather than 'GObject' do so for backward compatibility
+-- reasons.
+--
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----Object
+-- |         +----'Widget'
+-- |         +----'Adjustment'
+-- |         +----'CellRenderer'
+-- |         +----'FileFilter'
+-- |         +----'ItemFactory'
+-- |         +----'Tooltips'
+-- |         +----'TreeViewColumn'
+-- @
+
+-- * Types
   Object,
   ObjectClass,
   castToObject,
+
+-- * Methods
   objectSink,
   makeNewObject,
   objectSetProperty,
@@ -50,7 +75,8 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
--- methods
+--------------------
+-- Methods
 
 -- turn the initial floating state to sunk
 --

Index: Box.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Abstract/Box.chs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Box.chs	12 Feb 2005 17:19:20 -0000	1.2
+++ Box.chs	25 Feb 2005 01:11:31 -0000	1.3
@@ -28,10 +28,72 @@
 -- supplies all methods to add and remove children.
 --
 module Graphics.UI.Gtk.Abstract.Box (
+-- * Description
+-- 
+-- | 'Box' is an abstract widget which encapsulates functionallity for a
+-- particular kind of container, one that organizes a variable number of
+-- widgets into a rectangular area. 'Box' currently has two derived classes,
+-- 'HBox' and 'VBox'.
+--
+-- The rectangular area of a 'Box' is organized into either a single row or
+-- a single column of child widgets depending upon whether the box is of type
+-- 'HBox' or 'VBox', respectively. 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.
+--
+-- 'Box' uses a notion of /packing/. Packing refers to adding widgets with
+-- reference to a particular position in a 'Container'. For a 'Box', there are
+-- two reference positions: the /start/ and the /end/ of the box. For a 'VBox',
+-- 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 right side.
+--
+-- Use repeated calls to 'boxPackStart' to pack widgets into a 'Box' from
+-- start to end. Use 'boxPackEnd' to add widgets from end to start. You may
+-- intersperse these calls and add widgets from both ends of the same 'Box'.
+--
+-- Use 'boxPackStartDefaults' or 'boxPackEndDefaults' to pack widgets into a
+-- 'Box' if you do not need to specify the expand, fill, or padding attributes
+-- of the child to be added.
+--
+-- Because 'Box' is a 'Container', you may also use 'containerAdd' to insert
+-- widgets into the box, and they will be packed as if with
+-- 'boxPackStartDefaults'. Use 'containerRemove' to remove widgets from the
+-- 'Box'.
+--
+-- Use 'boxSetHomogeneous' to specify whether or not all children of the
+-- 'Box' are forced to get the same amount of space.
+--
+-- Use 'boxSetSpacing' to determine how much space will be minimally placed
+-- between all children in the 'Box'.
+--
+-- Use 'boxReorderChild' to move a 'Box' child to a different place in the
+-- box.
+--
+-- Use 'boxSetChildPacking' to reset the expand, fill, and padding
+-- attributes of any 'Box' child. Use 'boxQueryChildPacking' to query these
+-- fields.
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----'Object'
+-- |         +----'Widget'
+-- |               +----'Container'
+-- |                     +----Box
+-- |                           +----'ButtonBox'
+-- |                           +----'VBox'
+-- |                           +----'HBox'
+-- @
+
+-- * Types
   Box,
   BoxClass,
   castToBox,
   Packing(..),
+
+-- * Methods
   boxPackStart,
   boxPackEnd,
   boxPackStartDefaults,
@@ -56,8 +118,8 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
--- methods
-
+--------------------
+-- Methods
 
 -- | Insert a widget at the beginning of the box
 -- container.
@@ -88,7 +150,6 @@
 boxPackEnd b w p pad = {#call box_pack_end#} (toBox b) (toWidget w)
   (fromBool $ p/=PackNatural) (fromBool $ p==PackGrow) (fromIntegral pad)
 
-
 -- | Like 'boxPackStart' but uses the
 -- default parameters 'PackRepel' and 0 for padding.
 --
@@ -167,7 +228,3 @@
 boxGetSpacing :: BoxClass b => b -> IO Int
 boxGetSpacing b = 
   liftM fromIntegral $ {#call unsafe box_get_spacing#} (toBox b)
-
-
-
-

Index: ButtonBox.chs.pp
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Abstract/ButtonBox.chs.pp,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -d -r1.1 -r1.2
--- ButtonBox.chs.pp	8 Jan 2005 15:11:46 -0000	1.1
+++ ButtonBox.chs.pp	25 Feb 2005 01:11:31 -0000	1.2
@@ -2,29 +2,70 @@
 --  GIMP Toolkit (GTK) Widget ButtonBox
 --
 --  Author : Matthew Walton
---          
+--
 --  Created: 28 April 2004
 --
 --  Version $Revision$ from $Date$
 --
---  Copyright (c) 2004 Matthew Walton
+--  Copyright (C) 2004-2005 Matthew Walton
 --
---  This file is free software; you can redistribute it and/or modify
---  it under the terms of the GNU General Public License as published by
---  the Free Software Foundation; either version 2 of the License, or
---  (at your option) any later version.
+--  This library is free software; you can redistribute it and/or
+--  modify it under the terms of the GNU Lesser General Public
+--  License as published by the Free Software Foundation; either
+--  version 2.1 of the License, or (at your option) any later version.
 --
---  This file is distributed in the hope that it will be useful,
+--  This library is distributed in the hope that it will be useful,
 --  but WITHOUT ANY WARRANTY; without even the implied warranty of
---  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
---  GNU General Public License for more details.
+--  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+--  Lesser General Public License for more details.
 --
 -- |
+-- Maintainer  : gtk...@li...
+-- Stability   : provisional
+-- Portability : portable (depends on GHC)
+--
+-- Base class for 'HButtonBox' and 'VButtonBox'
 --
 module Graphics.UI.Gtk.Abstract.ButtonBox (
+-- * Description
+-- 
+-- | The primary purpose of this class is to keep track of the various
+-- properties of 'HButtonBox' and 'VButtonBox' widgets.
+--
+-- 'buttonBoxGetChildSize' retrieves the minimum width and height for
+-- widgets in a given button box. 'buttonBoxSetChildSize' allows those
+-- properties to be changed.
+--
+-- The internal padding of buttons can be retrieved and changed per button
+-- box using 'buttonBoxGetChildIpadding' and 'buttonBoxSetChildIpadding'
+-- respectively.
+--
+-- 'buttonBoxGetSpacing' and 'buttonBoxSetSpacing' retrieve and change
+-- default number of pixels between buttons, respectively.
+--
+-- 'buttonBoxGetLayout' and 'buttonBoxSetLayout' retrieve and alter the
+-- method used to spread the buttons in a button box across the container,
+-- respectively.
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----'Object'
+-- |         +----'Widget'
+-- |               +----'Container'
+-- |                     +----'Box'
+-- |                           +----ButtonBox
+-- |                                 +----'HButtonBox'
+-- |                                 +----'VButtonBox'
+-- @
+
+-- * Types
   ButtonBox,
   ButtonBoxClass,
   castToButtonBox,
+
+-- * Methods
   buttonBoxGetLayout,
   buttonBoxSetLayout,
   buttonBoxSetChildSecondary,
@@ -45,7 +86,8 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
--- methods
+--------------------
+-- Methods
 
 -- | Retrieve the method being used to
 -- arrange the buttons in the button box

Index: Misc.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Abstract/Misc.chs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Misc.chs	12 Feb 2005 17:19:21 -0000	1.2
+++ Misc.chs	25 Feb 2005 01:11:31 -0000	1.3
@@ -24,12 +24,41 @@
 -- Stability   : provisional
 -- Portability : portable (depends on GHC)
 --
--- a base class for widgets with alignments and padding.
+-- A base class for widgets with alignments and padding.
 --
 module Graphics.UI.Gtk.Abstract.Misc (
+-- * Description
+-- 
+-- | The 'Misc' widget is an abstract widget which is not useful itself, but
+-- is used to derive subclasses which have alignment and padding attributes.
+--
+-- The horizontal and vertical padding attributes allows extra space to be
+-- added around the widget.
+--
+-- The horizontal and vertical alignment attributes enable the widget to be
+-- positioned within its allocated area. Note that if the widget is added to a
+-- container in such a way that it expands automatically to fill its allocated
+-- area, the alignment settings will not alter the widgets position.
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----'Object'
+-- |         +----'Widget'
+-- |               +----Misc
+-- |                     +----'Label'
+-- |                     +----'Arrow'
+-- |                     +----'Image'
+-- |                     +----'Pixmap'
+-- @
+
+-- * Types
   Misc,
   MiscClass,
   castToMisc,
+
+-- * Methods
   miscSetAlignment,
   miscGetAlignment,
   miscSetPadding,
@@ -45,9 +74,8 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
--- Misc type declaration
-
--- methods
+--------------------
+-- Methods
 
 -- | Set the alignment of the widget.
 --

Index: Paned.chs.pp
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Abstract/Paned.chs.pp,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Paned.chs.pp	12 Feb 2005 17:19:21 -0000	1.2
+++ Paned.chs.pp	25 Feb 2005 01:11:31 -0000	1.3
@@ -29,9 +29,50 @@
 -- concrete implementations are HPaned and VPaned.
 --
 module Graphics.UI.Gtk.Abstract.Paned (
+-- * Description
+-- 
+-- | 'Paned' is the base class for widgets with two panes, arranged either
+-- horizontally ('HPaned') or vertically ('VPaned'). Child widgets are added to
+-- the panes of the widget with 'panedPack1' and 'panedPack2'. 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. (The space in which
+-- the separator is called the gutter.) Often, it is useful to put each child
+-- inside a 'Frame' with the shadow type set to 'ShadowIn' so that the gutter
+-- appears as a ridge.
+--
+-- Each child has two options that can be set, @resize@ and @shrink@. If
+-- @resize@ is true, then when the 'Paned' is resized, that child will expand
+-- or shrink along with the paned widget. If @shrink@ is true, then when 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 'panedSetPosition'.
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----'Object'
+-- |         +----'Widget'
+-- |               +----'Container'
+-- |                     +----Paned
+-- |                           +----'HPaned'
+-- |                           +----'VPaned'
+-- @
+
+-- * Types
   Paned,
   PanedClass,
   castToPaned,
+
+-- * Methods
   panedAdd1,
   panedAdd2,
   panedPack1,
@@ -53,7 +94,8 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
--- methods
+--------------------
+-- Methods
 
 -- | Add a widget to the first (top or left) area.
 --

Index: Widget.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Abstract/Widget.chs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Widget.chs	12 Feb 2005 17:19:21 -0000	1.2
+++ Widget.chs	25 Feb 2005 01:11:31 -0000	1.3
@@ -19,20 +19,9 @@
 --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 --  Lesser General Public License for more details.
 --
--- |
--- Maintainer  : gtk...@li...
--- Stability   : provisional
--- Portability : portable (depends on GHC)
---
---  Widget is the base class of all widgets. It provides the methods to
---  attach and detach signals.
---
---  * This modules reexports everything a normal widget needs from GObject
---    and Object.
---
 -- TODO
 --
--- * unimplemented methods that seem to be useful in user programs:
+-- unimplemented methods that seem to be useful in user programs:
 --      widgetSizeRequest, widgetAddAccelerator, widgetRemoveAccelerator,
 --	widgetAcceleratorSignal, widgetIntersect, widgetGrabDefault,
 --	widgetGetPointer, widgetPath, widgetClassPath, getCompositeName,
@@ -42,13 +31,50 @@
 --	widgetPango*, widgetSetAdjustments
 --	
 --
--- * implement the following methods in GtkWindow object:
+-- implement the following methods in GtkWindow object:
 --      widget_set_uposition, widget_set_usize
 --
--- * implement the following methods in GtkDrawingArea object:
+-- implement the following methods in GtkDrawingArea object:
 --      widgetQueueDrawArea, widgetSetDoubleBufferd, widgetRegionIntersect
 --
+-- |
+-- Maintainer  : gtk...@li...
+-- Stability   : provisional
+-- Portability : portable (depends on GHC)
+--
+-- Base class for all widgets
+-- 
 module Graphics.UI.Gtk.Abstract.Widget (
+-- * Description
+-- 
+-- | 'Widget' introduces style properties - these are basically object
+-- properties that are stored not on the object, but in the style object
+-- associated to the widget. Style properties are set in resource files. This
+-- mechanism is used for configuring such things as the location of the
+-- scrollbar arrows through the theme, giving theme authors more control over
+-- the look of applications without the need to write a theme engine in C.
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----'Object'
+-- |         +----Widget
+-- |               +----'Misc'
+-- |               +----'Container'
+-- |               +----'Calendar'
+-- |               +----'DrawingArea'
+-- |               +----'Entry'
+-- |               +----'Ruler'
+-- |               +----'Range'
+-- |               +----'Separator'
+-- |               +----'Invisible'
+-- |               +----'OldEditable'
+-- |               +----'Preview'
+-- |               +----'Progress'
+-- @
+
+-- * Types
   Widget,
   WidgetClass,
   castToWidget,
@@ -170,7 +196,8 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
--- methods
+--------------------
+-- Methods
 
 -- | Queue a show request.
 --
@@ -379,10 +406,8 @@
 --widgetUnlockAccelerators :: WidgetClass w => w -> IO ()
 --widgetUnlockAccelerators = {#call widget_unlock_accelerators#}.toWidget
 
-
-
-
--- signals
+--------------------
+-- Signals
 
 -- Because there are so many similar signals (those that take an Event and
 -- return a Bool) we will abstract out the skeleton. As some of these events

Index: Scale.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Abstract/Scale.chs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Scale.chs	12 Feb 2005 17:19:21 -0000	1.2
+++ Scale.chs	25 Feb 2005 01:11:31 -0000	1.3
@@ -28,9 +28,36 @@
 -- management of an adjustable value.
 --
 module Graphics.UI.Gtk.Abstract.Scale (
+-- * Description
+-- 
+-- | A '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, 'Range',
+-- in addition to the methods for 'Scale' itself. To set the value of a scale,
+-- you would normally use 'rangeSetValue'. To detect changes to the value, you
+-- would normally use the 'onValueVhanged' signal.
+--
+-- The 'Scale' widget is an abstract class, used only for deriving the
+-- subclasses 'HScale' and 'VScale'. To create a scale widget, call
+-- 'hScaleNewWithRange' or 'vScaleNewWithRange'.
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----'Object'
+-- |         +----'Widget'
+-- |               +----'Range'
+-- |                     +----Scale
+-- |                           +----'HScale'
+-- |                           +----'VScale'
+-- @
+
+-- * Types
   Scale,
   ScaleClass,
   castToScale,
+
+-- * Methods
   scaleSetDigits,
   scaleGetDigits,
   scaleSetDrawValue,
@@ -50,7 +77,8 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
--- methods
+--------------------
+-- Methods
 
 -- | Set the number of displayed digits after the comma.
 --

Index: Container.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Abstract/Container.chs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Container.chs	12 Feb 2005 17:19:20 -0000	1.2
+++ Container.chs	25 Feb 2005 01:11:31 -0000	1.3
@@ -28,9 +28,115 @@
 -- into one compound widget.
 --
 module Graphics.UI.Gtk.Abstract.Container (
+-- * Description
+-- 
+-- | A Gtk+ user interface is constructed by nesting widgets inside widgets.
+-- Container widgets are the inner nodes in the resulting tree of widgets: they
+-- contain other widgets. So, for example, you might have a 'Window' containing
+-- a 'Frame' containing a 'Label'. If you wanted an image instead of a textual
+-- label inside the frame, you might replace the 'Label' widget with a 'Image'
+-- widget.
+--
+-- There are two major kinds of container widgets in Gtk+. Both are
+-- subclasses of the abstract 'Container' base class.
+--
+-- The first type of container widget has a single child widget and derives
+-- from 'Bin'. These containers are decorators, which add some kind of
+-- functionality to the child. For example, a 'Button' makes its child into a
+-- clickable button; a 'Frame' draws a frame around its child and a 'Window'
+-- places its child widget inside a top-level window.
+--
+-- The second type of container can have more than one child; its purpose is
+-- to manage layout. This means that these containers assign sizes and
+-- positions to their children. For example, a 'HBox' arranges its children in
+-- a horizontal row, and a 'Table' arranges the widgets it contains in a
+-- two-dimensional grid.
+--
+-- To fulfill its task, a layout container must negotiate the size
+-- requirements with its parent and its children. This negotiation is carried
+-- out in two phases, size requisition and size allocation.
+
+-- ** Size Requisition
+-- 
+-- | The size requisition of a widget is it's desired width and height. This
+-- is represented by a 'Requisition'.
+--
+-- How a widget determines its desired size depends on the widget. A
+-- 'Label', for example, requests enough space to display all its text.
+-- Container widgets generally base their size request on the requisitions of
+-- their children.
+--
+-- The size requisition phase of the widget layout process operates
+-- top-down. It starts at a top-level widget, typically a 'Window'. The
+-- top-level widget asks its child for its size requisition by calling
+-- 'widgetSizeRequest'. To determine its requisition, the child asks its own
+-- children for their requisitions and so on. Finally, the top-level widget
+-- will get a requisition back from its child.
+
+-- ** Size Allocation
+-- 
+-- | When the top-level widget has determined how much space its child would
+-- like to have, the second phase of the size negotiation, size allocation,
+-- begins. Depending on its configuration (see 'windowSetResizable'), the
+-- top-level widget may be able to expand in order to satisfy the size request
+-- or it may have to ignore the size request and keep its fixed size. It then
+-- tells its child widget how much space it gets by calling
+-- 'widgetSizeAllocate'. The child widget divides the space among its children
+-- and tells each child how much space it got, and so on. Under normal
+-- circumstances, a 'Window' will always give its child the amount of space the
+-- child requested.
+--
+-- A child's size allocation is represented by an 'Allocation'.
+-- This contains not only a width and height, but also a
+-- position (i.e. X and Y coordinates), so that containers can tell their
+-- children not only how much space they have gotten, but also where they are
+-- positioned inside the space available to the container.
+--
+-- Widgets are required to honor the size allocation they receive; a size
+-- request is only a request, and widgets must be able to cope with any size.
+
+-- ** Child properties
+-- 
+-- | 'Container' introduces child properties - these are object properties
+-- that are not specific to either the container or the contained widget, but
+-- rather to their relation. Typical examples of child properties are the
+-- position or pack-type of a widget which is contained in a 'Box'.
+--
+-- To set the value of a child property, use 'containerChildSetProperty',
+-- 'containerChildSet' or 'containerChildSetValist'. To obtain the value of a
+-- child property, use 'containerChildGetProperty', 'containerChildGet' or
+-- 'containerChildGetValist'.
+-- 
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----'Object'
+-- |         +----'Widget'
+-- |               +----Container
+-- |                     +----'Bin'
+-- |                     +----'Box'
+-- |                     +----'CList'
+-- |                     +----'Fixed'
+-- |                     +----'Paned'
+-- |                     +----'Layout'
+-- |                     +----'List'
+-- |                     +----'MenuShell'
+-- |                     +----'Notebook'
+-- |                     +----'Socket'
+-- |                     +----'Table'
+-- |                     +----'TextView'
+-- |                     +----'Toolbar'
+-- |                     +----'TreeView'
+-- @
+
+-- * Types
   Container,
   ContainerClass,
   castToContainer,
+
+-- * Methods
   containerAdd,
   containerRemove,
   containerForeach,
@@ -49,6 +155,8 @@
   containerGetBorderWidth,
   containerChildSetProperty,
   containerChildGetProperty,
+
+-- * Signals
   onAdd,
   afterAdd,
   onCheckResize,
@@ -76,7 +184,8 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
--- methods
+--------------------
+-- Methods
 
 -- | Add a widget to the container.
 --
@@ -244,7 +353,8 @@
   valueUnset valPtr
   return res
 
--- signals
+--------------------
+-- Signals
 
 -- | This signal is called each time a new widget is added
 -- to this container.

Index: Bin.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Abstract/Bin.chs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Bin.chs	12 Feb 2005 17:19:20 -0000	1.2
+++ Bin.chs	25 Feb 2005 01:11:31 -0000	1.3
@@ -27,10 +27,45 @@
 -- This abstract widget implements a container with just one child.
 --
 module Graphics.UI.Gtk.Abstract.Bin (
+-- * Description
+-- 
+-- | The 'Bin' widget is a container with just one child. It is not very
+-- useful itself, but it is useful for deriving subclasses, since it provides
+-- common code needed for handling a single child widget.
+--
+-- Many Gtk+ widgets are subclasses of 'Bin', including 'Window', 'Button',
+-- 'Frame', 'HandleBox', and 'ScrolledWindow'.
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----'Object'
+-- |         +----'Widget'
+-- |               +----'Container'
+-- |                     +----Bin
+-- |                           +----'Alignment'
+-- |                           +----'Frame'
+-- |                           +----'Button'
+-- |                           +----'Item'
+-- |                           +----'Window'
+-- |                           +----'ComboBox'
+-- |                           +----'EventBox'
+-- |                           +----'Expander'
+-- |                           +----'HandleBox'
+-- |                           +----'ToolItem'
+-- |                           +----'ScrolledWindow'
+-- |                           +----'Viewport'
+-- @
+
+-- * Types
   Bin,
   BinClass,
+  castToBin,
+
+-- * Methods
   binGetChild
-) where
+  ) where
 
 import System.Glib.FFI
 
@@ -39,6 +74,9 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
+--------------------
+-- Methods
+
 binGetChild :: BinClass bin => bin -> IO Widget
 binGetChild bin =
   makeNewObject mkWidget $ {# call gtk_bin_get_child #} (toBin bin)