[Gtk2hs-commit] gtk2hs/gtk/Graphics/UI/Gtk/Multiline TextBuffer.chs,1.2,1.3 TextMark.chs,1.2,1.3 TextTag.chs.pp,1.2,1.3 TextTagTable.chs,1.2,1.3 TextView.chs,1.2,1.3

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

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

Modified Files:
	TextBuffer.chs TextMark.chs TextTag.chs.pp TextTagTable.chs 
	TextView.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: TextView.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Multiline/TextView.chs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- TextView.chs	12 Feb 2005 17:19:24 -0000	1.2
+++ TextView.chs	25 Feb 2005 01:11:36 -0000	1.3
@@ -19,12 +19,23 @@
 --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 --  Lesser General Public License for more details.
 --
+-- TODO
+--
+-- If PangoTabArray is bound: do textViewSetTabs and textViewGetTabs
+--
 -- |
 -- Maintainer  : gtk...@li...
 -- Stability   : provisional
 -- Portability : portable (depends on GHC)
 --
--- Widget that displays a GtkTextBuffer
+-- Widget that displays a 'TextBuffer'
+--
+module Graphics.UI.Gtk.Multiline.TextView (
+-- * Description
+-- 
+-- | You may wish to begin by reading the text widget conceptual overview
+-- which gives an overview of all the objects and data types related to the
+-- text widget and how they work together.
 --
 -- * Throughout we distinguish between buffer coordinates which are pixels
 --   with the origin at the upper left corner of the first character on the
@@ -32,12 +43,22 @@
 --   is visible in the current 'TextView'. Coordinates from Events 
 --   are in the latter relation. The conversion can be done with 
 --   'textViewWindowToBufferCoords'.
---
--- TODO
---
--- * If PangoTabArray is bound: do textViewSetTabs and textViewGetTabs
---
-module Graphics.UI.Gtk.Multiline.TextView (
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----'Object'
+-- |         +----'Widget'
+-- |               +----'Container'
+-- |                     +----TextView
+-- |
+-- |
+-- |  'GObject'
+-- |   +----TextChildAnchor
+-- @
+
+-- * Types
   TextView,
   TextViewClass,
   TextChildAnchor,
@@ -49,8 +70,12 @@
   MovementStep(..),
   TextWindowType(..),
   WrapMode(..),
+
+-- * Constructors
   textViewNew,
   textViewNewWithBuffer,
+
+-- * Methods
   textViewSetBuffer,
   textViewGetBuffer,
   textViewScrollToMark,
@@ -102,6 +127,8 @@
   textViewSetIndent,
   textViewGetIndent,
   textViewGetDefaultAttributes,
+
+-- * Signals
   onCopyClipboard,
   afterCopyClipboard,
   onCutClipboard,
@@ -145,8 +172,8 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
-
--- methods
+--------------------
+-- Constructors
 
 -- | Create a new 'TextView' widget with a
 -- default 'TextBuffer'.
@@ -162,6 +189,9 @@
 textViewNewWithBuffer tb = makeNewGObject mkTextView $ liftM castPtr $
   {#call unsafe text_view_new_with_buffer#} tb
 
+--------------------
+-- Methods
+
 -- | Set the 'TextBuffer' for a given 'TextView' widget.
 --
 textViewSetBuffer :: TextViewClass tv => tv -> TextBuffer -> IO ()

Index: TextMark.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Multiline/TextMark.chs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- TextMark.chs	12 Feb 2005 17:19:24 -0000	1.2
+++ TextMark.chs	25 Feb 2005 01:11:36 -0000	1.3
@@ -27,10 +27,44 @@
 -- A position in the buffer preserved across buffer modifications
 --
 module Graphics.UI.Gtk.Multiline.TextMark (
+-- * Description
+-- 
+-- | You may wish to begin by reading the text widget conceptual overview
+-- which gives an overview of all the objects and data types related to the
+-- text widget and how they work together.
+--
+-- A 'TextMark' is like a bookmark in a text buffer; it preserves a position
+-- in the text. You can convert the mark to an iterator using
+-- 'textBufferGetIterAtMark'. Unlike iterators, marks remain valid across
+-- buffer mutations, because their behavior is defined when text is inserted or
+-- deleted. When text containing a mark is deleted, the mark remains in the
+-- position originally occupied by the deleted text. When text is inserted at a
+-- mark, a mark with left gravity will be moved to the beginning of the
+-- newly-inserted text, and a mark with right gravity will be moved to the end.
+--
+-- Marks can be deleted from the buffer at any time
+-- with 'textBufferDeleteMark'. Once deleted from the buffer, a mark is
+-- essentially useless.
+--
+-- Marks optionally have names; these can be convenient to avoid passing the
+-- 'TextMark' object around.
+--
+-- Marks are typically created using the 'textBufferCreateMark' function.
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----TextMark
+-- @
+
+-- * Types
   TextMark,
   TextMarkClass,
   castToTextMark,
   MarkName,
+
+-- * Methods
   textMarkSetVisible,
   textMarkGetVisible,
   textMarkGetDeleted,
@@ -51,7 +85,8 @@
 
 type MarkName = String
 
--- methods
+--------------------
+-- Methods
 
 -- | Set the visibility of a 'TextMark'.
 --
@@ -101,5 +136,3 @@
 textMarkGetLeftGravity tm = liftM toBool $
   {#call unsafe text_mark_get_left_gravity#} (toTextMark tm)
 
-
- 

Index: TextTag.chs.pp
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Multiline/TextTag.chs.pp,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- TextTag.chs.pp	12 Feb 2005 17:19:24 -0000	1.2
+++ TextTag.chs.pp	25 Feb 2005 01:11:36 -0000	1.3
@@ -31,11 +31,37 @@
 -- * accessor functions for TextAttributes
 --
 module Graphics.UI.Gtk.Multiline.TextTag (
+-- * Description
+-- 
+-- | You may wish to begin by reading the text widget conceptual overview
+-- which gives an overview of all the objects and data types related to the
+-- text widget and how they work together.
+--
+-- Tags should be in the 'TextTagTable' for a given 'TextBuffer' before
+-- using them with that buffer.
+--
+-- 'textBufferCreateTag' is the best way to create tags.
+--
+-- The \"invisible\" property was not implemented for Gtk+ 2.0; it's planned
+-- to be implemented in future releases.
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----TextTag
+-- @
+
+-- * Types
   TextTag,
   TextTagClass,
   castToTextTag,
   TagName,
+
+-- * Constructors
   textTagNew,
+
+-- * Methods
   textTagSetPriority,
   textTagGetPriority,
   TextAttributes(..),
@@ -54,7 +80,8 @@
 
 type TagName = String
 
--- TextTag methods
+--------------------
+-- Constructors
 
 -- | Creates a 'TextTag'.
 --
@@ -63,6 +90,9 @@
   withCString name $ \strPtr ->
   makeNewGObject mkTextTag $ {#call unsafe text_tag_new#} strPtr
 
+--------------------
+-- Methods
+
 -- | Get the tag priority.
 --
 textTagGetPriority :: TextTagClass obj => obj -> IO Int

Index: TextTagTable.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Multiline/TextTagTable.chs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- TextTagTable.chs	12 Feb 2005 17:19:24 -0000	1.2
+++ TextTagTable.chs	25 Feb 2005 01:11:36 -0000	1.3
@@ -24,11 +24,31 @@
 -- Stability   : provisional
 -- Portability : portable (depends on GHC)
 --
+-- Collection of tags that can be used together
+--
 module Graphics.UI.Gtk.Multiline.TextTagTable (
+-- * Description
+-- 
+-- | You may wish to begin by reading the text widget conceptual overview
+-- which gives an overview of all the objects and data types related to the
+-- text widget and how they work together.
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----TextTagTable
+-- @
+
+-- * Types
   TextTagTable,
   TextTagTableClass,
   castToTextTagTable,
+
+-- * Constructors
   textTagTableNew,
+
+-- * Methods
   textTagTableAdd,
   textTagTableRemove,
   textTagTableLookup,
@@ -45,6 +65,9 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
+--------------------
+-- Constructors
+
 -- | Creates a new 'TextTagTable'. The table contains no tags by default.
 --
 textTagTableNew :: IO TextTagTable
@@ -52,6 +75,9 @@
   makeNewGObject mkTextTagTable $ 
   {#call unsafe text_tag_table_new#}
 
+--------------------
+-- Methods
+
 -- | Add a tag to the table. The tag is assigned the highest priority in the
 -- table.
 --

Index: TextBuffer.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Multiline/TextBuffer.chs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- TextBuffer.chs	12 Feb 2005 17:19:24 -0000	1.2
+++ TextBuffer.chs	25 Feb 2005 01:11:36 -0000	1.3
@@ -19,6 +19,29 @@
 --  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 --  Lesser General Public License for more details.
 --
+-- TODO
+--
+-- The functionality of inserting widgets (child anchors) is not implemented
+--   since there will probably some changes before the final release. The
+--   following functions are not bound:
+--     gtk_text_buffer_insert_child_anchor
+--     gtk_text_buffer_create_child_anchor
+--     gtk_text_buffer_get_iter_at_anchor
+--     connectToInsertChildAnchor
+--     
+-- Check 'textBufferGetInsert', in case there is no cursor in 
+--   the editor,
+--   is there a mark called \"insert\"? If not, the function needs to return
+--   Maybe TextMark. The same holds for 
+--   'textBufferGetSelectionBound'.
+--
+-- If Clipboards are bound, then these functions need to be bound as well:
+--     gtk_text_buffer_paste_clipboard
+--     gtk_text_buffer_copy_clipboard
+--     gtk_text_buffer_cut_clipboard
+--     gtk_text_buffer_add_selection_clipboard
+--     gtk_text_buffer_remove_selection_clipboard
+--
 -- |
 -- Maintainer  : gtk...@li...
 -- Stability   : provisional
@@ -43,34 +66,24 @@
 -- * The function gtk_text_buffer_get_selection_bounds is only used to test
 --   if there is a selection  (see 'textBufferHasSelection').
 --
--- TODO
---
--- * The functionality of inserting widgets (child anchors) is not implemented
---   since there will probably some changes before the final release. The
---   following functions are not bound:
---     gtk_text_buffer_insert_child_anchor
---     gtk_text_buffer_create_child_anchor
---     gtk_text_buffer_get_iter_at_anchor
---     connectToInsertChildAnchor
---     
--- * Check 'textBufferGetInsert', in case there is no cursor in 
---   the editor,
---   is there a mark called \"insert\"? If not, the function needs to return
---   Maybe TextMark. The same holds for 
---   'textBufferGetSelectionBound'.
---
--- * If Clipboards are bound, then these functions need to be bound as well:
---     gtk_text_buffer_paste_clipboard
---     gtk_text_buffer_copy_clipboard
---     gtk_text_buffer_cut_clipboard
---     gtk_text_buffer_add_selection_clipboard
---     gtk_text_buffer_remove_selection_clipboard
---
 module Graphics.UI.Gtk.Multiline.TextBuffer (
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----TextBuffer
+-- @
+
+-- * Types
   TextBuffer,
   TextBufferClass,
   castToTextBuffer,
+
+-- * Constructors
   textBufferNew,
+
+-- * Methods
   textBufferGetLineCount,
   textBufferGetCharCount,
   textBufferGetTagTable,
@@ -112,18 +125,30 @@
   textBufferHasSelection,
   textBufferBeginUserAction,
   textBufferEndUserAction,
-  onApplyTag, afterApplyTag,
-  onBeginUserAction, afterBeginUserAction,
-  onBufferChanged, afterBufferChanged,
-  onDeleteRange, afterDeleteRange,
-  onEndUserAction, afterEndUserAction,
-  onInsertPixbuf, afterInsertPixbuf,
-  onInsertText, afterInsertText,
-  onMarkDeleted, afterMarkDeleted,
-  onMarkSet, afterMarkSet,
-  onModifiedChanged, afterModifiedChanged,
-  onRemoveTag, afterRemoveTag,
-  
+
+-- * Signals
+  onApplyTag,
+  afterApplyTag,
+  onBeginUserAction,
+  afterBeginUserAction,
+  onBufferChanged,
+  afterBufferChanged,
+  onDeleteRange,
+  afterDeleteRange,
+  onEndUserAction,
+  afterEndUserAction,
+  onInsertPixbuf,
+  afterInsertPixbuf,
+  onInsertText,
+  afterInsertText,
+  onMarkDeleted,
+  afterMarkDeleted,
+  onMarkSet,
+  afterMarkSet,
+  onModifiedChanged,
+  afterModifiedChanged,
+  onRemoveTag,
+  afterRemoveTag
   ) where
 
 import Monad	(liftM)
@@ -140,7 +165,8 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
--- methods
+--------------------
+-- Constructors
 
 -- | Create a new text buffer, possibly taking a
 -- table of 'TextTag'.
@@ -150,6 +176,9 @@
   {#call unsafe text_buffer_new#} 
   (fromMaybe (mkTextTagTable nullForeignPtr) tt)
 
+--------------------
+-- Methods
+
 -- | Obtain the number of lines in the buffer.
 --
 textBufferGetLineCount :: TextBufferClass tb => tb -> IO Int
@@ -567,8 +596,8 @@
 textBufferEndUserAction  = {#call text_buffer_end_user_action#} .
 			   toTextBuffer
 
-
--- callbacks
+--------------------
+-- Signals
 
 -- | A 'TextTag' was applied to a region of
 -- text.