[Gtk2hs-commit] gtk2hs/gtk/Graphics/UI/Gtk/General IconFactory.chs.pp,1.3,1.4 Style.chs,1.2,1.3

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

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

Modified Files:
	IconFactory.chs.pp Style.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: Style.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/General/Style.chs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Style.chs	12 Feb 2005 17:19:23 -0000	1.2
+++ Style.chs	25 Feb 2005 01:11:34 -0000	1.3
@@ -19,6 +19,14 @@
 --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 --  Lesser General Public License for more details.
 --
+-- TODO
+--
+-- It seems sensible to treat Styles as read only. The only way to modify
+--   a style should be for the programmer to apply the RcStyle patches directly
+--   to the widget.
+--
+-- Bind the draw... functions, they might be useful.
+--
 -- |
 -- Maintainer  : gtk...@li...
 -- Stability   : provisional
@@ -26,32 +34,27 @@
 --
 -- Customization of widgets.
 --
--- * Styles are attached to widgets and determine how particular parts are
---   drawn and with what color. Thus they are should be seen as mandatory 
---   when one implements a new
---   custom widgets via 'DrawingArea'. Although the parameterized
---   drawing function don't have to be used, it is
---   strongly advisable (and more robust)
---   to make use of the predefined graphics contexts for the different
---   states of a widget (retrieved by 'widgetGetState').
---
--- * When creating complicated objects in 'DrawingArea' the predefined
---   graphics contexts and the single font in the canvas 
---   might not be enough to customize the rendering process. 
---   gtk_rc_get_style_by_paths is the solution for this.
---
---
--- TODO
---
--- * It seems sensible to treat Styles as read only. The only way to modify
---   a style should be for the programmer to apply the RcStyle patches directly
---   to the widget.
+module Graphics.UI.Gtk.General.Style (
+-- * Description
+-- 
+-- | Styles are attached to widgets and determine how particular parts are
+-- drawn and with what color. Thus they are should be seen as mandatory when
+-- one implements a new custom widgets via 'DrawingArea'. Although the
+-- parameterized drawing function don't have to be used, it is strongly
+-- advisable (and more robust) to make use of the predefined graphics contexts
+-- for the different states of a widget (retrieved by 'widgetGetState').
 --
--- * Bind the draw... functions, they might be useful.
+-- When creating complicated objects in 'DrawingArea' the predefined graphics
+-- contexts and the single font in the canvas might not be enough to customize
+-- the rendering process. gtk_rc_get_style_by_paths is the solution for this.
 --
-module Graphics.UI.Gtk.General.Style (
+
+-- * Types
   Style,
   StyleClass,
+  castToStyle,
+
+-- * Methods
   styleGetForeground,
   styleGetBackground,
   styleGetLight,

Index: IconFactory.chs.pp
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/General/IconFactory.chs.pp,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- IconFactory.chs.pp	13 Feb 2005 16:25:57 -0000	1.3
+++ IconFactory.chs.pp	25 Feb 2005 01:11:34 -0000	1.4
@@ -19,6 +19,14 @@
 --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 --  Lesser General Public License for more details.
 --
+-- TODO
+--
+-- The following functions are not bound:
+--   iconFactoryLookup, iconFactoryLookupDefault
+--   It is not a good idea to lookup an IconSet directly. If an Icon needs to
+--   be displayed it happends always in the context of a widget. The best
+--   practice is to get the widgets Style and call styleLookupIconSet.
+--
 -- |
 -- Maintainer  : gtk...@li...
 -- Stability   : provisional
@@ -26,17 +34,45 @@
 --
 -- This module provides access to IconFactory, IconSet and IconSource.
 --
--- TODO
+module Graphics.UI.Gtk.General.IconFactory (
+-- * Description
+-- 
+-- | Browse the available stock icons in the list of stock IDs found here. You
+-- can also use the gtk-demo application for this purpose.
 --
--- * The following functions are not bound:
---   iconFactoryLookup, iconFactoryLookupDefault
---   It is not a good idea to lookup an IconSet directly. If an Icon needs to
---   be displayed it happends always in the context of a widget. The best
---   practice is to get the widgets Style and call styleLookupIconSet.
+-- An icon factory manages a collection of 'IconSet'; a 'IconSet' manages a
+-- set of variants of a particular icon (i.e. a 'IconSet' contains variants for
+-- different sizes and widget states). Icons in an icon factory are named by a
+-- stock ID, which is a simple string identifying the icon. Each 'Style' has a
+-- list of 'IconFactory' derived from the current theme; those icon factories
+-- are consulted first when searching for an icon. If the theme doesn't set a
+-- particular icon, Gtk+ looks for the icon in a list of default icon
+-- factories, maintained by 'iconFactoryAddDefault' and
+-- 'iconFactoryRemoveDefault'. Applications with icons should add a default
+-- icon factory with their icons, which will allow themes to override the icons
+-- for the application.
 --
-module Graphics.UI.Gtk.General.IconFactory (
+-- To display an icon, always use 'styleLookupIconSet' on the widget that
+-- will display the icon, or the convenience function 'widgetRenderIcon'. These
+-- functions take the theme into account when looking up the icon to use for a
+-- given stock ID.
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----IconFactory
+-- @
+
+-- * Types
   IconFactory,
+  IconFactoryClass,
+  castToIconFactory,
+
+-- * Constructors
   iconFactoryNew,
+
+-- * Methods
   iconFactoryAdd,
   iconFactoryAddDefault,
   iconFactoryLookup,
@@ -97,8 +133,23 @@
 
 {#pointer *IconSet foreign newtype#}
 
--- methods
+--------------------
+-- Constructors
 
+-- | Create a new IconFactory.
+--
+-- * An application should create a new 'IconFactory' and add all
+--   needed icons.
+--   By calling 'iconFactoryAddDefault' these icons become
+--   available as stock objects and can easily be displayed by
+--   'Image'. Furthermore, a theme can override the icons defined by
+--   the application.
+--
+iconFactoryNew :: IO IconFactory
+iconFactoryNew  = makeNewGObject mkIconFactory {#call unsafe icon_factory_new#}
+
+--------------------
+-- Methods
 
 -- | Add an IconSet to an IconFactory.
 --
@@ -142,18 +193,6 @@
   if iconSetPtr == nullPtr then return Nothing else liftM (Just . IconSet) $
     newForeignPtr iconSetPtr (icon_set_unref iconSetPtr)
 
--- | Create a new IconFactory.
---
--- * An application should create a new 'IconFactory' and add all
---   needed icons.
---   By calling 'iconFactoryAddDefault' these icons become
---   available as stock objects and can easily be displayed by
---   'Image'. Furthermore, a theme can override the icons defined by
---   the application.
---
-iconFactoryNew :: IO IconFactory
-iconFactoryNew  = makeNewGObject mkIconFactory {#call unsafe icon_factory_new#}
-
 -- | Remove an IconFactory from the
 -- application's stock database.
 --