*curses.txt;*                                 Last change: 2023 Sep 09

"curses" — Terminal handling for character-cell displays
********************************************************

**Source code:** Lib/curses

======================================================================

The "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 Windows, DOS, 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.

Note:

  Whenever the documentation mentions a _character_ it can be
  specified as an integer, a one-character Unicode string or a one-
  byte byte string.Whenever the documentation mentions a _character
  string_ it can be specified as a Unicode string or a byte string.

See also:

  Module "curses.ascii"
     Utilities for working with ASCII characters, regardless of your
     locale settings.

  Module "curses.panel"
     A panel stack extension that adds depth to  curses windows.

  Module "curses.textpad"
     Editable text widget for curses supporting  **Emacs**-like
     bindings.

  Curses Programming with Python
     Tutorial material on using curses with Python, by Andrew Kuchling
     and Eric Raymond.


Functions
=========

The module "curses" defines the following exception:

exception curses.error                            *error..curses.txt;*

   Exception raised when a curses library function returns an error.

Note:

  Whenever _x_ or _y_ arguments to a function or a method are
  optional, they default to the current cursor location. Whenever
  _attr_ is optional, it defaults to "A_NORMAL".

The module "curses" defines the following functions:

curses.baudrate()                            *baudrate()..curses.txt;*

   Return 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.

curses.beep()                                    *beep()..curses.txt;*

   Emit a short attention sound.

curses.can_change_color()            *can_change_color()..curses.txt;*

   Return "True" or "False", depending on whether the programmer can
   change the colors displayed by the terminal.

curses.cbreak()                                *cbreak()..curses.txt;*

   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
   "raw()" then "cbreak()" leaves the terminal in cbreak mode.

curses.color_content(color_number)      *color_content()..curses.txt;*

   Return the intensity of the red, green, and blue (RGB) components
   in the color _color_number_, which must be between "0" and "COLORS
   - 1".  Return a 3-tuple, containing the R,G,B values for the given
   color, which will be between "0" (no component) and "1000" (maximum
   amount of component).

curses.color_pair(pair_number)             *color_pair()..curses.txt;*

   Return the attribute value for displaying text in the specified
   color pair. Only the first 256 color pairs are supported. This
   attribute value can be combined with "A_STANDOUT", "A_REVERSE", and
   the other "A_*" attributes.  "pair_number()" is the counterpart to
   this function.

curses.curs_set(visibility)                  *curs_set()..curses.txt;*

   Set the cursor state.  _visibility_ can be set to "0", "1", or "2",
   for invisible, normal, or very visible.  If the terminal supports
   the visibility requested, return the previous cursor state;
   otherwise raise an exception.  On many terminals, the “visible”
   mode is an underline cursor and the “very visible” mode is a block
   cursor.

curses.def_prog_mode()                  *def_prog_mode()..curses.txt;*

   Save 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 "reset_prog_mode()" will restore this mode.

curses.def_shell_mode()                *def_shell_mode()..curses.txt;*

   Save 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 "reset_shell_mode()" will restore this mode.

curses.delay_output(ms)                  *delay_output()..curses.txt;*

   Insert an _ms_ millisecond pause in output.

curses.doupdate()                            *doupdate()..curses.txt;*

   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
   "doupdate()" ground updates the physical screen to match the
   virtual screen.

   The virtual screen may be updated by a "noutrefresh()" call after
   write operations such as "addstr()" have been performed on a
   window.  The normal "refresh()" call is simply "noutrefresh()"
   followed by "doupdate()"; if you have to update multiple windows,
   you can speed performance and perhaps reduce screen flicker by
   issuing "noutrefresh()" calls on all windows, followed by a single
   "doupdate()".

curses.echo()                                    *echo()..curses.txt;*

   Enter echo mode.  In echo mode, each character input is echoed to
   the screen as it is entered.

curses.endwin()                                *endwin()..curses.txt;*

   De-initialize the library, and return terminal to normal status.

curses.erasechar()                          *erasechar()..curses.txt;*

   Return the user’s current erase character as a one-byte bytes
   object.  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.

curses.filter()                                *filter()..curses.txt;*

   The "filter()" routine, if used, must be called before "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.

curses.flash()                                  *flash()..curses.txt;*

   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
   "beep()".

curses.flushinp()                            *flushinp()..curses.txt;*

   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.

curses.getmouse()                            *getmouse()..curses.txt;*

   After "getch()" returns "KEY_MOUSE" to signal a mouse event, this
   method should be called to retrieve the queued mouse event,
   represented as a 5-tuple "(id, x, y, z, bstate)". _id_ is an ID
   value used to distinguish multiple devices, and _x_, _y_, _z_ are
   the event’s coordinates.  (_z_ is currently unused.)  _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 _n_ is the button number from 1 to 5:
   "BUTTONn_PRESSED", "BUTTONn_RELEASED", "BUTTONn_CLICKED",
   "BUTTONn_DOUBLE_CLICKED", "BUTTONn_TRIPLE_CLICKED", "BUTTON_SHIFT",
   "BUTTON_CTRL", "BUTTON_ALT".

   Changed in version 3.10: The "BUTTON5_*" constants are now exposed
   if they are provided by the underlying curses library.

curses.getsyx()                                *getsyx()..curses.txt;*

   Return the current coordinates of the virtual screen cursor as a
   tuple "(y, x)".  If "leaveok" is currently "True", then return
   "(-1, -1)".

curses.getwin(file)                            *getwin()..curses.txt;*

   Read window related data stored in the file by an earlier
   "window.putwin()" call. The routine then creates and initializes a
   new window using that data, returning the new window object.

curses.has_colors()                        *has_colors()..curses.txt;*

   Return "True" if the terminal can display colors; otherwise, return
   "False".

                           *has_extended_color_support()..curses.txt;*
curses.has_extended_color_support()

   Return "True" if the module supports extended colors; otherwise,
   return "False". Extended color support allows more than 256 color
   pairs for terminals that support more than 16 colors (e.g. xterm-
   256color).

   Extended color support requires ncurses version 6.1 or later.

   New in version 3.10.

curses.has_ic()                                *has_ic()..curses.txt;*

   Return "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.

curses.has_il()                                *has_il()..curses.txt;*

   Return "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.

curses.has_key(ch)                            *has_key()..curses.txt;*

   Take a key value _ch_, and return "True" if the current terminal
   type recognizes a key with that value.

curses.halfdelay(tenths)                    *halfdelay()..curses.txt;*

   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 _tenths_ tenths of seconds,
   raise an exception if nothing has been typed.  The value of
   _tenths_ must be a number between "1" and "255".  Use "nocbreak()"
   to leave half-delay mode.

curses.init_color(color_number, r, g, b)   *init_color()..curses.txt;*

   Change 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 _color_number_ must be
   between "0" and "COLORS - 1".  Each of _r_, _g_, _b_, must be a
   value between "0" and "1000".  When "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 "can_change_color()" returns "True".

curses.init_pair(pair_number, fg, bg)       *init_pair()..curses.txt;*

   Change 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
   _pair_number_ must be between "1" and "COLOR_PAIRS - 1" (the "0"
   color pair is wired to white on black and cannot be changed).  The
   value of _fg_ and _bg_ arguments must be between "0" and "COLORS -
   1", or, after calling "use_default_colors()", "-1". If the color-
   pair was previously initialized, the screen is refreshed and all
   occurrences of that color-pair are changed to the new definition.

curses.initscr()                              *initscr()..curses.txt;*

   Initialize the library. Return a window object which represents the
   whole screen.

   Note:

     If there is an error opening the terminal, the underlying curses
     library may cause the interpreter to exit.

                                      *is_term_resized()..curses.txt;*
