UI.NCurses

Primary types

data Curses a

A small wrapper around IO, to ensure the ncurses library is initialized while running.

Instances

Monad Curses

Methods

(>>=) :: Curses a -> (a -> Curses b) -> Curses b

(>>) :: Curses a -> Curses b -> Curses b

return :: a -> Curses a

fail :: String -> Curses a

Functor Curses

Methods

fmap :: (a -> b) -> Curses a -> Curses b

(<$) :: a -> Curses b -> Curses a

MonadFix Curses

Methods

mfix :: (a -> Curses a) -> Curses a

Applicative Curses

Methods

pure :: a -> Curses a

(<*>) :: Curses (a -> b) -> Curses a -> Curses b

(*>) :: Curses a -> Curses b -> Curses b

(<*) :: Curses a -> Curses b -> Curses a

MonadIO Curses

Methods

liftIO :: IO a -> Curses a

data Update a

Instances

Monad Update

Methods

(>>=) :: Update a -> (a -> Update b) -> Update b

(>>) :: Update a -> Update b -> Update b

return :: a -> Update a

fail :: String -> Update a

Functor Update

Methods

fmap :: (a -> b) -> Update a -> Update b

(<$) :: a -> Update b -> Update a

MonadFix Update

Methods

mfix :: (a -> Update a) -> Update a

Applicative Update

Methods

pure :: a -> Update a

(<*>) :: Update (a -> b) -> Update a -> Update b

(*>) :: Update a -> Update b -> Update b

(<*) :: Update a -> Update b -> Update a

data Window

data CursesException

Instances

Show CursesException

Methods

showsPrec :: Int -> CursesException -> ShowS

show :: CursesException -> String

showList :: [CursesException] -> ShowS

Exception CursesException

Methods

toException :: CursesException -> SomeException

fromException :: SomeException -> Maybe CursesException

displayException :: CursesException -> String

Initialization

runCurses :: Curses a -> IO a

Put the terminal in graphical mode, including enabling special keys, colors, and mouse events (if supported).

After the Curses block has finished running, the terminal is reset to text mode.

defaultWindow :: Curses Window

The default window created when ncurses is initialized, also known as stdscr.

Window management

newWindow

Arguments

:: Integer

Rows

-> Integer

Columns

-> Integer

Begin Y

-> Integer

Begin X

-> Curses Window

Create a new Window, with the given dimensions. To create a fullscreen window, use newWindow 0 0 0 0.

When the window is no longer needed, call closeWindow. Windows are not garbage–collected, because there’s no way to know if they’re still in use (as a background, or event source, etc).

closeWindow :: Window -> Curses ()

Close a window, and free all resources associated with it. Once a window has been closed, it is no longer safe to use.

Note: this computation will not automatically clear the window from the screen.

cloneWindow :: Window -> Curses Window

Create a separate window, initialised with the state of an existing window.

moveWindow :: Integer -> Integer -> Update ()

Moves the window to the given (row,column) coordinate.

windowPosition :: Update (Integer, Integer)

Returns the current (row, column) coordinates of the window.

resizeWindow :: Integer -> Integer -> Update ()

Resizes the window to the given row and column dimensions.

windowSize :: Update (Integer, Integer)

updateWindow :: Window -> Update a -> Curses a

Apply a window update to the window. After all of an application’s windows have been updated, call render to update the terminal’s contents.

Copying window content

data OverlayMode

Constructors

OverlayMerge

Overlay only non-blank characters.

OverlayReplace

Overlay all characters, including blanks.

Instances

Eq OverlayMode

Methods

(==) :: OverlayMode -> OverlayMode -> Bool

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

Show OverlayMode

Methods

showsPrec :: Int -> OverlayMode -> ShowS

show :: OverlayMode -> String

showList :: [OverlayMode] -> ShowS

overlay :: Window -> OverlayMode -> Update ()

Overlay the entire content of another window onto this window.

The overlay mode specifies whether to copy blank characters.

Use copyWindow if precise control over coordinates is required.

copyWindow :: Window -> OverlayMode -> Integer -> Integer -> Integer -> Integer -> Integer -> Integer -> Update ()

Overlay a region of another window onto this window.

Use overlay for copying the entire area of a window.

Virtual windows (pads)

data Pad

A Pad is a Window that is not associated with the screen.

newPad

Arguments

:: Integer

Rows

-> Integer

Columns

-> Curses Pad

Create a new Pad with the given dimensions.

When the pad is no longer needed, call closePad. Pads are not garbage–collected, because there’s no way to know if they’re still in use.

closePad :: Pad -> Curses ()

Close a pad, and free all resources associated with it. Once a pad has been closed, it is no longer safe to use.

updatePad :: Pad -> Integer -> Integer -> Integer -> Integer -> Integer -> Integer -> Update a -> Curses a

