UI.HSCurses.Curses

Binding to the [wn]curses library. From the ncurses man page:

      The curses library routines give the user a terminal-inde-
      pendent method of updating character screens with  reason-
      able  optimization.

Sections of the quoted documentation are from the OpenBSD man pages, which are distributed under a BSD license.

A useful reference is: Writing Programs with NCURSES, by Eric S. Raymond and Zeyd M. Ben-Halim, http://dickey.his.com/ncurses/

N.B attrs don't work with Irix curses.h. This should be fixed.

Basic Functions

stdScr :: Window

The standard screen

initScr :: IO Window

initscr is normally the first curses routine to call when initializing a program. curs_initscr(3):

     To initialize the routines, the routine initscr or newterm
     must be called before any of the other routines that  deal
     with  windows  and  screens  are used.

     The initscr code determines the terminal type and initial-
     izes all curses data structures.  initscr also causes  the
     first  call  to  refresh  to  clear the screen.  If errors
     occur, initscr writes  an  appropriate  error  message  to
     standard error and exits; otherwise, a pointer is returned
     to stdscr.

initCurses :: IO ()

initCurses fn does all initialization necessary for a Curses application.

resetParams :: IO ()

endWin :: IO ()

  The program must call endwin for each terminal being used before
  exiting from curses.

scrSize :: IO (Int, Int)

get the dimensions of the screen

Windows and Pads

type Window = Ptr WindowTag

touchWin :: Window -> IO ()

newPad :: Int -> Int -> IO Window

pRefresh :: Window -> Int -> Int -> Int -> Int -> Int -> Int -> IO ()

delWin :: Window -> IO ()

newWin :: Int -> Int -> Int -> Int -> IO Window

Refresh Routines

refresh :: IO ()

refresh curses windows and lines. curs_refresh(3)

update :: IO ()

Do an actual update. Used after endWin on linux to restore the terminal

resizeTerminal :: Int -> Int -> IO ()

timeout :: Int -> IO ()

Set a delay in milliseconds.

noqiflush :: IO ()

Navigation

move :: Int -> Int -> IO ()

    move the cursor associated with the window
    to line y and column x.  This routine does  not  move  the
    physical  cursor  of the terminal until refresh is called.
    The position specified is relative to the upper  left-hand
    corner of the window, which is (0,0).

Note that move_c may be a macro.

getYX :: Window -> IO (Int, Int)

Get the current cursor coordinates

Input

getCh :: IO Key

read a character from the window

getch :: IO CInt

      The getch, wgetch, mvgetch and mvwgetch, routines read a
      character  from the window.

decodeKey :: CInt -> Key

ungetCh :: Integral a => a -> IO ()

keyResizeCode :: Maybe CInt

Input Options

cBreak :: Bool -> IO ()

 The cbreak routine
 disables line buffering and erase/kill  character-process-
 ing  (interrupt  and  flow  control  characters  are unaf-
 fected), making characters typed by the  user  immediately
 available  to  the  program.  The nocbreak routine returns
 the terminal to normal (cooked) mode.

raw :: Bool -> IO ()

    The  raw and noraw routines place the terminal into or out
     of raw mode.  Raw mode is similar to cbreak mode, in  that
     characters  typed  are  immediately  passed through to the
     user program.  The differences are that in raw  mode,  the
     interrupt,  quit, suspend, and flow control characters are
     all passed through uninterpreted, instead of generating  a
     signal.   The  behavior  of the BREAK key depends on other
     bits in the tty driver that are not set by curses.

echo :: Bool -> IO ()

      The  echo  and  noecho routines control whether characters
       typed by the user are echoed by getch as they  are  typed.
       Echoing  by  the  tty  driver is always disabled, but ini-
       tially getch is in echo  mode,  so  characters  typed  are
       echoed.  Authors of most interactive programs prefer to do
       their own echoing in a controlled area of the  screen,  or
       not  to  echo  at  all, so they disable echoing by calling
       noecho.  [See curs_getch(3) for a discussion of how  these
       routines interact with cbreak and nocbreak.]

intrFlush :: Bool -> IO ()

       If  the intrflush option is enabled, (bf is TRUE), when an
        interrupt key  is  pressed  on  the  keyboard  (interrupt,
        break,  quit)  all  output in the tty driver queue will be
        flushed, giving the  effect  of  faster  response  to  the
        interrupt,  but  causing  curses to have the wrong idea of
        what is on the  screen.   Disabling  (bf  is  FALSE),  the
        option  prevents the flush.

keypad :: Window -> Bool -> IO ()

Enable the keypad of the user's terminal.

noDelay :: Window -> Bool -> IO ()

Output

wAddStr :: Window -> [Char] -> IO ()

normalise the string, stripping \r and making control chars printable. Called over all output(?)

addLn :: IO ()

mvWAddStr :: Window -> Int -> Int -> String -> IO ()

