Ncurses Module

Global Variables

Colors

The following color constants are available for use the Ncurses windows through functions like ncurses.setPair(), ncurses.setBackground(), or ncurses.setAttribute().

ncurses.BLACK

ncurses.RED

ncurses.GREEN

ncurses.YELLOW

ncurses.BLUE

ncurses.MAGENTA

ncurses.CYAN

ncurses.WHITE

Style attributes

These constants may also be used in pairs, backgrounds, or attribute masks. Be warned, many of them do not work in a Windows console.

ncurses.NORMAL

ncurses.STANDOUT

ncurses.UNDERLINE

ncurses.REVERSE

ncurses.BLINK

ncurses.DIM

ncurses.BOLD

ncurses.PROTECT

ncurses.INVIS

ncurses.ALTCHARSET

ncurses.CHARTEXT

Default window

The default Ncurses window can be identified by STDSCR. Unless you want to output to a specified window, STDSCR is where you'll put it.

init

ncurses.init()

As you can probably imagine, this initializes the Ncurses module. By default, Ncurses is not enabled. By calling this function, you will create the default Ncurses window (STDSCR) and enable the use of other Ncurses functions. That means, once this function is called, the "normal" output (STDOUT) will disappear and you'll be stuck with a black window. Any data output with print(), printf(), or io.write() will not appear on the Ncurses window, so make sure to only use Ncurses functions to output while in this mode.

cleanup

ncurses.cleanup()

When you are in Ncurses mode, calling this function will destroy the Ncurses environment and return you to standard output.

print

ncurses.print(window win, string str)

Prints data to an Ncurses window. The output begins at the virtual cursor's position (use ncurses.move() to reposition the cursor) in the specified Ncurses window. As with most Ncurses functions, you should pass STDSCR as the first parameter if you want to put data on the default window.

Take note that this function will not display the information immediately. The screen is only redrawn (and becomes visible) after you call ncurses.refresh().

refresh

ncurses.refresh(window win)

Redraw the given window to commit any changes. Call this after a single call or batch of calls to any output function to update the screen.

scrollok

ncurses.scrollok(window win, boolean scrolling)

Sets (or unsets) scrolling on the given window. By default, scrolling is disabled on windows. If you want text to scroll off the top as you continue to dump more text into it, set 'scrolling' to true.

clear

ncurses.clear(window win)

Erase the contents of window 'win'.

move

ncurses.move(window win, number y, number x)

Moves the position of the virtual cursor to y,x in the given window. Notice that the orientation is Y (row) before X (column) and not the other way around. The virtual cursor position is where output will be placed in the given Ncurses window.

Should the position you request be unavailable (probably because it extends beyond the constraints of the window), this function will fail and do nothing.

createWindow

window ncurses.createWindow(number sy, number sx, number width, number height)

Creates a new Ncurses window and returns it. 'sy' and 'sx' indicate the top-left corner of the window (in characters). 'width' and 'height' represent the window's width/height in characters.

If this function fails for any reason, it will return nil.

Note that the position is in Y,X order.

resizeWindow

boolean ncurses.resizeWindow(window win, number lines, number columns)

Resize a window to the given columns/lines. Returns true on success, false on failure.

moveWindow

boolean ncurses.moveWindow(window win, number y, number x)

Move a window to the given position. Returns true on success, false on failure.

getString

string ncurses.getString(window win)

Prompt the user for some input on an Ncurses window. Returns that input as a string value. While waiting for user input, the rest of the program is blocked from continuing.

getPair

number ncurses.getPair(number pairIndex)

Returns the attribute mask of a given color pair. Call ncurses.setPair() on the pair first, otherwise you're wasting your time.

setPair

ncurses.setPair(number pairIndex, number foregroundColor, number backgroundColor)

Modified the color (foreground/background) pair at a given index.

attributeOn

ncurses.attributeOn(window win, number attrib)

Turns an attribute (identified by 'attrib') on for the given window.

attributeOff

ncurses.attributeOff(window win, number attrib)

Turns an attribute (identified by 'attrib') off for the given window.

setAttribute

ncurses.setAttribute(window win, number attrib)

Sets an attribute mask (identified by 'attrib') on the given window. The attribute mask can represent a handful of attributes at once. You should use bit32.bor() to combine them.

getAttribute

number attributes, number pair ncurses.getAttribute(window win)

Returns the attribute mask and color pair for a Ncurses window. If this function fails, it will return nil.

setBackground

ncurses.setBackground(window win, number attrib)

Sets a background on the given window to the attribute mask.

getWindowSize

number y, number x ncurses.getWindowSize(window win)

Returns the size of a window.