curses.is_term_resized(nlines, ncols)

   Return "True" if "resize_term()" would modify the window structure,
   "False" otherwise.

curses.isendwin()                            *isendwin()..curses.txt;*

   Return "True" if "endwin()" has been called (that is, the  curses
   library has been deinitialized).

curses.keyname(k)                             *keyname()..curses.txt;*

   Return the name of the key numbered _k_ as a bytes object.  The
   name of a key generating printable ASCII character is the key’s
   character.  The name of a control-key combination is a two-byte
   bytes object consisting of a caret ("b'^'") followed by the
   corresponding printable ASCII character.  The name of an alt-key
   combination (128–255) is a bytes object consisting of the prefix
   "b'M-'" followed by the name of the corresponding ASCII character.

curses.killchar()                            *killchar()..curses.txt;*

   Return the user’s current line kill character as a one-byte bytes
   object. 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.

curses.longname()                            *longname()..curses.txt;*

   Return a bytes object 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 "initscr()".

curses.meta(flag)                                *meta()..curses.txt;*

   If _flag_ is "True", allow 8-bit characters to be input.  If _flag_
   is "False",  allow only 7-bit chars.

curses.mouseinterval(interval)          *mouseinterval()..curses.txt;*

   Set the maximum time in milliseconds that can elapse between press
   and release events in order for them to be recognized as a click,
   and return the previous interval value.  The default value is 200
   milliseconds, or one fifth of a second.

curses.mousemask(mousemask)                 *mousemask()..curses.txt;*

   Set the mouse events to be reported, and return a tuple
   "(availmask, oldmask)".   _availmask_ indicates which of the
   specified mouse events can be reported; on complete failure it
   returns "0".  _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.

curses.napms(ms)                                *napms()..curses.txt;*

   Sleep for _ms_ milliseconds.

curses.newpad(nlines, ncols)                   *newpad()..curses.txt;*

   Create and return a pointer to a new pad data structure with the
   given number of lines and columns.  Return a pad 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 "refresh()" and
   "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.

curses.newwin(nlines, ncols)                   *newwin()..curses.txt;*
curses.newwin(nlines, ncols, begin_y, begin_x)

   Return a new window, whose left-upper corner is at  "(begin_y,
   begin_x)", and whose height/width is  _nlines_/_ncols_.

   By default, the window will extend from the  specified position to
   the lower right corner of the screen.

curses.nl()                                        *nl()..curses.txt;*

   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.

curses.nocbreak()                            *nocbreak()..curses.txt;*

   Leave cbreak mode.  Return to normal “cooked” mode with line
   buffering.

curses.noecho()                                *noecho()..curses.txt;*

   Leave echo mode.  Echoing of input characters is turned off.

curses.nonl()                                    *nonl()..curses.txt;*

   Leave newline mode.  Disable translation of return into newline on
   input, and disable low-level translation of newline into
   newline/return on output (but this does not change the behavior of
   "addch('\n')", which always does the equivalent of return and line
   feed on the virtual screen).  With translation off, curses can
   sometimes speed up vertical motion a little; also, it will be able
   to detect the return key on input.

curses.noqiflush()                          *noqiflush()..curses.txt;*

   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 "noqiflush()" in
   a signal handler if you want output to continue as though the
   interrupt had not occurred, after the handler exits.

curses.noraw()                                  *noraw()..curses.txt;*

   Leave raw mode. Return to normal “cooked” mode with line buffering.

curses.pair_content(pair_number)         *pair_content()..curses.txt;*

   Return a tuple "(fg, bg)" containing the colors for the requested
   color pair. The value of _pair_number_ must be between "0" and
   "COLOR_PAIRS - 1".

curses.pair_number(attr)                  *pair_number()..curses.txt;*

   Return the number of the color-pair set by the attribute value
   _attr_. "color_pair()" is the counterpart to this function.

curses.putp(str)                                 *putp()..curses.txt;*

   Equivalent to "tputs(str, 1, putchar)"; emit the value of a
   specified terminfo capability for the current terminal.  Note that
   the output of "putp()" always goes to standard output.

curses.qiflush([flag])                        *qiflush()..curses.txt;*

   If _flag_ is "False", the effect is the same as calling
   "noqiflush()". If _flag_ is "True", or no argument is provided, the
   queues will be flushed when these control characters are read.

curses.raw()                                      *raw()..curses.txt;*

   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.

curses.reset_prog_mode()              *reset_prog_mode()..curses.txt;*

   Restore the  terminal  to “program” mode, as previously saved  by
   "def_prog_mode()".

curses.reset_shell_mode()            *reset_shell_mode()..curses.txt;*

   Restore the  terminal  to “shell” mode, as previously saved  by
   "def_shell_mode()".

curses.resetty()                              *resetty()..curses.txt;*

   Restore the state of the terminal modes to what it was at the last
   call to "savetty()".

curses.resize_term(nlines, ncols)         *resize_term()..curses.txt;*

   Backend function used by "resizeterm()", performing most of the
   work; when resizing the windows, "resize_term()" blank-fills the
   areas that are extended.  The calling application should fill in
   these areas with appropriate data.  The "resize_term()" function
   attempts to resize all windows.  However, due to the calling
   convention of pads, it is not possible to resize these without
   additional interaction with the application.

curses.resizeterm(nlines, ncols)           *resizeterm()..curses.txt;*

   Resize the standard and current windows to the specified
   dimensions, and adjusts other bookkeeping data used by the curses
   library that record the window dimensions (in particular the
   SIGWINCH handler).

curses.savetty()                              *savetty()..curses.txt;*

   Save the current state of the terminal modes in a buffer, usable by
   "resetty()".

curses.get_escdelay()                    *get_escdelay()..curses.txt;*

   Retrieves the value set by "set_escdelay()".

   New in version 3.9.

curses.set_escdelay(ms)                  *set_escdelay()..curses.txt;*

   Sets the number of milliseconds to wait after reading an escape
   character, to distinguish between an individual escape character
   entered on the keyboard from escape sequences sent by cursor and
   function keys.

   New in version 3.9.

curses.get_tabsize()                      *get_tabsize()..curses.txt;*

   Retrieves the value set by "set_tabsize()".

   New in version 3.9.

curses.set_tabsize(size)                  *set_tabsize()..curses.txt;*

   Sets the number of columns used by the curses library when
   converting a tab character to spaces as it adds the tab to a
   window.

   New in version 3.9.

curses.setsyx(y, x)                            *setsyx()..curses.txt;*

   Set the virtual screen cursor to _y_, _x_. If _y_ and _x_ are both
   "-1", then "leaveok" is set "True".

curses.setupterm(term=None, fd=-1)          *setupterm()..curses.txt;*

   Initialize the terminal.  _term_ is a string giving the terminal
   name, or "None"; if omitted or "None", the value of the "TERM"
   environment variable will be used.  _fd_ is the file descriptor to
   which any initialization sequences will be sent; if not supplied or
   "-1", the file descriptor for "sys.stdout" will be used.

curses.start_color()                      *start_color()..curses.txt;*

   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 "initscr()".

   "start_color()" initializes eight basic colors (black, red,  green,
   yellow, blue, magenta, cyan, and white), and two global variables
   in the "curses" module, "COLORS" and "COLOR_PAIRS", containing the
   maximum number of colors and color-pairs the terminal can support.
   It also restores the colors on the terminal to the values they had
   when the terminal was just turned on.

curses.termattrs()                          *termattrs()..curses.txt;*

   Return 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.

curses.termname()                            *termname()..curses.txt;*

   Return the value of the environment variable "TERM", as a bytes
   object, truncated to 14 characters.

curses.tigetflag(capname)                   *tigetflag()..curses.txt;*

   Return the value of the Boolean capability corresponding to the
   terminfo capability name _capname_ as an integer.  Return the value
   "-1" if _capname_ is not a Boolean capability, or "0" if it is
   canceled or absent from the terminal description.

