hscurses-1.2: NCurses bindings for Haskell




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

The standard screen

initScr :: IO WindowSource

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

initCurses fn does all initialization necessary for a Curses application.

endWin :: IO ()Source

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

scrSize :: IO (Int, Int)Source

get the dimensions of the screen

Windows and Pads

type Window = Ptr WindowTagSource

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

Refresh Routines

refresh :: IO ()Source

refresh curses windows and lines. curs_refresh(3)

update :: IO ()Source

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


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

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

Get the current cursor coordinates


getCh :: IO KeySource

read a character from the window

getch :: IO CIntSource

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

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

Input Options

cBreak :: Bool -> IO ()Source

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

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

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

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

Enable the keypad of the user's terminal.


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

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

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

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

Output Options

leaveOk :: Bool -> IO CIntSource

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

       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

cursSet :: CursorVisibility -> IO CursorVisibilitySource

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

startColor :: IO ()Source

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

newtype Pair Source


Pair Int 


colorPairs :: IO IntSource

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

newtype Color Source


Color Int 


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

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


attr0 :: AttrSource

Normal display (no highlight)

setBlink :: Attr -> Bool -> AttrSource

Setting attributes

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

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

Mouse Routines




cursesSigWinch :: Maybe SignalSource

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


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

recognize :: Char -> IO a -> (Word32 -> IO a) -> IO aSource