ncurses-0.2.1: Modernised bindings to GNU ncurses

Portability | portable (requires FFI)
Maintainer | jmillikin@gmail.com
Safe Haskell | None

UI.NCurses

Contents

- Primary types
- Initialization
- Window management
- Drawing to the screen
- Attributes
- Colors
- Glyphs
  - VT100 drawing glyphs
  - Teletype 5410v1 symbols
  - Other glyphs
- Event handling
  - Keyboard events
  - Mouse events
- misc

Description

Synopsis

- data Curses a
- data Update a
- data Window
- runCurses :: Curses a -> IO a
- defaultWindow :: Curses Window
- newWindow :: Integer -> Integer -> Integer -> Integer -> Curses Window
- closeWindow :: Window -> Curses ()
- cloneWindow :: Window -> Curses Window
- updateWindow :: Window -> Update a -> Curses a
- render :: Curses ()
- moveCursor :: Integer -> Integer -> Update ()
- setColor :: ColorID -> Update ()
- drawString :: String -> Update ()
- drawText :: Text -> Update ()
- drawBorder :: Maybe Glyph -> Maybe Glyph -> Maybe Glyph -> Maybe Glyph -> Maybe Glyph -> Maybe Glyph -> Maybe Glyph -> Maybe Glyph -> Update ()
- drawBox :: Maybe Glyph -> Maybe Glyph -> Update ()
- drawLineH :: Maybe Glyph -> Integer -> Update ()
- drawLineV :: Maybe Glyph -> Integer -> Update ()
- setBackground :: Glyph -> Update ()
- data Attribute
  - = AttributeStandout
  - | AttributeUnderline
  - | AttributeReverse
  - | AttributeBlink
  - | AttributeDim
  - | AttributeBold
  - | AttributeAltCharset
  - | AttributeInvisible
  - | AttributeProtect
- setAttribute :: Attribute -> Bool -> Update ()
- setAttributes :: [Attribute] -> Update ()
- data Color
  - = ColorBlack
  - | ColorRed
  - | ColorGreen
  - | ColorYellow
  - | ColorBlue
  - | ColorMagenta
  - | ColorCyan
  - | ColorWhite
- data ColorID
- supportsColor :: Curses Bool
- canDefineColor :: Curses Bool
- defineColor :: Color -> Integer -> Integer -> Integer -> Curses ()
- queryColor :: Color -> Curses (Integer, Integer, Integer)
- defaultColorID :: ColorID
- newColorID :: Color -> Color -> Integer -> Curses ColorID
- setColorID :: Color -> Color -> ColorID -> Curses ()
- maxColorID :: Curses Integer
- data Glyph = Glyph {
  - glyphCharacter :: Char
  - glyphAttributes :: [Attribute]
  }
- glyphCornerUL :: Glyph
- glyphCornerLL :: Glyph
- glyphCornerUR :: Glyph
- glyphCornerLR :: Glyph
- glyphTeeL :: Glyph
- glyphTeeR :: Glyph
- glyphTeeB :: Glyph
- glyphTeeT :: Glyph
- glyphLineH :: Glyph
- glyphLineV :: Glyph
- glyphPlus :: Glyph
- glyphScan1 :: Glyph
- glyphScan9 :: Glyph
- glyphDiamond :: Glyph
- glyphStipple :: Glyph
- glyphDegree :: Glyph
- glyphPlusMinus :: Glyph
- glyphBullet :: Glyph
- glyphArrowL :: Glyph
- glyphArrowR :: Glyph
- glyphArrowD :: Glyph
- glyphArrowU :: Glyph
- glyphBoard :: Glyph
- glyphLantern :: Glyph
- glyphBlock :: Glyph
- glyphS3 :: Glyph
- glyphS7 :: Glyph
- glyphNE :: Glyph
- glyphLTE :: Glyph
- glyphGTE :: Glyph
- glyphPi :: Glyph
- glyphSterling :: Glyph
- data Event
  - = EventCharacter Char
  - | EventSpecialKey Key
  - | EventMouse Integer MouseState
  - | EventResized
  - | EventUnknown Integer
- getEvent :: Window -> Maybe Integer -> Curses (Maybe Event)
- data Key
  - = KeyUpArrow
  - | KeyDownArrow
  - | KeyLeftArrow
  - | KeyRightArrow
  - | KeyHome
  - | KeyBackspace
  - | KeyFunction Integer
  - | KeyDeleteLine
  - | KeyInsertLine
  - | KeyDeleteCharacter
  - | KeyInsertCharacter
  - | KeyEIC
  - | KeyClear
  - | KeyEOS
  - | KeyEOL
  - | KeyScrollForward
  - | KeyScrollBackward
  - | KeyNextPage
  - | KeyPreviousPage
  - | KeySetTab
  - | KeyClearTab
  - | KeyClearAllTabs
  - | KeyEnter
  - | KeyPrint
  - | KeyHomeDown
  - | KeyA1
  - | KeyA3
  - | KeyB2
  - | KeyC1
  - | KeyC3
  - | 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