curses.tigetnum(capname)                     *tigetnum()..curses.txt;*

   Return the value of the numeric capability corresponding to the
   terminfo capability name _capname_ as an integer.  Return the value
   "-2" if _capname_ is not a numeric capability, or "-1" if it is
   canceled or absent from the terminal description.

curses.tigetstr(capname)                     *tigetstr()..curses.txt;*

   Return the value of the string capability corresponding to the
   terminfo capability name _capname_ as a bytes object.  Return
   "None" if _capname_ is not a terminfo “string capability”, or is
   canceled or absent from the terminal description.

curses.tparm(str[, ...])                        *tparm()..curses.txt;*

   Instantiate the bytes object _str_ with the supplied parameters,
   where _str_ should be a parameterized string obtained from the
   terminfo database.  E.g. "tparm(tigetstr("cup"), 5, 3)" could
   result in "b'\033[6;4H'", the exact result depending on terminal
   type.

curses.typeahead(fd)                        *typeahead()..curses.txt;*

   Specify that the file descriptor _fd_ be used for typeahead
   checking.  If _fd_ is "-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.

curses.unctrl(ch)                              *unctrl()..curses.txt;*

   Return a bytes object which is a printable representation of the
   character _ch_. Control characters are represented as a caret
   followed by the character, for example as "b'^C'". Printing
   characters are left as they are.

curses.ungetch(ch)                            *ungetch()..curses.txt;*

   Push _ch_ so the next "getch()" will return it.

   Note:

     Only one _ch_ can be pushed before "getch()" is called.

curses.update_lines_cols()          *update_lines_cols()..curses.txt;*

   Update the "LINES" and "COLS" module variables. Useful for
   detecting manual screen resize.

   New in version 3.5.

curses.unget_wch(ch)                        *unget_wch()..curses.txt;*

   Push _ch_ so the next "get_wch()" will return it.

   Note:

     Only one _ch_ can be pushed before "get_wch()" is called.

   New in version 3.3.

curses.ungetmouse(id, x, y, z, bstate)     *ungetmouse()..curses.txt;*

   Push a "KEY_MOUSE" event onto the input queue, associating the
   given state data with it.

curses.use_env(flag)                          *use_env()..curses.txt;*

   If used, this function should be called before "initscr()" or
   newterm are called.  When _flag_ is "False", the values of lines
   and columns specified in the terminfo database will be used, even
   if environment variables "LINES" and "COLUMNS" (used by default)
   are set, or if curses is running in a window (in which case default
   behavior would be to use the window size if "LINES" and "COLUMNS"
   are not set).

curses.use_default_colors()        *use_default_colors()..curses.txt;*

   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,  "init_pair(x, curses.COLOR_RED, -1)" initializes,
   for instance, color pair _x_ to a red foreground color on the
   default background.

curses.wrapper(func, /, *args, **kwargs)      *wrapper()..curses.txt;*

   Initialize curses and call another callable object, _func_, which
   should be the rest of your curses-using application.  If the
   application raises an exception, this function will restore the
   terminal to a sane state before re-raising the exception and
   generating a traceback.  The callable object _func_ is then passed
   the main window ‘stdscr’ as its first argument, followed by any
   other arguments passed to "wrapper()".  Before calling _func_,
   "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.


Window Objects
==============

Window objects, as returned by "initscr()" and "newwin()" above, have
the following methods and attributes:

window.addch(ch[, attr])                 *window.addch()..curses.txt;*
window.addch(y, x, ch[, attr])

   Paint character _ch_ at "(y, x)" with attributes _attr_,
   overwriting any character previously painted at that location.  By
   default, the character position and attributes are the current
   settings for the window object.

   Note:

     Writing outside the window, subwindow, or pad raises a
     "curses.error". Attempting to write to the lower right corner of
     a window, subwindow, or pad will cause an exception to be raised
     after the character is printed.

window.addnstr(str, n[, attr])         *window.addnstr()..curses.txt;*
window.addnstr(y, x, str, n[, attr])

   Paint at most _n_ characters of the character string _str_ at "(y,
   x)" with attributes _attr_, overwriting anything previously on the
   display.

window.addstr(str[, attr])              *window.addstr()..curses.txt;*
window.addstr(y, x, str[, attr])

   Paint the character string _str_ at "(y, x)" with attributes
   _attr_, overwriting anything previously on the display.

   Note:

     * Writing outside the window, subwindow, or pad raises
       "curses.error". Attempting to write to the lower right corner
       of a window, subwindow, or pad will cause an exception to be
       raised after the string is printed.

     * A bug in ncurses, the backend for this Python module, can cause
       SegFaults when resizing windows. This is fixed in
       ncurses-6.1-20190511.  If you are stuck with an earlier
       ncurses, you can avoid triggering this if you do not call
       "addstr()" with a _str_ that has embedded newlines.  Instead,
       call "addstr()" separately for each line.

window.attroff(attr)                   *window.attroff()..curses.txt;*

   Remove attribute _attr_ from the “background” set applied to all
   writes to the current window.

window.attron(attr)                     *window.attron()..curses.txt;*

   Add attribute _attr_ from the “background” set applied to all
   writes to the current window.

window.attrset(attr)                   *window.attrset()..curses.txt;*

   Set the “background” set of attributes to _attr_.  This set is
   initially "0" (no attributes).

window.bkgd(ch[, attr])                   *window.bkgd()..curses.txt;*

   Set the background property of the window to the character _ch_,
   with attributes _attr_.  The change is then applied to every
   character position in that window:

   * The attribute of every character in the window  is changed to the
     new background attribute.

   * Wherever  the  former background character appears, it is changed
     to the new background character.

window.bkgdset(ch[, attr])             *window.bkgdset()..curses.txt;*

   Set 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.

                                        *window.border()..curses.txt;*
window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, 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.

   Note:

     A "0" value for any parameter will cause the default character to
     be used for that parameter.  Keyword parameters can _not_ be
     used.  The defaults are listed in this table:

   +-------------+-----------------------+-------------------------+
   | Parameter   | Description           | Default value           |
   |=============|=======================|=========================|
   | _ls_        | Left side             | "ACS_VLINE"             |
   +-------------+-----------------------+-------------------------+
   | _rs_        | Right side            | "ACS_VLINE"             |
   +-------------+-----------------------+-------------------------+
   | _ts_        | Top                   | "ACS_HLINE"             |
   +-------------+-----------------------+-------------------------+
   | _bs_        | Bottom                | "ACS_HLINE"             |
   +-------------+-----------------------+-------------------------+
   | _tl_        | Upper-left corner     | "ACS_ULCORNER"          |
   +-------------+-----------------------+-------------------------+
   | _tr_        | Upper-right corner    | "ACS_URCORNER"          |
   +-------------+-----------------------+-------------------------+
   | _bl_        | Bottom-left corner    | "ACS_LLCORNER"          |
   +-------------+-----------------------+-------------------------+
   | _br_        | Bottom-right corner   | "ACS_LRCORNER"          |
   +-------------+-----------------------+-------------------------+

window.box([vertch, horch])                *window.box()..curses.txt;*

   Similar to "border()", but both _ls_ and _rs_ are _vertch_ and both
   _ts_ and _bs_ are _horch_.  The default corner characters are
   always used by this function.

window.chgat(attr)                       *window.chgat()..curses.txt;*
window.chgat(num, attr)
window.chgat(y, x, attr)
window.chgat(y, x, num, attr)

   Set the attributes of _num_ characters at the current cursor
   position, or at position "(y, x)" if supplied. If _num_ is not
   given or is "-1", the attribute will be set on all the characters
   to the end of the line.  This function moves cursor to position
   "(y, x)" if supplied. The changed line will be touched using the
   "touchline()" method so that the contents will be redisplayed by
   the next window refresh.

