Ncurses Module
Contents
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.
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.
