[Python-checkins] CVS: python/dist/src/Doc/lib libcurses.tex,1.8,1.9
Eric S. Raymond
python-dev@python.org
Sun, 23 Jul 2000 20:28:43 -0700
Update of /cvsroot/python/python/dist/src/Doc/lib
In directory slayer.i.sourceforge.net:/tmp/cvs-serv11569
Modified Files:
libcurses.tex
Log Message:
First round of curses documentation improvements; correct errors, flesh out
entry point descriptions.
Index: libcurses.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libcurses.tex,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -r1.8 -r1.9
*** libcurses.tex 2000/07/16 19:01:09 1.8
--- libcurses.tex 2000/07/24 03:28:40 1.9
***************
*** 1,7 ****
\section{\module{curses} ---
! Terminal independent console handling}
\declaremodule{extension}{curses}
\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
\modulesynopsis{An interface to the curses library.}
--- 1,8 ----
\section{\module{curses} ---
! Screen painting and input handling for character-cell terminals}
\declaremodule{extension}{curses}
\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
+ \sectionauthor{Eric Raymond}{esr@thyrsus.com}
\modulesynopsis{An interface to the curses library.}
***************
*** 11,17 ****
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}
--- 12,19 ----
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}
***************
*** 19,22 ****
--- 21,26 ----
characters, regardless of your locale
settings.}
+ \seemodule{curses.textbox}{Editable text widget for curses supporting
+ Emacs-like bindings.}
\seetext{Tutorial material on using curses with Python is available
on the Python Web site as Andrew Kuchling's
***************
*** 41,49 ****
\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}
--- 45,57 ----
\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}
***************
*** 54,58 ****
\begin{funcdesc}{cbreak}{}
! Enter cbreak mode.
\end{funcdesc}
--- 62,71 ----
\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}
***************
*** 76,80 ****
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}
--- 89,94 ----
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}
***************
*** 99,107 ****
\begin{funcdesc}{doupdate}{}
! Update the screen.
\end{funcdesc}
\begin{funcdesc}{echo}{}
! Enter echo mode.
\end{funcdesc}
--- 113,134 ----
\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}
***************
*** 111,132 ****
\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}
--- 138,165 ----
\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 cgaracter-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}
***************
*** 164,168 ****
\begin{funcdesc}{has_colors}{}
! Returns true if the terminal can manipulate colors; otherwise, it
returns false.
\end{funcdesc}
--- 197,201 ----
\begin{funcdesc}{has_colors}{}
! Returns true if the terminal can display colors; otherwise, it
returns false.
\end{funcdesc}
***************
*** 170,174 ****
\begin{funcdesc}{has_ic}{}
Returns true if the terminal has insert- and delete- character
! capabilities.
\end{funcdesc}
--- 203,208 ----
\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}
***************
*** 176,180 ****
Returns true if the terminal has insert- and
delete-line capabilities, or can simulate them using
! scrolling regions.
\end{funcdesc}
--- 210,215 ----
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}
***************
*** 189,193 ****
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}
--- 224,228 ----
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}
***************
*** 200,204 ****
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}
--- 235,240 ----
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. This function is a no-op on most terminals; it is active
! only if \function{can_change_color()} returns 1.
\end{funcdesc}
***************
*** 220,236 ****
\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
--- 256,280 ----
\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
***************
*** 239,243 ****
\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}
--- 283,287 ----
\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}
***************
*** 264,281 ****
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}
--- 308,324 ----
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. 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 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}
***************
*** 290,319 ****
\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}
--- 333,370 ----
\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
! addch('\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}
***************
*** 330,335 ****
\begin{funcdesc}{putp}{string}
! Equivalent to \code{tputs(str, 1, putchar)}. Note that the output of putp always
! goes to standard output.
\end{funcdesc}
--- 381,387 ----
\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}
***************
*** 342,346 ****
\begin{funcdesc}{raw}{}
! Enter raw mode.
\end{funcdesc}
--- 394,401 ----
\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}
***************
*** 434,437 ****
--- 489,493 ----
\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
***************
*** 453,465 ****
\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}
--- 509,524 ----
\begin{methoddesc}{attroff}{attr}
! Remove attribute \var{attr} from the ``background'' set applied to all
! writes to the current window.
\end{methoddesc}
\begin{methoddesc}{attron}{attr}
! Add attribute \var{attr} from the ``background'' set applied to all
! writes to the current window.
\end{methoddesc}
\begin{methoddesc}{attrset}{attr}
! Set the ``background'' set of attributes to \var{attr}. This set is
! initially 0 (no attributes).
\end{methoddesc}
***************
*** 521,525 ****
\begin{methoddesc}{clear}{}
! Like \method{erase()}, but also causes the whole screen to be repainted
upon next call to \method{refresh()}.
\end{methoddesc}
--- 580,584 ----
\begin{methoddesc}{clear}{}
! Like \method{erase()}, but also causes the whole window to be repainted
upon next call to \method{refresh()}.
\end{methoddesc}
***************
*** 527,535 ****
\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}
--- 586,594 ----
\begin{methoddesc}{clearok}{yes}
If \var{yes} is 1, the next call to \method{refresh()}
! will clear the window completely.
\end{methoddesc}
\begin{methoddesc}{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}
***************
*** 563,567 ****
\begin{methoddesc}{echochar}{ch\optional{, attr}}
Add character \var{ch} with attribute \var{attr}, and immediately
! call \method{refresh}.
\end{methoddesc}
--- 622,626 ----
\begin{methoddesc}{echochar}{ch\optional{, attr}}
Add character \var{ch} with attribute \var{attr}, and immediately
! call \method{refresh} on the window.
\end{methoddesc}
***************
*** 612,616 ****
\begin{methoddesc}{getyx}{}
! Return a tuple \code{(\var{y}, \var{x})} of current cursor position.
\end{methoddesc}
--- 671,676 ----
\begin{methoddesc}{getyx}{}
! Return a tuple \code{(\var{y}, \var{x})} of current cursor position
! relative to the window's upper-left corner.
\end{methoddesc}
***************
*** 713,723 ****
\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}
--- 773,782 ----
\begin{methoddesc}{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}
***************
*** 793,803 ****
\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}
--- 852,862 ----
\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}
***************
*** 808,812 ****
\begin{methoddesc}{standend}{}
! Turn off all attributes.
\end{methoddesc}
--- 867,872 ----
\begin{methoddesc}{standend}{}
! Turn off the standout attribute. On some terminals this has the
! side effect of turning off all attributes.
\end{methoddesc}
***************
*** 1005,1036 ****
\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}{}
--- 1065,1097 ----
\begin{tableii}{c|l}{code}{ACS code}{Meaning}
\lineii{ACS_BBSS}{}
! \lineii{ACS_BLOCK}{solid square block}
! \lineii{ACS_BOARD}{board of squares}
\lineii{ACS_BSBS}{}
\lineii{ACS_BSSB}{}
\lineii{ACS_BSSS}{}
! \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}{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}{}
\lineii{ACS_SBSB}{}
***************
*** 1040,1049 ****
\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}
--- 1101,1110 ----
\lineii{ACS_SSSB}{}
\lineii{ACS_SSSS}{}
! \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{tableii}