git.iko.soy/vty
on master help sign in
documentation fixes
commit41c42dffc49e71d93f9a29011846b3f94d8ba087 authorCorey O'Connor <corey@ooyala.com> dateFri 20 Dec 2013, 10:51 (13 years ago) parent4e45d7c
6 files changed+52−31
compare with master
unifiedsplit
src/Graphics/Vty.hs+15−4 src/Graphics/Vty/Image/Internal.hs+16−7 src/Graphics/Vty/Input.hs+1−3 src/Graphics/Vty/Output.hs+9−11 src/Graphics/Vty/Picture.hs+10−5 vty.cabal+1−1
src/Graphics/Vty.hs+15−4
@@ -1,15 +1,26 @@
1−-- | Vty supports input and output to terminal devices. The input is provides as a sequence of
2−-- 'Event's. The output is defined by a 'Picture'. Which is one or more layers of 'Image's.
3−--
4−-- - References
1+-- | Vty supports input and output to terminal devices.
2+--
3+-- - The input is provides as a sequence of 'Event's.
4+--
5+-- - The output is defined by a 'Picture'. Which is one or more layers of 'Image's.
6+-- The constructors in "Graphics.Vty.Image.Internal" should not be used directly. The module
7+-- "Graphics.Vty.Image" provides a number of constructor equations that will build correct
8+-- 'Image' values. See 'string', '<|>', and '<->' for starters.
59--
10+-- - 'Image's can be styled using 'Attr'. See "Graphics.Vty.Attributes".
11+--
612-- Good sources of documentation for terminal programming are:
713--
814-- - <https://github.com/b4winckler/vim/blob/master/src/term.c>
15+--
916-- - <http://invisible-island.net/xterm/ctlseqs/ctlseqs.html>
17+--
1018-- - <http://ulisse.elettra.trieste.it/services/doc/serial/config.html>
19+--
1120-- - <http://www.leonerd.org.uk/hacks/hints/xterm-8bit.html>
21+--
1222-- - <http://www.unixwiz.net/techtips/termios-vmin-vtime.html>
23+--
1324-- - <<http://vt100.net/docs/vt100-ug/chapter3.html vt100 control sequences>
1425module Graphics.Vty ( Vty(..)
1526 , mkVty
src/Graphics/Vty/Image/Internal.hs+16−7
@@ -1,4 +1,5 @@
11{-# LANGUAGE NamedFieldPuns #-}
2+{-# OPTIONS_HADDOCK hide #-}
23module Graphics.Vty.Image.Internal where
34
45import Graphics.Vty.Attributes
@@ -37,21 +38,29 @@ clip_text txt left_skip right_clip =
3738 clip_for_char_width _ _ _ = error "clip_for_char_width applied to undefined"
3839 in txt''
3940
40−-- | An image in VTY is
41+-- | This is the internal representation of Images. Use the constructors in "Graphics.Vty.Image" to
42+-- create instances.
4143--
42−-- * a horizontal line of characters with a single attribute.
43−-- * a fill of the picture's background. (background_fill)
44−-- * a horizontal and vertical crops from both directions.
45−-- * horizontal and vertical combinations
44+-- Images are:
45+--
46+-- * a horizontal span of text
47+--
48+-- * a horizontal or vertical join of two images
49+--
50+-- * a two dimensional fill of the 'Picture's background character
51+--
52+-- * a cropped image
53+--
54+-- * an empty image of no size or content.
4655data Image =
4756 -- | A horizontal text span is always >= 1 column and has a row height of 1.
4857 HorizText
4958 { attr :: Attr
5059 -- | The text to display. The display width of the text is always output_width.
5160 , display_text :: DisplayText
52− -- | The number of display columns for the text.
61+ -- | The number of display columns for the text. Always > 0.
5362 , output_width :: Int
54− -- | the number of characters in the text.
63+ -- | the number of characters in the text. Always > 0.
5564 , char_width :: Int
5665 }
5766 -- | A horizontal join can be constructed between any two images. However a HorizJoin instance is
src/Graphics/Vty/Input.hs+1−3
@@ -1,6 +1,4 @@
1−-- Copyright 2009-2010 Corey O'Connor
2−--
3−-- Right, I'm mostly guessing on these details. So, as far as I can figure:
1+-- | Right, I'm mostly guessing on these details. So, as far as I can figure:
42--
53-- There are two input modes:
64-- 1. 7 bit
src/Graphics/Vty/Output.hs+9−11
@@ -7,24 +7,22 @@
77-- 1. "Graphics.Vty.Output": This instantiates an abtract interface to the terminal interface based
88-- on the TERM and COLORTERM environment variables.
99--
10−-- 2. Graphics.Vty.Output.Interface: Defines the generic interface all terminals need to implement.
10+-- 2. "Graphics.Vty.Output.Interface": Defines the generic interface all terminals need to implement.
1111--
12−-- 3. Graphics.Vty.Output.TerminfoBased: Defines a terminal instance that uses terminfo for all
12+-- 3. "Graphics.Vty.Output.TerminfoBased": Defines a terminal instance that uses terminfo for all
1313-- control strings. No attempt is made to change the character set to UTF-8 for these terminals.
1414-- I don't know a way to reliably determine if that is required or how to do so.
1515--
16−-- 4. Graphics.Vty.Output.XTermColor: This module contains an interface suitable for xterm-like
16+-- 4. "Graphics.Vty.Output.XTermColor": This module contains an interface suitable for xterm-like
1717-- terminals. These are the terminals where TERM == xterm. This does use terminfo for as many
1818-- control codes as possible.
19−--
20−-- Copyright 2009-2010 Corey O'Connor
2119module Graphics.Vty.Output ( module Graphics.Vty.Output
22− , Output(..) -- \todo hide constructors
23− , AssumedState(..)
24− , DisplayContext(..) -- \todo hide constructors
25− , output_picture
26− , display_context
27− )
20+ , Output(..) -- \todo hide constructors
21+ , AssumedState(..)
22+ , DisplayContext(..) -- \todo hide constructors
23+ , output_picture
24+ , display_context
25+ )
2826 where
2927
3028
src/Graphics/Vty/Picture.hs+10−5
@@ -14,6 +14,7 @@ import Graphics.Vty.Image
1414import Control.DeepSeq
1515
1616-- | The type of images to be displayed using 'update'.
17+--
1718-- Can be constructed directly or using `pic_for_image`. Which provides an initial instance with
1819-- reasonable defaults for pic_cursor and pic_background.
1920data Picture = Picture
@@ -28,12 +29,15 @@ instance Show Picture where
2829instance NFData Picture where
2930 rnf (Picture c l b) = c `deepseq` l `deepseq` b `deepseq` ()
3031
32+-- | a picture with no cursor, background or image layers
3133empty_picture :: Picture
3234empty_picture = Picture NoCursor [] ClearBackground
3335
36+-- | The given 'Image' is added as the top layer of the 'Picture'
3437add_to_top :: Picture -> Image -> Picture
3538add_to_top p i = p {pic_layers = i : pic_layers p}
3639
40+-- | The given 'Image' is added as the bottom layer of the 'Picture'
3741add_to_bottom :: Picture -> Image -> Picture
3842add_to_bottom p i = p {pic_layers = pic_layers p ++ [i]}
3943
@@ -48,7 +52,7 @@ pic_for_image i = Picture
4852
4953-- | Create a picture for display with the given layers. Ordered top to bottom.
5054--
51−-- The first image is the top layer.
55+-- The first 'Image' is the top layer.
5256pic_for_layers :: [Image] -> Picture
5357pic_for_layers is = Picture
5458 { pic_cursor = NoCursor
@@ -72,10 +76,11 @@ instance NFData Cursor where
7276 rnf NoCursor = ()
7377 rnf (Cursor w h) = w `seq` h `seq` ()
7478
75−-- | Unspecified regions are filled with the picture's background pattern. The background pattern
76−-- can specify a character and a display attribute. If the display attribute used previously should
77−-- be used for a background fill then use `current_attr` for the background attribute. This is the
78−-- default background display attribute.
79+-- | A 'Picture' has a background pattern. The background is either ClearBackground. Which shows the
80+-- layer below or is blank if the bottom layer. Or the background pattern is a character and a
81+-- display attribute. If the display attribute used previously should be used for a background fill
82+-- then use `current_attr` for the background attribute. This is the default background display
83+-- attribute.
7984--
8085-- \todo The current attribute is always set to the default attributes at the start of updating the
8186-- screen to a picture.
vty.cabal+1−1
@@ -34,6 +34,7 @@ data-files: README.md,
3434 AUTHORS,
3535 CHANGELOG,
3636 LICENSE
37+tested-with: ghc >= 7.6.2
3738
3839library
3940 default-language: Haskell2010
@@ -105,7 +106,6 @@ library
105106 ghc-prof-options: -O2 -funbox-strict-fields -threaded -caf-all -Wall -fspec-constr -fspec-constr-count=10
106107
107108 cc-options: -O2
108− tested-with: ghc >= 7.6.2
109109
110110test-suite verify-attribute-ops
111111 default-language: Haskell2010