vty-6.4: A simple terminal UI library

Safe Haskell | None
Language | Haskell2010

Graphics.Vty

Description

Vty provides interfaces for both terminal input and terminal output.

- User input to the terminal is provided to the Vty application as a sequence of `Event`s.
- Output is provided to by the application to Vty in the form of a `Picture`. A `Picture` is one or more layers of `Image`s. `Image` values can be built by the various constructors in Graphics.Vty.Image. Output can be syled using `Attr` (attribute) values in the Graphics.Vty.Attributes module.
- Each platform on which Vty is supported provides a package that provides Vty with access to the platform-specific terminal interface. For example, on Unix systems, the `vty-unix` package must be used to initialize Vty with access to a Unix terminal.

As a small example, the following program demonstrates the use of Vty on a Unix system using the `vty-unix` package:

    import Graphics.Vty
    import Graphics.Vty.Platform.Unix (mkVty)

    main = do
        vty <- mkVty defaultConfig
        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)

Vty uses threads internally, so programs made with Vty must be compiled with the threaded runtime using the GHC `-threaded` option.

Synopsis

- data Vty = Vty {
  - update :: Picture -> IO ()
  - nextEvent :: IO Event
  - nextEventNonblocking :: IO (Maybe Event)
  - inputIface :: Input
  - outputIface :: Output
  - refresh :: IO ()
  - shutdown :: IO ()
  - isShutdown :: IO Bool
  }
- setWindowTitle :: Vty -> String -> IO ()
- installCustomWidthTable :: Maybe FilePath -> Maybe String -> [(String, FilePath)] -> IO ()
- mkVtyFromPair :: Input -> Output -> IO Vty
- module Graphics.Vty.Config
- module Graphics.Vty.Input
- module Graphics.Vty.Input.Events
- module Graphics.Vty.Output
- module Graphics.Vty.Picture
- module Graphics.Vty.Image
- module Graphics.Vty.Attributes

# Documentation

data Vty Source #

A `Vty` value represents a handle to the Vty library that the application must create in order to use Vty.

The use of this library typically follows this process:

1. Initialize Vty with the `mkVty` implementation for your platform's Vty package (e.g. `vty-unix`), or, more generically, with `mkVtyFromPair`. This takes control of (and sets up) the terminal.
2. Use `update` to display a picture.
3. Use `nextEvent` to get the next input event.
4. Depending on the event, go to 2 or 5.
5. Shutdown Vty and restore the terminal state with `shutdown`. At this point the `Vty` handle cannot be used again.

Operations on Vty handles are not thread-safe.

Constructors

Vty |

Fields

- update :: Picture -> IO ()

  Output the given `Picture` to the terminal.

- nextEvent :: IO Event

  Return the next `Event` or block until one becomes available.

- nextEventNonblocking :: IO (Maybe Event)

  Non-blocking version of `nextEvent`.

- inputIface :: Input

  The input interface. See `Input`.

- outputIface :: Output

  The output interface. See `Output`.

- refresh :: IO ()

  Refresh the display. If other programs output to the terminal and mess up the display then the application might want to force a refresh using this function.

- shutdown :: IO ()

  Clean up after vty. A call to this function is necessary to cleanly restore the terminal state before application exit. The above methods will throw an exception if executed after this is executed. Idempotent.

- isShutdown :: IO Bool

setWindowTitle :: Vty -> String -> IO () Source #

Set the terminal window title string.

installCustomWidthTable Source #

Arguments

:: Maybe FilePath | Optional path to a log file where log messages should be written when attempting to load a width table.
-> Maybe String | Optional width table entry name (usually the terminal name, e.g. value of `TERM` on Unix systems). If omitted, this function does not attempt to load a table.
-> [(String, FilePath)] | Mapping from width table entry names to width table file paths. This is usually obtained from `configTermWidthMaps` of `VtyUserConfig`.
-> IO () |

Attempt to load and install a custom character width table into this process.

This looks up the specified terminal name in the specified width table map and, if a map file path is found, the map is loaded and installed. This is exposed for Vty platform package implementors; application developers should never need to call this.

mkVtyFromPair :: Input -> Output -> IO Vty Source #

Build a `Vty` handle from an input/output pair.

This is exposed for Vty platform package implementors; application developers should never need to call this, and should instead call `mkVty` or equivalent from their platform package of choice.

module Graphics.Vty.Config

module Graphics.Vty.Input

module Graphics.Vty.Input.Events

module Graphics.Vty.Output

module Graphics.Vty.Picture

module Graphics.Vty.Image

module Graphics.Vty.Attributes