Termbox

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

1. Renders a scene.
2. Polls for an event.

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

{-# LANGUAGE LambdaCase #-}

import qualified Termbox

main :: IO ()
main =
  Termbox.run (\_width _height render poll -> loop render poll 0)

loop :: (Termbox.Cells -> Termbox.Cursor -> IO ()) -> IO Termbox.Event -> Int -> IO ()
loop render poll n = do
  render (string (show n)) Termbox.NoCursor

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

string :: Int -> Int -> String -> Termbox.Cells
string col row =
  foldMap (\(i, c) -> Termbox.set (col + i) row (Termbox.Cell c 0 0)) . zip [0..]

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

This module is intended to be imported qualified.

Initialization

run :: (Int -> Int -> (Cells -> Cursor -> IO ()) -> IO Event -> IO a) -> IO a

Run a termbox program and restore the terminal state afterwards.

The function provided to run is provided:

• The initial terminal width
• The initial terminal height
• An action that renders a scene
• An action that polls for an event indefinitely

Throws: InitError

data InitError

Termbox initialization errors.

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 -> Cells

Set a single cell's value (column, then row).

data Cells

A grid of cells. Create with set and combine with (<>).

Instances

Semigroup Cells

Defined in Termbox.Cells

Methods

(<>) :: Cells -> Cells -> Cells

sconcat :: NonEmpty Cells -> Cells

stimes :: Integral b => b -> Cells -> Cells

Monoid Cells

Defined in Termbox.Cells

Methods

mempty :: Cells

mappend :: Cells -> Cells -> Cells

mconcat :: [Cells] -> Cells

data Cell

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

Constructors

Cell !Char !Attr !Attr

Instances

Eq Cell

Defined in Termbox.Cell

Methods

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

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

Show Cell

Defined in Termbox.Cell

Methods

showsPrec :: Int -> Cell -> ShowS

show :: Cell -> String

showList :: [Cell] -> ShowS

Storable Cell

Defined in Termbox.Cell

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

data Cursor

A cursor.

Constructors

Cursor !Int !Int

Column, then row

NoCursor

Event handling

data Event

A input event.

Constructors

EventKey !Key

Key event

EventResize !Int !Int

Resize event (width, then height)

EventMouse !Mouse !Int !Int

Mouse event (column, then row)

Instances

Eq Event

Defined in Termbox.Event

Methods

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

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

Show Event

Defined in Termbox.Event

Methods

showsPrec :: Int -> Event -> ShowS

show :: Event -> String

showList :: [Event] -> ShowS

data Key

A key event.

Constructors

KeyChar Char

KeyArrowDown

KeyArrowLeft

KeyArrowRight

KeyArrowUp

KeyBackspace

KeyCtrlBackspace

Also: Ctrl+H

KeyCtrl6

KeyCtrl8

KeyCtrlA

KeyCtrlB

KeyCtrlBackslash

Also: Ctrl-4

KeyCtrlC

KeyCtrlD

KeyCtrlE

KeyCtrlF

KeyCtrlG

KeyCtrlJ

KeyCtrlK

KeyCtrlL

KeyCtrlN

KeyCtrlO

KeyCtrlP

KeyCtrlQ

KeyCtrlR

KeyCtrlRsqBracket

Also: Ctrl-5

KeyCtrlS

KeyCtrlSlash

Also: Ctrl-/, Ctrl-_

KeyCtrlTilde

Also: Ctrl+2

KeyCtrlT

KeyCtrlU

KeyCtrlV

KeyCtrlW

KeyCtrlX

KeyCtrlY

KeyCtrlZ

KeyDelete

KeyEnd

KeyEnter

Also: Ctrl-M

KeyEsc

Also: Ctrl-[, Ctrl-3

KeyF1

KeyF10

KeyF11

KeyF12

KeyF2

KeyF3

KeyF4

KeyF5

KeyF6

KeyF7

KeyF8

KeyF9

KeyHome

KeyInsert

KeyPageDn

KeyPageUp

KeySpace

KeyTab

Also: Ctrl+I

Instances

Eq Key

Defined in Termbox.Key

Methods

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

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

Ord Key

Defined in Termbox.Key

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.Key

Methods

showsPrec :: Int -> Key -> ShowS

show :: Key -> String

showList :: [Key] -> ShowS

In a few cases, distinct key sequences map to equivalent key events. The pattern synonyms below are provided for an alternate syntax in these cases, if desired.

pattern KeyCtrlH :: Key

pattern KeyCtrlLsqBracket :: Key

pattern KeyCtrl2 :: Key

pattern KeyCtrl3 :: Key

pattern KeyCtrl4 :: Key

pattern KeyCtrl5 :: Key

pattern KeyCtrl7 :: Key

pattern KeyCtrlM :: Key

pattern KeyCtrlI :: Key

pattern KeyCtrlUnderscore :: Key

data Mouse

A mouse event.

Constructors

MouseLeft

MouseMiddle

MouseRelease

MouseRight

MouseWheelDown

MouseWheelUp

Instances

Eq Mouse

Defined in Termbox.Mouse

Methods

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

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

Ord Mouse

Defined in Termbox.Mouse

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.Mouse

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.Event

Methods

showsPrec :: Int -> PollError -> ShowS

show :: PollError -> String

showList :: [PollError] -> ShowS

Exception PollError

Defined in Termbox.Event

Methods

toException :: PollError -> SomeException

fromException :: SomeException -> Maybe PollError

displayException :: PollError -> String

Attributes

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.Attr

Methods

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

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

Num Attr

Provided for numeric literals.

Defined in Termbox.Attr

Methods

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

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

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

negate :: Attr -> Attr

abs :: Attr -> Attr

signum :: Attr -> Attr

fromInteger :: Integer -> Attr

Show Attr

Defined in Termbox.Attr

Methods

showsPrec :: Int -> Attr -> ShowS

show :: Attr -> String

showList :: [Attr] -> ShowS

Semigroup Attr

Right-biased color; attributes are merged.

Defined in Termbox.Attr

Methods

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

sconcat :: NonEmpty Attr -> Attr

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

Monoid Attr

Defined in Termbox.Attr

Methods

mempty :: Attr

mappend :: Attr -> Attr -> Attr

mconcat :: [Attr] -> Attr

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.