[Gtk2hs-commit] gtk2hs/gtk/Graphics/UI/Gtk/Embedding Plug.chs,1.2,1.3 Socket.chs,1.2,1.3

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

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

Modified Files:
	Plug.chs Socket.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: Plug.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Embedding/Plug.chs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Plug.chs	12 Feb 2005 17:19:22 -0000	1.2
+++ Plug.chs	25 Feb 2005 01:11:33 -0000	1.3
@@ -24,17 +24,40 @@
 -- Stability   : provisional
 -- Portability : portable (depends on GHC)
 --
--- Plug is a window that is to be attached to the window of another
--- application. If you have managed to receive the 'XID' from
--- the inviting application you can construct the Plug and add your widgets
--- to it.
+-- Toplevel for embedding into other processes.
 --
 module Graphics.UI.Gtk.Embedding.Plug (
+-- * Description
+-- 
+-- | Together with 'Socket', 'Plug' provides the ability to embed widgets from
+-- one process into another process in a fashion that is transparent to the
+-- user. One process creates a 'Socket' widget and, passes the ID of that
+-- widgets window to the other process, which then creates a 'Plug' with that
+-- window ID. Any widgets contained in the 'Plug' then will appear inside the
+-- first applications window.
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----'Object'
+-- |         +----'Widget'
+-- |               +----'Container'
+-- |                     +----'Bin'
+-- |                           +----'Window'
+-- |                                 +----Plug
+-- @
+
+-- * Types
   Plug,
   PlugClass,
   castToPlug,
   NativeWindowId,
+
+-- * Constructors
   plugNew,
+
+-- * Methods
   plugGetId
   ) where
 
@@ -49,7 +72,8 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
--- methods
+--------------------
+-- Constructors
 
 -- | Create a new 'Window' to hold another
 -- application.
@@ -64,6 +88,9 @@
 plugNew mnw = makeNewObject mkPlug $ liftM castPtr $
   {#call unsafe plug_new#} (fromIntegral (fromMaybe 0 mnw))
 
+--------------------
+-- Methods
+
 -- | Retrieve the 'NativeWindowId'.
 --
 -- * The result should be passed to the application which is to be embedded.
@@ -72,6 +99,9 @@
 plugGetId :: PlugClass p => p -> IO NativeWindowId
 plugGetId p = liftM fromIntegral $ {#call unsafe plug_get_id#} (toPlug p)
 
+--------------------
+-- Signals
+
 -- | This plug received another application.
 --
 onEmbedded, afterEmbedded :: PlugClass p => p -> IO () -> IO (ConnectId p)

Index: Socket.chs
===================================================================
RCS file: /cvsroot/gtk2hs/gtk2hs/gtk/Graphics/UI/Gtk/Embedding/Socket.chs,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Socket.chs	12 Feb 2005 17:19:22 -0000	1.2
+++ Socket.chs	25 Feb 2005 01:11:33 -0000	1.3
@@ -24,30 +24,70 @@
 -- Stability   : provisional
 -- Portability : portable (depends on GHC)
 --
--- This widget provides the possibility that other application display their
--- widgets within this application.
+-- Container for widgets from other processes.
 --
--- * After creation of the Socket, you may retrieve the 
---   'NativeWindow' of the socket. 
---   For this to work, the socket must at least be realized (e.g. shown).
+module Graphics.UI.Gtk.Embedding.Socket (
+-- * Description
+-- 
+-- | Together with 'Plug', 'Socket' provides the ability to embed widgets from
+-- one process into another process in a fashion that is transparent to the
+-- user. One process creates a 'Socket' widget and, passes the that widget's
+-- window ID to the other process, which then creates a 'Plug' with that window
+-- ID. Any widgets contained in the 'Plug' then will appear inside the first
+-- applications window.
 --
--- * The application has to make sure the 'Socket'
---   is not destroyed while the
---   other application tries to connect. If the 'NativeWindow' was 
---   transmitted, the
---   inviting application can check with 'socketHasPlug' if the 
---   plug has
---   already connected.
+-- The socket's window ID is obtained by using 'socketGetId'. Before using
+-- this function, the socket must have been realized, and for hence, have been
+-- added to its parent.
 --
-module Graphics.UI.Gtk.Embedding.Socket (
+-- Note that if you pass the window ID of the socket to another process that
+-- will create a plug in the socket, you must make sure that the socket widget
+-- is not destroyed until that plug is created. Violating this rule will cause
+-- unpredictable consequences, the most likely consequence being that the plug
+-- will appear as a separate toplevel window. You can check if the plug has
+-- been created by calling 'socketHasPlug'.
+-- If this returns @True@, then the plug has been successfully created inside
+--  of the socket.
+--
+-- When Gtk+ is notified that the embedded window has been destroyed, then
+-- it will destroy the socket as well. You should always, therefore, be
+-- prepared for your sockets to be destroyed at any time when the main event
+-- loop is running.
+--
+-- The communication between a 'Socket' and a 'Plug' follows the XEmbed
+-- protocol. This protocol has also been implemented in other toolkits, e.g.
+-- Qt, allowing the same level of integration when embedding a Qt widget in
+-- Gtk+ or vice versa.
+--
+-- A socket can also be used to swallow arbitrary pre-existing top-level
+-- windows using 'socketSteal', though the integration when this is done will
+-- not be as close as between a 'Plug' and a 'Socket'.
+
+-- * Class Hierarchy
+-- |
+-- @
+-- |  'GObject'
+-- |   +----'Object'
+-- |         +----'Widget'
+-- |               +----'Container'
+-- |                     +----Socket
+-- @
+
+-- * Types
   Socket,
   SocketClass,
   castToSocket,
   NativeWindowId,
+
+-- * Constructors
   socketNew,
+
+-- * Methods
   socketHasPlug,
   socketAddId,
   socketGetId,
+
+-- * Signals
   onPlugAdded,
   afterPlugAdded,
   onPlugRemoved,
@@ -64,7 +104,8 @@
 
 {# context lib="gtk" prefix="gtk" #}
 
--- methods
+--------------------
+-- Constructors
 
 -- | Create a 'Container' for embedding.
 --
@@ -76,6 +117,9 @@
 socketNew :: IO Socket
 socketNew = makeNewObject mkSocket $ liftM castPtr {#call unsafe socket_new#}
 
+--------------------
+-- Methods
+
 -- | Insert another application into this socket.
 --
 -- * Inserts the other application into this plug. The
@@ -97,6 +141,9 @@
 socketGetId soc = liftM fromIntegral $
 		  {#call unsafe socket_get_id#} (toSocket soc)
 
+--------------------
+-- Signals
+
 -- | This socket was added into another application.
 --
 onPlugAdded, afterPlugAdded :: SocketClass s => s -> IO () -> IO (ConnectId s)