Module `curses`

Full-screen Text Terminal Manipulation.

In the underlying curses C library, the following functions:

getstr()   (and wgetstr(), mvgetstr(), and mvwgetstr())
inchstr()  (and winchstr(), mvinchstr(), and mvwinchstr())
instr()    (and winstr(), mvinstr(), and mvwinstr())

are subject to buffer overflow attack. This is because you pass in the buffer to be filled in, which has to be of finite length. But in this Lua module, a buffer is assigned automatically and the function returns the string, so there is no security issue. You may still use the alternate functions:

s = stdscr:getnstr()
s = stdscr:inchnstr()
s = stdscr:innstr()

which take an extra "size of buffer" argument, in order to impose a maximum length on the string the user may type in.

Some of the C functions beginning with "no" do not exist in Lua. You should use curses.nl(false) and curses.nl(true) instead of nonl() and nl(), and likewise curses.echo(false) and curses.echo(true) instead of noecho() and echo() .

In this Lua module the stdscr:getch() function always returns an integer. In C, a single character is an integer, but in Lua (and Perl) a single character is a short string. The Perl Curses function getch() returns a char if it was a char, and a number if it was a constant; to get this behaviour in Lua you have to convert explicitly, e.g.:

if c < 256 then c = string.char(c) end

Some Lua functions take a different set of parameters than their C counterparts; for example, you should use str = stdscr.getstr() and y, x = stdscr.getyx() instead of getstr(str) and getyx(y, x), and likewise for getbegyx and getmaxyx and getparyx and pair_content. The Perl Curses module now uses the C-compatible parameters, so be aware of this difference when translating code from Perl into Lua, as well as from C into Lua.

Many curses functions have variants starting with the prefixes w-, mv-, and/or wmv-. These variants differ only in the explicit addition of a window, or by the addition of two coordinates that are used to move the cursor first. For example, in C addch() has three other variants: waddch(), mvaddch() and mvwaddch(). The Lua equivalents, respectively being stdscr:addch(), somewindow:addch(), stdscr:mvaddch() and somewindow:mvaddch(), with the window argument passed implicitly with Lua's : syntax sugar.

Functions

baudrate ()	Fetch the output speed of the terminal.
beep ()	Send the terminal audible bell.
cbreak ([on])	Put the terminal into cbreak mode.
color_pair (pair)	Return the attributes for the given color pair id.
color_pairs ()	How may distinct color pairs are supported by this terminal?
colors ()	How many colors are available for this terminal?
cols ()	Number of columns in the main screen window.
curs_set (vis)	Change the visibility of the cursor.
delay_output (ms)	Insert padding characters to force a short delay.
doupdate ()	Refresh the visible terminal screen.
echo ([on])	Whether characters are echoed to the terminal as they are typed.
endwin ()	Clean up terminal prior to exiting or escaping curses.
erasechar ()	Fetch the terminal's current erase character.
flash ()	Send the terminal visible bell.
flushinp ()	Throw away any typeahead in the keyboard input buffer.
halfdelay (tenths)	Put the terminal into halfdelay mode.
has_colors ()	Does the terminal have color capability?
has_ic ()	Fetch the character insert and delete capability of the terminal.
has_il ()	Fetch the line insert and delete capability of the terminal.
init_pair (pair, f, b)	Associate a color pair id with a specific foreground and background color.
initscr ()	Initialise screen.
isendwin ()	Has endwin been called more recently than curses.window:refresh?
keyname (c)	Return a printable representation of a key.
killchar ()	Fetch the terminal's current kill character.
lines ()	Number of lines in the main screen window.
longname ()	Fetch the verbose name of the terminal.
napms (ms)	Sleep for a few milliseconds.
new_chstr (len)	Create a new line drawing buffer instance.
newpad (nlines, ncols)	Create a new pad.
newwin (nlines, ncols, begin_y, begin_x)	Create a new window.
nl ([on])	Whether to translate a return key to newline on input.
pair_content (pair)	Return the foreground and background colors associated with a color pair id.
raw ([on])	Put the terminal into raw mode.
resizeterm (nlines, ncols)	Change the terminal size.
ripoffline (top_line, callback)	Reduce the available size of the main screen.
slk_attroff (attrs)	Disable an attribute for soft labels.
slk_attron (attrs)	Enable an attribute for soft labels.
slk_attrset (attrs)	Set the attributes for soft labels.
slk_clear ()	Clears the soft labels from the screen.
slk_init (fmt)	Initialise the soft label keys area.
slk_label (labnum)	Fetch the label for a soft label key.
slk_noutrefresh ()	Copy the soft label key area backing screen to the virtual screen.
slk_refresh ()	Refresh the soft label key area.
slk_restore ()	Restores the soft labels to the screen.
slk_set (labnum, label, fmt)	Set the label for a soft label key.
slk_touch ()	Mark the soft label key area for refresh.
start_color ()	Initialise color output facility.
stdscr ()	Retern the main screen window.
termattrs ([a])	Bitwise OR of all (or selected) video attributes supported by the terminal.
termname ()	Fetch the name of the terminal.
tigetflag (capname)	Fetch terminfo boolean capability.
tigetnum (capname)	Fetch terminfo numeric capability.
tigetstr (capname)	Fetch terminfo string capability.
unctrl (c)	Return a printable representation of a character, ignoring attributes.
ungetch (c)	Return a character to the keyboard input buffer.
use_default_colors ()	Reserve `-1` to represent terminal default colors.