- data ButtonState
  - = ButtonPressed
  - | ButtonReleased
  - | ButtonClicked
  - | ButtonDoubleClicked
  - | ButtonTripleClicked
- data MouseState = MouseState {
  - mouseCoordinates :: (Integer, Integer, Integer)
  - mouseButtons :: [(Integer, ButtonState)]
  - mouseAlt :: Bool
  - mouseShift :: Bool
  - mouseControl :: Bool
  }
- setRaw :: Bool -> Curses ()
- setCBreak :: Bool -> Curses ()
- setEcho :: Bool -> Curses ()
- baudrate :: Curses Integer
- beep :: Curses ()
- flash :: Curses ()
- hasMouse :: Curses Bool
- enclosed :: Window -> Integer -> Integer -> Curses Bool
- screenSize :: Curses (Integer, Integer)
- setTouched :: Bool -> Update ()
- setRowsTouched :: Bool -> Integer -> Integer -> Update ()
- setKeypad :: Window -> Bool -> Curses ()
- getCursor :: Window -> Curses (Integer, Integer)

# Primary types

data Curses a Source

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 Source

Instances

Monad Update |
Functor Update |
MonadFix Update |
Applicative Update |

data Window Source

# 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 Window Source

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

# Window management

newWindow Source

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

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.

moveCursor Source

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.

drawBorder Source

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

data Attribute Source

Constructors

AttributeStandout |
AttributeUnderline |
AttributeReverse |
AttributeBlink |
AttributeDim |
AttributeBold |
AttributeAltCharset |
AttributeInvisible |
AttributeProtect |

Instances

Eq Attribute |
Show Attribute |

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

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

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

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

# Colors

data Color Source

Constructors

ColorBlack |
ColorRed |
ColorGreen |
ColorYellow |
ColorBlue |
ColorMagenta |
ColorCyan |
ColorWhite |

Instances

Eq Color |
Show Color |

data ColorID Source

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

Instances

Eq ColorID |
Show ColorID |

supportsColor :: Curses Bool Source

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

canDefineColor :: Curses Bool Source

Check if the terminal supports changing color defintiions.

defineColor Source

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 :: ColorID Source

The default color ID

newColorID Source

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 Source

Arguments

:: Color | Foreground
-> Color | Background
-> ColorID | The `ColorID` to change
-> Curses () |

maxColorID :: Curses Integer Source

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 |

Fields

glyphCharacter :: Char
glyphAttributes :: [Attribute]

Instances

Eq Glyph |
Show Glyph |

## VT100 drawing glyphs

glyphCornerUL :: Glyph Source

Upper left corner

glyphCornerLL :: Glyph Source

Lower left corner

glyphCornerUR :: Glyph Source

Upper right corner

glyphCornerLR :: Glyph Source

Lower right corner

glyphTeeL :: Glyph Source

Tee pointing right

glyphTeeR :: Glyph Source

Tee pointing left

glyphTeeB :: Glyph Source

Tee pointing up

glyphTeeT :: Glyph Source

Tee pointing down

glyphLineH :: Glyph Source

Horizontal line

glyphLineV :: Glyph Source

Vertical line

glyphPlus :: Glyph Source

Large plus or crossover

glyphScan1 :: Glyph Source

Scan line 1

glyphScan9 :: Glyph Source

Scan line 9

glyphDiamond :: Glyph Source

Diamond

glyphStipple :: Glyph Source

Stipple, or checker board

glyphDegree :: Glyph Source

Degree symbol

glyphPlusMinus :: Glyph Source

Plus/minus

glyphBullet :: Glyph Source

Bullet

## Teletype 5410v1 symbols

glyphArrowL :: Glyph Source

Arrow pointing left

glyphArrowR :: Glyph Source

Arrow pointing right

glyphArrowD :: Glyph Source

Arrow pointing down

glyphArrowU :: Glyph Source

Arrow pointing up

glyphBoard :: Glyph Source

Board of squares

glyphLantern :: Glyph Source

Lantern symbol

glyphBlock :: Glyph Source

Solid square block

## Other glyphs

glyphS3 :: Glyph Source

Scan line 3

glyphS7 :: Glyph Source

Scan line 7

glyphNE :: Glyph Source

Not equal

glyphLTE :: Glyph Source

Less than or equal

glyphGTE :: Glyph Source

Greater than or equal

glyphPi :: Glyph Source

Pi

glyphSterling :: Glyph Source

UK pounds sterling symbol

# Event handling

data Event Source

Constructors

EventCharacter Char |
EventSpecialKey Key |
EventMouse Integer MouseState |
EventResized |
EventUnknown Integer |

Instances

Eq Event |
Show Event |

getEvent Source

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 Source

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 Source

Constructors

ButtonPressed |
ButtonReleased |
ButtonClicked |
ButtonDoubleClicked |
ButtonTripleClicked |

Instances

Eq ButtonState |
Show ButtonState |

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

Instances

Eq MouseState |
Show MouseState |

# 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 Integer Source

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

beep :: Curses ()Source

flash :: Curses ()Source

hasMouse :: Curses Bool Source

Check if the terminal has a mouse

enclosed Source

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.

setRowsTouched Source

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.

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