mvAddCh :: Int -> Int -> ChType -> IO ()

wMove :: Window -> Int -> Int -> IO ()

    move the cursor associated with the window
    to line y and column x.  This routine does  not  move  the
    physical  cursor  of the terminal until refresh is called.
    The position specified is relative to the upper  left-hand
    corner of the window, which is (0,0).

bkgrndSet :: Attr -> Pair -> IO ()

erase :: IO ()

wclear :: Window -> IO ()

clrToEol :: IO ()

wClrToEol :: Window -> IO ()

beep :: IO ()

waddch :: Window -> ChType -> IO CInt

waddchnstr :: Window -> CString -> CInt -> IO CInt

Output Options

clearOk :: Bool -> IO CInt

leaveOk :: Bool -> IO CInt

Normally, the hardware cursor is left at the location of the window cursor being refreshed. The leaveok option allows the cursor to be left wherever the update happens to leave it. It is useful for applications where the cur- sor is not used, since it reduces the need for cursor motions. If possible, the cursor is made invisible when this option is enabled.

nl :: Bool -> IO ()

       The  nl  and  nonl routines control whether the underlying
        display device translates the return key into  newline  on
        input,  and  whether it translates newline into return and
        line-feed on output (in either case, the call  addch('\n')
        does the equivalent of return and line feed on the virtual
        screen).  Initially, these translations do occur.  If  you
        disable  them using nonl, curses will be able to make bet-
        ter use of the line-feed capability, resulting  in  faster
        cursor  motion.   Also, curses will then be able to detect
        the return key.

Cursor Routines

data CursorVisibility

Constructors

CursorInvisible

CursorVisible

CursorVeryVisible

cursSet :: CursorVisibility -> IO CursorVisibility

Set the cursor state

       The curs_set routine sets  the  cursor  state  is  set  to
       invisible, normal, or very visible for visibility equal to
       0, 1, or 2 respectively.  If  the  terminal  supports  the
       visibility   requested,   the  previous  cursor  state  is
       returned; otherwise, ERR is returned.

Color Support

hasColors :: IO Bool

startColor :: IO ()

Initialise the color settings, also sets the screen to the default colors (white on black)

useDefaultColors :: IO ()

newtype Pair

Constructors

Pair Int

Instances

Eq Pair

Ord Pair

Show Pair

Ix Pair

colorPairs :: IO Int

colorPairs defines the maximum number of color-pairs the terminal can support).

newtype Color

Constructors

Color Int

Instances

Eq Color

Ord Color

Ix Color

colors :: IO Int

color :: String -> Maybe Color

initPair :: Pair -> Color -> Color -> IO ()

curses support color attributes on terminals with that capability. To use these routines start_color must be called, usually right after initscr. Colors are always used in pairs (referred to as color-pairs). A color-pair consists of a foreground color (for characters) and a background color (for the blank field on which the charac- ters are displayed). A programmer initializes a color- pair with the routine init_pair. After it has been ini- tialized, COLOR_PAIR(n), a macro defined in curses.h, can be used as a new video attribute.

If a terminal is capable of redefining colors, the pro- grammer can use the routine init_color to change the defi- nition of a color.

The init_pair routine changes the definition of a color- pair. It takes three arguments: the number of the color- pair to be changed, the foreground color number, and the background color number. For portable applications:

• The value of the first argument must be between 1 and COLOR_PAIRS-1.
• The value of the second and third arguments must be between 0 and COLORS (the 0 color pair is wired to white on black and cannot be changed).

pairContent :: Pair -> IO (Color, Color)

canChangeColor :: IO Bool

initColor :: Color -> (Int, Int, Int) -> IO ()

colorContent :: Color -> IO (Int, Int, Int)

defaultBackground :: Color

defaultForeground :: Color

Attributes

attrPlus :: Attr -> Attr -> Attr

data Attr

Instances

Eq Attr

Num Attr

Show Attr

Storable Attr

Bits Attr

attr0 :: Attr

Normal display (no highlight)

isAltCharset :: Attr -> Bool

isBlink :: Attr -> Bool

isBold :: Attr -> Bool

isDim :: Attr -> Bool

isHorizontal :: Attr -> Bool

isInvis :: Attr -> Bool

isLeft :: Attr -> Bool

isLow :: Attr -> Bool

isProtect :: Attr -> Bool

isReverse :: Attr -> Bool

isRight :: Attr -> Bool

isStandout :: Attr -> Bool

isTop :: Attr -> Bool

isUnderline :: Attr -> Bool

isVertical :: Attr -> Bool

setAltCharset :: Attr -> Bool -> Attr

setBlink :: Attr -> Bool -> Attr

Setting attributes

setBold :: Attr -> Bool -> Attr

setDim :: Attr -> Bool -> Attr

setHorizontal :: Attr -> Bool -> Attr

setInvis :: Attr -> Bool -> Attr