window.clear()                           *window.clear()..curses.txt;*

   Like "erase()", but also cause the whole window to be repainted
   upon next call to "refresh()".

window.clearok(flag)                   *window.clearok()..curses.txt;*

   If _flag_ is "True", the next call to "refresh()" will clear the
   window completely.

window.clrtobot()                     *window.clrtobot()..curses.txt;*

   Erase from cursor to the end of the window: all lines below the
   cursor are deleted, and then the equivalent of "clrtoeol()" is
   performed.

window.clrtoeol()                     *window.clrtoeol()..curses.txt;*

   Erase from cursor to the end of the line.

window.cursyncup()                   *window.cursyncup()..curses.txt;*

   Update the current cursor position of all the ancestors of the
   window to reflect the current cursor position of the window.

window.delch([y, x])                     *window.delch()..curses.txt;*

   Delete any character at "(y, x)".

window.deleteln()                     *window.deleteln()..curses.txt;*

   Delete the line under the cursor. All following lines are moved up
   by one line.

window.derwin(begin_y, begin_x)         *window.derwin()..curses.txt;*
window.derwin(nlines, ncols, begin_y, begin_x)

   An abbreviation for “derive window”, "derwin()" is the same as
   calling "subwin()", except that _begin_y_ and _begin_x_ are
   relative to the origin of the window, rather than relative to the
   entire screen.  Return a window object for the derived window.

window.echochar(ch[, attr])           *window.echochar()..curses.txt;*

   Add character _ch_ with attribute _attr_, and immediately  call
   "refresh()" on the window.

window.enclose(y, x)                   *window.enclose()..curses.txt;*

   Test 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.

   Changed in version 3.10: Previously it returned "1" or "0" instead
   of "True" or "False".

window.encoding                         *window.encoding..curses.txt;*

   Encoding used to encode method arguments (Unicode strings and
   characters). The encoding attribute is inherited from the parent
   window when a subwindow is created, for example with
   "window.subwin()". By default, current locale encoding is used (see
   "locale.getencoding()").

   New in version 3.3.

window.erase()                           *window.erase()..curses.txt;*

   Clear the window.

window.getbegyx()                     *window.getbegyx()..curses.txt;*

   Return a tuple "(y, x)" of co-ordinates of upper-left corner.

window.getbkgd()                       *window.getbkgd()..curses.txt;*

   Return the given window’s current background character/attribute
   pair.

window.getch([y, x])                     *window.getch()..curses.txt;*

   Get a character. Note that the integer returned does _not_ have to
   be in ASCII range: function keys, keypad keys and so on are
   represented by numbers higher than 255.  In no-delay mode, return
   "-1" if there is no input, otherwise wait until a key is pressed.

window.get_wch([y, x])                 *window.get_wch()..curses.txt;*

   Get a wide character. Return a character for most keys, or an
   integer for function keys, keypad keys, and other special keys. In
   no-delay mode, raise an exception if there is no input.

   New in version 3.3.

window.getkey([y, x])                   *window.getkey()..curses.txt;*

   Get a character, returning a string instead of an integer, as
   "getch()" does. Function keys, keypad keys and other special keys
   return a multibyte string containing the key name.  In no-delay
   mode, raise an exception if there is no input.

window.getmaxyx()                     *window.getmaxyx()..curses.txt;*

   Return a tuple "(y, x)" of the height and width of the window.

window.getparyx()                     *window.getparyx()..curses.txt;*

   Return the beginning coordinates of this window relative to its
   parent window as a tuple "(y, x)".  Return "(-1, -1)" if this
   window has no parent.

window.getstr()                         *window.getstr()..curses.txt;*
window.getstr(n)
window.getstr(y, x)
window.getstr(y, x, n)

   Read a bytes object from the user, with primitive line editing
   capacity.

window.getyx()                           *window.getyx()..curses.txt;*

   Return a tuple "(y, x)" of current cursor position  relative to the
   window’s upper-left corner.

window.hline(ch, n)                      *window.hline()..curses.txt;*
window.hline(y, x, ch, n)

   Display a horizontal line starting at "(y, x)" with length _n_
   consisting of the character _ch_.

window.idcok(flag)                       *window.idcok()..curses.txt;*

   If _flag_ is "False", curses no longer considers using the hardware
   insert/delete character feature of the terminal; if _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.

window.idlok(flag)                       *window.idlok()..curses.txt;*

   If _flag_ is "True", "curses" will try and use hardware line
   editing facilities. Otherwise, line insertion/deletion are
   disabled.

window.immedok(flag)                   *window.immedok()..curses.txt;*

   If _flag_ is "True", any change in the window image automatically
   causes the window to be refreshed; you no longer have to call
   "refresh()" yourself. However, it may degrade performance
   considerably, due to repeated calls to wrefresh.  This option is
   disabled by default.

window.inch([y, x])                       *window.inch()..curses.txt;*

   Return the character at the given position in the window. The
   bottom 8 bits are the character proper, and upper bits are the
   attributes.

window.insch(ch[, attr])                 *window.insch()..curses.txt;*
window.insch(y, x, ch[, attr])

   Paint character _ch_ at "(y, x)" with attributes _attr_, moving the
   line from position _x_ right by one character.

window.insdelln(nlines)               *window.insdelln()..curses.txt;*

   Insert _nlines_ lines into the specified window above the current
   line.  The _nlines_ bottom lines are lost.  For negative _nlines_,
   delete _nlines_ lines starting with the one under the cursor, and
   move the remaining lines up.  The bottom _nlines_ lines are
   cleared.  The current cursor position remains the same.

window.insertln()                     *window.insertln()..curses.txt;*

   Insert a blank line under the cursor. All following lines are moved
   down by one line.

window.insnstr(str, n[, attr])         *window.insnstr()..curses.txt;*
window.insnstr(y, x, str, n[, attr])

   Insert a character string (as many characters as will fit on the
   line) before the character under the cursor, up to _n_ characters.
   If _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 _y_, _x_, if specified).

window.insstr(str[, attr])              *window.insstr()..curses.txt;*
window.insstr(y, x, str[, 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 _y_, _x_, if specified).

window.instr([n])                        *window.instr()..curses.txt;*
window.instr(y, x[, n])

   Return a bytes object of characters, extracted from the window
   starting at the current cursor position, or at _y_, _x_ if
   specified. Attributes are stripped from the characters.  If _n_ is
   specified, "instr()" returns a string at most _n_ characters long
   (exclusive of the trailing NUL).

window.is_linetouched(line)     *window.is_linetouched()..curses.txt;*

   Return "True" if the specified line was modified since the last
   call to "refresh()"; otherwise return "False".  Raise a
   "curses.error" exception if _line_ is not valid for the given
   window.

window.is_wintouched()           *window.is_wintouched()..curses.txt;*

   Return "True" if the specified window was modified since the last
   call to "refresh()"; otherwise return "False".

window.keypad(flag)                     *window.keypad()..curses.txt;*

   If _flag_ is "True", escape sequences generated by some keys
   (keypad,  function keys) will be interpreted by "curses". If _flag_
   is "False", escape sequences will be left as is in the input
   stream.

window.leaveok(flag)                   *window.leaveok()..curses.txt;*

   If _flag_ is "True", 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 _flag_ is "False", cursor will always be at “cursor position”
   after an update.

window.move(new_y, new_x)                 *window.move()..curses.txt;*

   Move cursor to "(new_y, new_x)".

window.mvderwin(y, x)                 *window.mvderwin()..curses.txt;*

   Move 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.

window.mvwin(new_y, new_x)               *window.mvwin()..curses.txt;*

   Move the window so its upper-left corner is at "(new_y, new_x)".

window.nodelay(flag)                   *window.nodelay()..curses.txt;*

   If _flag_ is "True", "getch()" will be non-blocking.

window.notimeout(flag)               *window.notimeout()..curses.txt;*

   If _flag_ is "True", escape sequences will not be timed out.

   If _flag_ is "False", after a few milliseconds, an escape sequence
   will not be interpreted, and will be left in the input stream as
   is.

window.noutrefresh()               *window.noutrefresh()..curses.txt;*

   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  "doupdate()".

                                       *window.overlay()..curses.txt;*
window.overlay(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])

   Overlay the window on top of _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 _destwin_.

   To get fine-grained control over the copied region, the second form
   of "overlay()" can be used. _sminrow_ and _smincol_ are the upper-
   left coordinates of the source window, and the other variables mark
   a rectangle in the destination window.

                                     *window.overwrite()..curses.txt;*
