Termbox

This module provides a high-level wrapper around termbox, a simple C library for writing text-based user interfaces: https://github.com/termbox/termbox

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 qualified

main :: IO ()
main = do
  result <-
    Termbox.run
      Termbox.Program
        { initialize,
          pollEvent,
          handleEvent,
          handleEventError,
          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

handleEventError :: MyState -> IO MyState
handleEventError state =
  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.Pos {row = pos.row, col = pos.col + i}
        cell)
    (zip [0 ..] cells)

Termbox

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.

Either returns immediately with an InitError, or once the program state is finished with the final state.

data InitError

termbox initialization errors.

Constructors

FailedToOpenTTY

PipeTrapError

UnsupportedTerminal

Instances

Exception InitError

Defined in Termbox

Methods

toException :: InitError -> SomeException

fromException :: SomeException -> Maybe InitError

displayException :: InitError -> String

Show InitError

Defined in Termbox

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 !Pos

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.0.0-DPWGBoIlJyKFQWwmcVdGn9" '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) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 Pos)) :+: 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 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

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 where

A mouse event.

Bundled Patterns

pattern MouseLeft :: Mouse

pattern MouseMiddle :: Mouse

pattern MouseRelease :: Mouse

pattern MouseRight :: Mouse

pattern MouseWheelDown :: Mouse

pattern MouseWheelUp :: Mouse

Instances

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

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.0.0-DPWGBoIlJyKFQWwmcVdGn9" '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.0.0-DPWGBoIlJyKFQWwmcVdGn9" 'False) (C1 ('MetaCons "Size" 'PrefixI 'True) (S1 ('MetaSel ('Just "width") 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Int) :*: S1 ('MetaSel ('Just "height") 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 Int)))