setLeft :: Attr -> Bool -> Attr

setLow :: Attr -> Bool -> Attr

setProtect :: Attr -> Bool -> Attr

setReverse :: Attr -> Bool -> Attr

setRight :: Attr -> Bool -> Attr

setStandout :: Attr -> Bool -> Attr

setTop :: Attr -> Bool -> Attr

setUnderline :: Attr -> Bool -> Attr

setVertical :: Attr -> Bool -> Attr

attrSet :: Attr -> Pair -> IO ()

attrOn :: Attr -> IO ()

attrOff :: Attr -> IO ()

standout :: IO Int

standend :: IO Int

attrDim :: Int

attrBold :: Int

attrDimOn :: IO ()

attrDimOff :: IO ()

attrBoldOn :: IO ()

attrBoldOff :: IO ()

wAttrOn :: Window -> Int -> IO ()

wAttrOff :: Window -> Int -> IO ()

wAttrSet :: Window -> (Attr, Pair) -> IO ()

wAttrGet :: Window -> IO (Attr, Pair)

manipulate the current attributes of the named window. see curs_attr(3)

Mouse Routines

withMouseEventMask :: MonadIO m => [ButtonEvent] -> m a -> m a

data ButtonEvent

Constructors

ButtonPressed Int

ButtonReleased Int

ButtonClicked Int

ButtonDoubleClicked Int

ButtonTripleClicked Int

ButtonShift

ButtonControl

ButtonAlt

Instances

Eq ButtonEvent

Show ButtonEvent

data MouseEvent

Constructors

MouseEvent

Fields

mouseEventId :: Int

mouseEventX :: Int

mouseEventY :: Int

mouseEventZ :: Int

mouseEventButton :: [ButtonEvent]

Instances

Show MouseEvent

Keys

data Key

Map curses keys to key abstraction

Constructors

KeyChar Char

KeyBreak

KeyDown

KeyUp

KeyLeft

KeyRight

KeyHome

KeyBackspace

KeyF Int

KeyDL

KeyIL

KeyDC

KeyIC

KeyEIC

KeyClear

KeyEOS

KeyEOL

KeySF

KeySR

KeyNPage

KeyPPage

KeySTab

KeyCTab

KeyCATab

KeyEnter

KeySReset

KeyReset

KeyPrint

KeyLL

KeyA1

KeyA3

KeyB2

KeyC1

KeyC3

KeyBTab

KeyBeg

KeyCancel

KeyClose

KeyCommand

KeyCopy

KeyCreate

KeyEnd

KeyExit

KeyFind

KeyHelp

KeyMark

KeyMessage

KeyMove

KeyNext

KeyOpen

KeyOptions

KeyPrevious

KeyRedo

KeyReference

KeyRefresh

KeyReplace

KeyRestart

KeyResume

KeySave

KeySBeg

KeySCancel

KeySCommand

KeySCopy

KeySCreate

KeySDC

KeySDL

KeySelect

KeySEnd

KeySEOL

KeySExit

KeySFind

KeySHelp

KeySHome

KeySIC

KeySLeft

KeySMessage

KeySMove

KeySNext

KeySOptions

KeySPrevious

KeySPrint

KeySRedo

KeySReplace

KeySRight

KeySRsume

KeySSave

KeySSuspend

KeySUndo

KeySuspend

KeyUndo

KeyResize

KeyMouse

KeyUnknown Int

Instances

Eq Key

Show Key

cERR :: CInt

cKEY_UP :: ChType

cKEY_DOWN :: ChType

cKEY_LEFT :: ChType

cKEY_RIGHT :: ChType

cTRUE :: NBool

Lines

vline :: Char -> Int -> IO ()

ulCorner :: Char

llCorner :: Char

urCorner :: Char

lrCorner :: Char

rTee :: Char

lTee :: Char

bTee :: Char

tTee :: Char

hLine :: Char

vLine :: Char

plus :: Char

s1 :: Char

s9 :: Char

diamond :: Char

ckBoard :: Char

degree :: Char

plMinus :: Char

bullet :: Char

lArrow :: Char

rArrow :: Char

dArrow :: Char

uArrow :: Char

board :: Char

lantern :: Char

block :: Char

s3 :: Char

s7 :: Char

lEqual :: Char

gEqual :: Char

pi :: Char

nEqual :: Char

sterling :: Char

Signals

cursesSigWinch :: Maybe Signal

The SIGWINCH signal is sent whenever the terminal size changes. This signal is not available on all platforms, so it is a |Maybe| value.

Misc

cursesTest :: IO ()

throwIfErr :: Num a => String -> IO a -> IO a

throwIfErr_ :: Num a => String -> IO a -> IO ()

errI :: IO CInt -> IO ()

flushinp :: IO CInt

recognize :: Char -> IO a -> (ChType -> IO a) -> IO a

type ChType = Word32

type NBool = Word8