curses.init

Determines the terminal type and initializes all curses data structures. It also causes the first call to refresh to clear the screen.

If errors occur, curses.init writes an appropriate error message to standard error and exits; otherwise, an user data object is returned representing the main window.

Before you call any other curses functions curses.init must be called to make sure you access the correct information (with some exceptions like curses.slk_init and curses.ripoffline).

See also: curses.main_window window

curses.done

A program should always call curses.done before exiting or escaping from curses mode temporarily. This routine restores tty modes, moves the cursor to the lower left-hand corner of the screen and resets the terminal into the proper non-visual mode. Calling window:refresh or curses.doupdate after a temporary escape causes the program to resume visual mode.

See also: curses.init

curses.isdone

The curses.isdone routine returns true if curses.done has been called without any subsequent calls to window:refresh or curses.doupdate, and false otherwise.

curses.main_window

Returns an user data object representing the main window.

See also: curses.init window

curses.columns

Returns the number of columns of the terminal.

curses.lines

Returns the number of lines of the terminal.

curses.has_color

It returns true if the terminal can manipulate colors; otherwise, it returns false. This routine facilitates writing terminal-independent programs. For example, a programmer can use it to decide whether to use color or some other video attribute.

Note on using colors:

Curses support color attributes on terminals with that capability. To use these routines curses.start_color must be called, usually right after curses.init. 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 characters are displayed). A programmer initializes a color-pair with the routine curses.init_pair. After it has been initialized, curses.color_pair can be used as a new video attribute.

curses.start_color

It must be called if the programmer wants to use colors, and before any other color manipulation routine is called. It is good practice to call this routine right after curses.init. curses.start_color initializes eight basic colors (black, red, green, yellow, blue, magenta, cyan, and white), and values, returned by curses.colors and curses.color_pairs (respectively defining the maximum number of colors and color-pairs the terminal can support). It also restores the colors on the terminal to the values they had when the terminal was just turned on.

Returns false in case of error, true otherwise.

curses.init_pair

curses.init_pair(color_pair_number, foreground_color, background_color)

The curses.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 curses.color_pairs - 1.
• The value of the second and third arguments must be between 0 and curses.colors (the 0 color pair is wired to white on black and cannot be changed).

If the color-pair was previously initialized, the screen is refreshed and all occurrences of that color-pair are changed to the new definition.

Returns false in case of error, true otherwise.

curses.pair_content

fg, bg = curses.pair_content(color_pair_number)

This routine allows programmers to find out what colors a given color-pair consists of.

In case of success, it returns two numbers defining the foreground color and the background color respectively.

Returns nil in case of error.

See also: curses.colors

curses.colors

Returns the maximum number of colors the terminal can support.

curses.color_pairs

Returns the maximum number of color pairs the terminal can support.

curses.color_pair

syntax: attribute = curses.color_pair(color_pair_number)

Returns a number that can be used as a video attribute.

curses.baudrate

The curses.baudrate routine returns the output speed of the terminal. The number returned is in bits per second, for example 9600, and is a number (integer).

curses.erase_char

The curses.erase_char routine returns the user's current erase character.

curses.kill_char

The curses.kill_char routine returns the user's current line kill character.

curses.has_insert_char

The curses.has_insert_char routine returns true if the terminal has insert and delete character capabilities.

curses.has_insert_line

The curses.has_insert_line routine returns true if the terminal has insert and delete line capabilities, or can simulate them using scrolling regions. This might be used to determine if it would be appropriate to turn on physical scrolling using window:scrollok.

curses.termattrs

Return a logical or (binary or) of all video attributes supported by the terminal using curses.A_xxx constants.

To check for a specific attribute, pass the attribute value to <code>curses.termattrs()</code>. It will return true if the attribute is supported.

This information is useful when a curses program needs complete control over the appearance of the screen.

syntax: attributes = curses.termattrs()
syntax: has_attribute = curses.termattrs(attribute)

curses.termname

The curses.termname routine returns the value of the environmental variable TERM (truncated to 14 characters).

curses.longname

The curses.longname routine returns a verbose description of the current terminal. The maximum length of a verbose description is 128 characters. It is defined only after the call to curses.init.

curses.ripoffline

function ripline(window, columns)
    -- do something with the window (line)
end

top = true -- take a line from the top of the screen
curses.ripoffline(top, ripline)

