Termbox.Tea

This module provides an Elm Architecture interface to termbox, a simple C library for writing text-based user interfaces: https://github.com/termbox/termbox

See also:

• termbox-banana, a reactive-banana FRP interface.

This module is intended to be imported qualified.

👉 Quick start example

This termbox program displays the number of keys pressed.

{-# LANGUAGE DerivingStrategies #-}
{-# LANGUAGE DuplicateRecordFields #-}
{-# LANGUAGE ImportQualifiedPost #-}
{-# LANGUAGE LambdaCase #-}
{-# LANGUAGE OverloadedRecordDot #-}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE NoFieldSelectors #-}

import Data.Foldable (fold)
import Data.Void (Void)
import Termbox.Tea qualified as Termbox

main :: IO ()
main = do
  result <-
    Termbox.run
      Termbox.Program
        { initialize,
          pollEvent,
          handleEvent,
          render,
          finished
        }
  case result of
    Left err -> putStrLn ("Termbox program failed to initialize: " ++ show err)
    Right state -> putStrLn ("Final state: " ++ show state)

data MyState = MyState
  { keysPressed :: Int,
    pressedEsc :: Bool
  }
  deriving stock (Show)

initialize :: Termbox.Size -> MyState
initialize _size =
  MyState
    { keysPressed = 0,
      pressedEsc = False
    }

pollEvent :: Maybe (IO Void)
pollEvent =
  Nothing

handleEvent :: MyState -> Termbox.Event Void -> IO MyState
handleEvent state = \case
  Termbox.EventKey key ->
    pure
      MyState
        { keysPressed = state.keysPressed + 1,
          pressedEsc =
            case key of
              Termbox.KeyEsc -> True
              _ -> False
        }
  _ -> pure state

render :: MyState -> Termbox.Scene
render state =
  fold
    [ string
        Termbox.Pos {row = 2, col = 4}
        ("Number of keys pressed: " ++ map Termbox.char (show state.keysPressed))
    , string
        Termbox.Pos {row = 4, col = 4}
        ("Press " ++ map (Termbox.bold . Termbox.char) "Esc" ++ " to quit.")
    ]

finished :: MyState -> Bool
finished state =
  state.pressedEsc

string :: Termbox.Pos -> [Termbox.Cell] -> Termbox.Scene
string pos cells =
  foldMap (\(i, cell) -> Termbox.cell (Termbox.posRight i pos) cell) (zip [0 ..] cells)

Main

data Program s

A termbox program, parameterized by state s.

Constructors

forall e. Program

Fields

• initialize :: Size -> s

  The initial state, given the initial terminal size.

• pollEvent :: Maybe (IO e)

  Poll for a user event. Every value that this IO action returns is provided to handleEvent.

• handleEvent :: s -> Event e -> IO s

  Handle an event.

• render :: s -> Scene

  Render the current state.

• finished :: s -> Bool

  Is the current state finished?

run :: Program s -> IO (Either InitError s)

Run a termbox program.

run either:

• Returns immediately with an InitError.
• Returns the final state, once it's finished.

data InitError

termbox initialization errors.

Constructors

FailedToOpenTTY

PipeTrapError

UnsupportedTerminal

Instances

Exception InitError

Defined in Termbox.Internal.Main

Methods

toException :: InitError -> SomeException

fromException :: SomeException -> Maybe InitError

displayException :: InitError -> String

Show InitError

Defined in Termbox.Internal.Main

Methods

showsPrec :: Int -> InitError -> ShowS

show :: InitError -> String

showList :: [InitError] -> ShowS

Terminal contents

Scene

data Scene

A scene.

• Set individual cells with cell.
• Set the background fill color with fill.
• Set the cursor position with cursor.
• Combine scenes together with <>.

Instances

Monoid Scene

Defined in Termbox.Internal.Scene

Methods

mempty :: Scene

mappend :: Scene -> Scene -> Scene

mconcat :: [Scene] -> Scene

Semigroup Scene

Defined in Termbox.Internal.Scene

Methods

(<>) :: Scene -> Scene -> Scene

sconcat :: NonEmpty Scene -> Scene

stimes :: Integral b => b -> Scene -> Scene

cell :: Pos -> Cell -> Scene

Set a single cell.

fill :: Color -> Scene

Set the background fill color.

cursor :: Pos -> Scene

Set the cursor position.

Cell

data Cell

A single cell.

• Create a cell with char, or with a string literal.
• Set a cell's color with fg, bg.
• Style a cell with bold, underline, blink.

Instances

IsString [Cell]

Defined in Termbox.Internal.Cell

Methods

fromString :: String -> [Cell]

char :: Char -> Cell

Create a cell from a character.

If the character is not 1 character wide, it will not be displayed.

fg :: Color -> Cell -> Cell

Set the foreground color of a cell.

bg :: Color -> Cell -> Cell

Set the background color of a cell.

bold :: Cell -> Cell

Make a cell bold.

underline :: Cell -> Cell

Make a cell underlined.

blink :: Cell -> Cell

Make a cell blink.

Colors

data Color

A color.

There are three classes of colors:

• Basic named colors and their bright variants, such as red and bright blue.
• Miscellaneous colors, such as color 33.
• Monochrome colors that range from black (gray 0) to white (gray 23).

Basic colors

defaultColor :: Color

red :: Color

green :: Color

yellow :: Color

blue :: Color

magenta :: Color

cyan :: Color

white :: Color

bright :: Color -> Color

Make a basic color brighter.

216 miscellaneous colors

color :: Int -> Color

A miscellaneous color.

Valid values are in the range [0, 215]; values outside of this range are clamped.

24 monochrome colors

gray :: Int -> Color

A monochrome color; black is 0 and white is 23.

Valid values are in the range [0, 23]; values outside of this range are clamped.

Event handling

data Event e

An input event.

Constructors

EventKey !Key

Key event

EventResize !Size

Resize event

EventMouse !Mouse

Mouse event

EventUser !e

User event

Instances

Generic (Event e)

Defined in Termbox.Internal.Event

Associated Types

type Rep (Event e) :: Type -> Type

Methods

from :: Event e -> Rep (Event e) x

to :: Rep (Event e) x -> Event e

Show e => Show (Event e)

Defined in Termbox.Internal.Event

Methods

showsPrec :: Int -> Event e -> ShowS

show :: Event e -> String

showList :: [Event e] -> ShowS

Eq e => Eq (Event e)

Defined in Termbox.Internal.Event

Methods

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

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

type Rep (Event e)

Defined in Termbox.Internal.Event

type Rep (Event e) = D1 ('MetaData "Event" "Termbox.Internal.Event" "termbox-1.1.0-LJiljUmeV4XCrRZs1766tr" 'False) ((C1 ('MetaCons "EventKey" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Key)) :+: C1 ('MetaCons "EventResize" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Size))) :+: (C1 ('MetaCons "EventMouse" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Mouse)) :+: C1 ('MetaCons "EventUser" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 e))))

data Key

A key event.

Some distinct key sequences map to the same key event. For example, to a termbox program, Enter is indistinguishable from Ctrl+M. Pattern synonyms below are provided for an alternate syntax in these cases, if desired.

Constructors

KeyChar Char

KeyArrowDown

KeyArrowLeft

KeyArrowRight

KeyArrowUp

KeyBackspace

KeyCtrlBackspace

Also KeyCtrlH

KeyCtrl6

KeyCtrl8

KeyCtrlA

KeyCtrlB

KeyCtrlBackslash

Also KeyCtrl4

KeyCtrlC

KeyCtrlD

KeyCtrlE

KeyCtrlF

KeyCtrlG

KeyCtrlJ

KeyCtrlK

KeyCtrlL

KeyCtrlN

KeyCtrlO

KeyCtrlP

KeyCtrlQ

KeyCtrlR

KeyCtrlRsqBracket

Also KeyCtrl5

KeyCtrlS

KeyCtrlSlash

Also KeyCtrl7, KeyCtrlUnderscore

KeyCtrlTilde

Also KeyCtrl2

KeyCtrlT

KeyCtrlU

KeyCtrlV

KeyCtrlW

KeyCtrlX

KeyCtrlY

KeyCtrlZ

KeyDelete

KeyEnd

KeyEnter

Also KeyCtrlM

KeyEsc

Also KeyCtrlLsqBracket, KeyCtrl3

KeyF1

KeyF10

KeyF11

KeyF12

KeyF2

KeyF3

KeyF4

KeyF5

KeyF6

KeyF7

KeyF8

KeyF9

KeyHome

KeyInsert

KeyPageDn

KeyPageUp

KeySpace

KeyTab

Also KeyCtrlI

Bundled Patterns

pattern KeyCtrlUnderscore :: Key

pattern KeyCtrlI :: Key

pattern KeyCtrlM :: Key

pattern KeyCtrl7 :: Key

pattern KeyCtrl5 :: Key

pattern KeyCtrl4 :: Key

pattern KeyCtrl3 :: Key

pattern KeyCtrl2 :: Key

pattern KeyCtrlLsqBracket :: Key

pattern KeyCtrlH :: Key

Instances

Show Key

Defined in Termbox.Internal.Key

Methods

showsPrec :: Int -> Key -> ShowS

show :: Key -> String

showList :: [Key] -> ShowS

Eq Key

Defined in Termbox.Internal.Key

Methods

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

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

Ord Key

Defined in Termbox.Internal.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

data Mouse

A mouse event.

Constructors

Mouse

Fields

• button :: !MouseButton
• pos :: !Pos

Instances

Generic Mouse

Defined in Termbox.Internal.Mouse

Associated Types

type Rep Mouse :: Type -> Type

Methods

from :: Mouse -> Rep Mouse x

to :: Rep Mouse x -> Mouse

Show Mouse

Defined in Termbox.Internal.Mouse

Methods

showsPrec :: Int -> Mouse -> ShowS

show :: Mouse -> String

showList :: [Mouse] -> ShowS

Eq Mouse

Defined in Termbox.Internal.Mouse

Methods

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

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

Ord Mouse

Defined in Termbox.Internal.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

type Rep Mouse

Defined in Termbox.Internal.Mouse

type Rep Mouse = D1 ('MetaData "Mouse" "Termbox.Internal.Mouse" "termbox-1.1.0-LJiljUmeV4XCrRZs1766tr" 'False) (C1 ('MetaCons "Mouse" 'PrefixI 'True) (S1 ('MetaSel ('Just "button") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 MouseButton) :*: S1 ('MetaSel ('Just "pos") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Pos)))

data MouseButton where

A mouse button.

Bundled Patterns

pattern WheelUp :: MouseButton

pattern WheelDown :: MouseButton

pattern ReleaseClick :: MouseButton

pattern RightClick :: MouseButton

pattern MiddleClick :: MouseButton

pattern LeftClick :: MouseButton

Instances

Show MouseButton

Defined in Termbox.Internal.Mouse

Methods

showsPrec :: Int -> MouseButton -> ShowS

show :: MouseButton -> String

showList :: [MouseButton] -> ShowS

Eq MouseButton

Defined in Termbox.Internal.Mouse

Methods

(==) :: MouseButton -> MouseButton -> Bool

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

Ord MouseButton

Defined in Termbox.Internal.Mouse

Methods

compare :: MouseButton -> MouseButton -> Ordering

(<) :: MouseButton -> MouseButton -> Bool

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

(>) :: MouseButton -> MouseButton -> Bool

(>=) :: MouseButton -> MouseButton -> Bool

max :: MouseButton -> MouseButton -> MouseButton

min :: MouseButton -> MouseButton -> MouseButton

Miscellaneous types

data Pos

A terminal position.

Constructors

Pos

Fields

• row :: !Int
• col :: !Int

Instances

Generic Pos

Defined in Termbox.Internal.Pos

Associated Types

type Rep Pos :: Type -> Type

Methods

from :: Pos -> Rep Pos x

to :: Rep Pos x -> Pos

Show Pos

Defined in Termbox.Internal.Pos

Methods

showsPrec :: Int -> Pos -> ShowS

show :: Pos -> String

showList :: [Pos] -> ShowS

Eq Pos

Defined in Termbox.Internal.Pos

Methods

(==) :: Pos -> Pos -> Bool

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

Ord Pos

Defined in Termbox.Internal.Pos

Methods

compare :: Pos -> Pos -> Ordering

(<) :: Pos -> Pos -> Bool

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

(>) :: Pos -> Pos -> Bool

(>=) :: Pos -> Pos -> Bool

max :: Pos -> Pos -> Pos

min :: Pos -> Pos -> Pos

type Rep Pos

Defined in Termbox.Internal.Pos

type Rep Pos = D1 ('MetaData "Pos" "Termbox.Internal.Pos" "termbox-1.1.0-LJiljUmeV4XCrRZs1766tr" 'False) (C1 ('MetaCons "Pos" 'PrefixI 'True) (S1 ('MetaSel ('Just "row") 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Int) :*: S1 ('MetaSel ('Just "col") 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Int)))

posUp :: Int -> Pos -> Pos

Move a position up.

posDown :: Int -> Pos -> Pos

Move a position down.

posLeft :: Int -> Pos -> Pos

Move a position left.

posRight :: Int -> Pos -> Pos

Move a position right.

data Size

A terminal size.

Constructors

Size

Fields

• width :: !Int
• height :: !Int

Instances

Generic Size

Defined in Termbox.Internal.Size

Associated Types

type Rep Size :: Type -> Type

Methods

from :: Size -> Rep Size x

to :: Rep Size x -> Size

Show Size

Defined in Termbox.Internal.Size

Methods

showsPrec :: Int -> Size -> ShowS

show :: Size -> String

showList :: [Size] -> ShowS

Eq Size

Defined in Termbox.Internal.Size

Methods

(==) :: Size -> Size -> Bool

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

Ord Size

Defined in Termbox.Internal.Size

Methods

compare :: Size -> Size -> Ordering

(<) :: Size -> Size -> Bool

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

(>) :: Size -> Size -> Bool

(>=) :: Size -> Size -> Bool

max :: Size -> Size -> Size

min :: Size -> Size -> Size

type Rep Size

Defined in Termbox.Internal.Size

type Rep Size = D1 ('MetaData "Size" "Termbox.Internal.Size" "termbox-1.1.0-LJiljUmeV4XCrRZs1766tr" 'False) (C1 ('MetaCons "Size" 'PrefixI 'True) (S1 ('MetaSel ('Just "width") 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Int) :*: S1 ('MetaSel ('Just "height") 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Int)))