-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | A simple terminal UI 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;
--   
--   Project is hosted on github.com:
--   https:github.comcoreyoconnorvty
--   
--   git clone git:github.comcoreyoconnorvty.git
--   
--   © 2006-2007 Stefan O'Rear; BSD3 license.
--   
--   © 2008-2012 Corey O'Connor; BSD3 license.
@package vty
@version 4.7.0.20

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
attr_style :: Attr -> !(MaybeDefault Style)
attr_fore_color :: Attr -> !(MaybeDefault Color)
attr_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 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:
--   
--   
--   
- 16 color palette. Where the first 8 colors are equal to the 8
--   colors of the ISO 6429 (ANSI) 8 color palette and the second 8 colors
--   are bright/vivid versions of the first 8 colors.
--   
- 240 color palette. This palette is a regular sampling of the full
--   RGB colorspace.
--   
--   
--   The 8 ISO 6429 (ANSI) colors are as follows:
--   
--   
--   
- black
--   
- red
--   
- green
--   
- yellow
--   
- blue
--   
- magenta
--   
- cyan
--   
- 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.
black :: Color

-- | Standard 8-color ANSI terminal color codes.
white :: Color

-- | Standard 8-color ANSI terminal color codes.
cyan :: Color

-- | Standard 8-color ANSI terminal color codes.
magenta :: Color

-- | Standard 8-color ANSI terminal color codes.
blue :: Color

-- | Standard 8-color ANSI terminal color codes.
yellow :: Color

-- | Standard 8-color ANSI terminal color codes.
green :: Color

-- | Standard 8-color ANSI terminal color codes.
red :: Color

-- | Bright/Vivid variants of the standard 8-color ANSI
bright_black :: Color

-- | Bright/Vivid variants of the standard 8-color ANSI
bright_yellow :: Color

-- | Bright/Vivid variants of the standard 8-color ANSI
bright_green :: Color

-- | Bright/Vivid variants of the standard 8-color ANSI
bright_red :: Color
bright_blue :: Color
bright_white :: Color
bright_cyan :: Color
bright_magenta :: 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:
--   
--   
--   
- standout
--   
- underline
--   
- reverse_video
--   
- blink
--   
- dim
--   
- bold/bright
--   
--   
--   ( The invisible, protect, and altcharset display attributes some
--   terminals support are not supported via VTY.)
standout :: Style

-- | The 6 possible style attributes:
--   
--   
--   
- standout
--   
- underline
--   
- reverse_video
--   
- blink
--   
- dim
--   
- bold/bright
--   
--   
--   ( The invisible, protect, and altcharset display attributes some
--   terminals support are not supported via VTY.)
bold :: Style

-- | The 6 possible style attributes:
--   
--   
--   
- standout
--   
- underline
--   
- reverse_video
--   
- blink
--   
- dim
--   
- bold/bright
--   
--   
--   ( The invisible, protect, and altcharset display attributes some
--   terminals support are not supported via VTY.)
dim :: Style

-- | The 6 possible style attributes:
--   
--   
--   
- standout
--   
- underline
--   
- reverse_video
--   
- blink
--   
- dim
--   
- bold/bright
--   
--   
--   ( The invisible, protect, and altcharset display attributes some
--   terminals support are not supported via VTY.)
blink :: Style

-- | The 6 possible style attributes:
--   
--   
--   
- standout
--   
- underline
--   
- reverse_video
--   
- blink
--   
- dim
--   
- bold/bright
--   
--   
--   ( The invisible, protect, and altcharset display attributes some
--   terminals support are not supported via VTY.)
reverse_video :: Style

-- | The 6 possible style attributes:
--   
--   
--   
- standout
--   
- underline
--   
- reverse_video
--   
- blink
--   
- dim
--   
- bold/bright
--   
--   
--   ( The invisible, protect, and altcharset display attributes some
--   terminals support are not supported via VTY.)
underline :: 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 v => Show (MaybeDefault v)
instance Eq v => Eq (MaybeDefault v)
instance Eq Color
instance Show Color
instance Eq FixedAttr
instance Show FixedAttr
instance Eq Attr
instance Show Attr
instance Eq v => Monoid (MaybeDefault v)
instance Monoid Attr

