UI.NCurses

Primary types

data Curses a

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

Instances

Monad Curses

Functor Curses

MonadFix Curses

Applicative Curses

MonadIO Curses

data Update a

Instances

Monad Update

Functor Update

MonadFix Update

Applicative Update

data Window

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.

Drawing to the screen

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.

render :: Curses ()

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

moveCursor

Arguments

:: Integer

Row

-> Integer

Column

-> Update ()

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

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.

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.

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

AttributeStandout

AttributeUnderline

AttributeReverse

AttributeBlink

AttributeDim

AttributeBold

AttributeAltCharset

AttributeInvisible

AttributeProtect

Instances

Eq Attribute

Show Attribute

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.

Instances

Eq Color

Show Color

data ColorID

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

Instances

Eq ColorID

Show ColorID

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

Show Glyph

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

Show Event

getEvent

Arguments

:: Window

-> Maybe Integer

Timeout, in milliseconds

-> Curses (Maybe Event)

Get the next Event from a given window.

If the timeout is specified, and no event is received within the timeout, 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

Show Key

Mouse events

data ButtonState

Constructors

ButtonPressed

ButtonReleased

ButtonClicked

ButtonDoubleClicked

ButtonTripleClicked

Instances

Eq ButtonState

Show ButtonState

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

Show MouseState

Cursor mode

data CursorMode

Constructors

CursorInvisible

CursorVisible

CursorVeryVisible

Instances

Eq CursorMode

Show CursorMode

setCursorMode :: CursorMode -> Curses CursorMode

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

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.

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