ncurses-0.2.11: Modernised bindings to GNU ncurses

Safe Haskell | Safe
Language | Haskell98

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
- Cursor mode
- misc

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
  - | ColorDefault
- 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
  }
- data CursorMode
  - = CursorInvisible
  - | CursorVisible
  - | CursorVeryVisible
- setCursorMode :: CursorMode -> Curses CursorMode
- 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 Source |
Functor Curses Source |
MonadFix Curses Source |
Applicative Curses Source |
MonadIO Curses Source |

data Update a Source

Instances

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

data Window Source

# Initialization

runCurses :: Curses a -> IO a Source

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

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 Source |
Show Attribute Source |

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

data ColorID Source

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

Instances

Eq ColorID Source |
Show ColorID Source |

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 Source |
Show Glyph Source |

## 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 Source |
Show Event Source |

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 Source |
Show Key Source |

## Mouse events

data ButtonState Source

Constructors

ButtonPressed |
ButtonReleased |
ButtonClicked |
ButtonDoubleClicked |
ButtonTripleClicked |

Instances

Eq ButtonState Source |
Show ButtonState Source |

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 Source |
Show MouseState Source |

# Cursor mode

data CursorMode Source

Constructors

CursorInvisible |
CursorVisible |
CursorVeryVisible |

Instances

Eq CursorMode Source |
Show CursorMode Source |

setCursorMode :: CursorMode -> Curses CursorMode Source

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