window.overwrite(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])

   Overwrite the window on top of _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 _destwin_.

   To get fine-grained control over the copied region, the second form
   of "overwrite()" can be used. _sminrow_ and _smincol_ are the
   upper-left coordinates of the source window, the other variables
   mark a rectangle in the destination window.

window.putwin(file)                     *window.putwin()..curses.txt;*

   Write all data associated with the window into the provided file
   object.  This information can be later retrieved using the
   "getwin()" function.

window.redrawln(beg, num)             *window.redrawln()..curses.txt;*

   Indicate that the _num_ screen lines, starting at line _beg_, are
   corrupted and should be completely redrawn on the next "refresh()"
   call.

window.redrawwin()                   *window.redrawwin()..curses.txt;*

   Touch the entire window, causing it to be completely redrawn on the
   next "refresh()" call.

                                       *window.refresh()..curses.txt;*
window.refresh([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 "newpad()".  The additional parameters are needed
   to indicate what part of the pad and screen are involved. _pminrow_
   and _pmincol_ specify the upper left-hand corner of the rectangle
   to be displayed in the pad.  _sminrow_, _smincol_, _smaxrow_, and
   _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 _pminrow_, _pmincol_, _sminrow_, or _smincol_ are treated
   as if they were zero.

window.resize(nlines, ncols)            *window.resize()..curses.txt;*

   Reallocate storage for a curses window to adjust its dimensions to
   the specified values.  If either dimension is larger than the
   current values, the window’s data is filled with blanks that have
   the current background rendition (as set by "bkgdset()") merged
   into them.

window.scroll([lines=1])                *window.scroll()..curses.txt;*

   Scroll the screen or scrolling region upward by _lines_ lines.

window.scrollok(flag)                 *window.scrollok()..curses.txt;*

   Control 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 _flag_ is "False", the cursor is left on the
   bottom line.  If _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 "idlok()".

window.setscrreg(top, bottom)        *window.setscrreg()..curses.txt;*

   Set the scrolling region from line _top_ to line _bottom_. All
   scrolling actions will take place in this region.

window.standend()                     *window.standend()..curses.txt;*

   Turn off the standout attribute.  On some terminals this has the
   side effect of turning off all attributes.

window.standout()                     *window.standout()..curses.txt;*

   Turn on attribute _A_STANDOUT_.

window.subpad(begin_y, begin_x)         *window.subpad()..curses.txt;*
window.subpad(nlines, ncols, begin_y, begin_x)

   Return a sub-window, whose upper-left corner is at "(begin_y,
   begin_x)", and whose width/height is _ncols_/_nlines_.

window.subwin(begin_y, begin_x)         *window.subwin()..curses.txt;*
window.subwin(nlines, ncols, begin_y, begin_x)

   Return a sub-window, whose upper-left corner is at "(begin_y,
   begin_x)", and whose width/height is _ncols_/_nlines_.

   By default, the sub-window will extend from the specified position
   to the lower right corner of the window.

window.syncdown()                     *window.syncdown()..curses.txt;*

   Touch each location in the window that has been touched in any of
   its ancestor windows.  This routine is called by "refresh()", so it
   should almost never be necessary to call it manually.

window.syncok(flag)                     *window.syncok()..curses.txt;*

   If _flag_ is "True", then "syncup()" is called automatically
   whenever there is a change in the window.

window.syncup()                         *window.syncup()..curses.txt;*

   Touch all locations in ancestors of the window that have been
   changed in  the window.

window.timeout(delay)                  *window.timeout()..curses.txt;*

   Set blocking or non-blocking read behavior for the window.  If
   _delay_ is negative, blocking read is used (which will wait
   indefinitely for input).  If _delay_ is zero, then non-blocking
   read is used, and "getch()" will return "-1" if no input is
   waiting.  If _delay_ is positive, then "getch()" will block for
   _delay_ milliseconds, and return "-1" if there is still no input at
   the end of that time.

                                     *window.touchline()..curses.txt;*
window.touchline(start, count[, changed])

   Pretend _count_ lines have been changed, starting with line
   _start_.  If _changed_ is supplied, it specifies whether the
   affected lines are marked as having been changed (_changed_"=True")
   or unchanged (_changed_"=False").

window.touchwin()                     *window.touchwin()..curses.txt;*

   Pretend the whole window has been changed, for purposes of drawing
   optimizations.

window.untouchwin()                 *window.untouchwin()..curses.txt;*

   Mark all lines in  the  window  as unchanged since the last call to
   "refresh()".

window.vline(ch, n[, attr])              *window.vline()..curses.txt;*
window.vline(y, x, ch, n[, attr])

   Display a vertical line starting at "(y, x)" with length _n_
   consisting of the character _ch_ with attributes _attr_.


Constants
=========

The "curses" module defines the following data members:

curses.ERR                                          *ERR..curses.txt;*

   Some curses routines  that  return  an integer, such as "getch()",
   return "ERR" upon failure.

curses.OK                                            *OK..curses.txt;*

   Some curses routines  that  return  an integer, such as  "napms()",
   return "OK" upon success.

curses.version                                  *version..curses.txt;*

curses.__version__                          *__version__..curses.txt;*

   A bytes object representing the current version of the module.

curses.ncurses_version                  *ncurses_version..curses.txt;*

   A named tuple containing the three components of the ncurses
   library version: _major_, _minor_, and _patch_.  All values are
   integers.  The components can also be accessed by name,  so
   "curses.ncurses_version[0]" is equivalent to
   "curses.ncurses_version.major" and so on.

   Availability: if the ncurses library is used.

   New in version 3.8.

curses.COLORS                                    *COLORS..curses.txt;*

   The maximum number of colors the terminal can support. It is
   defined only after the call to "start_color()".

curses.COLOR_PAIRS                          *COLOR_PAIRS..curses.txt;*

   The maximum number of color pairs the terminal can support. It is
   defined only after the call to "start_color()".

curses.COLS                                        *COLS..curses.txt;*

   The width of the screen, i.e., the number of columns. It is defined
   only after the call to "initscr()". Updated by
   "update_lines_cols()", "resizeterm()" and "resize_term()".

curses.LINES                                      *LINES..curses.txt;*

   The height of the screen, i.e., the number of lines. It is defined
   only after the call to "initscr()". Updated by
   "update_lines_cols()", "resizeterm()" and "resize_term()".

Some constants are available to specify character cell attributes. The
exact constants available are system dependent.

