@@ -2,23 +2,7 @@
22{-# LANGUAGE BangPatterns #-}
33{-# LANGUAGE NamedFieldPuns #-}
44{-# LANGUAGE DisambiguateRecordFields #-}
5−{-# LANGUAGE MagicHash, UnboxedTuples #-}
65{-# OPTIONS_GHC -funbox-strict-fields #-}
7−{- A picutre in VTY defines
8− - * properties required to display the image. These are properties that effect the output image
9− - but are independent of position
10− - * A set of position-dependent text and attribute regions. The possible regions are
11− - * a point
12− - * a horizontal line of characters with a single attribute
13− - * a vertical line of a single character
14− - * a horizontal line of a single character.
15− - * a rectangle of a single character
16− -
17− -
18− -
19− - todo: Move to UTF-8 encoded bytestring streams?
20− -}
21−
226module Graphics.Vty.Image ( Image(..)
237 , image_width
248 , image_height
@@ -31,7 +15,7 @@ module Graphics.Vty.Image ( Image(..)
3115 , background_fill
3216 , char
3317 , string
34− , iso_10464_string
18+ , iso_10646_string
3519 , utf8_string
3620 , utf8_bytestring
3721 , char_fill
@@ -56,17 +40,34 @@ infixr 4 <->
5640
5741type StringSeq = Seq.Seq Char
5842
43+-- | An image in VTY defines:
44+--
45+-- * properties required to display the image. These are properties that effect the output image
46+-- but are independent of position
47+--
48+-- * A set of position-dependent text and attribute regions. The possible regions are:
49+--
50+-- * a point. ( char )
51+--
52+-- * a horizontal line of characters with a single attribute. (string, utf8_string,
53+-- utf8_bytestring )
54+--
55+-- * a fill of a single character. (char_fill)
56+--
57+-- * a fill of the picture's background. (background_fill)
58+--
59+-- todo: increase the number of encoded bytestring formats supported.
5960data Image =
60− -- | A horizontal text span is always >= 1 column and has a row height of 1.
61+ -- A horizontal text span is always >= 1 column and has a row height of 1.
6162 HorizText
6263 { attr :: !Attr
63− -- | All character data is stored as Char sequences with the ISO-10646 encoding.
64+ -- All character data is stored as Char sequences with the ISO-10646 encoding.
6465 , text :: StringSeq
65− -- | in columns
66+ -- in columns
6667 , output_width :: !Word -- >= 0
6768 , char_width :: !Word -- >= 1
6869 }
69− -- | A horizontal join can be constructed between any two images. However a HorizJoin instance is
70+ -- A horizontal join can be constructed between any two images. However a HorizJoin instance is
7071 -- required to be between two images of equal height. The horiz_join constructor adds blanks to
7172 -- the provided images that assure this is true for the HorizJoin value produced.
7273 | HorizJoin
@@ -75,7 +76,7 @@ data Image =
7576 , output_width :: !Word -- >= 1
7677 , output_height :: !Word -- >= 1
7778 }
78− -- | A veritical join can be constructed between any two images. However a VertJoin instance is
79+ -- A veritical join can be constructed between any two images. However a VertJoin instance is
7980 -- required to be between two images of equal width. The horiz_join constructor adds blanks to
8081 -- the provides images that assure this is true for the HorizJoin value produced.
8182 | VertJoin
@@ -84,7 +85,7 @@ data Image =
8485 , output_width :: !Word -- >= 1
8586 , output_height :: !Word -- >= 1
8687 }
87− -- | A background fill will be filled with the background pattern. The background pattern is
88+ -- A background fill will be filled with the background pattern. The background pattern is
8889 -- defined as a property of the Picture this Image is used to form.
8990 | BGFill
9091 { output_width :: !Word -- >= 1
@@ -173,14 +174,14 @@ vert_join i_0 i_1 w h
173174 w h
174175vert_join _ _ _ _ = error "vert_join applied to undefined values."
175176
176−-- | An area of the picture's bacground (See `Background`) of w columns and h rows.
177+-- | An area of the picture's bacground (See Background) of w columns and h rows.
177178background_fill :: Word -> Word -> Image
178179background_fill w h
179180 | w == 0 = IdImage
180181 | h == 0 = IdImage
181182 | otherwise = BGFill w h
182183
183−-- | Access the width of an Image.
184+-- | The width of an Image. This is the number display columns the image will occupy.
184185image_width :: Image -> Word
185186image_width HorizText { output_width = w } = w
186187image_width HorizJoin { output_width = w } = w
@@ -188,7 +189,7 @@ image_width VertJoin { output_width = w } = w
188189image_width BGFill { output_width = w } = w
189190image_width IdImage = 0
190191
191−-- | Access the height of an Image.
192+-- | The height of an Image. This is the number of display rows the image will occupy.
192193image_height :: Image -> Word
193194image_height HorizText {} = 1
194195image_height HorizJoin { output_height = r } = r
@@ -197,10 +198,10 @@ image_height BGFill { output_height = r } = r
197198image_height IdImage = 0
198199
199200-- | Combines two images side by side.
200−-- The result image will have a width equal to the sum of the two images width.
201−-- The height will equal the largest height of the two images
202−-- The area not defined in one image due to a height missmatch will be filled with the background
203−-- pattern.
201+--
202+-- The result image will have a width equal to the sum of the two images width. And the height will
203+-- equal the largest height of the two images. The area not defined in one image due to a height
204+-- missmatch will be filled with the background pattern.
204205(<|>) :: Image -> Image -> Image
205206
206207-- Two horizontal text spans with the same attributes can be merged.
@@ -257,24 +258,30 @@ vertcat :: [Image] -> Image
257258vertcat = vert_cat
258259
259260-- | an image of a single character. This is a standard Haskell 31-bit character assumed to be in
260−-- the ISO-10464 encoding.
261+-- the ISO-10646 encoding.
261262char :: Attr -> Char -> Image
262263char !a !c = HorizText a (Seq.singleton c) (safe_wcwidth c) 1
263264
264−-- | A string of characters layed out on a single row. The string is assumed to be a sequence of
265−-- ISO-10464 characters. Note: depending on how the Haskell compiler represents string literals a
266−-- string literal in a UTF-8 encoded source file, for example, may be represented as a ISO-10464
267−-- string. That is, I think, the case with GHC 6.10.
268−iso_10464_string :: Attr -> String -> Image
269−iso_10464_string !a !str = horiz_text a (Seq.fromList str) (safe_wcswidth str)
265+-- | A string of characters layed out on a single row with the same display attribute. The string is
266+-- assumed to be a sequence of ISO-10646 characters.
267+--
268+-- Note: depending on how the Haskell compiler represents string literals a string literal in a
269+-- UTF-8 encoded source file, for example, may be represented as a ISO-10646 string.
270+-- That is, I think, the case with GHC 6.10. This means, for the most part, you don't need to worry
271+-- about the encoding format when outputting string literals. Just provide the string literal
272+-- directly to iso_10646_string or string.
273+--
274+iso_10646_string :: Attr -> String -> Image
275+iso_10646_string !a !str = horiz_text a (Seq.fromList str) (safe_wcswidth str)
270276
271277-- | Alias for iso_10646_string. Since the usual case is that a literal string like "foo" is
272−-- represented internally as a list of ISO 10646 31 bit characters.
278+-- represented internally as a list of ISO 10646 31 bit characters.
279+--
273280-- Note: Keep in mind that GHC will compile source encoded as UTF-8 but the literal strings, while
274281-- UTF-8 encoded in the source, will be transcoded to a ISO 10646 31 bit characters runtime
275282-- representation.
276283string :: Attr -> String -> Image
277−string = iso_10464_string
284+string = iso_10646_string
278285
279286-- | A string of characters layed out on a single row. The string is assumed to be a sequence of
280287-- UTF-8 characters.
@@ -295,6 +302,10 @@ safe_wcswidth str = case wcswidth str of
295302utf8_bytestring :: Attr -> BS.ByteString -> Image
296303utf8_bytestring !a !bs = string a (UTF8.toString $ UTF8.fromRep bs)
297304
305+-- | creates a fill of the specified character. The dimensions are in number of characters wide and
306+-- number of rows high.
307+--
308+-- Unlike the Background fill character this character can have double column display width.
298309char_fill :: Enum d => Attr -> Char -> d -> d -> Image
299310char_fill !a !c w h =
300311 vert_cat $ replicate (fromEnum h) $ horiz_cat $ replicate (fromEnum w) $ char a c