module Graphics.Vty.Image

-- | We pair each character with it's display length. This way we only
--   compute the length once per character. * Though currently the width of
--   some strings is still compute multiple times.
type DisplayString = Seq (Char, Word)

-- | An image in VTY defines:
--   
--   
--   
- properties required to display the image. These are properties
--   that effect the output image but are independent of position
--   
- A set of position-dependent text and attribute regions. The
--   possible regions are:
--   
- a point. ( char )
--   
- a horizontal line of characters with a single attribute. (string,
--   utf8_string, utf8_bytestring )
--   
- a fill of a single character. (char_fill)
--   
- a fill of the picture's background. (background_fill)
--   
--   
--   todo: increase the number of encoded bytestring formats supported.
data Image
HorizText :: !Attr -> DisplayString -> !Word -> !Word -> Image
attr :: Image -> !Attr
text :: Image -> DisplayString
output_width :: Image -> !Word
char_width :: Image -> !Word
HorizJoin :: Image -> Image -> !Word -> !Word -> Image
part_left :: Image -> Image
part_right :: Image -> Image
output_width :: Image -> !Word
output_height :: Image -> !Word
VertJoin :: Image -> Image -> !Word -> !Word -> Image
part_top :: Image -> Image
part_bottom :: Image -> Image
output_width :: Image -> !Word
output_height :: Image -> !Word
BGFill :: !Word -> !Word -> Image
output_width :: Image -> !Word
output_height :: Image -> !Word
EmptyImage :: Image
Translation :: (Int, Int) -> Image -> Image
ImageCrop :: (Word, Word) -> Image -> Image
ImagePad :: (Word, Word) -> Image -> 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-10646 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-10646
--   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-10646 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_10646_string or string.
iso_10646_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

-- | The empty image. Useful for fold combinators. These occupy no space
--   nor define any display attributes.
empty_image :: Image

-- | Apply the given offset to the image.
translate :: (Int, Int) -> Image -> Image

-- | Returns the display width of a character. Assumes all characters with
--   unknown widths are 1 width
safe_wcwidth :: Char -> Word

-- | Returns the display width of a string. Assumes all characters with
--   unknown widths are 1 width
safe_wcswidth :: String -> Word
wcwidth :: Char -> Int
wcswidth :: String -> Int

-- | Ensure an image is no larger than the provided size. If the image is
--   larger then crop.
crop :: (Word, Word) -> Image -> Image

-- | Ensure an image is at least the provided size. If the image is smaller
--   then pad.
pad :: (Word, Word) -> Image -> Image
instance Eq Image
instance Monoid Image
instance Show 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
KBegin :: 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 Eq Key
instance Show Key
instance Ord Key
instance Eq Modifier
instance Show Modifier
instance Ord Modifier
instance Eq Button
instance Show Button
instance Ord Button
instance Eq Event
instance Show Event
instance Ord Event
instance Show KClass

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.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:
--   
--   
--   
- properties required to display the image. These are properties
--   that effect the output image but are independent of position
--   
- A set of position-dependent text and attribute regions. The
--   possible regions are:
--   
- a point. ( char )
--   
- a horizontal line of characters with a single attribute. (string,
--   utf8_string, utf8_bytestring )
--   
- a fill of a single character. (char_fill)
--   
- a fill of the picture's background. (background_fill)
--   
--   
--   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-10646 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-10646
--   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-10646 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_10646_string or string.
iso_10646_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

-- | The empty image. Useful for fold combinators. These occupy no space
--   nor define any display attributes.
empty_image :: Image

-- | Apply the given offset to the image.
translate :: (Int, Int) -> Image -> Image

-- | Ensure an image is no larger than the provided size. If the image is
--   larger then crop.
crop :: (Word, Word) -> Image -> Image

-- | Ensure an image is at least the provided size. If the image is smaller
--   then pad.
pad :: (Word, Word) -> Image -> Image
instance Show Picture

