Termbox

A termbox program is typically constructed as an infinite loop that:

1. clears the terminal backbuffer.
2. Renders the program state by setting individual pixels.
3. flushes the backbuffer to the terminal.
4. polls for an event to update the program state.

For example, this progam simply displays the number of keys pressed, and quits on Esc:

{-# LANGUAGE LambdaCase #-}

import Data.Foldable (for_)
import qualified Termbox

main :: IO ()
main =
  Termbox.run_ (loop 0)

loop :: Int -> IO ()
loop n = do
  Termbox.clear mempty mempty
  render n
  Termbox.flush

  Termbox.poll >>= \case
    Termbox.EventKey Termbox.KeyEsc _ ->
      pure ()
    _ ->
      loop (n+1)

render :: Int -> IO ()
render n =
  for_
    (zip [0..] (show n))
    (\(i, c) ->
      Termbox.set i 0 (Termbox.Cell c mempty mempty))

Other termbox features include cell attributes (style, color), cursor display, and mouse click handling.

This module is intended to be imported qualified.

Initialization

run :: IO a -> IO (Either InitError a)

Run a termbox program and restore the terminal state afterwards.

run_ :: IO a -> IO a

Like run, but throws InitErrors as IO exceptions.

data InitError

Termbox initialization errors that can be returned by run.

Constructors

FailedToOpenTTY

PipeTrapError

UnsupportedTerminal

Instances

Show InitError

Defined in Termbox

Methods

showsPrec :: Int -> InitError -> ShowS

show :: InitError -> String

showList :: [InitError] -> ShowS

Exception InitError

Defined in Termbox

Methods

toException :: InitError -> SomeException

fromException :: SomeException -> Maybe InitError

displayException :: InitError -> String

Terminal contents

set :: Int -> Int -> Cell -> IO ()

Set the cell at the given coordinates (column, then row).

getCells :: IO (Array (Int, Int) Cell)

Get the terminal's two-dimensional array of cells (indexed by row, then column).

clear :: Attr -> Attr -> IO ()

Clear the back buffer with the given foreground and background attributes.

flush :: IO ()

Synchronize the internal back buffer with the terminal.

data Cell

A Cell contains a character, foreground attribute, and background attribute.

Constructors

Cell !Char !Attr !Attr

Instances

Eq Cell

Defined in Termbox

Methods

(==) :: Cell -> Cell -> Bool

(/=) :: Cell -> Cell -> Bool

Show Cell

Defined in Termbox

Methods

showsPrec :: Int -> Cell -> ShowS

show :: Cell -> String

showList :: [Cell] -> ShowS

Storable Cell

Defined in Termbox

Methods

sizeOf :: Cell -> Int

alignment :: Cell -> Int

peekElemOff :: Ptr Cell -> Int -> IO Cell

pokeElemOff :: Ptr Cell -> Int -> Cell -> IO ()

peekByteOff :: Ptr b -> Int -> IO Cell

pokeByteOff :: Ptr b -> Int -> Cell -> IO ()

peek :: Ptr Cell -> IO Cell

poke :: Ptr Cell -> Cell -> IO ()

Terminal size

getSize :: IO (Int, Int)

Get the terminal size (width, then height).

Cursor manipulation

setCursor :: Int -> Int -> IO ()

Set the cursor coordinates (column, then row).

hideCursor :: IO ()

Hide the cursor.

Event handling

poll :: IO Event

Block until an Event arrives.

Note: termbox v1.1.2 does not properly handle OS signals that interrupt the underlying select system call, so unfortunately the familiar Ctrl-C will not be able to stop a program stuck in pollEvent.

You can work around this issue by polling in a background thread using the threaded runtime, or simply writing event-handling code that is responsive to intuitive "quit" keys like q and Esc.

Throws: PollError

data Event

A input event.

Constructors

EventKey !Key !Bool

Key event. The bool indicates the alt modifier.

EventResize !Int !Int

Resize event (width, then height)

EventMouse !Mouse !Int !Int

Mouse event (column, then row)

Instances

Eq Event

Defined in Termbox

Methods

(==) :: Event -> Event -> Bool

(/=) :: Event -> Event -> Bool

Show Event

Defined in Termbox

Methods

showsPrec :: Int -> Event -> ShowS

show :: Event -> String

showList :: [Event] -> ShowS

data Key

A key event.

Constructors

KeyChar Char

KeyArrowDown

KeyArrowLeft

KeyArrowRight

KeyArrowUp

KeyBackspace

KeyBackspace2

KeyCtrl2

KeyCtrl3

KeyCtrl4

KeyCtrl5

KeyCtrl6

KeyCtrl7

KeyCtrl8

KeyCtrlA

KeyCtrlB

KeyCtrlBackslash

KeyCtrlC

KeyCtrlD

KeyCtrlE

KeyCtrlF

KeyCtrlG

KeyCtrlH

KeyCtrlI

KeyCtrlJ

KeyCtrlK

KeyCtrlL

KeyCtrlLsqBracket

KeyCtrlM

KeyCtrlN

KeyCtrlO

KeyCtrlP

KeyCtrlQ

KeyCtrlR

KeyCtrlRsqBracket

KeyCtrlS

KeyCtrlSlash

KeyCtrlT

KeyCtrlTilde

KeyCtrlU

KeyCtrlUnderscore

KeyCtrlV

KeyCtrlW

KeyCtrlX

KeyCtrlY

KeyCtrlZ

KeyDelete

KeyEnd

KeyEnter

KeyEsc

KeyF1

KeyF10

KeyF11

KeyF12

KeyF2

KeyF3

KeyF4

KeyF5

KeyF6

KeyF7

KeyF8

KeyF9

KeyHome

KeyInsert

KeyPageDn

KeyPageUp

KeySpace

KeyTab

Instances

Eq Key

Defined in Termbox

Methods

(==) :: Key -> Key -> Bool

(/=) :: Key -> Key -> Bool

Ord Key

Defined in Termbox

Methods

compare :: Key -> Key -> Ordering

(<) :: Key -> Key -> Bool

(<=) :: Key -> Key -> Bool

(>) :: Key -> Key -> Bool

(>=) :: Key -> Key -> Bool

max :: Key -> Key -> Key

min :: Key -> Key -> Key

Show Key

Defined in Termbox

Methods

showsPrec :: Int -> Key -> ShowS

show :: Key -> String

showList :: [Key] -> ShowS

data Mouse

A mouse event.

Constructors

MouseLeft

MouseMiddle

MouseRelease

MouseRight

MouseWheelDown

MouseWheelUp

Instances

Eq Mouse

Defined in Termbox

Methods

(==) :: Mouse -> Mouse -> Bool

(/=) :: Mouse -> Mouse -> Bool

Ord Mouse

Defined in Termbox

Methods

compare :: Mouse -> Mouse -> Ordering

(<) :: Mouse -> Mouse -> Bool

(<=) :: Mouse -> Mouse -> Bool

(>) :: Mouse -> Mouse -> Bool

(>=) :: Mouse -> Mouse -> Bool

max :: Mouse -> Mouse -> Mouse

min :: Mouse -> Mouse -> Mouse

Show Mouse

Defined in Termbox

Methods

showsPrec :: Int -> Mouse -> ShowS

show :: Mouse -> String

showList :: [Mouse] -> ShowS

data PollError

An error occurred when polling, due to mysterious circumstances that are not well-documented in the original C codebase.

Constructors

PollError

Instances

Show PollError

Defined in Termbox

Methods

showsPrec :: Int -> PollError -> ShowS

show :: PollError -> String

showList :: [PollError] -> ShowS

Exception PollError

Defined in Termbox

Methods

toException :: PollError -> SomeException

fromException :: SomeException -> Maybe PollError

displayException :: PollError -> String

Attributes

black :: Attr

black = 1.

red :: Attr

red = 2.

green :: Attr

green = 3.

yellow :: Attr

yellow = 4.

blue :: Attr

blue = 5.

magenta :: Attr

magenta = 6.

cyan :: Attr

cyan = 7.

white :: Attr

white = 8.

bold :: Attr

Bold modifier attribute.

underline :: Attr

Underline modifier attribute.

reverse :: Attr

Reverse modifier attribute.

data Attr

A cell attribute, which includes its color, and whether or not it is bold, underlined, and/or reversed.

A cell can only have one color, but may be (for example) bold and underlined. The Monoid instance combines Attrs this way, with a right bias.

Instances

Eq Attr

Defined in Termbox

Methods

(==) :: Attr -> Attr -> Bool

(/=) :: Attr -> Attr -> Bool

Num Attr

Provided for numeric literals.

Defined in Termbox

Methods

(+) :: Attr -> Attr -> Attr

(-) :: Attr -> Attr -> Attr

(*) :: Attr -> Attr -> Attr

negate :: Attr -> Attr

abs :: Attr -> Attr

signum :: Attr -> Attr

fromInteger :: Integer -> Attr

Semigroup Attr

Left-biased color; attributes are merged.

Defined in Termbox

Methods

(<>) :: Attr -> Attr -> Attr

sconcat :: NonEmpty Attr -> Attr

stimes :: Integral b => b -> Attr -> Attr

Monoid Attr

Defined in Termbox

Methods

mempty :: Attr

mappend :: Attr -> Attr -> Attr

mconcat :: [Attr] -> Attr

Terminal modes

getInputMode :: HasCallStack => IO InputMode

Get the current input mode.

setInputMode :: InputMode -> IO ()

Set the input mode.

data InputMode

The input modes.

• Esc. When ESC sequence is in the buffer and it doesn't match any known sequence, ESC means KeyEsc.
• Alt. When ESC sequence is in the buffer and it doesn't match any known sequence, ESC enables the alt modifier for the next keyboard event.

Constructors

InputModeEsc MouseMode

Default.

InputModeAlt MouseMode

Instances

Eq InputMode

Defined in Termbox

Methods

(==) :: InputMode -> InputMode -> Bool

(/=) :: InputMode -> InputMode -> Bool

Ord InputMode

Defined in Termbox

Methods

compare :: InputMode -> InputMode -> Ordering

(<) :: InputMode -> InputMode -> Bool

(<=) :: InputMode -> InputMode -> Bool

(>) :: InputMode -> InputMode -> Bool

(>=) :: InputMode -> InputMode -> Bool

max :: InputMode -> InputMode -> InputMode

min :: InputMode -> InputMode -> InputMode

Show InputMode

Defined in Termbox

Methods

showsPrec :: Int -> InputMode -> ShowS

show :: InputMode -> String

showList :: [InputMode] -> ShowS

data MouseMode

The mouse mode.

• No. Don't handle mouse events.
• Yes. Handle mouse events.

Constructors

MouseModeNo

Default.

MouseModeYes

Instances

Eq MouseMode

Defined in Termbox

Methods

(==) :: MouseMode -> MouseMode -> Bool

(/=) :: MouseMode -> MouseMode -> Bool

Ord MouseMode

Defined in Termbox

Methods

compare :: MouseMode -> MouseMode -> Ordering

(<) :: MouseMode -> MouseMode -> Bool

(<=) :: MouseMode -> MouseMode -> Bool

(>) :: MouseMode -> MouseMode -> Bool

(>=) :: MouseMode -> MouseMode -> Bool

max :: MouseMode -> MouseMode -> MouseMode

min :: MouseMode -> MouseMode -> MouseMode

Show MouseMode

Defined in Termbox

Methods

showsPrec :: Int -> MouseMode -> ShowS

show :: MouseMode -> String

showList :: [MouseMode] -> ShowS

getOutputMode :: HasCallStack => IO OutputMode

Get the current output mode.

setOutputMode :: OutputMode -> IO ()

Set the output mode.

data OutputMode

The output modes.

• Normal. Supports colors 0..8, which includes all named color attributes exported by this library, e.g. red.
• Grayscale. Supports colors 0..23.
• 216. Supports colors 0..216.
• 256. Supports colors 0..255.

Constructors

OutputModeNormal

Default.

OutputModeGrayscale

OutputMode216

OutputMode256

Instances

Eq OutputMode

Defined in Termbox

Methods

(==) :: OutputMode -> OutputMode -> Bool

(/=) :: OutputMode -> OutputMode -> Bool

Ord OutputMode

Defined in Termbox

Methods

compare :: OutputMode -> OutputMode -> Ordering

(<) :: OutputMode -> OutputMode -> Bool

(<=) :: OutputMode -> OutputMode -> Bool

(>) :: OutputMode -> OutputMode -> Bool

(>=) :: OutputMode -> OutputMode -> Bool

max :: OutputMode -> OutputMode -> OutputMode

min :: OutputMode -> OutputMode -> OutputMode

Show OutputMode

Defined in Termbox

Methods

showsPrec :: Int -> OutputMode -> ShowS

show :: OutputMode -> String

showList :: [OutputMode] -> ShowS