The ripoffline routine provides access to the same facility that curses.slk_init uses to reduce the size of the screen. curses.ripoffline must be called before curses.init. If top is true, a line is removed from the top of the screen; if top is false, a line is removed from the bottom.

When this is done inside curses.init, the function supplied by the user is called with two arguments: a user data object representing the one-line window that has been allocated and a number with the number of columns in the window. Inside this initialization routine, the values of curses.columns and curses.lines are not guaranteed to be accurate and window:refresh or curses.doupdate must not be called. It is allowable to call window:noutrefresh during the initialization routine.

curses.napms

ms = 1000 -- sleep for 1 second
curses.sleep(ms)

Sleep for ms milliseconds.

curses.cursor_set

previous_state = curses.cursor_set(1)

The curses.cursor_set routine sets the cursor state 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, nil is returned.

curses.beep

The curses.beep and curses.flash routines are used to alert the terminal user. The routine beep sounds an audible alarm on the terminal, if possible; otherwise it flashes the screen (visible bell). The routine flash flashes the screen, and if that is not possible, sounds the alert. If neither alert is possible, nothing happens. Nearly all terminals have an audible alert (bell or beep), but only some can flash the screen.

curses.beep()   -- terminal bell
curses.flash()  -- flash screen

curses.flash

See curses.beep.

curses.new_window

window = curses.new_window(lines, columns, y, x)

Calling curses.new_window creates and returns an user data object representing the new window with the given number of lines and columns. The upper left-hand corner of the window is at line y, column x. If either lines or columns is zero, they default to curses.lines() - y and curses.columns() - x. A new full-screen window is created by calling curses.new_window(0,0,0,0).

See also: curses.lines curses.columns window curses.new_pad

curses.new_pad

pad = curses.new_pad(lines, columns)

The curses.new_pad routine creates and returns an user data object representing the new pad data structure with the given number of lines, lines, and columns, columns. A pad is like a window, except that it is not restricted by the screen size, and is not necessarily associated with a particular part of the screen. Pads can be used when a large window is needed, and only a part of the window will be on the screen at one time. Automatic refreshes of pads (e.g., from scrolling or echoing of input) do not occur. It is not legal to call window:refresh with a pad as an argument; the routines window:prefresh or window:pnoutrefresh should be called instead. Note that these routines require additional parameters to specify the part of the pad to be displayed and the location on the screen to be used for the display.

See also: curses.new_window window

curses.doupdate

Call curses.doupdate to update the physical screen with the actual changes.

See also: window:refresh

curses.nl

The curses.nl routine 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 window:addch('\n') does the equivalent of return and line feed on the virtual screen). Initially, these translations do occur. If you disable them using curses.nl(false), curses will be able to make better use of the line-feed capability, resulting in faster cursor motion. Also, curses will then be able to detect the return key.

See also: window:addch

curses.cbreak

curses.cbreak(mode)

Normally, the tty driver buffers typed characters until a newline or carriage return is typed. The curses.cbreak(true) routine disables line buffering and erase/kill character-processing (interrupt and flow control characters are unaffected), making characters typed by the user immediately available to the program. The curses.cbreak(false) routine returns the terminal to normal (cooked) mode.

Initially the terminal may or may not be in curses.cbreak(true) mode, as the mode is inherited; therefore, a program should call curses.cbreak explicitly. Most interactive programs using curses set the curses.cbreak(true) mode. Note that cbreak overrides curses.raw.

See also: curses.halfdelay

curses.echo

curses.echo(mode)

The curses.echo routine control whether characters typed by the user are echoed by window:getch as they are typed. Echoing by the tty driver is always disabled, but initially 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 curses.echo(false).

curses.raw

curses.raw(mode)

The curses.raw routine place the terminal into or out of raw mode. Raw mode is similar to curses.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.

curses.halfdelay

curses.halfdelay(tenths)

The curses.halfdelay routine is used for half-delay mode, which is similar to cbreak mode in that characters typed by the user are immediately available to the program. However, after blocking for tenths tenths of seconds, false is returned if nothing has been typed. The value of tenths must be a number between 1 and 255. Use curses.cbreak(false) to leave half-delay mode.

See also: curses.cbreak

curses.unctrl

str = curses.unctrl(ch)

The curses.unctrl routine returns a string which is a printable representation of the character ch, ignoring attributes. Control characters are displayed in the ^X notation. Printing characters are displayed as is.