+--------------------------+---------------------------------+
| Attribute                | Meaning                         |
|==========================|=================================|
| curses.A_ALTCHARSET      | Alternate character set mode    |
+--------------------------+---------------------------------+
| curses.A_BLINK           | Blink mode                      |
+--------------------------+---------------------------------+
| curses.A_BOLD            | Bold mode                       |
+--------------------------+---------------------------------+
| curses.A_DIM             | Dim mode                        |
+--------------------------+---------------------------------+
| curses.A_INVIS           | Invisible or blank mode         |
+--------------------------+---------------------------------+
| curses.A_ITALIC          | Italic mode                     |
+--------------------------+---------------------------------+
| curses.A_NORMAL          | Normal attribute                |
+--------------------------+---------------------------------+
| curses.A_PROTECT         | Protected mode                  |
+--------------------------+---------------------------------+
| curses.A_REVERSE         | Reverse background and          |
|                          | foreground colors               |
+--------------------------+---------------------------------+
| curses.A_STANDOUT        | Standout mode                   |
+--------------------------+---------------------------------+
| curses.A_UNDERLINE       | Underline mode                  |
+--------------------------+---------------------------------+
| curses.A_HORIZONTAL      | Horizontal highlight            |
+--------------------------+---------------------------------+
| curses.A_LEFT            | Left highlight                  |
+--------------------------+---------------------------------+
| curses.A_LOW             | Low highlight                   |
+--------------------------+---------------------------------+
| curses.A_RIGHT           | Right highlight                 |
+--------------------------+---------------------------------+
| curses.A_TOP             | Top highlight                   |
+--------------------------+---------------------------------+
| curses.A_VERTICAL        | Vertical highlight              |
+--------------------------+---------------------------------+

New in version 3.7: "A_ITALIC" was added.

Several constants are available to extract corresponding attributes
returned by some methods.

+---------------------------+---------------------------------+
| Bit-mask                  | Meaning                         |
|===========================|=================================|
| curses.A_ATTRIBUTES       | Bit-mask to extract attributes  |
+---------------------------+---------------------------------+
| curses.A_CHARTEXT         | Bit-mask to extract a character |
+---------------------------+---------------------------------+
| curses.A_COLOR            | Bit-mask to extract color-pair  |
|                           | field information               |
+---------------------------+---------------------------------+

Keys are referred to by integer constants with names starting with
"KEY_". The exact keycaps available are system dependent.

+---------------------------+----------------------------------------------+
| Key constant              | Key                                          |
|===========================|==============================================|
| curses.KEY_MIN            | Minimum key value                            |
+---------------------------+----------------------------------------------+
| curses.KEY_BREAK          | Break key (unreliable)                       |
+---------------------------+----------------------------------------------+
| curses.KEY_DOWN           | Down-arrow                                   |
+---------------------------+----------------------------------------------+
| curses.KEY_UP             | Up-arrow                                     |
+---------------------------+----------------------------------------------+
| curses.KEY_LEFT           | Left-arrow                                   |
+---------------------------+----------------------------------------------+
| curses.KEY_RIGHT          | Right-arrow                                  |
+---------------------------+----------------------------------------------+
| curses.KEY_HOME           | Home key (upward+left arrow)                 |
+---------------------------+----------------------------------------------+
| curses.KEY_BACKSPACE      | Backspace (unreliable)                       |
+---------------------------+----------------------------------------------+
| curses.KEY_F0             | Function keys.  Up to 64 function keys are   |
|                           | supported.                                   |
+---------------------------+----------------------------------------------+
| curses.KEY_Fn             | Value of function key _n_                    |
+---------------------------+----------------------------------------------+
| curses.KEY_DL             | Delete line                                  |
+---------------------------+----------------------------------------------+
| curses.KEY_IL             | Insert line                                  |
+---------------------------+----------------------------------------------+
| curses.KEY_DC             | Delete character                             |
+---------------------------+----------------------------------------------+
| curses.KEY_IC             | Insert char or enter insert mode             |
+---------------------------+----------------------------------------------+
| curses.KEY_EIC            | Exit insert char mode                        |
+---------------------------+----------------------------------------------+
| curses.KEY_CLEAR          | Clear screen                                 |
+---------------------------+----------------------------------------------+
| curses.KEY_EOS            | Clear to end of screen                       |
+---------------------------+----------------------------------------------+
| curses.KEY_EOL            | Clear to end of line                         |
+---------------------------+----------------------------------------------+
| curses.KEY_SF             | Scroll 1 line forward                        |
+---------------------------+----------------------------------------------+
| curses.KEY_SR             | Scroll 1 line backward (reverse)             |
+---------------------------+----------------------------------------------+
| curses.KEY_NPAGE          | Next page                                    |
+---------------------------+----------------------------------------------+
| curses.KEY_PPAGE          | Previous page                                |
+---------------------------+----------------------------------------------+
| curses.KEY_STAB           | Set tab                                      |
+---------------------------+----------------------------------------------+
| curses.KEY_CTAB           | Clear tab                                    |
+---------------------------+----------------------------------------------+
| curses.KEY_CATAB          | Clear all tabs                               |
+---------------------------+----------------------------------------------+
| curses.KEY_ENTER          | Enter or send (unreliable)                   |
+---------------------------+----------------------------------------------+
| curses.KEY_SRESET         | Soft (partial) reset (unreliable)            |
+---------------------------+----------------------------------------------+
| curses.KEY_RESET          | Reset or hard reset (unreliable)             |
+---------------------------+----------------------------------------------+
| curses.KEY_PRINT          | Print                                        |
+---------------------------+----------------------------------------------+
| curses.KEY_LL             | Home down or bottom (lower left)             |
+---------------------------+----------------------------------------------+
| curses.KEY_A1             | Upper left of keypad                         |
+---------------------------+----------------------------------------------+
| curses.KEY_A3             | Upper right of keypad                        |
+---------------------------+----------------------------------------------+
| curses.KEY_B2             | Center of keypad                             |
+---------------------------+----------------------------------------------+
| curses.KEY_C1             | Lower left of keypad                         |
+---------------------------+----------------------------------------------+
| curses.KEY_C3             | Lower right of keypad                        |
+---------------------------+----------------------------------------------+
| curses.KEY_BTAB           | Back tab                                     |
+---------------------------+----------------------------------------------+
| curses.KEY_BEG            | Beg (beginning)                              |
+---------------------------+----------------------------------------------+
| curses.KEY_CANCEL         | Cancel                                       |
+---------------------------+----------------------------------------------+
| curses.KEY_CLOSE          | Close                                        |
+---------------------------+----------------------------------------------+
| curses.KEY_COMMAND        | Cmd (command)                                |
+---------------------------+----------------------------------------------+
| curses.KEY_COPY           | Copy                                         |
+---------------------------+----------------------------------------------+
| curses.KEY_CREATE         | Create                                       |
+---------------------------+----------------------------------------------+
| curses.KEY_END            | End                                          |
+---------------------------+----------------------------------------------+
| curses.KEY_EXIT           | Exit                                         |
+---------------------------+----------------------------------------------+
| curses.KEY_FIND           | Find                                         |
+---------------------------+----------------------------------------------+
| curses.KEY_HELP           | Help                                         |
+---------------------------+----------------------------------------------+
| curses.KEY_MARK           | Mark                                         |
+---------------------------+----------------------------------------------+
| curses.KEY_MESSAGE        | Message                                      |
+---------------------------+----------------------------------------------+
| curses.KEY_MOVE           | Move                                         |
+---------------------------+----------------------------------------------+
| curses.KEY_NEXT           | Next                                         |
+---------------------------+----------------------------------------------+
| curses.KEY_OPEN           | Open                                         |
+---------------------------+----------------------------------------------+
| curses.KEY_OPTIONS        | Options                                      |
+---------------------------+----------------------------------------------+
| curses.KEY_PREVIOUS       | Prev (previous)                              |
+---------------------------+----------------------------------------------+
| curses.KEY_REDO           | Redo                                         |
+---------------------------+----------------------------------------------+
| curses.KEY_REFERENCE      | Ref (reference)                              |
+---------------------------+----------------------------------------------+
| curses.KEY_REFRESH        | Refresh                                      |
+---------------------------+----------------------------------------------+
| curses.KEY_REPLACE        | Replace                                      |
+---------------------------+----------------------------------------------+
| curses.KEY_RESTART        | Restart                                      |
+---------------------------+----------------------------------------------+
| curses.KEY_RESUME         | Resume                                       |
+---------------------------+----------------------------------------------+
| curses.KEY_SAVE           | Save                                         |
+---------------------------+----------------------------------------------+
| curses.KEY_SBEG           | Shifted Beg (beginning)                      |
+---------------------------+----------------------------------------------+
| curses.KEY_SCANCEL        | Shifted Cancel                               |
+---------------------------+----------------------------------------------+
| curses.KEY_SCOMMAND       | Shifted Command                              |
+---------------------------+----------------------------------------------+
| curses.KEY_SCOPY          | Shifted Copy                                 |
+---------------------------+----------------------------------------------+
| curses.KEY_SCREATE        | Shifted Create                               |
+---------------------------+----------------------------------------------+
| curses.KEY_SDC            | Shifted Delete char                          |
+---------------------------+----------------------------------------------+
| curses.KEY_SDL            | Shifted Delete line                          |
+---------------------------+----------------------------------------------+
| curses.KEY_SELECT         | Select                                       |
+---------------------------+----------------------------------------------+
| curses.KEY_SEND           | Shifted End                                  |
+---------------------------+----------------------------------------------+
| curses.KEY_SEOL           | Shifted Clear line                           |
+---------------------------+----------------------------------------------+
| curses.KEY_SEXIT          | Shifted Exit                                 |
+---------------------------+----------------------------------------------+
| curses.KEY_SFIND          | Shifted Find                                 |
+---------------------------+----------------------------------------------+
| curses.KEY_SHELP          | Shifted Help                                 |
+---------------------------+----------------------------------------------+
| curses.KEY_SHOME          | Shifted Home                                 |
+---------------------------+----------------------------------------------+
| curses.KEY_SIC            | Shifted Input                                |
+---------------------------+----------------------------------------------+
| curses.KEY_SLEFT          | Shifted Left arrow                           |
+---------------------------+----------------------------------------------+
| curses.KEY_SMESSAGE       | Shifted Message                              |
+---------------------------+----------------------------------------------+
| curses.KEY_SMOVE          | Shifted Move                                 |
+---------------------------+----------------------------------------------+
| curses.KEY_SNEXT          | Shifted Next                                 |
+---------------------------+----------------------------------------------+
| curses.KEY_SOPTIONS       | Shifted Options                              |
+---------------------------+----------------------------------------------+
| curses.KEY_SPREVIOUS      | Shifted Prev                                 |
+---------------------------+----------------------------------------------+
| curses.KEY_SPRINT         | Shifted Print                                |
+---------------------------+----------------------------------------------+
| curses.KEY_SREDO          | Shifted Redo                                 |
+---------------------------+----------------------------------------------+
| curses.KEY_SREPLACE       | Shifted Replace                              |
+---------------------------+----------------------------------------------+
| curses.KEY_SRIGHT         | Shifted Right arrow                          |
+---------------------------+----------------------------------------------+
| curses.KEY_SRSUME         | Shifted Resume                               |
+---------------------------+----------------------------------------------+
| curses.KEY_SSAVE          | Shifted Save                                 |
+---------------------------+----------------------------------------------+
| curses.KEY_SSUSPEND       | Shifted Suspend                              |
+---------------------------+----------------------------------------------+
| curses.KEY_SUNDO          | Shifted Undo                                 |
+---------------------------+----------------------------------------------+
| curses.KEY_SUSPEND        | Suspend                                      |
+---------------------------+----------------------------------------------+
| curses.KEY_UNDO           | Undo                                         |
+---------------------------+----------------------------------------------+
| curses.KEY_MOUSE          | Mouse event has occurred                     |
+---------------------------+----------------------------------------------+
| curses.KEY_RESIZE         | Terminal resize event                        |
+---------------------------+----------------------------------------------+
| curses.KEY_MAX            | Maximum key value                            |
+---------------------------+----------------------------------------------+

