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