curses.keyname

keyname = curses.keyname(key)

The curses.keyname routine returns a string corresponding to the key key. Control characters are displayed in the ^X notation. Values above 128 are either meta characters, shown in the M-X notation, or the names of function keys, or nil.

curses.delay_output

curses.delay_output(ms)

The curses.delay_output routine inserts an ms millisecond pause in output. This routine should not be used extensively because padding characters are used rather than a CPU pause.

curses.flush_input

The curses.flush_input routine throws away any typeahead that has been typed by the user and has not yet been read by the program.

curses.ungetch

curses.ungetch(ch)

The curses.ungetch routine places ch back onto the input queue to be returned by the next call to window:getch. There is just one input queue for all windows.

curses.slk_init

format = 0 -- arrange labels in 3-2-3 arrangement
ok = curses.slk_init(format)

The curses.slk_init routine must be called before curses.init is called. If curses.init eventually uses a line from curses.main_window to emulate the soft labels, then format determines how the labels are arranged on the screen. Setting format to 0 indicates a 3-2-3 arrangement of the labels, 1 indicates a 4-4 arrangement and 2 indicates the PC like 4-4-4 mode. If format is set to 3, it is again the PC like 4-4-4 mode, but in addition an index line is generated, helping the user to identify the key numbers easily.

curses.slk_set

ok = curses.slk_set(labnum, label, format)

The curses.slk_set routine requires labnum to be a label number, from 1 to 8 (resp. 12); label must be the string to be put on the label, up to eight (resp. five) characters in length. format is either 0, 1, or 2, indicating whether the label is to be left-justified, centered, or right-justified, respectively, within the label.

curses.slk_refresh

The curses.slk_refresh and curses.slk_noutrefresh routines correspond to the window:refresh and window:noutrefresh routines.

curses.slk_noutrefresh

See curses.slk_refresh.

curses.slk_label

label = curses.slk_label(labnum)

The curses.slk_label routine returns the current label for label number labnum, with leading and trailing blanks stripped.

curses.slk_clear

The curses.slk_clear routine clears the soft labels from the screen.

curses.slk_restore

The curses.slk_restore routine restores the soft labels to the screen after a curses.slk_clear has been performed.

curses.slk_touch

The curses.slk_touch routine forces all the soft labels to be output the next time a curses.slk_noutrefresh is performed.

curses.slk_attron

The curses.slk_attron, curses.slk_attrset, curses.slk_attroff have an effect only if soft labels are simulated on the bottom line of the screen.

curses.slk_attroff

See curses.slk_attron.

curses.slk_attrset

See curses.slk_attron.

curses.new_chstr

len = 10
chstr = curses.new_chstr(len) -- create chstr object with len positions to use

Creates a new chstr object to use as a buffered line to draw into. It will have len positions to use.

See also: chstr

curses.map_output

oldmode = curses.map_output(mode)

Maps the curses chstr characters to a character that has a printable representation if that is not the case.

mode is a boolean value indicating if chstr characters are to be mapped or not. If mode is nil the mode is not changed.

See also: chstr

curses.map_keyboard

oldmode = curses.map_keyboard(mode)

This is a PDCurses specific (at the moment at least) that will attempt to make some keys behave like other curses implementations.

It affects window:getch. For a consistent behaviour it is advised to turn it on.

mode is a boolean value indicating if keys are to be mapped or not. If mode is nil the mode is not changed.

window:close

window:close()