The cursor

moveCursor

Arguments

:: Integer

Row

-> Integer

Column

-> Update ()

Move the window’s cursor position to the given row and column.

cursorPosition :: Update (Integer, Integer)

Returns the current (row,column) coordinates of the cursor.

This is the same as getCursor, but is usable within an Update.

getCursor :: Window -> Curses (Integer, Integer)

Return current cursor position as (row, column).

This is the same as cursorPosition, but is usable outside of an Update.

Drawing to the screen

render :: Curses ()

Re–draw any portions of the screen which have changed since the last render.

setColor :: ColorID -> Update ()

Set the current foreground and background colors. See newColorID for how to create color IDs.

drawString :: String -> Update ()

Add some text to the window, at the current cursor position.

drawText :: Text -> Update ()

Add some text to the window, at the current cursor position.

drawGlyph :: Glyph -> Update ()

drawBorder

Arguments

:: Maybe Glyph

Left edge

-> Maybe Glyph

Right edge

-> Maybe Glyph

Top edge

-> Maybe Glyph

Bottom edge

-> Maybe Glyph

Top left corner

-> Maybe Glyph

Top right corner

-> Maybe Glyph

Bottom left corner

-> Maybe Glyph

Bottom right corner

-> Update ()

Draw a border around the edge of the window. For any edge, passing Nothing means to use the default glyph.

drawBox :: Maybe Glyph -> Maybe Glyph -> Update ()

drawBox v h = drawBorder v v h h Nothing Nothing Nothing Nothing

drawLineH :: Maybe Glyph -> Integer -> Update ()

Draw a horizontal line from left to right, using the given glyph and maximum character count. The cursor position is not changed.

drawLineV :: Maybe Glyph -> Integer -> Update ()

Draw a vertical line from top to bottom, using the given glyph and maximum character count. The cursor position is not changed.

clear :: Update ()

Clear the window content by drawing blanks to every position.

clearLine :: Update ()

Clear the current line starting from the current cursor position (inclusive) to the end of the line.

setBackground :: Glyph -> Update ()

Set the window’s background glyph. The glyph will be drawn in place of any blank characters, and the glyph’s attributes will be combined with those of every character.

Attributes

data Attribute

Constructors

AttributeColor ColorID

A_COLOR

AttributeStandout

A_STANDOUT

AttributeUnderline

A_UNDERLINE

AttributeReverse

A_REVERSE

AttributeBlink

A_BLINK

AttributeDim

A_DIM

AttributeBold

A_BOLD

AttributeAltCharset

A_ALTCHARSET

AttributeInvisible

A_INVISIBLE

AttributeProtect

A_PROTECT

AttributeHorizontal

A_HORIZONTAL

AttributeLeft

A_LEFT

AttributeLow

A_LOW

AttributeRight

A_RIGHT

AttributeTop

A_TOP

AttributeVertical

A_VERTICAL

Instances

Eq Attribute

Methods

(==) :: Attribute -> Attribute -> Bool

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

Show Attribute

Methods

showsPrec :: Int -> Attribute -> ShowS

show :: Attribute -> String

showList :: [Attribute] -> ShowS

setAttribute :: Attribute -> Bool -> Update ()

Set a single Attribute on the current window. No other attributes are modified.

setAttributes :: [Attribute] -> Update ()

Set all Attributes at once on the current window. Any attributes not included in the list will be unset.

Colors

data Color

Constructors

ColorBlack

ColorRed

ColorGreen

ColorYellow

ColorBlue

ColorMagenta

ColorCyan

ColorWhite

ColorDefault

An unspecified default terminal color, for terminals that support ISO/IEC 6429 escape sequences (or equivalent).

This is most useful for terminals with translucent backgrounds.

Color Int16

A color outside of the standard COLOR_* enum space, for terminals that support more than eight colors.

Color-related functions may fail if a Color is provided that cannot be supported by the current terminal. Users are responsible for checking maxColor when using extended colors.

Instances

Eq Color

Methods

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

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

Show Color

Methods

showsPrec :: Int -> Color -> ShowS

show :: Color -> String

showList :: [Color] -> ShowS

maxColor :: Curses Integer

data ColorID

A wrapper around Integer to ensure clients don’t use an uninitialized color in an attribute.

Instances

Eq ColorID

Methods

(==) :: ColorID -> ColorID -> Bool

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

Show ColorID

Methods

showsPrec :: Int -> ColorID -> ShowS

show :: ColorID -> String

showList :: [ColorID] -> ShowS

supportsColor :: Curses Bool

Check if the terminal supports color. If it doesn’t, alternative indicators (such as underlines or bold) should be used.

canDefineColor :: Curses Bool

Check if the terminal supports changing color defintiions.

defineColor

Arguments

