vty-5.38: A simple terminal UI library

Safe Haskell | Safe-Inferred
Language | Haskell2010

Graphics.Vty

Description

Vty provides interfaces for both terminal input and terminal output.

- Input to the terminal is provided to the Vty application as a sequence of `Event`s.
- Output is provided to Vty by the application 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.

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

     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)

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
  }
- mkVty :: Config -> IO Vty
- setWindowTitle :: Vty -> String -> IO ()
- data Mode
  - = Mouse
  - | BracketedPaste
  - | Focus
  - | Hyperlink
- module Graphics.Vty.Config
- module Graphics.Vty.Input
- module Graphics.Vty.Output
- module Graphics.Vty.Output.Interface
- 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 Vty typically follows this process:

1. Initialize vty with `mkVty` (this takes control of 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 ()

  Outputs the given `Picture`.

- 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

mkVty :: Config -> IO Vty Source #

Create a Vty handle. At most one handle should be created at a time for a given terminal device.

The specified configuration is added to the the configuration loaded by `userConfig` with the `userConfig` configuration taking precedence. See Graphics.Vty.Config.

For most applications `mkVty defaultConfig` is sufficient.

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

Set the terminal window title string.

This function emits an Xterm-compatible escape sequence that we anticipate will work for essentially all modern terminal emulators. Ideally we'd use a terminal capability for this, but there does not seem to exist a termcap for setting window titles. If you find that this function does not work for a given terminal emulator, please report the issue.

For details, see:

https://tldp.org/HOWTO/Xterm-Title-3.html

data Mode Source #

Modal terminal features that can be enabled and disabled.

Constructors

Mouse | Mouse mode (whether the terminal is configured to provide mouse input events)
BracketedPaste | Paste mode (whether the terminal is configured to provide events on OS pastes)
Focus | Focus-in/focus-out events (whether the terminal is configured to provide events on focus change)
Hyperlink | Hyperlink mode via the `withURL` attribute modifier (see https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda). Note that this may not work gracefully in all terminal emulators so be sure to test this mode with the terminals you intend to support. It is off by default.

#### Instances

Instances details

Read Mode Source # |
Instance details Defined in Graphics.Vty.Output.Interface Methods readsPrec :: Int -> ReadS Mode Source # readList :: ReadS [Mode] Source # readPrec :: ReadPrec Mode Source # readListPrec :: ReadPrec [Mode] Source #
Show Mode Source # |
Instance details Defined in Graphics.Vty.Output.Interface Methods showsPrec :: Int -> Mode -> ShowS Source # show :: Mode -> String Source # showList :: [Mode] -> ShowS Source #
Eq Mode Source # |
Instance details Defined in Graphics.Vty.Output.Interface Methods (==) :: Mode -> Mode -> Bool Source # (/=) :: Mode -> Mode -> Bool Source #

module Graphics.Vty.Config

module Graphics.Vty.Input

module Graphics.Vty.Output

module Graphics.Vty.Output.Interface

module Graphics.Vty.Picture

module Graphics.Vty.Image

module Graphics.Vty.Attributes