| \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 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} |
| |
| \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{0} 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_BLCORNER}} |
| \lineiii{br}{Bottom-right corner}{\constant{ACS_BRCORNER}} |
| \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]{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} |
| Pretend \var{count} lines have been changed, starting with line |
| \var{start}. |
| \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 keybboard, 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 containin 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 is 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 |
| passing it further up the stack 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. |
| |