-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A simple terminal access library -- -- vty is terminal GUI library in the niche of ncurses. It is intended to -- be easy to use, have no confusing corner cases, and good support for -- common terminal types. -- -- Included in the source distribution is a program -- test/interactive_terminal_test.hs that demonstrates the various -- features. -- -- If your terminal is not behaving as expected the results of the -- test/interactive_terminal_test.hs program should be sent to the Vty -- maintainter to aid in debugging the issue. -- -- Notable infelicities: Sometimes poor efficiency; Assumes UTF-8 -- character encoding support by the terminal; -- -- You can 'darcs get' it from http://code.haskell.org/vty/ -- -- © 2006-2007 Stefan O'Rear; BSD3 license. -- -- © 2008-2009 Corey O'Connor; BSD3 license. @package vty @version 4.0.0 module Graphics.Vty.DisplayRegion data DisplayRegion DisplayRegion :: !Word -> !Word -> DisplayRegion region_width :: DisplayRegion -> !Word region_height :: DisplayRegion -> !Word instance Show DisplayRegion instance Eq DisplayRegion module Graphics.Vty.Attributes -- | A display attribute defines the Color and Style of all the characters -- rendered after the attribute is applied. -- -- At most 256 colors, picked from a 240 and 16 color palette, are -- possible for the background and foreground. The 240 colors and 16 -- colors are points in different palettes. See Color for more -- information. data Attr Attr :: !MaybeDefault Style -> !MaybeDefault Color -> !MaybeDefault Color -> Attr style :: Attr -> !MaybeDefault Style fore_color :: Attr -> !MaybeDefault Color back_color :: Attr -> !MaybeDefault Color -- | Specifies the display attributes such that the final style and color -- values do not depend on the previously applied display attribute. The -- display attributes can still depend on the terminal's default colors -- (unfortunately). data FixedAttr FixedAttr :: !Style -> !Maybe Color -> !Maybe Color -> FixedAttr fixed_style :: FixedAttr -> !Style fixed_fore_color :: FixedAttr -> !Maybe Color fixed_back_color :: FixedAttr -> !Maybe Color -- | The style and color attributes can either be the terminal defaults. Or -- be equivalent to the previously applied style. Or be a specific value. data (Eq v) => MaybeDefault v Default :: MaybeDefault v KeepCurrent :: MaybeDefault v SetTo :: !v -> MaybeDefault v -- | Abstract data type representing a color. -- -- Currently the foreground and background color are specified as points -- in either a: -- -- -- -- The 8 ISO 6429 (ANSI) colors are as follows: -- -- 0. black -- -- 1. red -- -- 2. green -- -- 3. yellow -- -- 4. blue -- -- 5. magenta -- -- 6. cyan -- -- 7. white -- -- The mapping from points in the 240 color palette to colors actually -- displayable by the terminal depends on the number of colors the -- terminal claims to support. Which is usually determined by the -- terminfo colors property. If this property is not being -- accurately reported then the color reproduction will be incorrect. -- -- If the terminal reports <= 16 colors then the 240 color palette -- points are only mapped to the 8 color pallete. I'm not sure of the RGB -- points for the bright colors which is why they are not -- addressable via the 240 color palette. -- -- If the terminal reports > 16 colors then the 240 color palette -- points are mapped to the nearest points in a (color count - 16) -- subsampling of the 240 color palette. -- -- All of this assumes the terminals are behaving similarly to xterm and -- rxvt when handling colors. And that the individual colors have not -- been remapped by the user. There may be a way to verify this through -- terminfo but I don't know it. -- -- Seriously, terminal color support is INSANE. data Color ISOColor :: !Word8 -> Color Color240 :: !Word8 -> Color -- | Standard 8-color ANSI terminal color codes. red :: Color green :: Color yellow :: Color blue :: Color magenta :: Color cyan :: Color white :: Color black :: Color -- | Bright/Vivid variants of the standard 8-color ANSI bright_red :: Color bright_green :: Color bright_yellow :: Color bright_black :: Color bright_magenta :: Color bright_cyan :: Color bright_white :: Color bright_blue :: Color -- | Styles are represented as an 8 bit word. Each bit in the word is 1 if -- the style attribute assigned to that bit should be applied and 0 if -- the style attribute should not be applied. type Style = Word8 -- | The 6 possible style attributes: -- -- -- -- ( The invisible, protect, and altcharset display attributes some -- terminals support are not supported via VTY.) underline :: Style reverse_video :: Style blink :: Style dim :: Style bold :: Style standout :: Style default_style_mask :: Style style_mask :: Attr -> Word8 -- | true if the given Style value has the specified Style set. has_style :: Style -> Style -> Bool -- | Set the foreground color of an Attr. with_fore_color :: Attr -> Color -> Attr -- | Set the background color of an Attr. with_back_color :: Attr -> Color -> Attr -- | Add the given style attribute with_style :: Attr -> Style -> Attr -- | Sets the style, background color and foreground color to the default -- values for the terminal. There is no easy way to determine what the -- default background and foreground colors are. def_attr :: Attr -- | Keeps the style, background color and foreground color that was -- previously set. Used to override some part of the previous style. -- -- EG: current_style with_fore_color bright_magenta -- -- Would be the currently applied style (be it underline, bold, etc) but -- with the foreground color set to bright_magenta. current_attr :: Attr instance Eq Color instance Show Color instance (Eq v) => Eq (MaybeDefault v) instance (Eq v, Show v) => Show (MaybeDefault v) instance Eq FixedAttr instance Show FixedAttr instance Eq Attr instance Show Attr module Graphics.Vty.Picture -- | The type of images to be displayed using update. Can be constructed -- directly or using pic_for_image. Which provides an initial -- instance with reasonable defaults for pic_cursor and pic_background. data Picture Picture :: Cursor -> Image -> Background -> Picture pic_cursor :: Picture -> Cursor pic_image :: Picture -> Image pic_background :: Picture -> Background -- | Create a picture for display for the given image. The picture will not -- have a displayed cursor and the background display attribute will be -- current_attr. pic_for_image :: Image -> Picture -- | A picture can be configured either to not show the cursor or show the -- cursor at the specified character position. -- -- There is not a 1 to 1 map from character positions to a row and column -- on the screen due to characters that take more than 1 column. -- -- todo: The Cursor can be given a (character,row) offset outside of the -- visible bounds of the output region. In this case the cursor will not -- be shown. data Cursor NoCursor :: Cursor Cursor :: Word -> Word -> Cursor -- | Unspecified regions are filled with the picture's background pattern. -- The background pattern can specify a character and a display -- attribute. If the display attribute used previously should be used for -- a background fill then use current_attr for the background -- attribute. This is the default background display attribute. -- -- (tofix) The current attribute is always set to the default attributes -- at the start of updating the screen to a picture. -- -- (tofix) The background character *must* occupy a single column and no -- more. data Background Background :: Char -> Attr -> Background background_char :: Background -> Char background_attr :: Background -> Attr -- | An image in VTY defines: -- -- -- -- todo: increase the number of encoded bytestring formats supported. data Image -- | The width of an Image. This is the number display columns the image -- will occupy. image_width :: Image -> Word -- | The height of an Image. This is the number of display rows the image -- will occupy. image_height :: Image -> Word -- | Combines two images side by side. -- -- The result image will have a width equal to the sum of the two images -- width. And the height will equal the largest height of the two images. -- The area not defined in one image due to a height missmatch will be -- filled with the background pattern. (<|>) :: Image -> Image -> Image -- | Combines two images vertically. The result image will have a height -- equal to the sum of the heights of both images. The width will equal -- the largest width of the two images. The area not defined in one image -- due to a width missmatch will be filled with the background pattern. (<->) :: Image -> Image -> Image -- | Compose any number of images horizontally. horiz_cat :: [Image] -> Image -- | Compose any number of images vertically. vert_cat :: [Image] -> Image -- | An area of the picture's bacground (See Background) of w columns and h -- rows. background_fill :: Word -> Word -> Image -- | an image of a single character. This is a standard Haskell 31-bit -- character assumed to be in the ISO-10464 encoding. char :: Attr -> Char -> Image -- | Alias for iso_10646_string. Since the usual case is that a literal -- string like foo is represented internally as a list of ISO -- 10646 31 bit characters. -- -- Note: Keep in mind that GHC will compile source encoded as UTF-8 but -- the literal strings, while UTF-8 encoded in the source, will be -- transcoded to a ISO 10646 31 bit characters runtime representation. string :: Attr -> String -> Image -- | A string of characters layed out on a single row with the same display -- attribute. The string is assumed to be a sequence of ISO-10464 -- characters. -- -- Note: depending on how the Haskell compiler represents string literals -- a string literal in a UTF-8 encoded source file, for example, may be -- represented as a ISO-10464 string. That is, I think, the case with GHC -- 6.10. This means, for the most part, you don't need to worry about the -- encoding format when outputting string literals. Just provide the -- string literal directly to iso_10464_string or string. iso_10464_string :: Attr -> String -> Image -- | A string of characters layed out on a single row. The string is -- assumed to be a sequence of UTF-8 characters. utf8_string :: Attr -> [Word8] -> Image -- | Renders a UTF-8 encoded bytestring. utf8_bytestring :: Attr -> ByteString -> Image -- | creates a fill of the specified character. The dimensions are in -- number of characters wide and number of rows high. -- -- Unlike the Background fill character this character can have double -- column display width. char_fill :: (Enum d) => Attr -> Char -> d -> d -> Image module Graphics.Vty.LLInput -- | Representations of non-modifier keys. data Key KEsc :: Key KFun :: Int -> Key KBackTab :: Key KPrtScr :: Key KPause :: Key KASCII :: Char -> Key KBS :: Key KIns :: Key KHome :: Key KPageUp :: Key KDel :: Key KEnd :: Key KPageDown :: Key KNP5 :: Key KUp :: Key KMenu :: Key KLeft :: Key KDown :: Key KRight :: Key KEnter :: Key -- | Modifier keys. Key codes are interpreted such that users are more -- likely to have Meta than Alt; for instance on the PC Linux console, -- MMeta will generally correspond to the physical Alt key. data Modifier MShift :: Modifier MCtrl :: Modifier MMeta :: Modifier MAlt :: Modifier -- | Mouse buttons. Not yet used. data Button BLeft :: Button BMiddle :: Button BRight :: Button -- | Generic events. data Event EvKey :: Key -> [Modifier] -> Event EvMouse :: Int -> Int -> Button -> [Modifier] -> Event EvResize :: Int -> Int -> Event -- | Set up the terminal for input. Returns a function which reads key -- events, and a function for shutting down the terminal access. initTermInput :: Int -> Terminal -> IO (IO Event, IO ()) instance Show KClass instance Eq Event instance Show Event instance Ord Event instance Eq Button instance Show Button instance Ord Button instance Eq Modifier instance Show Modifier instance Ord Modifier instance Eq Key instance Show Key instance Ord Key module Graphics.Vty.Terminal -- | Returns a TerminalHandle (an abstract Terminal instance) for the -- current terminal. -- -- The specific Terminal implementation used is hidden from the API user. -- All terminal implementations are assumed to perform more, or less, the -- same. Currently all implementations use terminfo for at least some -- terminal specific information. This is why platforms without terminfo -- are not supported. However, as mentioned before, any specifics about -- it being based on terminfo are hidden from the API user. If a terminal -- implementation is developed for a terminal for a platform without -- terminfo support then Vty should work as expected on that terminal. -- -- Selection of a terminal is done as follows: -- -- -- -- The terminal has to be determined dynamically at runtime. To satisfy -- this requirement all terminals instances are lifted into an abstract -- terminal handle via existential qualification. This implies that the -- only equations that can used are those in the terminal class. -- -- To differentiate between Mac OS X terminals this uses the TERM_PROGRAM -- environment variable. However, an xterm started by Terminal or iTerm -- *also* has TERM_PROGRAM defined since the environment variable is not -- reset/cleared by xterm. However a Terminal.app or iTerm.app started -- from an xterm under X11 on mac os x will likely be done via open. -- Since this does not propogate environment variables (I think?) this -- assumes that XTERM_VERSION will never be set for a true Terminal.app -- or iTerm.app session. -- -- todo: add an implementation for windows that does not depend on -- terminfo. Should be installable with only what is provided in the -- haskell platform. -- -- todo: The Terminal interface does not provide any input support. terminal_handle :: IO TerminalHandle -- | Sets the cursor position to the given output column and row. -- -- This is not necessarially the same as the character position with the -- same coordinates. Characters can be a variable number of columns in -- width. -- -- Currently, the only way to set the cursor position to a given -- character coordinate is to specify the coordinate in the Picture -- instance provided to output_picture or refresh. set_cursor_pos :: TerminalHandle -> Word -> Word -> IO () -- | Hides the cursor hide_cursor :: TerminalHandle -> IO () -- | Shows the cursor show_cursor :: TerminalHandle -> IO () class Terminal t terminal_ID :: (Terminal t) => t -> String release_terminal :: (Terminal t) => t -> IO () reserve_display :: (Terminal t) => t -> IO () release_display :: (Terminal t) => t -> IO () display_bounds :: (Terminal t) => t -> IO DisplayRegion display_terminal_instance :: (Terminal t) => t -> DisplayRegion -> (forall d. (DisplayTerminal d) => d -> DisplayHandle) -> IO DisplayHandle output_byte_buffer :: (Terminal t) => t -> OutputBuffer -> Word -> IO () data TerminalHandle TerminalHandle :: t -> TerminalState -> TerminalHandle data DisplayHandle DisplayHandle :: d -> TerminalHandle -> DisplayState -> DisplayHandle -- | Displays the given Picture. -- -- 0. The image is cropped to the display size. -- -- 1. Converted into a sequence of attribute changes and text spans. -- -- 2. The cursor is hidden. -- -- 3. Serialized to the display. -- -- 4. The cursor is then shown and positioned or kept hidden. -- -- todo: specify possible IO exceptions. abstract from IO monad to a -- MonadIO instance. output_picture :: DisplayHandle -> Picture -> IO () -- | Acquire display access to the given region of the display. Currently -- all regions have the upper left corner of (0,0) and the lower right -- corner at (max display_width provided_width, max display_height -- provided_height) display_context :: TerminalHandle -> DisplayRegion -> IO DisplayHandle module Graphics.Vty -- | The main object. At most one should be created. An alternative is to -- use unsafePerformIO to automatically create a singleton Vty instance -- when required. -- -- This does not assure any thread safety. In theory, as long as an -- update action is not executed when another update action is already -- then it's safe to call this on multiple threads. -- -- todo: Once the Terminal interface encompasses input this interface -- will be deprecated. Currently, just using the Terminal interface there -- is no support for input events. data Vty Vty :: (Picture -> IO ()) -> IO Event -> TerminalHandle -> IO () -> IO () -> Vty -- | Outputs the given Picture. Equivalent to output_picture applied to a -- display context implicitly managed by Vty. update :: Vty -> Picture -> IO () -- | Get one Event object, blocking if necessary. next_event :: Vty -> IO Event -- | Handle to the terminal interface. See Terminal -- -- The use of Vty typically follows this process: -- -- 0. initialize vty -- -- 1. use the update equation of Vty to display a picture -- -- 2. repeat -- -- 3. shutdown vty. -- -- todo: provide a similar abstraction to Graphics.Vty.Terminal for -- input. Use haskeline's input backend for implementation. -- -- todo: remove explicit shutdown requirement. terminal :: Vty -> TerminalHandle -- | Refresh the display. Normally the library takes care of refreshing. -- Nonetheless, some other program might output to the terminal and mess -- the display. In that case the user might want to force a refresh. refresh :: Vty -> IO () -- | Clean up after vty. shutdown :: Vty -> IO () -- | Set up the state object for using vty. At most one state object should -- be created at a time. mkVty :: IO Vty mkVtyEscDelay :: Int -> IO Vty -- | Representations of non-modifier keys. data Key KEsc :: Key KFun :: Int -> Key KBackTab :: Key KPrtScr :: Key KPause :: Key KASCII :: Char -> Key KBS :: Key KIns :: Key KHome :: Key KPageUp :: Key KDel :: Key KEnd :: Key KPageDown :: Key KNP5 :: Key KUp :: Key KMenu :: Key KLeft :: Key KDown :: Key KRight :: Key KEnter :: Key -- | Modifier keys. Key codes are interpreted such that users are more -- likely to have Meta than Alt; for instance on the PC Linux console, -- MMeta will generally correspond to the physical Alt key. data Modifier MShift :: Modifier MCtrl :: Modifier MMeta :: Modifier MAlt :: Modifier -- | Mouse buttons. Not yet used. data Button BLeft :: Button BMiddle :: Button BRight :: Button -- | Generic events. data Event EvKey :: Key -> [Modifier] -> Event EvMouse :: Int -> Int -> Button -> [Modifier] -> Event EvResize :: Int -> Int -> Event