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

COLOR_BLACK

COLOR_RED

COLOR_GREEN

COLOR_YELLOW

COLOR_BLUE

COLOR_MAGENTA

COLOR_CYAN

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

A_NORMAL

A_STANDOUT

A_UNDERLINE

A_REVERSE

A_BLINK

A_DIM

A_BOLD

A_PROTECT

A_INVIS

A_ALTCHARSET

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

number getPair(number pairIndex)

ncurses.getPair()

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

setPair(number pairIndex, number foregroundColor, number backgroundColor)

ncurses.setPair()

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.