Doc/lib/libcurses.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 \emph{Curses
           Programming with Python}, at
           \url{http://www.python.org/doc/howto/curses/curses.html}.}
\end{seealso}


\subsection{Constants and 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}

\begin{datadesc}{A_NORMAL}
Normal attribute.
\end{datadesc}

\begin{datadesc}{A_STANDOUT}
Standout mode.
\end{datadesc}

\begin{datadesc}{A_UNDERLINE}
Underline mode.
\end{datadesc}

\begin{datadesc}{A_BLINK}
Blink mode.
\end{datadesc}

\begin{datadesc}{A_DIM}
Dim mode.
\end{datadesc}

\begin{datadesc}{A_BOLD}
Bold mode.
\end{datadesc}

\begin{datadesc}{A_ALTCHARSET}
Alternate character set mode.
\end{datadesc}

\begin{datadesc}{KEY_*}
Names for various keys. The exact names available are system dependant.
\end{datadesc}

\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}.

\strong{Note:} These are available only after \function{initscr()} has 
been called.
\end{datadesc}

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}{initscr}{}
Initialize the library. Returns a \class{WindowObject} which represents
the whole screen.
\end{funcdesc}

\begin{funcdesc}{endwin}{}
De-initialize the library, and return terminal to normal status.
\end{funcdesc}

\begin{funcdesc}{isendwin}{}
Returns true if \function{endwin()} has been called.
\end{funcdesc}

\begin{funcdesc}{doupdate}{}
Update the screen.
\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}{beep}{}
Emit a short sound.
\end{funcdesc}

\begin{funcdesc}{flash}{}
Flash the screen.
\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.
\end{funcdesc}

\begin{funcdesc}{flushinp}{}
Flush all input buffers.
\end{funcdesc}

\begin{funcdesc}{cbreak}{}
Enter cbreak mode.
\end{funcdesc}

\begin{funcdesc}{nocbreak}{}
Leave cbreak mode.
\end{funcdesc}

\begin{funcdesc}{echo}{}
Enter echo mode.
\end{funcdesc}

\begin{funcdesc}{noecho}{}
Leave echo mode.
\end{funcdesc}

\begin{funcdesc}{nl}{}
Enter nl mode.
\end{funcdesc}

\begin{funcdesc}{nonl}{}
Leave nl mode.
\end{funcdesc}

\begin{funcdesc}{raw}{}
Enter raw mode.
\end{funcdesc}

\begin{funcdesc}{noraw}{}
Leave raw 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.
\end{funcdesc}

\begin{funcdesc}{keyname}{k}
Return the name of the key numbered \var{k}.
\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}{refresh}{}
Update the display immediately (sync actual screen with previous
drawing/deleting methods).
\end{methoddesc}

\begin{methoddesc}{nooutrefresh}{}
Mark for refresh but wait.
\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}{move}{new_y, new_x}
Move cursor to \code{(\var{new_y}, \var{new_x})}.
\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}{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}{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}.
\end{methoddesc}

\begin{methoddesc}{addstr}{\optional{y, x,} str\optional{, attr}}
Paint string \var{str} at \code{(\var{y}, \var{x})} with attributes
\var{attr}, overwriting anything previously on the display.
\end{methoddesc}

\begin{methoddesc}{attron}{attr}
Turn on attribute \var{attr}.
\end{methoddesc}

\begin{methoddesc}{attroff}{attr}
Turn off attribute \var{attr}.
\end{methoddesc}

\begin{methoddesc}{setattr}{attr}
Set the current attributes to \var{attr}.
\end{methoddesc}

\begin{methoddesc}{standend}{}
Turn off all attributes.
\end{methoddesc}

\begin{methoddesc}{standout}{}
Turn on attribute \var{A_STANDOUT}.
\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}{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}{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}

\begin{methoddesc}{erase}{}
Clear the screen.
\end{methoddesc}

\begin{methoddesc}{deletln}{}
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.
\end{methoddesc}

\begin{methoddesc}{getyx}{}
Return a tuple \code{(\var{y}, \var{x})} of current cursor position.
\end{methoddesc}

\begin{methoddesc}{getbegyx}{}
Return a tuple \code{(\var{y}, \var{x})} of co-ordinates of upper-left
corner.
\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()}.
\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}{scroll}{\optional{lines\code{ = 1}}}
Scroll the screen upward by \var{lines} lines.
\end{methoddesc}

\begin{methoddesc}{touchwin}{}
Pretend the whole window has been changed, for purposes of drawing
optimizations.
\end{methoddesc}

\begin{methoddesc}{touchline}{start, count}
Pretend \var{count} lines have been changed, starting with line
\var{start}.
\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}{getstr}{\optional{x, y}}
Read a string from the user, with primitive line editing capacity.
\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}{clearok}{yes}
If \var{yes} is 1, the next call to \method{refresh()}
will clear the screen completely.
\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}{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}{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}{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}{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}