vty-5.4.0: A simple terminal UI library

Safe Haskell | None
Language | Haskell2010

Graphics.Vty

Description

Vty supports input and output to terminal devices.

- Input to the terminal is provided to the app as a sequence of `Event`s.

- The output is defined by a `Picture`. Which is one or more layers of `Image`s.

  - The module Graphics.Vty.Image provides a number of constructor equations that will build correct `Image` values. See `string`, `<|>`, and `<->` for starters.
  - The constructors in Graphics.Vty.Image.Internal should not be used.
- `Image`s can be styled using `Attr`. See Graphics.Vty.Attributes.

See the vty-examples package for a number of examples.

     import Graphics.Vty

     main = do
         cfg <- standardIOConfig
         vty <- mkVty cfg
         let line0 = string (defAttr ` withForeColor ` green) "first line"
             line1 = string (defAttr ` withBackColor ` blue) "second line"
             img = line0 <-> line1
             pic = picForImage img
         update vty pic
         e <- nextEvent vty
         shutdown vty
         print ("Last event was: " ++ show e)

Good sources of documentation for terminal programming are:

- https://github.com/b4winckler/vim/blob/master/src/term.c
- http://invisible-island.net/xterm/ctlseqs/ctlseqs.html
- http://ulisse.elettra.trieste.it/services/doc/serial/config.html
- http://www.leonerd.org.uk/hacks/hints/xterm-8bit.html
- http://www.unixwiz.net/techtips/termios-vmin-vtime.html
- vt100 control sequences

Synopsis

- data Vty = Vty {
  - update :: Picture -> IO ()
  - nextEvent :: IO Event
  - inputIface :: Input
  - outputIface :: Output
  - refresh :: IO ()
  - shutdown :: IO ()
  }
- mkVty :: Config -> IO Vty
- module Graphics.Vty.Config
- module Graphics.Vty.Input
- module Graphics.Vty.Output
- module Graphics.Vty.Picture
- type DisplayRegion = (Int, Int)

# Documentation

data Vty Source

The main object. At most one should be created.

The use of Vty typically follows this process:

1. initialize vty
2. use the update equation of Vty to display a picture
3. repeat
4. shutdown vty.

An alternative to tracking the Vty instance is to use `withVty` in Graphics.Vty.Inline.Unsafe.

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 Remove explicit `shutdown` requirement.

Constructors

Vty |

Fields

update :: Picture -> IO ()

  Outputs the given Picture. Equivalent to `outputPicture` applied to a display context implicitly managed by Vty. The managed display context is reset on resize.

nextEvent :: IO Event

  Get one Event object, blocking if necessary. This will refresh the terminal if the event is a `EvResize`.

inputIface :: Input

  The input interface. See `Input`

outputIface :: Output

  The output interface. See `Output`

refresh :: IO ()

  Refresh the display. `nextEvent` will refresh the display if a resize occurs. If other programs output to the terminal and mess up the display then the application might want to force a refresh.

shutdown :: IO ()

  Clean up after vty. The above methods will throw an exception if executed after this is executed.

mkVty :: Config -> IO Vty Source

Set up the state object for using vty. At most one state object should be created at a time for a given terminal device.

The specified config is added to the `userConfig`. With the `userConfig` taking precedence. See Graphics.Vty.Config

For most applications `mkVty def` is sufficient.

module Graphics.Vty.Config

module Graphics.Vty.Input

module Graphics.Vty.Output

module Graphics.Vty.Picture

type DisplayRegion = (Int, Int) Source

Named alias for a Int pair