On VT100s and their software emulations, such as X terminal emulators,
there are normally at least four function keys ("KEY_F1", "KEY_F2",
"KEY_F3", "KEY_F4") available, and the arrow keys mapped to "KEY_UP",
"KEY_DOWN", "KEY_LEFT" and "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:

+--------------------+-------------+
| Keycap             | Constant    |
|====================|=============|
| "Insert"           | KEY_IC      |
+--------------------+-------------+
| "Delete"           | KEY_DC      |
+--------------------+-------------+
| "Home"             | KEY_HOME    |
+--------------------+-------------+
| "End"              | KEY_END     |
+--------------------+-------------+
| "Page Up"          | KEY_PPAGE   |
+--------------------+-------------+
| "Page Down"        | KEY_NPAGE   |
+--------------------+-------------+

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 "initscr()" has  been called.

+--------------------------+--------------------------------------------+
| ACS code                 | Meaning                                    |
|==========================|============================================|
| curses.ACS_BBSS          | alternate name for upper right corner      |
+--------------------------+--------------------------------------------+
| curses.ACS_BLOCK         | solid square block                         |
+--------------------------+--------------------------------------------+
| curses.ACS_BOARD         | board of squares                           |
+--------------------------+--------------------------------------------+
| curses.ACS_BSBS          | alternate name for horizontal line         |
+--------------------------+--------------------------------------------+
| curses.ACS_BSSB          | alternate name for upper left corner       |
+--------------------------+--------------------------------------------+
| curses.ACS_BSSS          | alternate name for top tee                 |
+--------------------------+--------------------------------------------+
| curses.ACS_BTEE          | bottom tee                                 |
+--------------------------+--------------------------------------------+
| curses.ACS_BULLET        | bullet                                     |
+--------------------------+--------------------------------------------+
| curses.ACS_CKBOARD       | checker board (stipple)                    |
+--------------------------+--------------------------------------------+
| curses.ACS_DARROW        | arrow pointing down                        |
+--------------------------+--------------------------------------------+
| curses.ACS_DEGREE        | degree symbol                              |
+--------------------------+--------------------------------------------+
| curses.ACS_DIAMOND       | diamond                                    |
+--------------------------+--------------------------------------------+
| curses.ACS_GEQUAL        | greater-than-or-equal-to                   |
+--------------------------+--------------------------------------------+
| curses.ACS_HLINE         | horizontal line                            |
+--------------------------+--------------------------------------------+
| curses.ACS_LANTERN       | lantern symbol                             |
+--------------------------+--------------------------------------------+
| curses.ACS_LARROW        | left arrow                                 |
+--------------------------+--------------------------------------------+
| curses.ACS_LEQUAL        | less-than-or-equal-to                      |
+--------------------------+--------------------------------------------+
| curses.ACS_LLCORNER      | lower left-hand corner                     |
+--------------------------+--------------------------------------------+
| curses.ACS_LRCORNER      | lower right-hand corner                    |
+--------------------------+--------------------------------------------+
| curses.ACS_LTEE          | left tee                                   |
+--------------------------+--------------------------------------------+
| curses.ACS_NEQUAL        | not-equal sign                             |
+--------------------------+--------------------------------------------+
| curses.ACS_PI            | letter pi                                  |
+--------------------------+--------------------------------------------+
| curses.ACS_PLMINUS       | plus-or-minus sign                         |
+--------------------------+--------------------------------------------+
| curses.ACS_PLUS          | big plus sign                              |
+--------------------------+--------------------------------------------+
| curses.ACS_RARROW        | right arrow                                |
+--------------------------+--------------------------------------------+
| curses.ACS_RTEE          | right tee                                  |
+--------------------------+--------------------------------------------+
| curses.ACS_S1            | scan line 1                                |
+--------------------------+--------------------------------------------+
| curses.ACS_S3            | scan line 3                                |
+--------------------------+--------------------------------------------+
| curses.ACS_S7            | scan line 7                                |
+--------------------------+--------------------------------------------+
| curses.ACS_S9            | scan line 9                                |
+--------------------------+--------------------------------------------+
| curses.ACS_SBBS          | alternate name for lower right corner      |
+--------------------------+--------------------------------------------+
| curses.ACS_SBSB          | alternate name for vertical line           |
+--------------------------+--------------------------------------------+
| curses.ACS_SBSS          | alternate name for right tee               |
+--------------------------+--------------------------------------------+
| curses.ACS_SSBB          | alternate name for lower left corner       |
+--------------------------+--------------------------------------------+
| curses.ACS_SSBS          | alternate name for bottom tee              |
+--------------------------+--------------------------------------------+
| curses.ACS_SSSB          | alternate name for left tee                |
+--------------------------+--------------------------------------------+
| curses.ACS_SSSS          | alternate name for crossover or big plus   |
+--------------------------+--------------------------------------------+
| curses.ACS_STERLING      | pound sterling                             |
+--------------------------+--------------------------------------------+
| curses.ACS_TTEE          | top tee                                    |
+--------------------------+--------------------------------------------+
| curses.ACS_UARROW        | up arrow                                   |
+--------------------------+--------------------------------------------+
| curses.ACS_ULCORNER      | upper left corner                          |
+--------------------------+--------------------------------------------+
| curses.ACS_URCORNER      | upper right corner                         |
+--------------------------+--------------------------------------------+
| curses.ACS_VLINE         | vertical line                              |
+--------------------------+--------------------------------------------+

