mirror of
https://github.com/python/cpython.git
synced 2025-11-03 19:34:08 +00:00
f1dc5fa2c8
now complete, but probably still not very helpful or friendly. Note: two very large tables (of key names, and of character names) were added; these tables format terribly, and need some reworking.
987 lines
34 KiB
TeX
987 lines
34 KiB
TeX
\section{\module{curses} ---
|
|
Terminal independant console handling}
|
|
|
|
\declaremodule{extension}{curses}
|
|
\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
|
|
\modulesynopsis{An interface to the curses library.}
|
|
|
|
The \module{curses} module provides an interface to the curses \UNIX{}
|
|
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. The
|
|
extension module has not been tested with all available versions of
|
|
curses.
|
|
|
|
\begin{seealso}
|
|
\seetext{Tutorial material on using curses with Python is available
|
|
on the Python Web site as Andrew Kuchling's
|
|
\citetitle[http://www.python.org/doc/howto/curses/curses.html]{Curses
|
|
Programming with Python}, at
|
|
\url{http://www.python.org/doc/howto/curses/curses.html}.}
|
|
\end{seealso}
|
|
|
|
|
|
\subsection{Functions \label{curses-functions}}
|
|
|
|
The module \module{curses} defines the following exception:
|
|
\begin{excdesc}{error}
|
|
Curses function returned an error status.
|
|
\end{excdesc}
|
|
|
|
\strong{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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{beep}{}
|
|
Emit a short 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.
|
|
\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 0 and COLORS. A
|
|
3-tuple is returned, containing the R,G,B values for the given color,
|
|
which will be between 0 (no component) and 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.
|
|
\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 screen.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{echo}{}
|
|
Enter echo mode.
|
|
\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.
|
|
\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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{flash}{}
|
|
Flash the screen.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{flushinp}{}
|
|
Flush all input buffers.
|
|
\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 manipulate colors; otherwise, it
|
|
returns false.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{has_ic}{}
|
|
Returns true if the terminal has insert- and delete- character
|
|
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.
|
|
\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 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 0 and COLORS. Each of \var{r}, \var{g}, \var{b}, must be a
|
|
value between 0 and 1000. When \function{init_color()} is used, all
|
|
occurrences of that color on the screen immediately change to the new
|
|
definition.
|
|
\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 1 and COLOR_PAIRS-1 (the 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 0 and 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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{isendwin}{}
|
|
Returns true if \function{endwin()} has been called.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{keyname}{k}
|
|
Return the name of the key numbered \var{k}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{killchar}{}
|
|
Returns the user's current line kill character.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{longname}{}
|
|
Returns a string containing 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
|
|
\function{initscr()}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{meta}{yes}
|
|
If \var{yes} is 1, allow 8-bit characters. If \var{yes} is 0,
|
|
allow only 7-bit chars.
|
|
\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 (e.g., from scrolling or echoing of
|
|
input) do not occur. It is not legal to call wrefresh
|
|
with a pad as an argument; the routines prefresh or
|
|
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.
|
|
|
|
\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 nl mode.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{nocbreak}{}
|
|
Leave cbreak mode.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{noecho}{}
|
|
Leave echo mode.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{nonl}{}
|
|
Leave nl mode.
|
|
\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.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{pair_content}{pair_number}
|
|
Returns a tuple \var{(fg,bg)} containing the colors for the requested
|
|
color pair. The value of \var{pair_number} must be between 0 and
|
|
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)}. 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.
|
|
\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}{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, COLORS and 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}{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 \verb|^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.
|
|
\strong{Note:} only one \var{ch} can be pushed before \method{getch()}
|
|
is called.
|
|
\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 LINES and 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 LINES
|
|
and COLUMNS are not set).
|
|
\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}{addch}{\optional{y, x,} ch\optional{, attr}}
|
|
\strong{Note:} A \emph{character} means a C character (i.e., an
|
|
\ASCII{} code), rather then a Python character (a string of length 1).
|
|
(This note is true whenever the documentation mentions a character.)
|
|
|
|
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}{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}{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}{attroff}{attr}
|
|
Turn off attribute \var{attr}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{attron}{attr}
|
|
Turn on attribute \var{attr}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{attrset}{attr}
|
|
Set the attributes to \var{attr}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{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}{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}{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 must be specified as integers;
|
|
using one-character strings will cause \exception{TypeError} to be
|
|
raised.
|
|
|
|
\strong{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_BLCORNER}}
|
|
\lineiii{br}{Bottom-right corner}{\constant{ACS_BRCORNER}}
|
|
\end{tableiii}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{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}{clear}{}
|
|
Like \method{erase()}, but also causes the whole screen to be repainted
|
|
upon next call to \method{refresh()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{clearok}{yes}
|
|
If \var{yes} is 1, the next call to \method{refresh()}
|
|
will clear the screen completely.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{clrtobot}{}
|
|
Erase from cursor to the end of the screen: all lines below the cursor
|
|
are deleted, and then the equivalent of \method{clrtoeol()} is performed.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{clrtoeol}{}
|
|
Erase from cursor to the end of the line.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{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}{delch}{\optional{x, y}}
|
|
Delete any character at \code{(\var{y}, \var{x})}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{deleteln}{}
|
|
Delete the line under the cursor. All following lines are moved up
|
|
by 1 line.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{derwin}{\optional{nlines, ncols,} begin_y, begin_y}
|
|
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}{echochar}{ch\optional{, attr}}
|
|
Add character \var{ch} with attribute \var{attr}, and immediately
|
|
call \method{refresh}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{erase}{}
|
|
Clear the window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getbegyx}{}
|
|
Return a tuple \code{(\var{y}, \var{x})} of co-ordinates of upper-left
|
|
corner.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getch}{\optional{x, y}}
|
|
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 then 256. In no-delay mode, an exception is raised if there is
|
|
no input.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getkey}{\optional{x, y}}
|
|
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}{getmaxyx}{}
|
|
Return a tuple \code{(\var{y}, \var{x})} of the height and width of
|
|
the window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{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}{getstr}{\optional{x, y}}
|
|
Read a string from the user, with primitive line editing capacity.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getyx}{}
|
|
Return a tuple \code{(\var{y}, \var{x})} of current cursor position.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{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}{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}{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}{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}{inch}{\optional{x, y}}
|
|
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}{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}{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}{insertln}{}
|
|
Insert a blank line under the cursor. All following lines are moved
|
|
down by 1 line.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{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 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}{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 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}{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}{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}{is_wintouched}{}
|
|
Returns true if the specified window was modified since the last call to
|
|
\method{refresh()}; otherwise returns false.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{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}{leaveok}{yes}
|
|
If \var{yes} is 1,
|
|
cursor is left where it is, instead of being at ``cursor position.''
|
|
This reduces cursor movement where possible. If possible it will be made
|
|
invisible.
|
|
|
|
If \var{yes} is 0, cursor will always be at
|
|
``cursor position'' after an update.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{move}{new_y, new_x}
|
|
Move cursor to \code{(\var{new_y}, \var{new_x})}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{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}{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}{nodelay}{yes}
|
|
If \var{yes} is 1, \method{getch()} will be non-blocking.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{notimeout}{yes}
|
|
If \var{yes} is 1, escape sequences will not be timed out.
|
|
|
|
If \var{yes} is 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}{noutrefresh}{}
|
|
Mark for refresh but wait.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{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}{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}{redrawwin}{}
|
|
Touches the entire window, causing it to be completely redrawn on the
|
|
next \method{refresh()} call.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{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}{scroll}{\optional{lines\code{ = 1}}}
|
|
Scroll the screen upward by \var{lines} lines.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{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}{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}{standend}{}
|
|
Turn off all attributes.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{standout}{}
|
|
Turn on attribute \var{A_STANDOUT}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{subpad}{\optional{nlines, ncols,} begin_y, begin_y}
|
|
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}{subwin}{\optional{nlines, ncols,} begin_y, begin_y}
|
|
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}{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}{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}{syncup}{}
|
|
Touches all locations in ancestors of the window that have been changed in
|
|
the window.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{touchline}{start, count}
|
|
Pretend \var{count} lines have been changed, starting with line
|
|
\var{start}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{touchwin}{}
|
|
Pretend the whole window has been changed, for purposes of drawing
|
|
optimizations.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{untouchwin}{}
|
|
Marks all lines in the window as unchanged since the last call to
|
|
\method{refresh()}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{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}{version}
|
|
A string representing the current version of the module.
|
|
Also available as \constant{__version__}.
|
|
\end{datadesc}
|
|
|
|
|
|
\begin{tableii}{c|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
|
|
\code{KEY_}. The exact names available are system dependent.
|
|
|
|
% XXX this table is far too large!
|
|
% XXX should this table be alphabetized?
|
|
|
|
\begin{tableii}{c|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{tableii}
|
|
|
|
The following table lists characters from the alternate character set.
|
|
\strong{Note:} These are available only after \function{initscr()} has
|
|
been called.
|
|
|
|
\begin{tableii}{c|l}{code}{ACS code}{Meaning}
|
|
\lineii{ACS_BBSS}{}
|
|
\lineii{ACS_BLOCK}{}
|
|
\lineii{ACS_BOARD}{}
|
|
\lineii{ACS_BSBS}{}
|
|
\lineii{ACS_BSSB}{}
|
|
\lineii{ACS_BSSS}{}
|
|
\lineii{ACS_BTEE}{}
|
|
\lineii{ACS_BULLET}{}
|
|
\lineii{ACS_CKBOARD}{}
|
|
\lineii{ACS_DARROW}{}
|
|
\lineii{ACS_DEGREE}{}
|
|
\lineii{ACS_DIAMOND}{}
|
|
\lineii{ACS_GEQUAL}{ (Not available with SGI curses)}
|
|
\lineii{ACS_HLINE}{}
|
|
\lineii{ACS_LANTERN}{}
|
|
\lineii{ACS_LARROW}{}
|
|
\lineii{ACS_LEQUAL}{ (Not available with SGI curses)}
|
|
\lineii{ACS_LLCORNER}{}
|
|
\lineii{ACS_LRCORNER}{}
|
|
\lineii{ACS_LTEE}{}
|
|
\lineii{ACS_NEQUAL}{ (Not available with SGI curses)}
|
|
\lineii{ACS_PI}{ (Not available with SGI curses)}
|
|
\lineii{ACS_PLMINUS}{}
|
|
\lineii{ACS_PLUS}{}
|
|
\lineii{ACS_RARROW}{}
|
|
\lineii{ACS_RTEE}{}
|
|
\lineii{ACS_S1}{}
|
|
\lineii{ACS_S3}{ (Not available with SGI curses)}
|
|
\lineii{ACS_S9}{}
|
|
\lineii{ACS_SBBS}{}
|
|
\lineii{ACS_SBSB}{}
|
|
\lineii{ACS_SBSS}{}
|
|
\lineii{ACS_SSBB}{}
|
|
\lineii{ACS_SSBS}{}
|
|
\lineii{ACS_SSSB}{}
|
|
\lineii{ACS_SSSS}{}
|
|
\lineii{ACS_STERLING}{ (Not available with SGI curses)}
|
|
\lineii{ACS_TTEE}{}
|
|
\lineii{ACS_UARROW}{}
|
|
\lineii{ACS_ULCORNER}{}
|
|
\lineii{ACS_URCORNER}{}
|
|
\lineii{ACS_VLINE}{}
|
|
\end{tableii}
|
|
|
|
The following table lists the predefined colors:
|
|
|
|
\begin{tableii}{c|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}
|
|
|