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 (lines,cols)

Windows and Pads

type Window = Ptr WindowTag

data Border

Constructors

Border

Fields

ls :: Char

rs :: Char

ts :: Char

bs :: Char

tl :: Char

tr :: Char

bl :: Char

br :: Char

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

wRefresh :: Window -> IO ()

wRefresh refreshes the specified window, copying the data | from the virtual screen to the physical screen.

wnoutRefresh :: Window -> IO ()

Stage an update to a window, but don't actually do the refresh until update is called. This allows multiple windows to be updated together more smoothly.

wBorder :: Window -> Border -> IO ()

   Draw a border around the edges of a window. defaultBorder is
   a record  representing all 0 parameters to wrecord.

defaultBorder :: Border

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

Copy blanks to every position in the screen.

wclear :: Window -> IO ()

Copy blanks to a window and set clearOk for that window.

werase :: Window -> IO ()

Copy blanks to every position in a window.

clrToEol :: IO ()

wClrToEol :: Window -> IO ()

beep :: IO ()

waddch :: Window -> ChType -> IO CInt

Raw NCurses routine.

winsch :: Window -> ChType -> IO CInt

Raw NCurses routine.

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

Raw NCurses routine.

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

Setting attributes

setBlink :: Attr -> Bool -> Attr

Setting attributes

setBold :: Attr -> Bool -> Attr

Setting attributes

setDim :: Attr -> Bool -> Attr

Setting attributes

setHorizontal :: Attr -> Bool -> Attr

Setting attributes

setInvis :: Attr -> Bool -> Attr

Setting attributes

setLeft :: Attr -> Bool -> Attr

Setting attributes

setLow :: Attr -> Bool -> Attr

Setting attributes

setProtect :: Attr -> Bool -> Attr

Setting attributes

setReverse :: Attr -> Bool -> Attr

Setting attributes

setRight :: Attr -> Bool -> Attr

Setting attributes

setStandout :: Attr -> Bool -> Attr

Setting attributes

setTop :: Attr -> Bool -> Attr

Setting attributes

setUnderline :: Attr -> Bool -> Attr

Setting attributes

setVertical :: Attr -> Bool -> Attr

Setting attributes

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 :: (Eq a, Show a, Num a) => String -> IO a -> IO a

throwIfErr_ :: (Eq a, Show a, Num a) => String -> IO a -> IO ()

errI :: IO CInt -> IO ()

flushinp :: IO CInt

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

type ChType = Word64

type NBool = Word8