vty-4.7.0.20: A simple terminal UI library

Safe Haskell | None

Graphics.Vty.Terminal

Synopsis

- terminal_handle :: (Applicative m, MonadIO m) => m TerminalHandle
- set_cursor_pos :: MonadIO m => TerminalHandle -> Word -> Word -> m ()
- hide_cursor :: MonadIO m => TerminalHandle -> m ()
- show_cursor :: MonadIO m => TerminalHandle -> m ()
- class Terminal t where
  - terminal_ID :: t -> String
  - release_terminal :: MonadIO m => t -> m ()
  - reserve_display :: MonadIO m => t -> m ()
  - release_display :: MonadIO m => t -> m ()
  - display_bounds :: MonadIO m => t -> m DisplayRegion
  - display_terminal_instance :: MonadIO m => t -> DisplayRegion -> (forall d. DisplayTerminal d => d -> DisplayHandle) -> m DisplayHandle
  - output_byte_buffer :: t -> OutputBuffer -> Word -> IO ()
  - output_handle :: t -> IO Handle
- data TerminalHandle where
  - TerminalHandle :: Terminal t => t -> IORef TerminalState -> TerminalHandle
- data DisplayHandle where
  - DisplayHandle :: forall d. DisplayTerminal d => d -> TerminalHandle -> DisplayState -> DisplayHandle
- output_picture :: MonadIO m => DisplayHandle -> Picture -> m ()
- display_context :: MonadIO m => TerminalHandle -> DisplayRegion -> m DisplayHandle

# Documentation

terminal_handle :: (Applicative m, MonadIO m) => m TerminalHandle Source

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.

set_cursor_pos :: MonadIO m => TerminalHandle -> Word -> Word -> m ()Source

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.

hide_cursor :: MonadIO m => TerminalHandle -> m ()Source

Hides the cursor

show_cursor :: MonadIO m => TerminalHandle -> m ()Source

Shows the cursor

class Terminal t where Source

Methods

terminal_ID :: t -> String Source

Text identifier for the terminal. Used for debugging.

release_terminal :: MonadIO m => t -> m ()Source

reserve_display :: MonadIO m => t -> m ()Source

Clear the display and initialize the terminal to some initial display state.

The expectation of a program is that the display starts in some initial state. The initial state would consist of fixed values: - cursor at top left - UTF-8 character encoding - drawing characteristics are the default The abstract operation I think all these behaviors are instances of is reserving exclusive access to a display such that: - The previous state cannot be determined - When exclusive access to a display is release the display returns to the previous state.

release_display :: MonadIO m => t -> m ()Source

Return the display to the state before reserve_display If no previous state then set the display state to the initial state.

display_bounds :: MonadIO m => t -> m DisplayRegion Source

Returns the current display bounds.

display_terminal_instance :: MonadIO m => t -> DisplayRegion -> (forall d. DisplayTerminal d => d -> DisplayHandle) -> m DisplayHandle Source

output_byte_buffer :: t -> OutputBuffer -> Word -> IO ()Source

Output the byte buffer of the specified size to the terminal device. The size is equal to end_ptr - start_ptr

output_handle :: t -> IO Handle Source

Handle of output device

Instances

Terminal TerminalHandle |

data TerminalHandle where Source

Constructors

TerminalHandle :: Terminal t => t -> IORef TerminalState -> TerminalHandle |

Instances

Terminal TerminalHandle |

data DisplayHandle where Source

Constructors

DisplayHandle :: forall d. DisplayTerminal d => d -> TerminalHandle -> DisplayState -> DisplayHandle |

output_picture :: MonadIO m => DisplayHandle -> Picture -> m ()Source

Displays the given `Picture`.

1. The image is cropped to the display size.
2. Converted into a sequence of attribute changes and text spans.
3. The cursor is hidden.
4. Serialized to the display.
5. The cursor is then shown and positioned or kept hidden.

todo: specify possible IO exceptions. abstract from IO monad to a MonadIO instance.

display_context :: MonadIO m => TerminalHandle -> DisplayRegion -> m DisplayHandle Source

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)