:: Color

-> Integer

Red (0 – 1000)

-> Integer

Green (0 – 1000)

-> Integer

Blue (0 – 1000)

-> Curses ()

Change the definition of an existing color. Use canDefineColor to determine whether changing color values is possible.

queryColor :: Color -> Curses (Integer, Integer, Integer)

Query the current definition of the given color (see defineColor). The returned tuple is (red, green, blue), with values 0 – 1000.

defaultColorID :: ColorID

The default color ID

newColorID

Arguments

:: Color

Foreground

-> Color

Background

-> Integer

A value n, such that (0 < n ≤ maxColorID)

-> Curses ColorID

Assign a new ColorID to some (foreground, background) color pair. The user may pick which color ID is assigned, but it must be valid. Use maxColorID to determine how many colors the current terminal supports.

setColorID

Arguments

:: Color

Foreground

-> Color

Background

-> ColorID

The ColorID to change

-> Curses ()

maxColorID :: Curses Integer

Get the maximum color ID supported by the current terminal

Glyphs

data Glyph

A glyph is a character, typically spacing, combined with a set of attributes.

Constructors

Glyph

Fields

• glyphCharacter :: Char
• glyphAttributes :: [Attribute]

Instances

Eq Glyph

Methods

(==) :: Glyph -> Glyph -> Bool

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

Show Glyph

Methods

showsPrec :: Int -> Glyph -> ShowS

show :: Glyph -> String

showList :: [Glyph] -> ShowS

VT100 drawing glyphs

glyphCornerUL :: Glyph

Upper left corner

glyphCornerLL :: Glyph

Lower left corner

glyphCornerUR :: Glyph

Upper right corner

glyphCornerLR :: Glyph

Lower right corner

glyphTeeL :: Glyph

Tee pointing right

glyphTeeR :: Glyph

Tee pointing left

glyphTeeB :: Glyph

Tee pointing up

glyphTeeT :: Glyph

Tee pointing down

glyphLineH :: Glyph

Horizontal line

glyphLineV :: Glyph

Vertical line

glyphPlus :: Glyph

Large plus or crossover

glyphScan1 :: Glyph

Scan line 1

glyphScan9 :: Glyph

Scan line 9

glyphDiamond :: Glyph

Diamond

glyphStipple :: Glyph

Stipple, or checker board

glyphDegree :: Glyph

Degree symbol

glyphPlusMinus :: Glyph

Plus/minus

glyphBullet :: Glyph

Bullet

Teletype 5410v1 symbols

glyphArrowL :: Glyph

Arrow pointing left

glyphArrowR :: Glyph

Arrow pointing right

glyphArrowD :: Glyph

Arrow pointing down

glyphArrowU :: Glyph

Arrow pointing up

glyphBoard :: Glyph

Board of squares

glyphLantern :: Glyph

Lantern symbol

glyphBlock :: Glyph

Solid square block

Other glyphs

glyphS3 :: Glyph

Scan line 3

glyphS7 :: Glyph

Scan line 7

glyphNE :: Glyph

Not equal

glyphLTE :: Glyph

Less than or equal

glyphGTE :: Glyph

Greater than or equal

glyphPi :: Glyph

Pi

glyphSterling :: Glyph

UK pounds sterling symbol

Event handling

data Event

Constructors

EventCharacter Char

EventSpecialKey Key

EventMouse Integer MouseState

EventResized

EventUnknown Integer

Instances

Eq Event

Methods

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

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

Show Event

Methods

showsPrec :: Int -> Event -> ShowS

show :: Event -> String

showList :: [Event] -> ShowS

getEvent

Arguments

:: Window

-> Maybe Integer

Timeout, in milliseconds

-> Curses (Maybe Event)

Get the next Event from a given window.

If the timeout is Nothing, getEvent blocks until an event is received.

If the timeout is specified, getEvent blocks for up to that many milliseconds. If no event is received before timing out, getEvent returns Nothing.

If the timeout is 0 or less, getEvent will not block at all.

Keyboard events

data Key

Constructors

KeyUpArrow

KeyDownArrow

KeyLeftArrow

KeyRightArrow

KeyHome

KeyBackspace

KeyFunction Integer

Function keys, F0 – F64

KeyDeleteLine

KeyInsertLine

KeyDeleteCharacter

KeyInsertCharacter

KeyEIC

Sent by rmir or smir in insert mode

KeyClear

Clear screen

KeyEOS

Clear to end of screen

KeyEOL

Clear to end of line

KeyScrollForward

KeyScrollBackward

KeyNextPage

KeyPreviousPage

KeySetTab

KeyClearTab

KeyClearAllTabs

KeyEnter

KeyPrint

KeyHomeDown

KeyA1

Upper left of keypad

KeyA3

Upper right of keypad