Constants

curses

Curses constants.

Functions

baudrate ()

Fetch the output speed of the terminal.

Returns:

int

Returns:

bool

true

Parameters:

on bool (optional)

Returns:

bool

true

Parameters:

pair int color pair id to act on

Returns:

int

pair

Returns:

int

Returns:

int

Returns:

int

Parameters:

vis int one of 0 (invisible), 1 (visible) or 2 (very visible)

Returns:

int

Or

vis

Parameters:

ms int delay time in milliseconds

Returns:

bool

true

Returns:

bool

true

Parameters:

on bool (optional)

Returns:

bool

true

Returns:

bool

true

Returns:

int

Returns:

bool

true

Returns:

bool

true

Parameters:

tenths int delay in tenths of a second

Returns:

bool

true

Returns:

bool

true

Usage:

if curses.has_colors () then
  curses.start_color ()
end

has_ic ()

Fetch the character insert and delete capability of the terminal.

Returns:

bool

true

Returns:

bool

true

Parameters:

pair int color pair id to act on
f int foreground color to assign
b int background color to assign

Returns:

bool

true

Returns:

window

Returns:

bool

endwin

Parameters:

c int a key

Returns:

string

Returns:

int

Returns:

int

Returns:

string

Parameters:

ms int time to wait in milliseconds

Returns:

bool

true

Parameters:

len int number of element to allocate

Returns:

chstr

Parameters:

nlines int
ncols int

Returns:

bool

true

Parameters:

nlines int number of window lines
ncols int number of window columns
begin_y int top line of window
begin_x int leftmost column of window

Returns:

window

Parameters:

on bool (optional)

Returns:

bool

true

Parameters:

pair int color pair id to act on

Returns:

int foreground color of pair
int background color of pair

Parameters:

on bool (optional)

Returns:

bool

true

Parameters:

nlines int number of lines
ncols int number of columns

Returns:

bool

true

Raises:

unimplemented

ripoffline (top_line, callback)

Reduce the available size of the main screen.

Parameters:

top_line bool
callback func

Returns:

bool

true

Parameters:

attrs int

Returns:

bool

true

Parameters:

attrs int

Returns:

bool

true

Parameters:

attrs int

Returns:

bool

true

Returns:

bool

true

Parameters:

fmt int

Returns:

bool

true

Parameters:

labnum int

Returns:

string

labnum

Returns:

bool

true

Returns:

bool

true

Returns:

bool

true

Parameters:

labnum int
label string
fmt int

Returns:

bool

true

Returns:

bool

true

Returns:

bool

true

Returns:

window

Parameters:

a int terminal attribute bits (optional)

Returns:

bool

true

Or

int

Returns:

string

Parameters:

capname string

Returns:

bool

Parameters:

capname string

Returns:

int

Parameters:

capname string

Returns:

string

Parameters:

c int character to act on

Returns:

string

Parameters:

c int

Returns:

bool

true

Returns:

bool

true

Constants

curses

Curses constants. Any constants not available in the underlying system will be nil valued, see curses.lua. Many of the KEY_ constants cannot be generated by modern keyboards and are mostly for historical compatibility with ancient terminal hardware keyboards.

