@@ -1,21 +1,14 @@
1−-- | Vty supports input and output to terminal devices.
1+-- | Vty provides interfaces for both terminal input and terminal
2+-- output.
23--
3−-- - Input to the terminal is provided to the app as a sequence of
4−-- 'Event's.
4+-- - Input to the terminal is provided to the Vty application as a
5+-- sequence of 'Event's.
56--
6−-- - The output is defined by a 'Picture'. Which is one or more layers
7−-- of 'Image's.
8−--
9−-- - The module "Graphics.Vty.Image" provides a number of
10−-- constructor equations that will build correct 'Image' values.
11−-- See 'string', '<|>', and '<->' for starters.
12−--
13−-- - The constructors in "Graphics.Vty.Image.Internal" should not
14−-- be used.
15−--
16−-- - 'Image's can be styled using 'Attr'. See "Graphics.Vty.Attributes".
17−--
18−-- See the vty-examples package for a number of examples.
7+-- - Output is provided to Vty by the application in the form of a
8+-- 'Picture'. A 'Picture' is one or more layers of 'Image's.
9+-- 'Image' values can be built by the various constructors in
10+-- "Graphics.Vty.Image". Output can be syled using 'Attr' (attribute)
11+-- values in the "Graphics.Vty.Attributes" module.
1912--
2013-- @
2114-- import "Graphics.Vty"
@@ -23,10 +16,8 @@
2316-- main = do
2417-- cfg <- 'standardIOConfig'
2518-- vty <- 'mkVty' cfg
26−-- let line0 = 'string' ('defAttr' ` 'withForeColor' ` 'green')
27−-- \"first line\"
28−-- line1 = 'string' ('defAttr' ` 'withBackColor' ` 'blue')
29−-- \"second line\"
19+-- let line0 = 'string' ('defAttr' ` 'withForeColor' ` 'green') \"first line\"
20+-- line1 = 'string' ('defAttr' ` 'withBackColor' ` 'blue') \"second line\"
3021-- img = line0 '<->' line1
3122-- pic = 'picForImage' img
3223-- 'update' vty pic
@@ -34,23 +25,10 @@
3425-- 'shutdown' vty
3526-- 'print' (\"Last event was: \" '++' 'show' e)
3627-- @
37−--
38−-- Good sources of documentation for terminal programming are:
39−--
40−-- - <https://github.com/b4winckler/vim/blob/master/src/term.c>
41−--
42−-- - <http://invisible-island.net/xterm/ctlseqs/ctlseqs.html>
43−--
44−-- - <http://ulisse.elettra.trieste.it/services/doc/serial/config.html>
45−--
46−-- - <http://www.leonerd.org.uk/hacks/hints/xterm-8bit.html>
47−--
48−-- - <http://www.unixwiz.net/techtips/termios-vmin-vtime.html>
49−--
50−-- - <http://vt100.net/docs/vt100-ug/chapter3.html vt100 control sequences>
5128module Graphics.Vty
5229 ( Vty(..)
5330 , mkVty
31+ , Mode(..)
5432 , module Graphics.Vty.Config
5533 , module Graphics.Vty.Input
5634 , module Graphics.Vty.Output
@@ -58,7 +36,6 @@ module Graphics.Vty
5836 , module Graphics.Vty.Picture
5937 , module Graphics.Vty.Image
6038 , module Graphics.Vty.Attributes
61− , Mode(..)
6239 )
6340where
6441
@@ -75,54 +52,52 @@ import Control.Concurrent.STM
7552import Data.IORef
7653import Data.Monoid
7754
78−-- | The main object. At most one should be created.
55+-- | A Vty value represents a handle to the Vty library that the
56+-- application must create in order to use Vty.
7957--
8058-- The use of Vty typically follows this process:
8159--
82−-- 0. initialize vty
60+-- 1. Initialize vty
8361--
84−-- 1. use the update equation of Vty to display a picture
62+-- 2. Use 'update' to display a picture.
8563--
86−-- 2. repeat
64+-- 3. Use 'nextEvent' to get the next input event.
8765--
88−-- 3. shutdown vty.
66+-- 4. Depending on the event, go to 2 or 5.
8967--
90−-- An alternative to tracking the Vty instance is to use 'withVty' in
91−-- "Graphics.Vty.Inline.Unsafe".
68+-- 5. Shutdown vty.
9269--
93−-- This does not assure any thread safety. In theory, as long as an
94−-- update action is not executed when another update action is already
95−-- then it's safe to call this on multiple threads.
70+-- Operations on Vty handles are not thread-safe.
9671data Vty = Vty
97− { -- | Outputs the given Picture. Equivalent to 'outputPicture'
98− -- applied to a display context implicitly managed by Vty. The
99− -- managed display context is reset on resize.
72+ { -- | Outputs the given 'Picture'.
10073 update :: Picture -> IO ()
101− -- | Get one Event object, blocking if necessary. This will
102− -- refresh the terminal if the event is a 'EvResize'.
74+ -- | Get one 'Event' object, blocking if none are available. This
75+ -- will refresh the terminal if the event is a 'EvResize'.
10376 , nextEvent :: IO Event
104− -- | The input interface. See 'Input'
77+ -- | The input interface. See 'Input'.
10578 , inputIface :: Input
106− -- | The output interface. See 'Output'
79+ -- | The output interface. See 'Output'.
10780 , outputIface :: Output
10881 -- | Refresh the display. 'nextEvent' will refresh the display if
109− -- a resize occurs. If other programs output to the terminal and
110− -- mess up the display then the application might want to force a
111− -- refresh.
82+ -- a resize occurs, but this can be used to refresh the display
83+ -- explicitly. If other programs output to the terminal and mess
84+ -- up the display then the application might want to force a
85+ -- refresh using this function.
11286 , refresh :: IO ()
113− -- | Clean up after vty.
114− -- The above methods will throw an exception if executed after
115− -- this is executed.
87+ -- | Clean up after vty. A call to this function is necessary to
88+ -- cleanly restore the terminal state before application exit. The
89+ -- above methods will throw an exception if executed after this is
90+ -- executed.
11691 , shutdown :: IO ()
11792 }
11893
119−-- | Set up the state object for using vty. At most one state object
120−-- should be created at a time for a given terminal device.
94+-- | Create a Vty handle. At most one handle should be created at a time
95+-- for a given terminal device.
12196--
122−-- The specified config is added to the 'userConfig'. With the
123−-- 'userConfig' taking precedence. See "Graphics.Vty.Config"
97+-- The specified configuration is added to the 'userConfig' with the
98+-- 'userConfig' taking precedence. See "Graphics.Vty.Config".
12499--
125−-- For most applications @mkVty def@ is sufficient.
100+-- For most applications @mkVty defaultConfig@ is sufficient.
126101mkVty :: Config -> IO Vty
127102mkVty appConfig = do
128103 config <- (<> appConfig) <$> userConfig