Deletes the named window, freeing all memory associated with it (it does not actually erase the window's screen image).

Note:

Sub windows must be deleted before the main window can be deleted.

window:sub

wsub = w:sub(lines, columns, begin_y, begin_x)

Calling window:sub creates and returns a new curses window with the given number of lines and columns. The window is at position (begin_y, begin_x) on the screen. (This position is relative to the screen, and not to the window w.) The window is made in the middle of the window w, so that changes made to one window will affect both windows. The subwindow shares memory with the window orig. When using this routine, it is necessary to call window:touch or window:touch_line on w before calling window:refresh on the subwindow.

window:derive

(TODO)

window:move_window

(TODO)

window:move_derived

(TODO)

window:clone

(TODO)

window:syncup

(TODO)

window:syncdown

(TODO)

window:syncok

(TODO)

window:cursyncup

(TODO)

window:intrflush

(TODO)

window:keypad

(TODO)

window:meta

(TODO)

window:nodelay

(TODO)

window:timeout

(TODO)

window:notimeout

(TODO)

window:clearok

(TODO)

window:idlok

(TODO)

window:leaveok

(TODO)

window:scrollok

(TODO)

window:idcok

(TODO)

window:immedok

(TODO)

window:wsetscrreg

(TODO)

window:subpad

(TODO)

window:prefresh

(TODO)

window:pnoutrefresh

(TODO)

window:pechochar

(TODO)

window:move

(TODO)

window:scroll

(TODO)

window:refresh

(TODO)

window:noutrefresh

(TODO)

window:redraw

(TODO)

window:redraw_line

(TODO)

window:erase

(TODO)

window:clear

(TODO)

window:clear_to_bottom

(TODO)

window:clear_to_eol

(TODO)

window:touch

(TODO)

window:touch_line

(TODO)

window:is_line_touched

(TODO)

window:is_touched

(TODO)

window:attrs

(TODO)

window:attroff

(TODO)

window:attron

(TODO)

window:attrset

(TODO)

window:standout

(TODO)

window:standend

(TODO)

window:getch

(TODO)

window:mvgetch

(TODO)

window:getyx

(TODO)

window:getparyx

(TODO)

window:getbegyx

(TODO)

window:getmaxyx

(TODO)

window:border

(TODO)

window:box

(TODO)

window:hline

(TODO)

window:vline

(TODO)

window:mvhline

(TODO)

window:mvvline

(TODO)

window:addch

(TODO)

window:mvaddch

(TODO)

window:echoch

(TODO)

window:addchstr

(TODO)

window:mvaddchstr

(TODO)

window:addstr

(TODO)

window:mvaddstr

(TODO)

window:wbkgdset

(TODO)

window:wbkgd

(TODO)

window:getbkgd

(TODO)

window:overlay

(TODO)

window:overwrite

(TODO)

window:copy

(TODO)

window:delch

(TODO)

window:mvdelch

(TODO)

window:delete_line

(TODO)

window:insert_line

(TODO)

window:winsdelln

(TODO)

window:getstr

(TODO)

window:mvgetstr

(TODO)

window:winch

(TODO)

window:mvwinch

(TODO)

window:winchnstr

(TODO)

window:mvwinchnstr

(TODO)

window:winnstr

(TODO)

window:mvwinnstr

(TODO)

window:winsch

(TODO)

window:mvwinsch

(TODO)

window:winsstr

(TODO)

window:winsnstr

(TODO)

window:mvwinsstr

(TODO)

window:mvwinsnstr

(TODO)

chstr:len

len = chstr:len()

Returns the length of the chstr object.

chstr:set_ch

chstr:set_ch(index, ch, [attr, [rep]])

Assign a character to the position index of the chstr object. attr is the attribute of the assigned character, if nil it will have the value curses.A_NORMAL. rep indicates the number of times the character is to be repeated, if it is nil it will be 1.

Use this if you want to use the alternate character set for drawing.

If the assigned positions are out of bounds, they are ignored.

Example:

-- create a chstr object and fill it will ACS_VLINE characters
str = curses.new_chstr(10)
str:set_ch(0, curses.ACS_VLINE, curses.A_NORMAL, 10)

chstr:set_str

chstr:set_str(index, str, [attr, [rep]])

Assign a string to the position index of the chstr object. attr is the attribute of the assigned string, if nil it will have the value curses.A_NORMAL. rep indicates the number of times the string is to be repeated, if it is nil it will be 1.

If the assigned positions are out of bounds, they are truncated/ignored.

Example:

-- create a chstr object and fill it with text
str = curses.new_chstr(10)
str:set_string(0, 'hello', curses.A_NORMAL, 3)

-- str = 'hellohellohe'

chstr:get

ch, attr, color = chstr:get(index)

Return the contents of the chstr object at the position index.

chstr:dup

str2 = str:dup()

Create a duplicate (independent) of the chstr object for manipulation.

curses.isalnum

(TODO)

curses.isalpha

(TODO)

curses.iscntrl

(TODO)

curses.isdigit

(TODO)

curses.isgraph

(TODO)

curses.islower

(TODO)

curses.isprint

(TODO)

curses.ispunct

(TODO)

curses.isspace

(TODO)

curses.isupper

(TODO)

curses.isxdigit

(TODO)