@@ -1,8 +1,7 @@
11{-# LANGUAGE BangPatterns #-}
2−-- | The 'Picture' data structure is representative of the final
3−-- terminal view.
4−--
5−-- A 'Picture' is a background paired with a layer of 'Image's.
2+-- A 'Picture' is a background paired with a set of 'Image' layers. The
3+-- 'Picture' data structure is representative of the final terminal
4+-- view.
65module Graphics.Vty.Picture
76 ( Picture(..)
87 , Cursor(..)
@@ -21,15 +20,17 @@ import Graphics.Vty.Attributes
2120
2221import Control.DeepSeq
2322
24−-- | The type of images to be displayed using 'update'.
23+-- | A Vty picture.
2524--
26−-- Can be constructed directly or using `picForImage`. Which provides
27−-- an initial instance with reasonable defaults for picCursor and
28−-- picBackground.
25+-- These can be constructed directly or using `picForImage`.
2926data Picture = Picture
3027 { picCursor :: Cursor
28+ -- ^ The picture's cursor.
3129 , picLayers :: [Image]
30+ -- ^ The picture's image layers (top-most first).
3231 , picBackground :: Background
32+ -- ^ The picture's background to be displayed in locations with no
33+ -- Image data.
3334 }
3435
3536instance Show Picture where
@@ -38,21 +39,21 @@ instance Show Picture where
3839instance NFData Picture where
3940 rnf (Picture c l b) = c `deepseq` l `deepseq` b `deepseq` ()
4041
41−-- | a picture with no cursor, background or image layers
42+-- | A picture with no cursor, background or image layers.
4243emptyPicture :: Picture
4344emptyPicture = Picture NoCursor [] ClearBackground
4445
45−-- | The given 'Image' is added as the top layer of the 'Picture'
46+-- | Add an 'Image' as the top-most layer of a 'Picture'.
4647addToTop :: Picture -> Image -> Picture
4748addToTop p i = p {picLayers = i : picLayers p}
4849
49−-- | The given 'Image' is added as the bottom layer of the 'Picture'
50+-- | Add an 'Image' as the bottom-most layer of a 'Picture'.
5051addToBottom :: Picture -> Image -> Picture
5152addToBottom p i = p {picLayers = picLayers p ++ [i]}
5253
53−-- | Create a picture for display for the given image. The picture
54−-- will not have a displayed cursor and no background pattern
55−-- (ClearBackground) will be used.
54+-- | Create a picture from the given image. The picture will not have a
55+-- displayed cursor and no background pattern (ClearBackground) will be
56+-- used.
5657picForImage :: Image -> Picture
5758picForImage i = Picture
5859 { picCursor = NoCursor
@@ -60,13 +61,10 @@ picForImage i = Picture
6061 , picBackground = ClearBackground
6162 }
6263
63−-- | Create a picture for display with the given layers. Ordered top to
64−-- bottom.
64+-- | Create a picture with the given layers, top-most first.
6565--
6666-- The picture will not have a displayed cursor and no background
67−-- apttern (ClearBackgroun) will be used.
68−--
69−-- The first 'Image' is the top layer.
67+-- pattern (ClearBackgroun) will be used.
7068picForLayers :: [Image] -> Picture
7169picForLayers is = Picture
7270 { picCursor = NoCursor
@@ -77,26 +75,28 @@ picForLayers is = Picture
7775-- | A picture can be configured either to not show the cursor or show
7876-- the cursor at the specified character position.
7977--
80−-- There is not a 1 to 1 map from character positions to a row and
81−-- column on the screen due to characters that take more than 1 column.
78+-- There is not a 1:1 map from character positions to a row and column
79+-- on the screen due to characters that take more than 1 column.
8280data Cursor =
83− -- | Hide the cursor
84− NoCursor
85− -- | Show the cursor at the given logical column accounting for
86− -- char width and row
81+ -- | Hide the cursor
82+ NoCursor
83+ -- | Show the cursor at the given logical column accounting for
84+ -- character width in the presence of multi-column characters.
8785 | Cursor !Int !Int
88− -- | Show the cursor at the given absolute terminal column and row
86+ -- | Show the cursor at the given absolute terminal column and row
8987 | AbsoluteCursor !Int !Int
9088
9189instance NFData Cursor where
9290 rnf c = c `seq` ()
9391
94−-- | A 'Picture' has a background pattern. The background is either
95−-- ClearBackground. Which shows the layer below or is blank if the
96−-- bottom layer. Or the background pattern is a character and a display
97−-- attribute. If the display attribute used previously should be used
98−-- for a background fill then use `currentAttr` for the background
99−-- attribute.
92+-- | A 'Picture' has a background pattern. The background is either:
93+--
94+-- * ClearBackground, which shows the layer below or is blank if the
95+-- bottom layer
96+-- * A character and a display attribute
97+--
98+-- If the display attribute used previously should be used for a
99+-- background fill then use `currentAttr` for the background attribute.
100100data Background
101101 = Background
102102 { backgroundChar :: Char
@@ -113,7 +113,10 @@ instance NFData Background where
113113 rnf (Background c a) = c `seq` a `seq` ()
114114 rnf ClearBackground = ()
115115
116−-- | Compatibility with applications that do not use more than a single
117−-- layer.
116+-- | Return the top-most 'Image' layer for a picture. This is unsafe for
117+-- 'Picture's without at least one layer.
118+--
119+-- This is provided for compatibility with applications that do not use
120+-- more than a single layer.
118121picImage :: Picture -> Image
119122picImage = head . picLayers