ncurses-0.2.3: Modernised bindings to GNU ncurses

Safe HaskellSafe-Infered

UI.NCurses

Contents

Synopsis

Primary types

data Curses a Source

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

Initialization

runCurses :: Curses a -> IO aSource

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 WindowSource

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

Window management

newWindowSource

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

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 WindowSource

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

Drawing to the screen

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

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

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

moveCursorSource

Arguments

:: Integer

Row

-> Integer

Column

-> Update () 

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

setColor :: ColorID -> Update ()Source

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

drawString :: String -> Update ()Source

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

drawText :: Text -> Update ()Source

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

drawBorderSource

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

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

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

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

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

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

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

setAttributes :: [Attribute] -> Update ()Source

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

Colors

data ColorID Source

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

Instances

supportsColor :: Curses BoolSource

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

canDefineColor :: Curses BoolSource

Check if the terminal supports changing color defintiions.

defineColorSource

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

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

defaultColorID :: ColorIDSource

The default color ID

newColorIDSource

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.

setColorIDSource

Arguments

:: Color

Foreground

-> Color

Background

-> ColorID

The ColorID to change

-> Curses () 

maxColorID :: Curses IntegerSource

Get the maximum color ID supported by the current terminal

Glyphs

data Glyph Source

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

Constructors

Glyph 

Instances

VT100 drawing glyphs

glyphCornerUL :: GlyphSource

Upper left corner

glyphCornerLL :: GlyphSource

Lower left corner

glyphCornerUR :: GlyphSource

Upper right corner

glyphCornerLR :: GlyphSource

Lower right corner

glyphTeeL :: GlyphSource

Tee pointing right

glyphTeeR :: GlyphSource

Tee pointing left

glyphTeeB :: GlyphSource

Tee pointing up

glyphTeeT :: GlyphSource

Tee pointing down

glyphLineH :: GlyphSource

Horizontal line

glyphLineV :: GlyphSource

Vertical line

glyphPlus :: GlyphSource

Large plus or crossover

glyphScan1 :: GlyphSource

Scan line 1

glyphScan9 :: GlyphSource

Scan line 9

glyphStipple :: GlyphSource

Stipple, or checker board

glyphDegree :: GlyphSource

Degree symbol

Teletype 5410v1 symbols

glyphArrowL :: GlyphSource

Arrow pointing left

glyphArrowR :: GlyphSource

Arrow pointing right

glyphArrowD :: GlyphSource

Arrow pointing down

glyphArrowU :: GlyphSource

Arrow pointing up

glyphBoard :: GlyphSource

Board of squares

glyphLantern :: GlyphSource

Lantern symbol

glyphBlock :: GlyphSource

Solid square block

Other glyphs

glyphS3 :: GlyphSource

Scan line 3

glyphS7 :: GlyphSource

Scan line 7

glyphNE :: GlyphSource

Not equal

glyphLTE :: GlyphSource

Less than or equal

glyphGTE :: GlyphSource

Greater than or equal

glyphSterling :: GlyphSource

UK pounds sterling symbol

Event handling

getEventSource

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

Mouse events

data MouseState Source

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
 

Cursor mode

setCursorMode :: CursorMode -> Curses CursorModeSource

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

misc

setRaw :: Bool -> Curses ()Source

Runs raw() or noraw()

setCBreak :: Bool -> Curses ()Source

Runs cbreak() or nocbreak()

setEcho :: Bool -> Curses ()Source

Runs echo() or noecho()

baudrate :: Curses IntegerSource

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

hasMouse :: Curses BoolSource

Check if the terminal has a mouse

enclosedSource

Arguments

:: Window 
-> Integer

Row

-> Integer

Column

-> Curses Bool 

Check if some position is contained within the given Window.

screenSize :: Curses (Integer, Integer)Source

Return (rows, columns) of current screen

setTouched :: Bool -> Update ()Source

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

setRowsTouchedSource

Arguments

:: Bool 
-> Integer

Start

-> Integer

Count

-> Update () 

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

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

Enable/disable support for special keys.