ncurses-0.2.16: Modernised bindings to GNU ncurses

Safe HaskellNone
LanguageHaskell98

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

data CursesException

Instances

Show CursesException 
Exception CursesException 
Typeable * CursesException 

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

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.

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

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 
Show Color 

maxColor :: Curses Integer

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

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

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

glyphStipple :: Glyph

Stipple, or checker board

glyphDegree :: Glyph

Degree symbol

glyphPlusMinus :: Glyph

Plus/minus

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

glyphSterling :: Glyph

UK pounds sterling symbol

Event handling

data Event

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

Mouse events

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

Cursor mode

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

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.