The following table lists mouse button constants used by "getmouse()":

+------------------------------------+-----------------------------------------------+
| Mouse button constant              | Meaning                                       |
|====================================|===============================================|
| curses.BUTTONn_PRESSED             | Mouse button _n_ pressed                      |
+------------------------------------+-----------------------------------------------+
| curses.BUTTONn_RELEASED            | Mouse button _n_ released                     |
+------------------------------------+-----------------------------------------------+
| curses.BUTTONn_CLICKED             | Mouse button _n_ clicked                      |
+------------------------------------+-----------------------------------------------+
| curses.BUTTONn_DOUBLE_CLICKED      | Mouse button _n_ double clicked               |
+------------------------------------+-----------------------------------------------+
| curses.BUTTONn_TRIPLE_CLICKED      | Mouse button _n_ triple clicked               |
+------------------------------------+-----------------------------------------------+
| curses.BUTTON_SHIFT                | Shift was down during button state change     |
+------------------------------------+-----------------------------------------------+
| curses.BUTTON_CTRL                 | Control was down during button state change   |
+------------------------------------+-----------------------------------------------+
| curses.BUTTON_ALT                  | Control was down during button state change   |
+------------------------------------+-----------------------------------------------+

   Changed in version 3.10: The "BUTTON5_*" constants are now exposed
   if they are provided by the underlying curses library.

The following table lists the predefined colors:

+---------------------------+------------------------------+
| Constant                  | Color                        |
|===========================|==============================|
| curses.COLOR_BLACK        | Black                        |
+---------------------------+------------------------------+
| curses.COLOR_BLUE         | Blue                         |
+---------------------------+------------------------------+
| curses.COLOR_CYAN         | Cyan (light greenish blue)   |
+---------------------------+------------------------------+
| curses.COLOR_GREEN        | Green                        |
+---------------------------+------------------------------+
| curses.COLOR_MAGENTA      | Magenta (purplish red)       |
+---------------------------+------------------------------+
| curses.COLOR_RED          | Red                          |
+---------------------------+------------------------------+
| curses.COLOR_WHITE        | White                        |
+---------------------------+------------------------------+
| curses.COLOR_YELLOW       | Yellow                       |
+---------------------------+------------------------------+


"curses.textpad" — Text input widget for curses programs
********************************************************

The "curses.textpad" module provides a "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 "curses.textpad" defines the following function:

                                            *rectangle()..curses.txt;*
curses.textpad.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.


Textbox objects
===============

You can instantiate a "Textbox" object as follows:

class curses.textpad.Textbox(win)               *Textbox..curses.txt;*

   Return a textbox widget object.  The _win_ argument should be a
   curses window object 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 "(0, 0)".
   The instance’s "stripspaces" flag is initially on.

   "Textbox" objects have the following methods:

   edit([validator])                        *Textbox.edit()..curses.txt;*

      This is the entry point you will normally use.  It accepts
      editing keystrokes until one of the termination keystrokes is
      entered.  If _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 "stripspaces" attribute.

   do_command(ch)                     *Textbox.do_command()..curses.txt;*

      Process a single command keystroke.  Here are the supported
      special keystrokes:

      +--------------------+---------------------------------------------+
      | Keystroke          | Action                                      |
      |====================|=============================================|
      | "Control-A"        | Go to left edge of window.                  |
      +--------------------+---------------------------------------------+
      | "Control-B"        | Cursor left, wrapping to previous line if   |
      |                    | appropriate.                                |
      +--------------------+---------------------------------------------+
      | "Control-D"        | Delete character under cursor.              |
      +--------------------+---------------------------------------------+
      | "Control-E"        | Go to right edge (stripspaces off) or end   |
      |                    | of line (stripspaces on).                   |
      +--------------------+---------------------------------------------+
      | "Control-F"        | Cursor right, wrapping to next line when    |
      |                    | appropriate.                                |
      +--------------------+---------------------------------------------+
      | "Control-G"        | Terminate, returning the window contents.   |
      +--------------------+---------------------------------------------+
      | "Control-H"        | Delete character backward.                  |
      +--------------------+---------------------------------------------+
      | "Control-J"        | Terminate if the window is 1 line,          |
      |                    | otherwise insert newline.                   |
      +--------------------+---------------------------------------------+
      | "Control-K"        | If line is blank, delete it, otherwise      |
      |                    | clear to end of line.                       |
      +--------------------+---------------------------------------------+
      | "Control-L"        | Refresh screen.                             |
      +--------------------+---------------------------------------------+
      | "Control-N"        | Cursor down; move down one line.            |
      +--------------------+---------------------------------------------+
      | "Control-O"        | Insert a blank line at cursor location.     |
      +--------------------+---------------------------------------------+
      | "Control-P"        | Cursor up; move up one line.                |
      +--------------------+---------------------------------------------+

      Move operations do nothing if the cursor is at an edge where the
      movement is not possible.  The following synonyms are supported
      where possible:

      +----------------------------------+--------------------+
      | Constant                         | Keystroke          |
      |==================================|====================|
      | "KEY_LEFT"                       | "Control-B"        |
      +----------------------------------+--------------------+
      | "KEY_RIGHT"                      | "Control-F"        |
      +----------------------------------+--------------------+
      | "KEY_UP"                         | "Control-P"        |
      +----------------------------------+--------------------+
      | "KEY_DOWN"                       | "Control-N"        |
      +----------------------------------+--------------------+
      | "KEY_BACKSPACE"                  | "Control-h"        |
      +----------------------------------+--------------------+

      All other keystrokes are treated as a command to insert the
      given character and move right (with line wrapping).

   gather()                               *Textbox.gather()..curses.txt;*

      Return the window contents as a string; whether blanks in the
      window are included is affected by the "stripspaces" member.

   stripspaces                         *Textbox.stripspaces..curses.txt;*

      This attribute 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.

vim:tw=78:ts=8:ft=help:norl: