Graphics.Vty

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 Events.
• Output is provided to by the application to Vty in the form of a Picture. A Picture is one or more layers of Images. 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.

Documentation

data Vty

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 ()

Set the terminal window title string.

installCustomWidthTable

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

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