@@ -1,21 +1,14 @@
1−-- | Vty supports input and output to terminal devices.
1+-- | Vty provides interfaces for both terminal input and terminal
3−-- - Input to the terminal is provided to the app as a sequence of
4+-- - Input to the terminal is provided to the Vty application as a
4−-- 'Event's.
5+-- sequence of 'Event's.
7+-- - Output is provided to Vty by the application in the form of a
6−-- - The output is defined by a 'Picture'. Which is one or more layers
8+-- 'Picture'. A 'Picture' is one or more layers of 'Image's.
7−-- of 'Image's.
9+-- 'Image' values can be built by the various constructors in
8−--
10+-- "Graphics.Vty.Image". Output can be syled using 'Attr' (attribute)
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.
13−-- - The constructors in "Graphics.Vty.Image.Internal" should not
16−-- - 'Image's can be styled using 'Attr'. See "Graphics.Vty.Attributes".
11+-- values in the "Graphics.Vty.Attributes" module.
18−-- See the vty-examples package for a number of examples.
21-- import "Graphics.Vty"
14-- import "Graphics.Vty"
@@ -23,10 +16,8 @@
23-- main = do
16-- main = do
24-- cfg <- 'standardIOConfig'
17-- cfg <- 'standardIOConfig'
25-- vty <- 'mkVty' cfg
18-- vty <- 'mkVty' cfg
26−-- let line0 = 'string' ('defAttr' ` 'withForeColor' ` 'green')
19+-- let line0 = 'string' ('defAttr' ` 'withForeColor' ` 'green') \"first line\"
28−-- line1 = 'string' ('defAttr' ` 'withBackColor' ` 'blue')
20+-- line1 = 'string' ('defAttr' ` 'withBackColor' ` 'blue') \"second line\"
30-- img = line0 '<->' line1
21-- img = line0 '<->' line1
31-- pic = 'picForImage' img
22-- pic = 'picForImage' img
32-- 'update' vty pic
23-- 'update' vty pic
@@ -34,23 +25,10 @@
34-- 'shutdown' vty
25-- 'shutdown' vty
35-- 'print' (\"Last event was: \" '++' 'show' e)
26-- 'print' (\"Last event was: \" '++' 'show' e)
38−-- Good sources of documentation for terminal programming are:
40−-- - <https://github.com/b4winckler/vim/blob/master/src/term.c>
42−-- - <http://invisible-island.net/xterm/ctlseqs/ctlseqs.html>
44−-- - <http://ulisse.elettra.trieste.it/services/doc/serial/config.html>
46−-- - <http://www.leonerd.org.uk/hacks/hints/xterm-8bit.html>
48−-- - <http://www.unixwiz.net/techtips/termios-vmin-vtime.html>
50−-- - <http://vt100.net/docs/vt100-ug/chapter3.html vt100 control sequences>
51module Graphics.Vty
28module Graphics.Vty
54 , module Graphics.Vty.Config
32 , module Graphics.Vty.Config
55 , module Graphics.Vty.Input
33 , module Graphics.Vty.Input
56 , module Graphics.Vty.Output
34 , module Graphics.Vty.Output
@@ -58,7 +36,6 @@ module Graphics.Vty
58 , module Graphics.Vty.Picture
36 , module Graphics.Vty.Picture
59 , module Graphics.Vty.Image
37 , module Graphics.Vty.Image
60 , module Graphics.Vty.Attributes
38 , module Graphics.Vty.Attributes
@@ -75,54 +52,52 @@ import Control.Concurrent.STM
75import Data.IORef
52import Data.IORef
76import Data.Monoid
53import Data.Monoid
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.
80-- The use of Vty typically follows this process:
58-- The use of Vty typically follows this process:
82−-- 0. initialize vty
60+-- 1. Initialize vty
84−-- 1. use the update equation of Vty to display a picture
62+-- 2. Use 'update' to display a picture.
86−-- 2. repeat
64+-- 3. Use 'nextEvent' to get the next input event.
88−-- 3. shutdown vty.
66+-- 4. Depending on the event, go to 2 or 5.
90−-- An alternative to tracking the Vty instance is to use 'withVty' in
68+-- 5. Shutdown vty.
91−-- "Graphics.Vty.Inline.Unsafe".
93−-- This does not assure any thread safety. In theory, as long as an
70+-- Operations on Vty handles are not thread-safe.
94−-- update action is not executed when another update action is already
95−-- then it's safe to call this on multiple threads.
96data Vty = Vty
71data Vty = Vty
97− { -- | Outputs the given Picture. Equivalent to 'outputPicture'
72+ { -- | Outputs the given 'Picture'.
98− -- applied to a display context implicitly managed by Vty. The
99− -- managed display context is reset on resize.
100 update :: Picture -> IO ()
73 update :: Picture -> IO ()
101− -- | Get one Event object, blocking if necessary. This will
74+ -- | Get one 'Event' object, blocking if none are available. This
102− -- refresh the terminal if the event is a 'EvResize'.
75+ -- will refresh the terminal if the event is a 'EvResize'.
103 , nextEvent :: IO Event
76 , nextEvent :: IO Event
104− -- | The input interface. See 'Input'
77+ -- | The input interface. See 'Input'.
105 , inputIface :: Input
78 , inputIface :: Input
106− -- | The output interface. See 'Output'
79+ -- | The output interface. See 'Output'.
107 , outputIface :: Output
80 , outputIface :: Output
108 -- | Refresh the display. 'nextEvent' will refresh the display if
81 -- | Refresh the display. 'nextEvent' will refresh the display if
82+ -- a resize occurs, but this can be used to refresh the display
109− -- a resize occurs. If other programs output to the terminal and
83+ -- explicitly. If other programs output to the terminal and mess
110− -- mess up the display then the application might want to force a
84+ -- up the display then the application might want to force a
111− -- refresh.
85+ -- refresh using this function.
112 , refresh :: IO ()
86 , refresh :: IO ()
113− -- | Clean up after vty.
87+ -- | Clean up after vty. A call to this function is necessary to
88+ -- cleanly restore the terminal state before application exit. The
114− -- The above methods will throw an exception if executed after
89+ -- above methods will throw an exception if executed after this is
115− -- this is executed.
90+ -- executed.
116 , shutdown :: IO ()
91 , shutdown :: IO ()
119−-- | Set up the state object for using vty. At most one state object
94+-- | Create a Vty handle. At most one handle should be created at a time
120−-- should be created at a time for a given terminal device.
95+-- for a given terminal device.
122−-- The specified config is added to the 'userConfig'. With the
97+-- The specified configuration is added to the 'userConfig' with the
123−-- 'userConfig' taking precedence. See "Graphics.Vty.Config"
98+-- 'userConfig' taking precedence. See "Graphics.Vty.Config".
125−-- For most applications @mkVty def@ is sufficient.
100+-- For most applications @mkVty defaultConfig@ is sufficient.
126mkVty :: Config -> IO Vty
101mkVty :: Config -> IO Vty
127mkVty appConfig = do
102mkVty appConfig = do
128 config <- (<> appConfig) <$> userConfig
103 config <- (<> appConfig) <$> userConfig