Note that almost all of these constants remain undefined (nil) until after curses.initscr has returned successfully.

Fields:

ACS_BLOCK int alternate character set solid block
ACS_BOARD int alternate character set board of squares
ACS_BTEE int alternate character set bottom-tee
ACS_BULLET int alternate character set bullet
ACS_CKBOARD int alternate character set stipple
ACS_DARROW int alternate character set down arrow
ACS_DEGREE int alternate character set degrees mark
ACS_DIAMOND int alternate character set diamond
ACS_HLINE int alternate character set horizontal line
ACS_LANTERN int alternate character set lantern
ACS_LARROW int alternate character set left arrow
ACS_LLCORNER int alternate character set lower left corner
ACS_LRCORNER int alternate character set lower right corner
ACS_LTEE int alternate character set left tee
ACS_PLMINUS int alternate character set plus/minus
ACS_PLUS int alternate character set plus
ACS_RARROW int alternate character set right arrow
ACS_RTEE int alternate character set right tee
ACS_S1 int alternate character set scan-line 1
ACS_S9 int alternate character set scan-line 9
ACS_TTEE int alternate character set top tee
ACS_UARROW int alternate character set up arrow
ACS_ULCORNER int alternate character set upper left corner
ACS_URCORNER int alternate character set upper right corner
ACS_VLINE int alternate character set vertical line
A_ALTCHARSET int alternatate character set attribute
A_ATTRIBUTES int attributed character attributes bitmask
A_BLINK int blinking attribute
A_BOLD int bold attribute
A_CHARTEXT int attributed character text bitmask
A_COLOR int attributed character color-pair bitmask
A_DIM int half-bright attribute
A_INVIS int invisible attribute
A_NORMAL int normal attribute (all attributes off)
A_PROTECT int protected attribute
A_REVERSE int reverse video attribute
A_STANDOUT int standout attribute
A_UNDERLINE int underline attribute
COLOR_BLACK int black color attribute
COLOR_BLUE int blue color attribute
COLOR_CYAN int cyan color attribute
COLOR_GREEN int green color attribute
COLOR_MAGENTA int magenta color attribute
COLOR_RED int red color attribute
COLOR_WHITE int white color attribute
COLOR_YELLOW int yellow color attribute
KEY_A1 int upper-left of keypad key
KEY_A3 int upper-right of keypad key
KEY_B2 int center of keypad key
KEY_BACKSPACE int backspace key
KEY_BEG int beginning key
KEY_BREAK int break key
KEY_BTAB int backtab key
KEY_C1 int bottom-left of keypad key
KEY_C3 int bottom-right of keypad key
KEY_CANCEL int cancel key
KEY_CATAB int clear all tabs key
KEY_CLEAR int clear screen key
KEY_CLOSE int close key
KEY_COMMAND int command key
KEY_COPY int copy key
KEY_CREATE int create key
KEY_CTAB int clear tab key
KEY_DC int delete character key
KEY_DL int delete line key
KEY_DOWN int down arrow key
KEY_EIC int exit insert char mode key
KEY_END int end key
KEY_ENTER int enter key
KEY_EOL int clear to end of line key
KEY_EOS int clear to end of screen key
KEY_EXIT int exit key
KEY_F0 int f0 key
KEY_F1 int f1 key
KEY_F2 int f2 key
KEY_F3 int f3 key
KEY_F4 int f4 key
KEY_F5 int f5 key
KEY_F6 int f6 key
KEY_F7 int f7 key
KEY_F8 int f8 key
KEY_F9 int f9 key
KEY_F10 int f10 key
KEY_F11 int f11 key
KEY_F12 int f12 key
KEY_F13 int f13 key
KEY_F14 int f14 key
KEY_F15 int f15 key
KEY_F16 int f16 key
KEY_F17 int f17 key
KEY_F18 int f18 key
KEY_F19 int f19 key
KEY_F20 int f20 key
KEY_F21 int f21 key
KEY_F22 int f22 key
KEY_F23 int f23 key
KEY_F24 int f24 key
KEY_F25 int f25 key
KEY_F26 int f26 key
KEY_F27 int f27 key
KEY_F28 int f28 key
KEY_F29 int f29 key
KEY_F30 int f30 key
KEY_F31 int f31 key
KEY_F32 int f32 key
KEY_F33 int f33 key
KEY_F34 int f34 key
KEY_F35 int f35 key
KEY_F36 int f36 key
KEY_F37 int f37 key
KEY_F38 int f38 key
KEY_F39 int f39 key
KEY_F40 int f40 key
KEY_F41 int f41 key
KEY_F42 int f42 key
KEY_F43 int f43 key
KEY_F44 int f44 key
KEY_F45 int f45 key
KEY_F46 int f46 key
KEY_F47 int f47 key
KEY_F48 int f48 key
KEY_F49 int f49 key
KEY_F50 int f50 key
KEY_F51 int f51 key
KEY_F52 int f52 key
KEY_F53 int f53 key
KEY_F54 int f54 key
KEY_F55 int f55 key
KEY_F56 int f56 key
KEY_F57 int f57 key
KEY_F58 int f58 key
KEY_F59 int f59 key
KEY_F60 int f60 key
KEY_F61 int f61 key
KEY_F62 int f62 key
KEY_F63 int f63 key
KEY_FIND int find key
KEY_HELP int help key
KEY_HOME int home key
KEY_IC int enter insert char mode key
KEY_IL int insert line key
KEY_LEFT int cursor left key
KEY_LL int home down or bottom key
KEY_MARK int mark key
KEY_MESSAGE int message key
KEY_MOUSE int mouse event available virtual key
KEY_MOVE int move key
KEY_NEXT int next object key
KEY_NPAGE int next page key
KEY_OPEN int open key
KEY_OPTIONS int options key
KEY_PPAGE int previous page key
KEY_PREVIOUS int prewious object key
KEY_PRINT int print key
KEY_REDO int redo key
KEY_REFERENCE int reference key
KEY_REFRESH int refresh key
KEY_REPLACE int replace key
KEY_RESET int hard reset key
KEY_RESIZE int resize event virtual key
KEY_RESTART int restart key
KEY_RESUME int resume key
KEY_RIGHT int cursor right key
KEY_SAVE int save key
KEY_SBEG int shift beginning key
KEY_SCANCEL int shift cancel key
KEY_SCOMMAND int shift command key
KEY_SCOPY int shift copy key
KEY_SCREATE int shift create key
KEY_SDC int shift delete character key
KEY_SDL int shift delete line key
KEY_SELECT int select key
KEY_SEND int send key
KEY_SEOL int shift clear to end of line key
KEY_SEXIT int shift exit key
KEY_SF int scroll one line forward key
KEY_SFIND int shift find key
KEY_SHELP int shift help key
KEY_SHOME int shift home key
KEY_SIC int shift enter insert mode key
KEY_SLEFT int shift cursor left key
KEY_SMESSAGE int shift message key
KEY_SMOVE int shift move key
KEY_SNEXT int shift next object key
KEY_SOPTIONS int shift options key
KEY_SPREVIOUS int shift previous object key
KEY_SPRINT int shift print key
KEY_SR int scroll one line backward key
KEY_SREDO int shift redo key
KEY_SREPLACE int shift replace key
KEY_SRESET int soft reset key
KEY_SRIGHT int shift cursor right key
KEY_SRSUME int shift resume key
KEY_SSAVE int shift save key
KEY_SSUSPEND int shift suspend key
KEY_STAB int shift tab key
KEY_SUNDO int shift undo key
KEY_SUSPEND int suspend key
KEY_UNDO int undo key
KEY_UP int cursor up key

Usage:

  -- Print curses constants supported on this host.
  for name, value in pairs (require "curses") do
    if type (value) == "number" then
      print (name, value)
     end
  end

lcurses 9.0.0

Contents

Modules

Classes

Examples

Module curses

Functions

Constants

Functions

Returns:

See also:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Returns:

See also:

Returns:

See also:

Returns:

See also:

Parameters:

Returns:

Or

See also:

Parameters:

Returns:

See also:

Returns:

See also:

Parameters:

Returns:

See also:

Returns:

See also:

Returns:

See also:

Returns:

See also:

Returns:

See also:

Parameters:

Returns:

See also:

Returns:

See also:

Usage:

Returns:

See also:

Returns:

See also:

Parameters:

Returns:

See also:

Returns:

See also:

Returns:

See also:

Parameters:

Returns:

See also:

Returns:

See also:

Returns:

See also:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Module `curses`