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

You may prefer to use one of the following interfaces instead:

• termbox-banana, a reactive-banana FRP interface.
• termbox-tea, an Elm Architecture interface.

Main

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

Initialize a termbox program, and if that succeeds, run the provided action, then finalize the termbox program.

initialize :: IO (Either InitError ())

Initialize a termbox program.

If initialize succeeds, it must be paired with a call to finalize.

finalize :: IO ()

Shut down a termbox program.

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, which contains an image, an optional background fill color, and an optional cursor.

• Create a scene with image.
• Set a scene's background fill color with fill.
• Set a scene's cursor position with cursor.

image :: Image -> Scene

Create a scene from an image.

fill :: Color -> Scene -> Scene

Set a scene's background fill color.

cursor :: Pos -> Scene -> Scene

Set a scene's cursor position.

render :: Scene -> IO ()

Render a scene.

Image

data Image

An image.

• Create an image with char.
• Set an image's color with fg / bg.
• Style an image with bold / underline / blink.
• Translate an image with at / atRow / atCol.
• Overlay an image atop another with (<>).

Instances

Monoid Image

Defined in Termbox.Internal.Image

Methods

mempty :: Image

mappend :: Image -> Image -> Image

mconcat :: [Image] -> Image

Semigroup Image

Defined in Termbox.Internal.Image

Methods

(<>) :: Image -> Image -> Image

sconcat :: NonEmpty Image -> Image

stimes :: Integral b => b -> Image -> Image

char :: Char -> Image

Create an image from a character.

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

Color

fg :: Color -> Image -> Image

Set the foreground color of an image.

bg :: Color -> Image -> Image

Set the background color of an image.

Style

bold :: Image -> Image

Make an image bold.

underline :: Image -> Image

Make an image underlined.

blink :: Image -> Image

Make an image blink.

Translation

at :: Pos -> Image -> Image

Translate an image.

atRow :: Int -> Image -> Image

Translate an image by a number of rows.

atCol :: Int -> Image -> Image

Translate an image by a number of columns.

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

Instances

Eq Color

Defined in Termbox.Internal.Color

Methods

(==) :: Color -> Color -> Bool

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

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

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-2.0.0.1-inplace" '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 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

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-2.0.0.1-inplace" '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 LeftClick :: MouseButton

pattern MiddleClick :: MouseButton

pattern ReleaseClick :: MouseButton

pattern RightClick :: MouseButton

pattern WheelDown :: MouseButton

pattern WheelUp :: 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

poll :: IO (Event e)

Poll for an event.

Miscellaneous types

data Pos

A relative terminal position.

Constructors

Pos

Fields

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

Instances

Monoid Pos

Defined in Termbox.Internal.Pos

Methods

mempty :: Pos

mappend :: Pos -> Pos -> Pos

mconcat :: [Pos] -> Pos

Semigroup Pos

Defined in Termbox.Internal.Pos

Methods

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

sconcat :: NonEmpty Pos -> Pos

stimes :: Integral b => b -> Pos -> Pos

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

getSize :: IO Size

Get the current terminal size.