summaryrefslogtreecommitdiffstats
path: root/Doc/lib/libcurses.tex
diff options
context:
space:
mode:
authorAndrew M. Kuchling <amk@amk.ca>2000-05-23 16:46:04 (GMT)
committerAndrew M. Kuchling <amk@amk.ca>2000-05-23 16:46:04 (GMT)
commitf1dc5fa2c8d97e3618a0a260e9f831e5e2fae554 (patch)
tree5093dda53eec6c453c493ebb5abb9efddc599373 /Doc/lib/libcurses.tex
parent03e644b8514e6628e480c046860ab712079aaadb (diff)
downloadcpython-f1dc5fa2c8d97e3618a0a260e9f831e5e2fae554.zip
cpython-f1dc5fa2c8d97e3618a0a260e9f831e5e2fae554.tar.gz
cpython-f1dc5fa2c8d97e3618a0a260e9f831e5e2fae554.tar.bz2
Updated docs to list all the new methods and functions. The docs are
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.
Diffstat (limited to 'Doc/lib/libcurses.tex')
-rw-r--r--Doc/lib/libcurses.tex945
1 files changed, 757 insertions, 188 deletions
diff --git a/Doc/lib/libcurses.tex b/Doc/lib/libcurses.tex
index a108002..e35c731 100644
--- a/Doc/lib/libcurses.tex
+++ b/Doc/lib/libcurses.tex
@@ -23,87 +23,219 @@ curses.
\end{seealso}
-\subsection{Constants and Functions \label{curses-functions}}
+\subsection{Functions \label{curses-functions}}
-The \module{curses} module defines the following data members:
-
-\begin{datadesc}{version}
-A string representing the current version of the module.
-\end{datadesc}
+The module \module{curses} defines the following exception:
+\begin{excdesc}{error}
+Curses function returned an error status.
+\end{excdesc}
-\begin{datadesc}{A_NORMAL}
-Normal attribute.
-\end{datadesc}
+\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}.
-\begin{datadesc}{A_STANDOUT}
-Standout mode.
-\end{datadesc}
+The module \module{curses} defines the following functions:
-\begin{datadesc}{A_UNDERLINE}
-Underline mode.
-\end{datadesc}
+\begin{funcdesc}{baudrate}{}
+Returns the output speed of the terminal in bits per second.
+\end{funcdesc}
-\begin{datadesc}{A_BLINK}
-Blink mode.
-\end{datadesc}
+\begin{funcdesc}{beep}{}
+Emit a short sound.
+\end{funcdesc}
-\begin{datadesc}{A_DIM}
-Dim mode.
-\end{datadesc}
+\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{datadesc}{A_BOLD}
-Bold mode.
-\end{datadesc}
+\begin{funcdesc}{cbreak}{}
+Enter cbreak mode.
+\end{funcdesc}
-\begin{datadesc}{A_ALTCHARSET}
-Alternate character set mode.
-\end{datadesc}
+\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{datadesc}{KEY_*}
-Names for various keys. The exact names available are system dependant.
-\end{datadesc}
+\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{datadesc}{ACS_*}
-Names for various characters:
-\constant{ACS_ULCORNER}, \constant{ACS_LLCORNER},
-\constant{ACS_URCORNER}, \constant{ACS_LRCORNER}, \constant{ACS_RTEE},
-\constant{ACS_LTEE}, \constant{ACS_BTEE}, \constant{ACS_TTEE},
-\constant{ACS_HLINE}, \constant{ACS_VLINE}, \constant{ACS_PLUS},
-\constant{ACS_S1}, \constant{ACS_S9}, \constant{ACS_DIAMOND},
-\constant{ACS_CKBOARD}, \constant{ACS_DEGREE}, \constant{ACS_PLMINUS},
-\constant{ACS_BULLET}, \constant{ACS_LARROW}, \constant{ACS_RARROW},
-\constant{ACS_DARROW}.
+\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}
-\strong{Note:} These are available only after \function{initscr()} has
-been called.
-\end{datadesc}
+\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}
-The module \module{curses} defines the following exception:
-\begin{excdesc}{error}
-Curses function returned an error status.
-\end{excdesc}
+\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}
-\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}.
+\begin{funcdesc}{delay_output}{ms}
+Inserts an \var{ms} millisecond pause in output.
+\end{funcdesc}
-The module \module{curses} defines the following functions:
+\begin{funcdesc}{doupdate}{}
+Update the screen.
+\end{funcdesc}
-\begin{funcdesc}{initscr}{}
-Initialize the library. Returns a \class{WindowObject} which represents
-the whole screen.
+\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}{doupdate}{}
-Update the screen.
+\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}
@@ -115,98 +247,129 @@ By default, the window will extend from the
specified position to the lower right corner of the screen.
\end{funcdesc}
-\begin{funcdesc}{beep}{}
-Emit a short sound.
+\begin{funcdesc}{nl}{}
+Enter nl mode.
\end{funcdesc}
-\begin{funcdesc}{flash}{}
-Flash the screen.
+\begin{funcdesc}{nocbreak}{}
+Leave cbreak mode.
\end{funcdesc}
-\begin{funcdesc}{ungetch}{ch}
-Push \var{ch} so the next \method{getch()} will return it; \var{ch} is
-an integer specifying the character to be pushed.
-\strong{Note:} only one \var{ch} can be pushed before \method{getch()}
-is called.
+\begin{funcdesc}{noecho}{}
+Leave echo mode.
\end{funcdesc}
-\begin{funcdesc}{flushinp}{}
-Flush all input buffers.
+\begin{funcdesc}{nonl}{}
+Leave nl mode.
\end{funcdesc}
-\begin{funcdesc}{cbreak}{}
-Enter cbreak mode.
+\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}{nocbreak}{}
-Leave cbreak mode.
+\begin{funcdesc}{noraw}{}
+Leave raw mode.
\end{funcdesc}
-\begin{funcdesc}{echo}{}
-Enter echo mode.
+\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}{noecho}{}
-Leave echo mode.
+\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}{nl}{}
-Enter nl mode.
+\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}{nonl}{}
-Leave nl mode.
+\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}{noraw}{}
-Leave raw mode.
+\begin{funcdesc}{reset_prog_mode}{}
+Restores the terminal to ``program'' mode, as previously saved
+by \function{def_prog_mode()}.
\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.
+\begin{funcdesc}{reset_shell_mode}{}
+Restores the terminal to ``shell'' mode, as previously saved
+by \function{def_shell_mode()}.
\end{funcdesc}
-\begin{funcdesc}{keyname}{k}
-Return the name of the key numbered \var{k}.
+\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}
-\subsection{Window Objects \label{curses-window-objects}}
-
-Window objects, as returned by \function{initscr()} and
-\function{newwin()} above, have the
-following methods:
+\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{methoddesc}{refresh}{}
-Update the display immediately (sync actual screen with previous
-drawing/deleting methods).
-\end{methoddesc}
+\begin{funcdesc}{termname}{}
+Returns the value of the environment variable TERM, truncated to 14
+characters.
+\end{funcdesc}
-\begin{methoddesc}{nooutrefresh}{}
-Mark for refresh but wait.
-\end{methoddesc}
+\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{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{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{methoddesc}{move}{new_y, new_x}
-Move cursor to \code{(\var{new_y}, \var{new_x})}.
-\end{methoddesc}
+\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}
-\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}.
+\subsection{Window Objects \label{curses-window-objects}}
-By default, the sub-window will extend from the
-specified position to the lower right corner of the window.
-\end{methoddesc}
+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
@@ -219,44 +382,52 @@ location. By default, the character position and attributes are the
current settings for the window object.
\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}{delch}{\optional{x, y}}
-Delete any character at \code{(\var{y}, \var{x})}.
-\end{methoddesc}
-
-\begin{methoddesc}{echochar}{ch\optional{, attr}}
-Add character \var{ch} with attribute \var{attr}, and immediately
-call \method{refresh}.
+\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 string \var{str} at \code{(\var{y}, \var{x})} with attributes
+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}{attroff}{attr}
-Turn off attribute \var{attr}.
+\begin{methoddesc}{attrset}{attr}
+Set the attributes to \var{attr}.
\end{methoddesc}
-\begin{methoddesc}{setattr}{attr}
-Set the current 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}
-\begin{methoddesc}{standend}{}
-Turn off all attributes.
\end{methoddesc}
-\begin{methoddesc}{standout}{}
-Turn on attribute \var{A_STANDOUT}.
+\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{,
@@ -290,32 +461,54 @@ Similar to \method{border()}, but both \var{ls} and \var{rs} are
corner characters are always used by this function.
\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}.
+\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}{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}.
+\begin{methoddesc}{clearok}{yes}
+If \var{yes} is 1, the next call to \method{refresh()}
+will clear the screen completely.
\end{methoddesc}
-\begin{methoddesc}{erase}{}
-Clear the screen.
+\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}{deletln}{}
+\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}{insertln}{}
-Insert a blank line under the cursor. All following lines are moved
-down by 1 line.
+\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}{getyx}{}
-Return a tuple \code{(\var{y}, \var{x})} of current cursor position.
+\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}{}
@@ -323,48 +516,64 @@ 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}{clear}{}
-Like \method{erase()}, but also causes the whole screen to be repainted
-upon next call to \method{refresh()}.
+\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}{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.
+\begin{methoddesc}{getstr}{\optional{x, y}}
+Read a string from the user, with primitive line editing capacity.
\end{methoddesc}
-\begin{methoddesc}{scroll}{\optional{lines\code{ = 1}}}
-Scroll the screen upward by \var{lines} lines.
+\begin{methoddesc}{getyx}{}
+Return a tuple \code{(\var{y}, \var{x})} of current cursor position.
\end{methoddesc}
-\begin{methoddesc}{touchwin}{}
-Pretend the whole window has been changed, for purposes of drawing
-optimizations.
+\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}{touchline}{start, count}
-Pretend \var{count} lines have been changed, starting with line
-\var{start}.
+\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}{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.
+\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}{getstr}{\optional{x, y}}
-Read a string from the user, with primitive line editing capacity.
+\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}}
@@ -372,15 +581,69 @@ 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}{clearok}{yes}
-If \var{yes} is 1, the next call to \method{refresh()}
-will clear the screen completely.
+\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}{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.
+\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}
@@ -393,17 +656,19 @@ If \var{yes} is 0, cursor will always be at
``cursor position'' after an update.
\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.
+\begin{methoddesc}{move}{new_y, new_x}
+Move cursor to \code{(\var{new_y}, \var{new_x})}.
\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}.
+\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}
-If \var{yes} is 0, escape sequences will be left as is in the input
-stream.
+\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}
@@ -416,3 +681,307 @@ 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}
+