@@ -2,35 +2,35 @@
22{-# LANGUAGE BangPatterns #-}
33{-# LANGUAGE NamedFieldPuns #-}
44{-# LANGUAGE DisambiguateRecordFields #-}
5+-- | A Vty program makes 'Picture's from 'Image's. This module provides
6+-- the core constructors for creating, combining, and modifying
7+-- 'Image's.
58module Graphics.Vty.Image
6− ( DisplayText
7− , DisplayRegion
8− , regionWidth
9− , regionHeight
10− , Image
9+ (
10+ -- * Images
11+ Image
1112 , imageWidth
1213 , imageHeight
13− , horizJoin
14− , (<|>)
15− , vertJoin
16− , (<->)
17− , horizCat
18− , vertCat
19− , backgroundFill
20− , text
21− , text'
14+ -- * Image constructors
15+ , emptyImage
2216 , char
2317 , string
2418 , iso10646String
2519 , utf8String
20+ , text
21+ , text'
22+ , backgroundFill
2623 , utf8Bytestring
2724 , utf8Bytestring'
2825 , charFill
29− , emptyImage
30− , safeWcwidth
31− , safeWcswidth
32− , wcwidth
33− , wcswidth
26+ -- * Combinators
27+ , horizJoin
28+ , (<|>)
29+ , vertJoin
30+ , (<->)
31+ , horizCat
32+ , vertCat
33+ -- * Image modifications
3434 , crop
3535 , cropRight
3636 , cropLeft
@@ -43,6 +43,16 @@ module Graphics.Vty.Image
4343 , translate
4444 , translateX
4545 , translateY
46+ -- * Character width functions
47+ , safeWcwidth
48+ , safeWcswidth
49+ , wcwidth
50+ , wcswidth
51+ -- * Display Regions
52+ , DisplayText
53+ , DisplayRegion
54+ , regionWidth
55+ , regionHeight
4656 )
4757where
4858
@@ -58,7 +68,7 @@ import qualified Data.Text.Lazy as TL
5868import qualified Data.Text.Lazy.Encoding as TL
5969import Data.Word
6070
61−-- | Named alias for a Int pair
71+-- | A region of the display (first width, then height)
6272type DisplayRegion = (Int,Int)
6373
6474regionWidth :: DisplayRegion -> Int
@@ -70,57 +80,62 @@ regionHeight = snd
7080infixr 5 <|>
7181infixr 4 <->
7282
73−-- | An area of the picture's bacground (See Background) of w columns
74−-- and h rows.
75−backgroundFill :: Int -> Int -> Image
83+-- | An area of the picture's background (See 'Background').
84+backgroundFill :: Int
85+ -- ^ Fill width in columns
86+ -> Int
87+ -- ^ Fill height in rows
88+ -> Image
7689backgroundFill w h
7790 | w == 0 = EmptyImage
7891 | h == 0 = EmptyImage
7992 | otherwise = BGFill w h
8093
81−-- | Combines two images horizontally. Alias for horizJoin
94+-- | Combines two images horizontally. This is an alias for 'horizJoin'.
8295--
8396-- infixr 5
8497(<|>) :: Image -> Image -> Image
8598(<|>) = horizJoin
8699
87−-- | Combines two images vertically. Alias for vertJoin
100+-- | Combines two images vertically. This is an alias for 'vertJoin'.
88101--
89102-- infixr 4
90103(<->) :: Image -> Image -> Image
91104(<->) = vertJoin
92105
93−-- | Compose any number of images horizontally.
106+-- | Compose any number of images together horizontally, with the first
107+-- in the list being leftmost.
94108horizCat :: [Image] -> Image
95109horizCat = foldr horizJoin EmptyImage
96110
97−-- | Compose any number of images vertically.
111+-- | Compose any number of images vertically, with the first in the list
112+-- being topmost.
98113vertCat :: [Image] -> Image
99114vertCat = foldr vertJoin EmptyImage
100115
101−-- | A Data.Text.Lazy value
116+-- | Make an 'Image' from a lazy text value.
102117text :: Attr -> TL.Text -> Image
103118text a txt = let displayWidth = safeWcswidth (TL.unpack txt)
104119 in HorizText a txt displayWidth (fromIntegral $! TL.length txt)
105120
106−-- | A Data.Text value
121+-- | Make an 'Image' from a text value.
107122text' :: Attr -> T.Text -> Image
108123text' a txt = let displayWidth = safeWcswidth (T.unpack txt)
109124 in HorizText a (TL.fromStrict txt) displayWidth (T.length txt)
110125
111−-- | An image of a single character. This is a standard Haskell 31-bit
112−-- character assumed to be in the ISO-10646 encoding.
126+-- | Make an image from a single character. This is a standard Haskell
127+-- 31-bit character assumed to be in the ISO-10646 encoding.
113128char :: Attr -> Char -> Image
114129char a c =
115130 let displayWidth = safeWcwidth c
116131 in HorizText a (TL.singleton c) displayWidth 1
117132
118−-- | A string of characters layed out on a single row with the same
119−-- display attribute. The string is assumed to be a sequence of
120−-- ISO-10646 characters.
133+-- | Make an image from a string of characters layed out on a single
134+-- row with the same display attribute. The string is assumed to be a
135+-- sequence of ISO-10646 characters.
121136--
122137-- Note: depending on how the Haskell compiler represents string
123−-- literals a string literal in a UTF-8 encoded source file, for
138+-- literals, a string literal in a UTF-8 encoded source file, for
124139-- example, may be represented as a ISO-10646 string. That is, I think,
125140-- the case with GHC 6.10. This means, for the most part, you don't need
126141-- to worry about the encoding format when outputting string literals.
@@ -130,9 +145,11 @@ iso10646String a str =
130145 let displayWidth = safeWcswidth str
131146 in HorizText a (TL.pack str) displayWidth (length str)
132147
133−-- | Alias for iso10646String. Since the usual case is that a literal
134−-- string like "foo" is represented internally as a list of ISO 10646 31
135−-- bit characters.
148+-- | Make an 'Image' from a 'String'.
149+--
150+-- This is an alias for iso10646String since the usual case is that a
151+-- literal string like "foo" is represented internally as a list of ISO
152+-- 10646 31 bit characters.
136153--
137154-- Note: Keep in mind that GHC will compile source encoded as UTF-8
138155-- but the literal strings, while UTF-8 encoded in the source, will be
@@ -140,22 +157,30 @@ iso10646String a str =
140157string :: Attr -> String -> Image
141158string = iso10646String
142159
143−-- | A string of characters layed out on a single row. The input is
144−-- assumed to be the bytes for UTF-8 encoded text.
160+-- | Make an 'Image' from a string of characters layed out on a single
161+-- row. The input is assumed to be the bytes for UTF-8 encoded text.
145162utf8String :: Attr -> [Word8] -> Image
146163utf8String a bytes = utf8Bytestring a (BL.pack bytes)
147164
148−-- | Renders a UTF-8 encoded lazy bytestring.
165+-- | Make an 'Image' from a UTF-8 encoded lazy bytestring.
149166utf8Bytestring :: Attr -> BL.ByteString -> Image
150167utf8Bytestring a bs = text a (TL.decodeUtf8 bs)
151168
152−-- | Renders a UTF-8 encoded strict bytestring.
169+-- | Make an 'Image' from a UTF-8 encoded lazy bytestring.
153170utf8Bytestring' :: Attr -> B.ByteString -> Image
154171utf8Bytestring' a bs = text' a (T.decodeUtf8 bs)
155172
156−-- | Creates a fill of the specified character. The dimensions are in
157−-- number of characters wide and number of rows high.
158−charFill :: Integral d => Attr -> Char -> d -> d -> Image
173+-- | Make an image filling a region with the specified character.
174+charFill :: Integral d
175+ => Attr
176+ -- ^ The attribute to use.
177+ -> Char
178+ -- ^ The character to use in filling the region.
179+ -> d
180+ -- ^ The region width.
181+ -> d
182+ -- ^ The region height.
183+ -> Image
159184charFill _a _c 0 _h = EmptyImage
160185charFill _a _c _w 0 = EmptyImage
161186charFill a c w h =
@@ -166,14 +191,23 @@ charFill a c w h =
166191 charWidth = fromIntegral w
167192
168193-- | The empty image. Useful for fold combinators. These occupy no space
169−-- nor define any display attributes.
194+-- and do not affect display attributes.
170195emptyImage :: Image
171196emptyImage = EmptyImage
172197
173198-- | Pad the given image. This adds background character fills to the
174−-- left, top, right, bottom. The pad values are how many display columns
175−-- or rows to add.
176−pad :: Int -> Int -> Int -> Int -> Image -> Image
199+-- left, top, right, bottom.
200+pad :: Int
201+ -- ^ How much padding to add to the left side of the image.
202+ -> Int
203+ -- ^ How much padding to add to the top of the image.
204+ -> Int
205+ -- ^ How much padding to add to the right side of the image.
206+ -> Int
207+ -- ^ How much padding to add to the bottom of the image.
208+ -> Image
209+ -- ^ The image to pad.
210+ -> Image
177211pad 0 0 0 0 i = i
178212pad inL inT inR inB inImage
179213 | inL < 0 || inT < 0 || inR < 0 || inB < 0 = error "cannot pad by negative amount"
@@ -194,22 +228,25 @@ pad inL inT inR inB inImage
194228 h = imageHeight i
195229
196230-- | Translates an image by padding or cropping the left and top.
197−-- First param is amount to translate left. Second param is amount to
198−-- translate top.
199231--
200−-- This can have an unexpected effect: Translating an image to less than
201−-- (0,0) then to greater than (0,0) will crop the image.
202−translate :: Int -> Int -> Image -> Image
232+-- If translation offsets are negative then the image is cropped.
233+translate :: Int
234+ -- ^ The horizontal translation offset (can be negative)
235+ -> Int
236+ -- ^ The vertical translation offset (can be negative)
237+ -> Image
238+ -- ^ The image to translate.
239+ -> Image
203240translate x y i = translateX x (translateY y i)
204241
205−-- | translates an image by padding or cropping the left
242+-- | Translates an image by padding or cropping its left side.
206243translateX :: Int -> Image -> Image
207244translateX x i
208245 | x < 0 = let s = abs x in CropLeft i s (imageWidth i - s) (imageHeight i)
209246 | x == 0 = i
210247 | otherwise = let h = imageHeight i in HorizJoin (BGFill x h) i (imageWidth i + x) h
211248
212−-- | translates an image by padding or cropping the top
249+-- | Translates an image by padding or cropping its top.
213250translateY :: Int -> Image -> Image
214251translateY y i
215252 | y < 0 = let s = abs y in CropTop i s (imageWidth i) (imageHeight i - s)
@@ -219,16 +256,22 @@ translateY y i
219256-- | Ensure an image is no larger than the provided size. If the image
220257-- is larger then crop the right or bottom.
221258--
222−-- This is transformed to a vertical crop from the bottom followed by
259+-- This is equivalent to a vertical crop from the bottom followed by
223260-- horizontal crop from the right.
224−crop :: Int -> Int -> Image -> Image
261+crop :: Int
262+ -- ^ Cropping width
263+ -> Int
264+ -- ^ Cropping height
265+ -> Image
266+ -- ^ The image to crop
267+ -> Image
225268crop 0 _ _ = EmptyImage
226269crop _ 0 _ = EmptyImage
227270crop w h i = cropBottom h (cropRight w i)
228271
229−-- | crop the display height. If the image is less than or equal in
230−-- height then this operation has no effect. Otherwise the image is
231−-- cropped from the bottom.
272+-- | Crop an image's height. If the image's height is less than or equal
273+-- to the specified height then this operation has no effect. Otherwise
274+-- the image is cropped from the bottom.
232275cropBottom :: Int -> Image -> Image
233276cropBottom 0 _ = EmptyImage
234277cropBottom h inI
@@ -243,8 +286,9 @@ cropBottom h inI
243286 | h >= imageHeight i = i
244287 | otherwise = CropBottom i (imageWidth i) h
245288
246−-- | ensure the image is no wider than the given width. If the image is
247−-- wider then crop the right side.
289+-- | Crop an image's width. If the image's width is less than or equal
290+-- to the specified width then this operation has no effect. Otherwise
291+-- the image is cropped from the right.
248292cropRight :: Int -> Image -> Image
249293cropRight 0 _ = EmptyImage
250294cropRight w inI
@@ -259,8 +303,9 @@ cropRight w inI
259303 | w >= imageWidth i = i
260304 | otherwise = CropRight i w (imageHeight i)
261305
262−-- | ensure the image is no wider than the given width. If the image is
263−-- wider then crop the left side.
306+-- | Crop an image's width. If the image's width is less than or equal
307+-- to the specified width then this operation has no effect. Otherwise
308+-- the image is cropped from the left.
264309cropLeft :: Int -> Image -> Image
265310cropLeft 0 _ = EmptyImage
266311cropLeft w inI
@@ -277,9 +322,9 @@ cropLeft w inI
277322 | imageWidth i <= w = i
278323 | otherwise = CropLeft i (imageWidth i - w) w (imageHeight i)
279324
280−-- | crop the display height. If the image is less than or equal in
281−-- height then this operation has no effect. Otherwise the image is
282−-- cropped from the top.
325+-- | Crop an image's height. If the image's height is less than or equal
326+-- to the specified height then this operation has no effect. Otherwise
327+-- the image is cropped from the top.
283328cropTop :: Int -> Image -> Image
284329cropTop 0 _ = EmptyImage
285330cropTop h inI
@@ -296,14 +341,14 @@ cropTop h inI
296341 | imageHeight i <= h = i
297342 | otherwise = CropTop i (imageHeight i - h) (imageWidth i) h
298343
299−-- | Generic resize. Pads and crops as required to assure the given
300−-- display width and height. This is biased to pad/crop the right and
301−-- bottom.
344+-- | Generic resize. Pads and crops are added to ensure that the
345+-- resulting image matches the specified dimensions. This is biased to
346+-- pad/crop the right and bottom.
302347resize :: Int -> Int -> Image -> Image
303348resize w h i = resizeHeight h (resizeWidth w i)
304349
305350-- | Resize the width. Pads and crops as required to assure the given
306−-- display width. This is biased to pad/crop the right.
351+-- display width. This is biased to pad/crop on the right.
307352resizeWidth :: Int -> Image -> Image
308353resizeWidth w i = case w `compare` imageWidth i of
309354 LT -> cropRight w i
@@ -311,7 +356,7 @@ resizeWidth w i = case w `compare` imageWidth i of
311356 GT -> i <|> BGFill (w - imageWidth i) (imageHeight i)
312357
313358-- | Resize the height. Pads and crops as required to assure the given
314−-- display height. This is biased to pad/crop the bottom.
359+-- display height. This is biased to pad/crop on the bottom.
315360resizeHeight :: Int -> Image -> Image
316361resizeHeight h i = case h `compare` imageHeight i of
317362 LT -> cropBottom h i