-- | The inline module provides a limited interface to changing the style
--   of terminal output. The intention is for this interface to be used
--   inline with other output systems.
--   
--   The changes specified by the InlineM monad are applied to the
--   terminals display attributes. These display attributes effect the
--   display of all following text output to the terminal file descriptor.
--   
--   For example, in an IO monad the following code with print the text
--   "Not styled. " Followed by the text " Styled! " drawn over a red
--   background and underlined.
--   
--   
--   t <- terminal_handle
--   putStr "Not styled. "
--   put_attr_change t $ do
--       back_color red 
--       apply_style underline
--   putStr " Styled! "
--   put_attr_change t $ default_all
--   putStrLn "Not styled."
--   release_terminal t
--   
--   
--   put_attr_change outputs the control codes to the terminal
--   device Handle. This is a duplicate of the stdout handle
--   when the terminal_handle was (first) acquired. If
--   stdout has since been changed then putStr,
--   putStrLn, print etc.. will output to a different
--   Handle than put_attr_change
--   
--   Copyright 2009-2010 Corey O'Connor
module Graphics.Vty.Inline
type InlineM v = State Attr v

-- | Set the background color to the provided Color
back_color :: Color -> InlineM ()

-- | Set the foreground color to the provided Color
fore_color :: Color -> InlineM ()

-- | Attempt to change the Style of the following text.
--   
--   If the terminal does not support the style change no error is
--   produced. The style can still be removed.
apply_style :: Style -> InlineM ()

-- | Attempt to remove the specified Style from the display of the
--   following text.
--   
--   This will fail if apply_style for the given style has not been
--   previously called.
remove_style :: Style -> InlineM ()

-- | Reset the display attributes
default_all :: InlineM ()

-- | Apply the provided display attribute changes to the terminal.
--   
--   This also flushes the stdout handle.
put_attr_change :: (Applicative m, MonadIO m) => TerminalHandle -> InlineM () -> m ()

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:
--   
--   
--   
- If TERM == xterm then the terminal might be one of the Mac OS X
--   .app terminals. Check if that might be the case and use MacOSX if so.
--   otherwise use XTermColor.
--   
- for any other TERM value TerminfoBased is used.
--   
--   
--   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.
--   
--   The file descriptor used for output will a duplicate of the current
--   stdout file descriptor.
--   
--   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 :: (Applicative m, MonadIO m) => m 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 :: MonadIO m => TerminalHandle -> Word -> Word -> m ()

-- | Hides the cursor
hide_cursor :: MonadIO m => TerminalHandle -> m ()

-- | Shows the cursor
show_cursor :: MonadIO m => TerminalHandle -> m ()
class Terminal t
terminal_ID :: Terminal t => t -> String
release_terminal :: (Terminal t, MonadIO m) => t -> m ()
reserve_display :: (Terminal t, MonadIO m) => t -> m ()
release_display :: (Terminal t, MonadIO m) => t -> m ()
display_bounds :: (Terminal t, MonadIO m) => t -> m DisplayRegion
display_terminal_instance :: (Terminal t, MonadIO m) => t -> DisplayRegion -> (forall d. DisplayTerminal d => d -> DisplayHandle) -> m DisplayHandle
output_byte_buffer :: Terminal t => t -> OutputBuffer -> Word -> IO ()
output_handle :: Terminal t => t -> IO Handle
data TerminalHandle
TerminalHandle :: t -> IORef TerminalState -> TerminalHandle
data DisplayHandle
DisplayHandle :: d -> TerminalHandle -> DisplayState -> DisplayHandle

-- | Displays the given Picture.
--   
--   
--   
- The image is cropped to the display size.
--   
- Converted into a sequence of attribute changes and text
--   spans.
--   
- The cursor is hidden.
--   
- Serialized to the display.
--   
- 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 :: MonadIO m => DisplayHandle -> Picture -> m ()

-- | 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 :: MonadIO m => TerminalHandle -> DisplayRegion -> m 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:
--   
--   
--   
- initialize vty
--   
- use the update equation of Vty to display a picture
--   
- repeat
--   
- 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

-- | Set up the state object for using vty. At most one state object should
--   be created at a time. The delay, in microseconds, specifies the period
--   of time to wait for a key following reading ESC from the terminal
--   before considering the ESC key press as a discrete event.
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
KBegin :: 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
