1394 lines
55 KiB
TeX
1394 lines
55 KiB
TeX
\section{\module{curses} ---
|
|
Terminal handling for character-cell displays}
|
|
|
|
\declaremodule{standard}{curses}
|
|
\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
|
|
\sectionauthor{Eric Raymond}{esr@thyrsus.com}
|
|
\modulesynopsis{An interface to the curses library, providing portable
|
|
terminal handling.}
|
|
|
|
\versionchanged[Added support for the \code{ncurses} library and
|
|
converted to a package]{1.6}
|
|
|
|
The \module{curses} module provides an interface to the curses
|
|
library, the de-facto standard for portable advanced terminal
|
|
handling.
|
|
|
|
While curses is most widely used in the \UNIX{} environment, versions
|
|
are available for DOS, OS/2, and possibly other systems as well. This
|
|
extension module is designed to match the API of ncurses, an
|
|
open-source curses library hosted on Linux and the BSD variants of
|
|
\UNIX.
|
|
|
|
\begin{seealso}
|
|
\seemodule{curses.ascii}{Utilities for working with \ASCII{}
|
|
characters, regardless of your locale
|
|
settings.}
|
|
\seemodule{curses.panel}{A panel stack extension that adds depth to
|
|
curses windows.}
|
|
\seemodule{curses.textpad}{Editable text widget for curses supporting
|
|
\program{Emacs}-like bindings.}
|
|
\seemodule{curses.wrapper}{Convenience function to ensure proper
|
|
terminal setup and resetting on
|
|
application entry and exit.}
|
|
\seetitle[http://www.python.org/doc/howto/curses/curses.html]{Curses
|
|
Programming with Python}{Tutorial material on using curses
|
|
with Python, by Andrew Kuchling and Eric Raymond, is
|
|
available on the Python Web site.}
|
|
\seetext{The \file{Demo/curses/} directory in the Python source
|
|
distribution contains some example programs using the
|
|
curses bindings provided by this module.}
|
|
\end{seealso}
|
|
|
|
|
|
\subsection{Functions \label{curses-functions}}
|
|
|
|
The module \module{curses} defines the following exception:
|
|
|
|
\begin{excdesc}{error}
|
|
Exception raised when a curses library function returns an error.
|
|
\end{excdesc}
|
|
|
|
\note{Whenever \var{x} or \var{y} arguments to a function
|
|
or a method are optional, they default to the current cursor location.
|
|
Whenever \var{attr} is optional, it defaults to \constant{A_NORMAL}.}
|
|
|
|
The module \module{curses} defines the following functions:
|
|
|
|
\begin{funcdesc}{baudrate}{}
|
|
Returns the output speed of the terminal in bits per second. On
|
|
software terminal emulators it will have a fixed high value.
|
|
Included for historical reasons; in former times, it was used to
|
|
write output loops for time delays and occasionally to change
|
|
interfaces depending on the line speed.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{beep}{}
|
|
Emit a short attention sound.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{can_change_color}{}
|
|
Returns true or false, depending on whether the programmer can change
|
|
the colors displayed by the terminal.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{cbreak}{}
|
|
Enter cbreak mode. In cbreak mode (sometimes called ``rare'' mode)
|
|
normal tty line buffering is turned off and characters are available
|
|
to be read one by one. However, unlike raw mode, special characters
|
|
(interrupt, quit, suspend, and flow control) retain their effects on
|
|
the tty driver and calling program. Calling first \function{raw()}
|
|
then \function{cbreak()} leaves the terminal in cbreak mode.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{color_content}{color_number}
|
|
Returns the intensity of the red, green, and blue (RGB) components in
|
|
the color \var{color_number}, which must be between \code{0} and
|
|
\constant{COLORS}. A 3-tuple is returned, containing the R,G,B values
|
|
for the given color, which will be between \code{0} (no component) and
|
|
\code{1000} (maximum amount of component).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{color_pair}{color_number}
|
|
Returns the attribute value for displaying text in the specified
|
|
color. This attribute value can be combined with
|
|
\constant{A_STANDOUT}, \constant{A_REVERSE}, and the other
|
|
\constant{A_*} attributes. \function{pair_number()} is the
|
|
counterpart to this function.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{curs_set}{visibility}
|
|
Sets the cursor state. \var{visibility} can be set to 0, 1, or 2, for
|
|
invisible, normal, or very visible. If the terminal supports the
|
|
visibility requested, the previous cursor state is returned;
|
|
otherwise, an exception is raised. On many terminals, the ``visible''
|
|
mode is an underline cursor and the ``very visible'' mode is a block cursor.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{def_prog_mode}{}
|
|
Saves the current terminal mode as the ``program'' mode, the mode when
|
|
the running program is using curses. (Its counterpart is the
|
|
``shell'' mode, for when the program is not in curses.) Subsequent calls
|
|
to \function{reset_prog_mode()} will restore this mode.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{def_shell_mode}{}
|
|
Saves the current terminal mode as the ``shell'' mode, the mode when
|
|
the running program is not using curses. (Its counterpart is the
|
|
``program'' mode, when the program is using curses capabilities.)
|
|
Subsequent calls
|
|
to \function{reset_shell_mode()} will restore this mode.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{delay_output}{ms}
|
|
Inserts an \var{ms} millisecond pause in output.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{doupdate}{}
|
|
Update the physical screen. The curses library keeps two data
|
|
structures, one representing the current physical screen contents
|
|
and a virtual screen representing the desired next state. The
|
|
\function{doupdate()} ground updates the physical screen to match the
|
|
virtual screen.
|
|
|
|
The virtual screen may be updated by a \method{noutrefresh()} call
|
|
after write operations such as \method{addstr()} have been performed
|
|
on a window. The normal \method{refresh()} call is simply
|
|
\method{noutrefresh()} followed by \function{doupdate()}; if you have
|
|
to update multiple windows, you can speed performance and perhaps
|
|
reduce screen flicker by issuing \method{noutrefresh()} calls on
|
|
all windows, followed by a single \function{doupdate()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{echo}{}
|
|
Enter echo mode. In echo mode, each character input is echoed to the
|
|
screen as it is entered.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{endwin}{}
|
|
De-initialize the library, and return terminal to normal status.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{erasechar}{}
|
|
Returns the user's current erase character. Under \UNIX{} operating
|
|
systems this is a property of the controlling tty of the curses
|
|
program, and is not set by the curses library itself.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{filter}{}
|
|
The \function{filter()} routine, if used, must be called before
|
|
\function{initscr()} is called. The effect is that, during those
|
|
calls, LINES is set to 1; the capabilities clear, cup, cud, cud1,
|
|
cuu1, cuu, vpa are disabled; and the home string is set to the value of cr.
|
|
The effect is that the cursor is confined to the current line, and so
|
|
are screen updates. This may be used for enabling character-at-a-time
|
|
line editing without touching the rest of the screen.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{flash}{}
|
|
Flash the screen. That is, change it to reverse-video and then change
|
|
it back in a short interval. Some people prefer such as `visible bell'
|
|
to the audible attention signal produced by \function{beep()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{flushinp}{}
|
|
Flush all input buffers. This throws away any typeahead that has
|
|
been typed by the user and has not yet been processed by the program.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getmouse}{}
|
|
After \method{getch()} returns \constant{KEY_MOUSE} to signal a mouse
|
|
event, this method should be call to retrieve the queued mouse event,
|
|
represented as a 5-tuple
|
|
\code{(\var{id}, \var{x}, \var{y}, \var{z}, \var{bstate})}.
|
|
\var{id} is an ID value used to distinguish multiple devices,
|
|
and \var{x}, \var{y}, \var{z} are the event's coordinates. (\var{z}
|
|
is currently unused.). \var{bstate} is an integer value whose bits
|
|
will be set to indicate the type of event, and will be the bitwise OR
|
|
of one or more of the following constants, where \var{n} is the button
|
|
number from 1 to 4:
|
|
\constant{BUTTON\var{n}_PRESSED},
|
|
\constant{BUTTON\var{n}_RELEASED},
|
|
\constant{BUTTON\var{n}_CLICKED},
|
|
\constant{BUTTON\var{n}_DOUBLE_CLICKED},
|
|
\constant{BUTTON\var{n}_TRIPLE_CLICKED},
|
|
\constant{BUTTON_SHIFT},
|
|
\constant{BUTTON_CTRL},
|
|
\constant{BUTTON_ALT}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getsyx}{}
|
|
Returns the current coordinates of the virtual screen cursor in y and
|
|
x. If leaveok is currently true, then -1,-1 is returned.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getwin}{file}
|
|
Reads window related data stored in the file by an earlier
|
|
\function{putwin()} call. The routine then creates and initializes a
|
|
new window using that data, returning the new window object.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{has_colors}{}
|
|
Returns true if the terminal can display colors; otherwise, it
|
|
returns false.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{has_ic}{}
|
|
Returns true if the terminal has insert- and delete- character
|
|
capabilities. This function is included for historical reasons only,
|
|
as all modern software terminal emulators have such capabilities.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{has_il}{}
|
|
Returns true if the terminal has insert- and
|
|
delete-line capabilities, or can simulate them using
|
|
scrolling regions. This function is included for historical reasons only,
|
|
as all modern software terminal emulators have such capabilities.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{has_key}{ch}
|
|
Takes a key value \var{ch}, and returns true if the current terminal
|
|
type recognizes a key with that value.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{halfdelay}{tenths}
|
|
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 \var{tenths} tenths of seconds, an
|
|
exception is raised if nothing has been typed. The value of
|
|
\var{tenths} must be a number between 1 and 255. Use
|
|
\function{nocbreak()} to leave half-delay mode.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{init_color}{color_number, r, g, b}
|
|
Changes the definition of a color, taking the number of the color to
|
|
be changed followed by three RGB values (for the amounts of red,
|
|
green, and blue components). The value of \var{color_number} must be
|
|
between \code{0} and \constant{COLORS}. Each of \var{r}, \var{g},
|
|
\var{b}, must be a value between \code{0} and \code{1000}. When
|
|
\function{init_color()} is used, all occurrences of that color on the
|
|
screen immediately change to the new definition. This function is a
|
|
no-op on most terminals; it is active only if
|
|
\function{can_change_color()} returns \code{1}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{init_pair}{pair_number, fg, bg}
|
|
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. The value of \var{pair_number} must
|
|
be between \code{1} and \code{COLOR_PAIRS - 1} (the \code{0} color
|
|
pair is wired to white on black and cannot be changed). The value of
|
|
\var{fg} and \var{bg} arguments must be between \code{0} and
|
|
\constant{COLORS}. If the color-pair was previously initialized, the
|
|
screen is refreshed and all occurrences of that color-pair are changed
|
|
to the new definition.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{initscr}{}
|
|
Initialize the library. Returns a \class{WindowObject} which represents
|
|
the whole screen. \note{If there is an error opening the terminal,
|
|
the underlying curses library may cause the interpreter to exit.}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{isendwin}{}
|
|
Returns true if \function{endwin()} has been called (that is, the
|
|
curses library has been deinitialized).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{keyname}{k}
|
|
Return the name of the key numbered \var{k}. The name of a key
|
|
generating printable ASCII character is the key's character. The name
|
|
of a control-key combination is a two-character string consisting of a
|
|
caret followed by the corresponding printable ASCII character. The
|
|
name of an alt-key combination (128-255) is a string consisting of the
|
|
prefix `M-' followed by the name of the corresponding ASCII character.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{killchar}{}
|
|
Returns the user's current line kill character. Under \UNIX{} operating
|
|
systems this is a property of the controlling tty of the curses
|
|
program, and is not set by the curses library itself.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{longname}{}
|
|
Returns a string containing the terminfo long name field describing the current
|
|
terminal. The maximum length of a verbose description is 128
|
|
characters. It is defined only after the call to
|
|
\function{initscr()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{meta}{yes}
|
|
If \var{yes} is 1, allow 8-bit characters to be input. If \var{yes} is 0,
|
|
allow only 7-bit chars.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mouseinterval}{interval}
|
|
Sets the maximum time in milliseconds that can elapse between press and
|
|
release events in order for them to be recognized as a click, and
|
|
returns the previous interval value. The default value is 200 msec,
|
|
or one fifth of a second.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mousemask}{mousemask}
|
|
Sets the mouse events to be reported, and returns a tuple
|
|
\code{(\var{availmask}, \var{oldmask})}.
|
|
\var{availmask} indicates which of the
|
|
specified mouse events can be reported; on complete failure it returns
|
|
0. \var{oldmask} is the previous value of the given window's mouse
|
|
event mask. If this function is never called, no mouse events are
|
|
ever reported.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{napms}{ms}
|
|
Sleep for \var{ms} milliseconds.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{newpad}{nlines, ncols}
|
|
Creates and returns a pointer to a new pad data structure with the
|
|
given number of lines and columns. A pad is returned as a
|
|
window object.
|
|
|
|
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 (such as from scrolling or echoing of input) do not
|
|
occur. The \method{refresh()} and \method{noutrefresh()} methods of a
|
|
pad require 6 arguments to specify the part of the pad to be
|
|
displayed and the location on the screen to be used for the display.
|
|
The arguments are pminrow, pmincol, sminrow, smincol, smaxrow,
|
|
smaxcol; the p arguments refer to the upper left corner of the pad
|
|
region to be displayed and the s arguments define a clipping box on
|
|
the screen within which the pad region is to be displayed.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{newwin}{\optional{nlines, ncols,} begin_y, begin_x}
|
|
Return a new window, whose left-upper corner is at
|
|
\code{(\var{begin_y}, \var{begin_x})}, and whose height/width is
|
|
\var{nlines}/\var{ncols}.
|
|
|
|
By default, the window will extend from the
|
|
specified position to the lower right corner of the screen.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{nl}{}
|
|
Enter newline mode. This mode translates the return key into newline
|
|
on input, and translates newline into return and line-feed on output.
|
|
Newline mode is initially on.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{nocbreak}{}
|
|
Leave cbreak mode. Return to normal ``cooked'' mode with line buffering.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{noecho}{}
|
|
Leave echo mode. Echoing of input characters is turned off.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{nonl}{}
|
|
Leave newline mode. Disable translation of return into newline on
|
|
input, and disable low-level translation of newline into
|
|
newline/return on output (but this does not change the behavior of
|
|
\code{addch('\e n')}, which always does the equivalent of return and
|
|
line feed on the virtual screen). With translation off, curses can
|
|
sometimes speed up vertical motion a little; also, it will be able to
|
|
detect the return key on input.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{noqiflush}{}
|
|
When the noqiflush routine is used, normal flush of input and
|
|
output queues associated with the INTR, QUIT and SUSP
|
|
characters will not be done. You may want to call
|
|
\function{noqiflush()} in a signal handler if you want output
|
|
to continue as though the interrupt had not occurred, after the
|
|
handler exits.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{noraw}{}
|
|
Leave raw mode. Return to normal ``cooked'' mode with line buffering.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pair_content}{pair_number}
|
|
Returns a tuple \code{(\var{fg}, \var{bg})} containing the colors for
|
|
the requested color pair. The value of \var{pair_number} must be
|
|
between \code{1} and \code{\constant{COLOR_PAIRS} - 1}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pair_number}{attr}
|
|
Returns the number of the color-pair set by the attribute value
|
|
\var{attr}. \function{color_pair()} is the counterpart to this
|
|
function.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{putp}{string}
|
|
Equivalent to \code{tputs(str, 1, putchar)}; emits the value of a
|
|
specified terminfo capability for the current terminal. Note that the
|
|
output of putp always goes to standard output.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{qiflush}{ \optional{flag} }
|
|
If \var{flag} is false, the effect is the same as calling
|
|
\function{noqiflush()}. If \var{flag} is true, or no argument is
|
|
provided, the queues will be flushed when these control characters are
|
|
read.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{raw}{}
|
|
Enter raw mode. In raw mode, normal line buffering and
|
|
processing of interrupt, quit, suspend, and flow control keys are
|
|
turned off; characters are presented to curses input functions one
|
|
by one.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{reset_prog_mode}{}
|
|
Restores the terminal to ``program'' mode, as previously saved
|
|
by \function{def_prog_mode()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{reset_shell_mode}{}
|
|
Restores the terminal to ``shell'' mode, as previously saved
|
|
by \function{def_shell_mode()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setsyx}{y, x}
|
|
Sets the virtual screen cursor to \var{y}, \var{x}.
|
|
If \var{y} and \var{x} are both -1, then leaveok is set.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{setupterm}{\optional{termstr, fd}}
|
|
Initializes the terminal. \var{termstr} is a string giving the
|
|
terminal name; if omitted, the value of the TERM environment variable
|
|
will be used. \var{fd} is the file descriptor to which any
|
|
initialization sequences will be sent; if not supplied, the file
|
|
descriptor for \code{sys.stdout} will be used.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{start_color}{}
|
|
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 \function{initscr()}.
|
|
|
|
\function{start_color()} initializes eight basic colors (black, red,
|
|
green, yellow, blue, magenta, cyan, and white), and two global
|
|
variables in the \module{curses} module, \constant{COLORS} and
|
|
\constant{COLOR_PAIRS}, containing 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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{termattrs}{}
|
|
Returns a logical OR of all video attributes supported by the
|
|
terminal. This information is useful when a curses program needs
|
|
complete control over the appearance of the screen.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{termname}{}
|
|
Returns the value of the environment variable TERM, truncated to 14
|
|
characters.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tigetflag}{capname}
|
|
Returns the value of the Boolean capability corresponding to the
|
|
terminfo capability name \var{capname}. The value \code{-1} is
|
|
returned if \var{capname} is not a Boolean capability, or \code{0} if
|
|
it is canceled or absent from the terminal description.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tigetnum}{capname}
|
|
Returns the value of the numeric capability corresponding to the
|
|
terminfo capability name \var{capname}. The value \code{-2} is
|
|
returned if \var{capname} is not a numeric capability, or \code{-1} if
|
|
it is canceled or absent from the terminal description.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tigetstr}{capname}
|
|
Returns the value of the string capability corresponding to the
|
|
terminfo capability name \var{capname}. \code{None} is returned if
|
|
\var{capname} is not a string capability, or is canceled or absent
|
|
from the terminal description.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{tparm}{str\optional{,...}}
|
|
Instantiates the string \var{str} with the supplied parameters, where
|
|
\var{str} should be a parameterized string obtained from the terminfo
|
|
database. E.g. \code{tparm(tigetstr("cup"), 5, 3)} could result in
|
|
\code{'\e{}033[6;4H'}, the exact result depending on terminal type.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{typeahead}{fd}
|
|
Specifies that the file descriptor \var{fd} be used for typeahead
|
|
checking. If \var{fd} is \code{-1}, then no typeahead checking is
|
|
done.
|
|
|
|
The curses library does ``line-breakout optimization'' by looking for
|
|
typeahead periodically while updating the screen. If input is found,
|
|
and it is coming from a tty, the current update is postponed until
|
|
refresh or doupdate is called again, allowing faster response to
|
|
commands typed in advance. This function allows specifying a different
|
|
file descriptor for typeahead checking.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{unctrl}{ch}
|
|
Returns a string which is a printable representation of the character
|
|
\var{ch}. Control characters are displayed as a caret followed by the
|
|
character, for example as \code{\textasciicircum C}. Printing
|
|
characters are left as they are.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{ungetch}{ch}
|
|
Push \var{ch} so the next \method{getch()} will return it.
|
|
\note{Only one \var{ch} can be pushed before \method{getch()}
|
|
is called.}
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{ungetmouse}{id, x, y, z, bstate}
|
|
Push a \constant{KEY_MOUSE} event onto the input queue, associating
|
|
the given state data with it.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{use_env}{flag}
|
|
If used, this function should be called before \function{initscr()} or
|
|
newterm are called. When \var{flag} is false, the values of
|
|
lines and columns specified in the terminfo database will be
|
|
used, even if environment variables \envvar{LINES} and
|
|
\envvar{COLUMNS} (used by default) are set, or if curses is running in
|
|
a window (in which case default behavior would be to use the window
|
|
size if \envvar{LINES} and \envvar{COLUMNS} are not set).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{use_default_colors}{}
|
|
Allow use of default values for colors on terminals supporting this
|
|
feature. Use this to support transparency in your
|
|
application. The default color is assigned to the color number -1.
|
|
After calling this function,
|
|
\code{init_pair(x, curses.COLOR_RED, -1)} initializes, for instance,
|
|
color pair \var{x} to a red foreground color on the default background.
|
|
\end{funcdesc}
|
|
|
|
\subsection{Window Objects \label{curses-window-objects}}
|
|
|
|
Window objects, as returned by \function{initscr()} and
|
|
\function{newwin()} above, have the
|
|
following methods:
|
|
|
|
\begin{methoddesc}[window]{addch}{\optional{y, x,} ch\optional{, attr}}
|
|
\note{A \emph{character} means a C character (an
|
|
\ASCII{} code), rather then a Python character (a string of length 1).
|
|
(This note is true whenever the documentation mentions a character.)
|
|
The builtin \function{ord()} is handy for conveying strings to codes.}
|
|
|
|
Paint character \var{ch} at \code{(\var{y}, \var{x})} with attributes
|
|
\var{attr}, overwriting any character previously painter at that
|
|
location. By default, the character position and attributes are the
|
|
current settings for the window object.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{addnstr}{\optional{y, x,} str, n\optional{, attr}}
|
|
Paint at most \var{n} characters of the
|
|
string \var{str} at \code{(\var{y}, \var{x})} with attributes
|
|
\var{attr}, overwriting anything previously on the display.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{addstr}{\optional{y, x,} str\optional{, attr}}
|
|
Paint the string \var{str} at \code{(\var{y}, \var{x})} with attributes
|
|
\var{attr}, overwriting anything previously on the display.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{attroff}{attr}
|
|
Remove attribute \var{attr} from the ``background'' set applied to all
|
|
writes to the current window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{attron}{attr}
|
|
Add attribute \var{attr} from the ``background'' set applied to all
|
|
writes to the current window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{attrset}{attr}
|
|
Set the ``background'' set of attributes to \var{attr}. This set is
|
|
initially 0 (no attributes).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{bkgd}{ch\optional{, attr}}
|
|
Sets the background property of the window to the character \var{ch},
|
|
with attributes \var{attr}. The change is then applied to every
|
|
character position in that window:
|
|
\begin{itemize}
|
|
\item
|
|
The attribute of every character in the window is
|
|
changed to the new background attribute.
|
|
\item
|
|
Wherever the former background character appears,
|
|
it is changed to the new background character.
|
|
\end{itemize}
|
|
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{bkgdset}{ch\optional{, attr}}
|
|
Sets the window's background. A window's background consists of a
|
|
character and any combination of attributes. The attribute part of
|
|
the background is combined (OR'ed) with all non-blank characters that
|
|
are written into the window. Both the character and attribute parts
|
|
of the background are combined with the blank characters. The
|
|
background becomes a property of the character and moves with the
|
|
character through any scrolling and insert/delete line/character
|
|
operations.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{border}{\optional{ls\optional{, rs\optional{,
|
|
ts\optional{, bs\optional{, tl\optional{,
|
|
tr\optional{, bl\optional{, br}}}}}}}}}
|
|
Draw a border around the edges of the window. Each parameter specifies
|
|
the character to use for a specific part of the border; see the table
|
|
below for more details. The characters can be specified as integers
|
|
or as one-character strings.
|
|
|
|
\note{A \code{0} value for any parameter will cause the
|
|
default character to be used for that parameter. Keyword parameters
|
|
can \emph{not} be used. The defaults are listed in this table:}
|
|
|
|
\begin{tableiii}{l|l|l}{var}{Parameter}{Description}{Default value}
|
|
\lineiii{ls}{Left side}{\constant{ACS_VLINE}}
|
|
\lineiii{rs}{Right side}{\constant{ACS_VLINE}}
|
|
\lineiii{ts}{Top}{\constant{ACS_HLINE}}
|
|
\lineiii{bs}{Bottom}{\constant{ACS_HLINE}}
|
|
\lineiii{tl}{Upper-left corner}{\constant{ACS_ULCORNER}}
|
|
\lineiii{tr}{Upper-right corner}{\constant{ACS_URCORNER}}
|
|
\lineiii{bl}{Bottom-left corner}{\constant{ACS_LLCORNER}}
|
|
\lineiii{br}{Bottom-right corner}{\constant{ACS_LRCORNER}}
|
|
\end{tableiii}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{box}{\optional{vertch, horch}}
|
|
Similar to \method{border()}, but both \var{ls} and \var{rs} are
|
|
\var{vertch} and both \var{ts} and {bs} are \var{horch}. The default
|
|
corner characters are always used by this function.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{clear}{}
|
|
Like \method{erase()}, but also causes the whole window to be repainted
|
|
upon next call to \method{refresh()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{clearok}{yes}
|
|
If \var{yes} is 1, the next call to \method{refresh()}
|
|
will clear the window completely.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{clrtobot}{}
|
|
Erase from cursor to the end of the window: all lines below the cursor
|
|
are deleted, and then the equivalent of \method{clrtoeol()} is performed.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{clrtoeol}{}
|
|
Erase from cursor to the end of the line.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{cursyncup}{}
|
|
Updates the current cursor position of all the ancestors of the window
|
|
to reflect the current cursor position of the window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{delch}{\optional{y, x}}
|
|
Delete any character at \code{(\var{y}, \var{x})}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{deleteln}{}
|
|
Delete the line under the cursor. All following lines are moved up
|
|
by 1 line.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{derwin}{\optional{nlines, ncols,} begin_y, begin_x}
|
|
An abbreviation for ``derive window'', \method{derwin()} is the same
|
|
as calling \method{subwin()}, except that \var{begin_y} and
|
|
\var{begin_x} are relative to the origin of the window, rather than
|
|
relative to the entire screen. Returns a window object for the
|
|
derived window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{echochar}{ch\optional{, attr}}
|
|
Add character \var{ch} with attribute \var{attr}, and immediately
|
|
call \method{refresh()} on the window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{enclose}{y, x}
|
|
Tests whether the given pair of screen-relative character-cell
|
|
coordinates are enclosed by the given window, returning true or
|
|
false. It is useful for determining what subset of the screen
|
|
windows enclose the location of a mouse event.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{erase}{}
|
|
Clear the window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{getbegyx}{}
|
|
Return a tuple \code{(\var{y}, \var{x})} of co-ordinates of upper-left
|
|
corner.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{getch}{\optional{y, x}}
|
|
Get a character. Note that the integer returned does \emph{not} have to
|
|
be in \ASCII{} range: function keys, keypad keys and so on return numbers
|
|
higher than 256. In no-delay mode, -1 is returned if there is
|
|
no input.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{getkey}{\optional{y, x}}
|
|
Get a character, returning a string instead of an integer, as
|
|
\method{getch()} does. Function keys, keypad keys and so on return a
|
|
multibyte string containing the key name. In no-delay mode, an
|
|
exception is raised if there is no input.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{getmaxyx}{}
|
|
Return a tuple \code{(\var{y}, \var{x})} of the height and width of
|
|
the window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{getparyx}{}
|
|
Returns the beginning coordinates of this window relative to its
|
|
parent window into two integer variables y and x. Returns
|
|
\code{-1,-1} if this window has no parent.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{getstr}{\optional{y, x}}
|
|
Read a string from the user, with primitive line editing capacity.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{getyx}{}
|
|
Return a tuple \code{(\var{y}, \var{x})} of current cursor position
|
|
relative to the window's upper-left corner.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{hline}{\optional{y, x,} ch, n}
|
|
Display a horizontal line starting at \code{(\var{y}, \var{x})} with
|
|
length \var{n} consisting of the character \var{ch}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{idcok}{flag}
|
|
If \var{flag} is false, curses no longer considers using the hardware
|
|
insert/delete character feature of the terminal; if \var{flag} is
|
|
true, use of character insertion and deletion is enabled. When curses
|
|
is first initialized, use of character insert/delete is enabled by
|
|
default.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{idlok}{yes}
|
|
If called with \var{yes} equal to 1, \module{curses} will try and use
|
|
hardware line editing facilities. Otherwise, line insertion/deletion
|
|
are disabled.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{immedok}{flag}
|
|
If \var{flag} is true, any change in the window image
|
|
automatically causes the window to be refreshed; you no longer
|
|
have to call \method{refresh()} yourself. However, it may
|
|
degrade performance considerably, due to repeated calls to
|
|
wrefresh. This option is disabled by default.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{inch}{\optional{y, x}}
|
|
Return the character at the given position in the window. The bottom
|
|
8 bits are the character proper, and upper bits are the attributes.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{insch}{\optional{y, x,} ch\optional{, attr}}
|
|
Paint character \var{ch} at \code{(\var{y}, \var{x})} with attributes
|
|
\var{attr}, moving the line from position \var{x} right by one
|
|
character.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{insdelln}{nlines}
|
|
Inserts \var{nlines} lines into the specified window above the current
|
|
line. The \var{nlines} bottom lines are lost. For negative
|
|
\var{nlines}, delete \var{nlines} lines starting with the one under
|
|
the cursor, and move the remaining lines up. The bottom \var{nlines}
|
|
lines are cleared. The current cursor position remains the same.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{insertln}{}
|
|
Insert a blank line under the cursor. All following lines are moved
|
|
down by 1 line.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{insnstr}{\optional{y, x,} str, n \optional{, attr}}
|
|
Insert a character string (as many characters as will fit on the line)
|
|
before the character under the cursor, up to \var{n} characters.
|
|
If \var{n} is zero or negative,
|
|
the entire string is inserted.
|
|
All characters to the right of
|
|
the cursor are shifted right, with the rightmost characters on the
|
|
line being lost. The cursor position does not change (after moving to
|
|
\var{y}, \var{x}, if specified).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{insstr}{\optional{y, x, } str \optional{, attr}}
|
|
Insert a character string (as many characters as will fit on the line)
|
|
before the character under the cursor. All characters to the right of
|
|
the cursor are shifted right, with the rightmost characters on the
|
|
line being lost. The cursor position does not change (after moving to
|
|
\var{y}, \var{x}, if specified).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{instr}{\optional{y, x} \optional{, n}}
|
|
Returns a string of characters, extracted from the window starting at
|
|
the current cursor position, or at \var{y}, \var{x} if specified.
|
|
Attributes are stripped from the characters. If \var{n} is specified,
|
|
\method{instr()} returns return a string at most \var{n} characters
|
|
long (exclusive of the trailing NUL).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{is_linetouched}{\var{line}}
|
|
Returns true if the specified line was modified since the last call to
|
|
\method{refresh()}; otherwise returns false. Raises a
|
|
\exception{curses.error} exception if \var{line} is not valid
|
|
for the given window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{is_wintouched}{}
|
|
Returns true if the specified window was modified since the last call to
|
|
\method{refresh()}; otherwise returns false.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{keypad}{yes}
|
|
If \var{yes} is 1, escape sequences generated by some keys (keypad,
|
|
function keys) will be interpreted by \module{curses}.
|
|
If \var{yes} is 0, escape sequences will be left as is in the input
|
|
stream.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{leaveok}{yes}
|
|
If \var{yes} is 1, cursor is left where it is on update, instead of
|
|
being at ``cursor position.'' This reduces cursor movement where
|
|
possible. If possible the cursor will be made invisible.
|
|
|
|
If \var{yes} is 0, cursor will always be at ``cursor position'' after
|
|
an update.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{move}{new_y, new_x}
|
|
Move cursor to \code{(\var{new_y}, \var{new_x})}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{mvderwin}{y, x}
|
|
Moves the window inside its parent window. The screen-relative
|
|
parameters of the window are not changed. This routine is used to
|
|
display different parts of the parent window at the same physical
|
|
position on the screen.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{mvwin}{new_y, new_x}
|
|
Move the window so its upper-left corner is at
|
|
\code{(\var{new_y}, \var{new_x})}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{nodelay}{yes}
|
|
If \var{yes} is \code{1}, \method{getch()} will be non-blocking.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{notimeout}{yes}
|
|
If \var{yes} is \code{1}, escape sequences will not be timed out.
|
|
|
|
If \var{yes} is \code{0}, after a few milliseconds, an escape sequence
|
|
will not be interpreted, and will be left in the input stream as is.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{noutrefresh}{}
|
|
Mark for refresh but wait. This function updates the data structure
|
|
representing the desired state of the window, but does not force
|
|
an update of the physical screen. To accomplish that, call
|
|
\function{doupdate()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{overlay}{destwin\optional{, sminrow, smincol,
|
|
dminrow, dmincol, dmaxrow, dmaxcol}}
|
|
Overlay the window on top of \var{destwin}. The windows need not be
|
|
the same size, only the overlapping region is copied. This copy is
|
|
non-destructive, which means that the current background character
|
|
does not overwrite the old contents of \var{destwin}.
|
|
|
|
To get fine-grained control over the copied region, the second form
|
|
of \method{overlay()} can be used. \var{sminrow} and \var{smincol} are
|
|
the upper-left coordinates of the source window, and the other variables
|
|
mark a rectangle in the destination window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{overwrite}{destwin\optional{, sminrow, smincol,
|
|
dminrow, dmincol, dmaxrow, dmaxcol}}
|
|
Overwrite the window on top of \var{destwin}. The windows need not be
|
|
the same size, in which case only the overlapping region is
|
|
copied. This copy is destructive, which means that the current
|
|
background character overwrites the old contents of \var{destwin}.
|
|
|
|
To get fine-grained control over the copied region, the second form
|
|
of \method{overwrite()} can be used. \var{sminrow} and \var{smincol} are
|
|
the upper-left coordinates of the source window, the other variables
|
|
mark a rectangle in the destination window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{putwin}{file}
|
|
Writes all data associated with the window into the provided file
|
|
object. This information can be later retrieved using the
|
|
\function{getwin()} function.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{redrawln}{beg, num}
|
|
Indicates that the \var{num} screen lines, starting at line \var{beg},
|
|
are corrupted and should be completely redrawn on the next
|
|
\method{refresh()} call.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{redrawwin}{}
|
|
Touches the entire window, causing it to be completely redrawn on the
|
|
next \method{refresh()} call.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{refresh}{\optional{pminrow, pmincol, sminrow,
|
|
smincol, smaxrow, smaxcol}}
|
|
Update the display immediately (sync actual screen with previous
|
|
drawing/deleting methods).
|
|
|
|
The 6 optional arguments can only be specified when the window is a
|
|
pad created with \function{newpad()}. The additional parameters are
|
|
needed to indicate what part of the pad and screen are involved.
|
|
\var{pminrow} and \var{pmincol} specify the upper left-hand corner of the
|
|
rectangle to be displayed in the pad. \var{sminrow}, \var{smincol},
|
|
\var{smaxrow}, and \var{smaxcol} specify the edges of the rectangle to
|
|
be displayed on the screen. The lower right-hand corner of the
|
|
rectangle to be displayed in the pad is calculated from the screen
|
|
coordinates, since the rectangles must be the same size. Both
|
|
rectangles must be entirely contained within their respective
|
|
structures. Negative values of \var{pminrow}, \var{pmincol},
|
|
\var{sminrow}, or \var{smincol} are treated as if they were zero.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{scroll}{\optional{lines\code{ = 1}}}
|
|
Scroll the screen or scrolling region upward by \var{lines} lines.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{scrollok}{flag}
|
|
Controls what happens when the cursor of a window is moved off the
|
|
edge of the window or scrolling region, either as a result of a
|
|
newline action on the bottom line, or typing the last character
|
|
of the last line. If \var{flag} is false, the cursor is left
|
|
on the bottom line. If \var{flag} is true, the window is
|
|
scrolled up one line. Note that in order to get the physical
|
|
scrolling effect on the terminal, it is also necessary to call
|
|
\method{idlok()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{setscrreg}{top, bottom}
|
|
Set the scrolling region from line \var{top} to line \var{bottom}. All
|
|
scrolling actions will take place in this region.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{standend}{}
|
|
Turn off the standout attribute. On some terminals this has the
|
|
side effect of turning off all attributes.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{standout}{}
|
|
Turn on attribute \var{A_STANDOUT}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{subpad}{\optional{nlines, ncols,} begin_y, begin_x}
|
|
Return a sub-window, whose upper-left corner is at
|
|
\code{(\var{begin_y}, \var{begin_x})}, and whose width/height is
|
|
\var{ncols}/\var{nlines}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{subwin}{\optional{nlines, ncols,} begin_y, begin_x}
|
|
Return a sub-window, whose upper-left corner is at
|
|
\code{(\var{begin_y}, \var{begin_x})}, and whose width/height is
|
|
\var{ncols}/\var{nlines}.
|
|
|
|
By default, the sub-window will extend from the
|
|
specified position to the lower right corner of the window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{syncdown}{}
|
|
Touches each location in the window that has been touched in any of
|
|
its ancestor windows. This routine is called by \method{refresh()},
|
|
so it should almost never be necessary to call it manually.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{syncok}{flag}
|
|
If called with \var{flag} set to true, then \method{syncup()} is
|
|
called automatically whenever there is a change in the window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{syncup}{}
|
|
Touches all locations in ancestors of the window that have been changed in
|
|
the window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{timeout}{delay}
|
|
Sets blocking or non-blocking read behavior for the window. If
|
|
\var{delay} is negative, blocking read is used (which will wait
|
|
indefinitely for input). If \var{delay} is zero, then non-blocking
|
|
read is used, and -1 will be returned by \method{getch()} if no input
|
|
is waiting. If \var{delay} is positive, then \method{getch()} will
|
|
block for \var{delay} milliseconds, and return -1 if there is still no
|
|
input at the end of that time.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{touchline}{start, count}
|
|
Pretend \var{count} lines have been changed, starting with line
|
|
\var{start}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{touchwin}{}
|
|
Pretend the whole window has been changed, for purposes of drawing
|
|
optimizations.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{untouchwin}{}
|
|
Marks all lines in the window as unchanged since the last call to
|
|
\method{refresh()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[window]{vline}{\optional{y, x,} ch, n}
|
|
Display a vertical line starting at \code{(\var{y}, \var{x})} with
|
|
length \var{n} consisting of the character \var{ch}.
|
|
\end{methoddesc}
|
|
|
|
\subsection{Constants}
|
|
|
|
The \module{curses} module defines the following data members:
|
|
|
|
\begin{datadesc}{ERR}
|
|
Some curses routines that return an integer, such as
|
|
\function{getch()}, return \constant{ERR} upon failure.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{OK}
|
|
Some curses routines that return an integer, such as
|
|
\function{napms()}, return \constant{OK} upon success.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{version}
|
|
A string representing the current version of the module.
|
|
Also available as \constant{__version__}.
|
|
\end{datadesc}
|
|
|
|
Several constants are available to specify character cell attributes:
|
|
|
|
\begin{tableii}{l|l}{code}{Attribute}{Meaning}
|
|
\lineii{A_ALTCHARSET}{Alternate character set mode.}
|
|
\lineii{A_BLINK}{Blink mode.}
|
|
\lineii{A_BOLD}{Bold mode.}
|
|
\lineii{A_DIM}{Dim mode.}
|
|
\lineii{A_NORMAL}{Normal attribute.}
|
|
\lineii{A_STANDOUT}{Standout mode.}
|
|
\lineii{A_UNDERLINE}{Underline mode.}
|
|
\end{tableii}
|
|
|
|
Keys are referred to by integer constants with names starting with
|
|
\samp{KEY_}. The exact keycaps available are system dependent.
|
|
|
|
% XXX this table is far too large!
|
|
% XXX should this table be alphabetized?
|
|
|
|
\begin{longtableii}{l|l}{code}{Key constant}{Key}
|
|
\lineii{KEY_MIN}{Minimum key value}
|
|
\lineii{KEY_BREAK}{ Break key (unreliable) }
|
|
\lineii{KEY_DOWN}{ Down-arrow }
|
|
\lineii{KEY_UP}{ Up-arrow }
|
|
\lineii{KEY_LEFT}{ Left-arrow }
|
|
\lineii{KEY_RIGHT}{ Right-arrow }
|
|
\lineii{KEY_HOME}{ Home key (upward+left arrow) }
|
|
\lineii{KEY_BACKSPACE}{ Backspace (unreliable) }
|
|
\lineii{KEY_F0}{ Function keys. Up to 64 function keys are supported. }
|
|
\lineii{KEY_F\var{n}}{ Value of function key \var{n} }
|
|
\lineii{KEY_DL}{ Delete line }
|
|
\lineii{KEY_IL}{ Insert line }
|
|
\lineii{KEY_DC}{ Delete character }
|
|
\lineii{KEY_IC}{ Insert char or enter insert mode }
|
|
\lineii{KEY_EIC}{ Exit insert char mode }
|
|
\lineii{KEY_CLEAR}{ Clear screen }
|
|
\lineii{KEY_EOS}{ Clear to end of screen }
|
|
\lineii{KEY_EOL}{ Clear to end of line }
|
|
\lineii{KEY_SF}{ Scroll 1 line forward }
|
|
\lineii{KEY_SR}{ Scroll 1 line backward (reverse) }
|
|
\lineii{KEY_NPAGE}{ Next page }
|
|
\lineii{KEY_PPAGE}{ Previous page }
|
|
\lineii{KEY_STAB}{ Set tab }
|
|
\lineii{KEY_CTAB}{ Clear tab }
|
|
\lineii{KEY_CATAB}{ Clear all tabs }
|
|
\lineii{KEY_ENTER}{ Enter or send (unreliable) }
|
|
\lineii{KEY_SRESET}{ Soft (partial) reset (unreliable) }
|
|
\lineii{KEY_RESET}{ Reset or hard reset (unreliable) }
|
|
\lineii{KEY_PRINT}{ Print }
|
|
\lineii{KEY_LL}{ Home down or bottom (lower left) }
|
|
\lineii{KEY_A1}{ Upper left of keypad }
|
|
\lineii{KEY_A3}{ Upper right of keypad }
|
|
\lineii{KEY_B2}{ Center of keypad }
|
|
\lineii{KEY_C1}{ Lower left of keypad }
|
|
\lineii{KEY_C3}{ Lower right of keypad }
|
|
\lineii{KEY_BTAB}{ Back tab }
|
|
\lineii{KEY_BEG}{ Beg (beginning) }
|
|
\lineii{KEY_CANCEL}{ Cancel }
|
|
\lineii{KEY_CLOSE}{ Close }
|
|
\lineii{KEY_COMMAND}{ Cmd (command) }
|
|
\lineii{KEY_COPY}{ Copy }
|
|
\lineii{KEY_CREATE}{ Create }
|
|
\lineii{KEY_END}{ End }
|
|
\lineii{KEY_EXIT}{ Exit }
|
|
\lineii{KEY_FIND}{ Find }
|
|
\lineii{KEY_HELP}{ Help }
|
|
\lineii{KEY_MARK}{ Mark }
|
|
\lineii{KEY_MESSAGE}{ Message }
|
|
\lineii{KEY_MOVE}{ Move }
|
|
\lineii{KEY_NEXT}{ Next }
|
|
\lineii{KEY_OPEN}{ Open }
|
|
\lineii{KEY_OPTIONS}{ Options }
|
|
\lineii{KEY_PREVIOUS}{ Prev (previous) }
|
|
\lineii{KEY_REDO}{ Redo }
|
|
\lineii{KEY_REFERENCE}{ Ref (reference) }
|
|
\lineii{KEY_REFRESH}{ Refresh }
|
|
\lineii{KEY_REPLACE}{ Replace }
|
|
\lineii{KEY_RESTART}{ Restart }
|
|
\lineii{KEY_RESUME}{ Resume }
|
|
\lineii{KEY_SAVE}{ Save }
|
|
\lineii{KEY_SBEG}{ Shifted Beg (beginning) }
|
|
\lineii{KEY_SCANCEL}{ Shifted Cancel }
|
|
\lineii{KEY_SCOMMAND}{ Shifted Command }
|
|
\lineii{KEY_SCOPY}{ Shifted Copy }
|
|
\lineii{KEY_SCREATE}{ Shifted Create }
|
|
\lineii{KEY_SDC}{ Shifted Delete char }
|
|
\lineii{KEY_SDL}{ Shifted Delete line }
|
|
\lineii{KEY_SELECT}{ Select }
|
|
\lineii{KEY_SEND}{ Shifted End }
|
|
\lineii{KEY_SEOL}{ Shifted Clear line }
|
|
\lineii{KEY_SEXIT}{ Shifted Dxit }
|
|
\lineii{KEY_SFIND}{ Shifted Find }
|
|
\lineii{KEY_SHELP}{ Shifted Help }
|
|
\lineii{KEY_SHOME}{ Shifted Home }
|
|
\lineii{KEY_SIC}{ Shifted Input }
|
|
\lineii{KEY_SLEFT}{ Shifted Left arrow }
|
|
\lineii{KEY_SMESSAGE}{ Shifted Message }
|
|
\lineii{KEY_SMOVE}{ Shifted Move }
|
|
\lineii{KEY_SNEXT}{ Shifted Next }
|
|
\lineii{KEY_SOPTIONS}{ Shifted Options }
|
|
\lineii{KEY_SPREVIOUS}{ Shifted Prev }
|
|
\lineii{KEY_SPRINT}{ Shifted Print }
|
|
\lineii{KEY_SREDO}{ Shifted Redo }
|
|
\lineii{KEY_SREPLACE}{ Shifted Replace }
|
|
\lineii{KEY_SRIGHT}{ Shifted Right arrow }
|
|
\lineii{KEY_SRSUME}{ Shifted Resume }
|
|
\lineii{KEY_SSAVE}{ Shifted Save }
|
|
\lineii{KEY_SSUSPEND}{ Shifted Suspend }
|
|
\lineii{KEY_SUNDO}{ Shifted Undo }
|
|
\lineii{KEY_SUSPEND}{ Suspend }
|
|
\lineii{KEY_UNDO}{ Undo }
|
|
\lineii{KEY_MOUSE}{ Mouse event has occurred }
|
|
\lineii{KEY_RESIZE}{ Terminal resize event }
|
|
\lineii{KEY_MAX}{Maximum key value}
|
|
\end{longtableii}
|
|
|
|
On VT100s and their software emulations, such as X terminal emulators,
|
|
there are normally at least four function keys (\constant{KEY_F1},
|
|
\constant{KEY_F2}, \constant{KEY_F3}, \constant{KEY_F4}) available,
|
|
and the arrow keys mapped to \constant{KEY_UP}, \constant{KEY_DOWN},
|
|
\constant{KEY_LEFT} and \constant{KEY_RIGHT} in the obvious way. If
|
|
your machine has a PC keyboard, it is safe to expect arrow keys and
|
|
twelve function keys (older PC keyboards may have only ten function
|
|
keys); also, the following keypad mappings are standard:
|
|
|
|
\begin{tableii}{l|l}{kbd}{Keycap}{Constant}
|
|
\lineii{Insert}{KEY_IC}
|
|
\lineii{Delete}{KEY_DC}
|
|
\lineii{Home}{KEY_HOME}
|
|
\lineii{End}{KEY_END}
|
|
\lineii{Page Up}{KEY_NPAGE}
|
|
\lineii{Page Down}{KEY_PPAGE}
|
|
\end{tableii}
|
|
|
|
The following table lists characters from the alternate character set.
|
|
These are inherited from the VT100 terminal, and will generally be
|
|
available on software emulations such as X terminals. When there
|
|
is no graphic available, curses falls back on a crude printable ASCII
|
|
approximation.
|
|
\note{These are available only after \function{initscr()} has
|
|
been called.}
|
|
|
|
\begin{longtableii}{l|l}{code}{ACS code}{Meaning}
|
|
\lineii{ACS_BBSS}{alternate name for upper right corner}
|
|
\lineii{ACS_BLOCK}{solid square block}
|
|
\lineii{ACS_BOARD}{board of squares}
|
|
\lineii{ACS_BSBS}{alternate name for horizontal line}
|
|
\lineii{ACS_BSSB}{alternate name for upper left corner}
|
|
\lineii{ACS_BSSS}{alternate name for top tee}
|
|
\lineii{ACS_BTEE}{bottom tee}
|
|
\lineii{ACS_BULLET}{bullet}
|
|
\lineii{ACS_CKBOARD}{checker board (stipple)}
|
|
\lineii{ACS_DARROW}{arrow pointing down}
|
|
\lineii{ACS_DEGREE}{degree symbol}
|
|
\lineii{ACS_DIAMOND}{diamond}
|
|
\lineii{ACS_GEQUAL}{greater-than-or-equal-to}
|
|
\lineii{ACS_HLINE}{horizontal line}
|
|
\lineii{ACS_LANTERN}{lantern symbol}
|
|
\lineii{ACS_LARROW}{left arrow}
|
|
\lineii{ACS_LEQUAL}{less-than-or-equal-to}
|
|
\lineii{ACS_LLCORNER}{lower left-hand corner}
|
|
\lineii{ACS_LRCORNER}{lower right-hand corner}
|
|
\lineii{ACS_LTEE}{left tee}
|
|
\lineii{ACS_NEQUAL}{not-equal sign}
|
|
\lineii{ACS_PI}{letter pi}
|
|
\lineii{ACS_PLMINUS}{plus-or-minus sign}
|
|
\lineii{ACS_PLUS}{big plus sign}
|
|
\lineii{ACS_RARROW}{right arrow}
|
|
\lineii{ACS_RTEE}{right tee}
|
|
\lineii{ACS_S1}{scan line 1}
|
|
\lineii{ACS_S3}{scan line 3}
|
|
\lineii{ACS_S7}{scan line 7}
|
|
\lineii{ACS_S9}{scan line 9}
|
|
\lineii{ACS_SBBS}{alternate name for lower right corner}
|
|
\lineii{ACS_SBSB}{alternate name for vertical line}
|
|
\lineii{ACS_SBSS}{alternate name for right tee}
|
|
\lineii{ACS_SSBB}{alternate name for lower left corner}
|
|
\lineii{ACS_SSBS}{alternate name for bottom tee}
|
|
\lineii{ACS_SSSB}{alternate name for left tee}
|
|
\lineii{ACS_SSSS}{alternate name for crossover or big plus}
|
|
\lineii{ACS_STERLING}{pound sterling}
|
|
\lineii{ACS_TTEE}{top tee}
|
|
\lineii{ACS_UARROW}{up arrow}
|
|
\lineii{ACS_ULCORNER}{upper left corner}
|
|
\lineii{ACS_URCORNER}{upper right corner}
|
|
\lineii{ACS_VLINE}{vertical line}
|
|
\end{longtableii}
|
|
|
|
The following table lists the predefined colors:
|
|
|
|
\begin{tableii}{l|l}{code}{Constant}{Color}
|
|
\lineii{COLOR_BLACK}{Black}
|
|
\lineii{COLOR_BLUE}{Blue}
|
|
\lineii{COLOR_CYAN}{Cyan (light greenish blue)}
|
|
\lineii{COLOR_GREEN}{Green}
|
|
\lineii{COLOR_MAGENTA}{Magenta (purplish red)}
|
|
\lineii{COLOR_RED}{Red}
|
|
\lineii{COLOR_WHITE}{White}
|
|
\lineii{COLOR_YELLOW}{Yellow}
|
|
\end{tableii}
|
|
|
|
\section{\module{curses.textpad} ---
|
|
Text input widget for curses programs}
|
|
|
|
\declaremodule{standard}{curses.textpad}
|
|
\sectionauthor{Eric Raymond}{esr@thyrsus.com}
|
|
\moduleauthor{Eric Raymond}{esr@thyrsus.com}
|
|
\modulesynopsis{Emacs-like input editing in a curses window.}
|
|
\versionadded{1.6}
|
|
|
|
The \module{curses.textpad} module provides a \class{Textbox} class
|
|
that handles elementary text editing in a curses window, supporting a
|
|
set of keybindings resembling those of Emacs (thus, also of Netscape
|
|
Navigator, BBedit 6.x, FrameMaker, and many other programs). The
|
|
module also provides a rectangle-drawing function useful for framing
|
|
text boxes or for other purposes.
|
|
|
|
The module \module{curses.textpad} defines the following function:
|
|
|
|
\begin{funcdesc}{rectangle}{win, uly, ulx, lry, lrx}
|
|
Draw a rectangle. The first argument must be a window object; the
|
|
remaining arguments are coordinates relative to that window. The
|
|
second and third arguments are the y and x coordinates of the upper
|
|
left hand corner of the rectangle to be drawn; the fourth and fifth
|
|
arguments are the y and x coordinates of the lower right hand corner.
|
|
The rectangle will be drawn using VT100/IBM PC forms characters on
|
|
terminals that make this possible (including xterm and most other
|
|
software terminal emulators). Otherwise it will be drawn with ASCII
|
|
dashes, vertical bars, and plus signs.
|
|
\end{funcdesc}
|
|
|
|
|
|
\subsection{Textbox objects \label{curses-textpad-objects}}
|
|
|
|
You can instantiate a \class{Textbox} object as follows:
|
|
|
|
\begin{classdesc}{Textbox}{win}
|
|
Return a textbox widget object. The \var{win} argument should be a
|
|
curses \class{WindowObject} in which the textbox is to be contained.
|
|
The edit cursor of the textbox is initially located at the upper left
|
|
hand corner of the containing window, with coordinates \code{(0, 0)}.
|
|
The instance's \member{stripspaces} flag is initially on.
|
|
\end{classdesc}
|
|
|
|
\class{Textbox} objects have the following methods:
|
|
|
|
\begin{methoddesc}{edit}{\optional{validator}}
|
|
This is the entry point you will normally use. It accepts editing
|
|
keystrokes until one of the termination keystrokes is entered. If
|
|
\var{validator} is supplied, it must be a function. It will be called
|
|
for each keystroke entered with the keystroke as a parameter; command
|
|
dispatch is done on the result. This method returns the window
|
|
contents as a string; whether blanks in the window are included is
|
|
affected by the \member{stripspaces} member.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{do_command}{ch}
|
|
Process a single command keystroke. Here are the supported special
|
|
keystrokes:
|
|
|
|
\begin{tableii}{l|l}{kbd}{Keystroke}{Action}
|
|
\lineii{Control-A}{Go to left edge of window.}
|
|
\lineii{Control-B}{Cursor left, wrapping to previous line if appropriate.}
|
|
\lineii{Control-D}{Delete character under cursor.}
|
|
\lineii{Control-E}{Go to right edge (stripspaces off) or end of line
|
|
(stripspaces on).}
|
|
\lineii{Control-F}{Cursor right, wrapping to next line when appropriate.}
|
|
\lineii{Control-G}{Terminate, returning the window contents.}
|
|
\lineii{Control-H}{Delete character backward.}
|
|
\lineii{Control-J}{Terminate if the window is 1 line, otherwise
|
|
insert newline.}
|
|
\lineii{Control-K}{If line is blank, delete it, otherwise clear to
|
|
end of line.}
|
|
\lineii{Control-L}{Refresh screen.}
|
|
\lineii{Control-N}{Cursor down; move down one line.}
|
|
\lineii{Control-O}{Insert a blank line at cursor location.}
|
|
\lineii{Control-P}{Cursor up; move up one line.}
|
|
\end{tableii}
|
|
|
|
Move operations do nothing if the cursor is at an edge where the
|
|
movement is not possible. The following synonyms are supported where
|
|
possible:
|
|
|
|
\begin{tableii}{l|l}{constant}{Constant}{Keystroke}
|
|
\lineii{KEY_LEFT}{\kbd{Control-B}}
|
|
\lineii{KEY_RIGHT}{\kbd{Control-F}}
|
|
\lineii{KEY_UP}{\kbd{Control-P}}
|
|
\lineii{KEY_DOWN}{\kbd{Control-N}}
|
|
\lineii{KEY_BACKSPACE}{\kbd{Control-h}}
|
|
\end{tableii}
|
|
|
|
All other keystrokes are treated as a command to insert the given
|
|
character and move right (with line wrapping).
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{gather}{}
|
|
This method returns the window contents as a string; whether blanks in
|
|
the window are included is affected by the \member{stripspaces}
|
|
member.
|
|
\end{methoddesc}
|
|
|
|
\begin{memberdesc}{stripspaces}
|
|
This data member is a flag which controls the interpretation of blanks in
|
|
the window. When it is on, trailing blanks on each line are ignored;
|
|
any cursor motion that would land the cursor on a trailing blank goes
|
|
to the end of that line instead, and trailing blanks are stripped when
|
|
the window contents are gathered.
|
|
\end{memberdesc}
|
|
|
|
|
|
\section{\module{curses.wrapper} ---
|
|
Terminal handler for curses programs}
|
|
|
|
\declaremodule{standard}{curses.wrapper}
|
|
\sectionauthor{Eric Raymond}{esr@thyrsus.com}
|
|
\moduleauthor{Eric Raymond}{esr@thyrsus.com}
|
|
\modulesynopsis{Terminal configuration wrapper for curses programs.}
|
|
\versionadded{1.6}
|
|
|
|
This module supplies one function, \function{wrapper()}, which runs
|
|
another function which should be the rest of your curses-using
|
|
application. If the application raises an exception,
|
|
\function{wrapper()} will restore the terminal to a sane state before
|
|
re-raising the exception and generating a traceback.
|
|
|
|
\begin{funcdesc}{wrapper}{func, \moreargs}
|
|
Wrapper function that initializes curses and calls another function,
|
|
\var{func}, restoring normal keyboard/screen behavior on error.
|
|
The callable object \var{func} is then passed the main window 'stdscr'
|
|
as its first argument, followed by any other arguments passed to
|
|
\function{wrapper()}.
|
|
\end{funcdesc}
|
|
|
|
Before calling the hook function, \function{wrapper()} turns on cbreak
|
|
mode, turns off echo, enables the terminal keypad, and initializes
|
|
colors if the terminal has color support. On exit (whether normally
|
|
or by exception) it restores cooked mode, turns on echo, and disables
|
|
the terminal keypad.
|
|
|