KeyB2

Center of keypad

KeyC1

Lower left of keypad

KeyC3

Lower right of keypad

KeyBackTab

KeyBegin

KeyCancel

KeyClose

KeyCommand

KeyCopy

KeyCreate

KeyEnd

KeyExit

KeyFind

KeyHelp

KeyMark

KeyMessage

KeyMove

KeyNext

KeyOpen

KeyOptions

KeyPrevious

KeyRedo

KeyReference

KeyRefresh

KeyReplace

KeyRestart

KeyResume

KeySave

KeyShiftedBegin

KeyShiftedCancel

KeyShiftedCommand

KeyShiftedCopy

KeyShiftedCreate

KeyShiftedDeleteCharacter

KeyShiftedDeleteLine

KeySelect

KeyShiftedEnd

KeyShiftedEOL

KeyShiftedExit

KeyShiftedFind

KeyShiftedHelp

KeyShiftedHome

KeyShiftedInsertCharacter

KeyShiftedLeftArrow

KeyShiftedMessage

KeyShiftedMove

KeyShiftedNext

KeyShiftedOptions

KeyShiftedPrevious

KeyShiftedPrint

KeyShiftedRedo

KeyShiftedReplace

KeyShiftedRightArrow

KeyShiftedResume

KeyShiftedSave

KeyShiftedSuspend

KeyShiftedUndo

KeySuspend

KeyUndo

Instances

Eq Key

Methods

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

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

Show Key

Methods

showsPrec :: Int -> Key -> ShowS

show :: Key -> String

showList :: [Key] -> ShowS

Mouse events

data ButtonState

Constructors

ButtonPressed

ButtonReleased

ButtonClicked

ButtonDoubleClicked

ButtonTripleClicked

Instances

Eq ButtonState

Methods

(==) :: ButtonState -> ButtonState -> Bool

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

Show ButtonState

Methods

showsPrec :: Int -> ButtonState -> ShowS

show :: ButtonState -> String

showList :: [ButtonState] -> ShowS

data MouseState

Constructors

MouseState

Fields

• mouseCoordinates :: (Integer, Integer, Integer)

  (X, Y, Z)

• mouseButtons :: [(Integer, ButtonState)]

  If the mouse event was caused by a change in button state, the buttons and their new state will be listed here.

• mouseAlt :: Bool
• mouseShift :: Bool
• mouseControl :: Bool

Instances

Eq MouseState

Methods

(==) :: MouseState -> MouseState -> Bool

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

Show MouseState

Methods

showsPrec :: Int -> MouseState -> ShowS

show :: MouseState -> String

showList :: [MouseState] -> ShowS

Cursor mode

data CursorMode

Constructors

CursorInvisible

CursorVisible

CursorVeryVisible

Instances

Eq CursorMode

Methods

(==) :: CursorMode -> CursorMode -> Bool

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

Show CursorMode

Methods

showsPrec :: Int -> CursorMode -> ShowS

show :: CursorMode -> String

showList :: [CursorMode] -> ShowS

setCursorMode :: CursorMode -> Curses CursorMode

Set the current cursor mode to visible, invisible, or "very visible". The previous cursor mode is returned.

Error handling

tryCurses :: Curses a -> Curses (Either CursesException a)

Returns Left if a Curses exception occured in the given computation.

See try for more details.

catchCurses :: Curses a -> (CursesException -> Curses a) -> Curses a

Handles errors in the given computation by passing them to a callback.

See catch for more details.

throwCurses :: CursesException -> Curses a

Throws an exception from within Curses handling code. This is useful for re-throwing errors from within a catchCurses callback.

See throwIO for more details.

misc

setRaw :: Bool -> Curses ()

Runs raw() or noraw()

setCBreak :: Bool -> Curses ()

Runs cbreak() or nocbreak()

setEcho :: Bool -> Curses ()

Runs echo() or noecho()

baudrate :: Curses Integer

Get the output speed of the current terminal, in bits per second.

beep :: Curses ()

flash :: Curses ()

hasMouse :: Curses Bool

Check if the terminal has a mouse

enclosed

Arguments

:: Window

-> Integer

Row

-> Integer

Column

-> Curses Bool

Check if some position is contained within the given Window.

screenSize :: Curses (Integer, Integer)

Return (rows, columns) of current screen

setTouched :: Bool -> Update ()

Set whether the entire window has been “touched”; touched characters are redrawn on the next refresh.

setRowsTouched

Arguments

:: Bool

-> Integer

Start

-> Integer

Count

-> Update ()

Set whether particular rows in the window have been “touched”.

setKeypad :: Window -> Bool -> Curses ()

Enable/disable support for special keys.

resizeTerminal :: Integer -> Integer -> Curses ()

Attempt to resize the terminal to the given number of lines and columns.