1 

     2 :mod:`curses` --- Terminal handling for character-cell displays

     3 ===============================================================

     4 

     5 .. module:: curses

     6    :synopsis: An interface to the curses library, providing portable terminal handling.

     7 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>

     8 .. sectionauthor:: Eric Raymond <esr@thyrsus.com>

     9 

    10 

    11 .. versionchanged:: 1.6

    12    Added support for the ``ncurses`` library and converted to a package.

    13 

    14 The :mod:`curses` module provides an interface to the curses library, the

    15 de-facto standard for portable advanced terminal handling.

    16 

    17 While curses is most widely used in the Unix environment, versions are available

    18 for DOS, OS/2, and possibly other systems as well.  This extension module is

    19 designed to match the API of ncurses, an open-source curses library hosted on

    20 Linux and the BSD variants of Unix.

    21 

    22 .. note::

    23 

    24    Since version 5.4, the ncurses library decides how to interpret non-ASCII data

    25    using the ``nl_langinfo`` function.  That means that you have to call

    26    :func:`locale.setlocale` in the application and encode Unicode strings

    27    using one of the system's available encodings.  This example uses the

    28    system's default encoding::

    29 

    30       import locale

    31       locale.setlocale(locale.LC_ALL, '')

    32       code = locale.getpreferredencoding()

    33 

    34    Then use *code* as the encoding for :meth:`str.encode` calls.

    35 

    36 .. seealso::

    37 

    38    Module :mod:`curses.ascii`

    39       Utilities for working with ASCII characters, regardless of your locale settings.

    40 

    41    Module :mod:`curses.panel`

    42       A panel stack extension that adds depth to  curses windows.

    43 

    44    Module :mod:`curses.textpad`

    45       Editable text widget for curses supporting  :program:`Emacs`\ -like bindings.

    46 

    47    Module :mod:`curses.wrapper`

    48       Convenience function to ensure proper terminal setup and resetting on

    49       application entry and exit.

    50 

    51    :ref:`curses-howto`

    52       Tutorial material on using curses with Python, by Andrew Kuchling and Eric

    53       Raymond.

    54 

    55    The :file:`Demo/curses/` directory in the Python source distribution contains

    56    some example programs using the curses bindings provided by this module.

    57 

    58 

    59 .. _curses-functions:

    60 

    61 Functions

    62 ---------

    63 

    64 The module :mod:`curses` defines the following exception:

    65 

    66 

    67 .. exception:: error

    68 

    69    Exception raised when a curses library function returns an error.

    70 

    71 .. note::

    72 

    73    Whenever *x* or *y* arguments to a function or a method are optional, they

    74    default to the current cursor location. Whenever *attr* is optional, it defaults

    75    to :const:`A_NORMAL`.

    76 

    77 The module :mod:`curses` defines the following functions:

    78 

    79 

    80 .. function:: baudrate()

    81 

    82    Returns the output speed of the terminal in bits per second.  On software

    83    terminal emulators it will have a fixed high value. Included for historical

    84    reasons; in former times, it was used to  write output loops for time delays and

    85    occasionally to change interfaces depending on the line speed.

    86 

    87 

    88 .. function:: beep()

    89 

    90    Emit a short attention sound.

    91 

    92 

    93 .. function:: can_change_color()

    94 

    95    Returns true or false, depending on whether the programmer can change the colors

    96    displayed by the terminal.

    97 

    98 

    99 .. function:: cbreak()

   100 

   101    Enter cbreak mode.  In cbreak mode (sometimes called "rare" mode) normal tty

   102    line buffering is turned off and characters are available to be read one by one.

   103    However, unlike raw mode, special characters (interrupt, quit, suspend, and flow

   104    control) retain their effects on the tty driver and calling program.  Calling

   105    first :func:`raw` then :func:`cbreak` leaves the terminal in cbreak mode.

   106 

   107 

   108 .. function:: color_content(color_number)

   109 

   110    Returns the intensity of the red, green, and blue (RGB) components in the color

   111    *color_number*, which must be between ``0`` and :const:`COLORS`.  A 3-tuple is

   112    returned, containing the R,G,B values for the given color, which will be between

   113    ``0`` (no component) and ``1000`` (maximum amount of component).

   114 

   115 

   116 .. function:: color_pair(color_number)

   117 

   118    Returns the attribute value for displaying text in the specified color.  This

   119    attribute value can be combined with :const:`A_STANDOUT`, :const:`A_REVERSE`,

   120    and the other :const:`A_\*` attributes.  :func:`pair_number` is the counterpart

   121    to this function.

   122 

   123 

   124 .. function:: curs_set(visibility)

   125 

   126    Sets the cursor state.  *visibility* can be set to 0, 1, or 2, for invisible,

   127    normal, or very visible.  If the terminal supports the visibility requested, the

   128    previous cursor state is returned; otherwise, an exception is raised.  On many

   129    terminals, the "visible" mode is an underline cursor and the "very visible" mode

   130    is a block cursor.

   131 

   132 

   133 .. function:: def_prog_mode()

   134 

   135    Saves the current terminal mode as the "program" mode, the mode when the running

   136    program is using curses.  (Its counterpart is the "shell" mode, for when the

   137    program is not in curses.)  Subsequent calls to :func:`reset_prog_mode` will

   138    restore this mode.

   139 

   140 

   141 .. function:: def_shell_mode()

   142 

   143    Saves the current terminal mode as the "shell" mode, the mode when the running

   144    program is not using curses.  (Its counterpart is the "program" mode, when the

   145    program is using curses capabilities.) Subsequent calls to

   146    :func:`reset_shell_mode` will restore this mode.

   147 

   148 

   149 .. function:: delay_output(ms)

   150 

   151    Inserts an *ms* millisecond pause in output.

   152 

   153 

   154 .. function:: doupdate()

   155 

   156    Update the physical screen.  The curses library keeps two data structures, one

   157    representing the current physical screen contents and a virtual screen

   158    representing the desired next state.  The :func:`doupdate` ground updates the

   159    physical screen to match the virtual screen.

   160 

   161    The virtual screen may be updated by a :meth:`noutrefresh` call after write

   162    operations such as :meth:`addstr` have been performed on a window.  The normal

   163    :meth:`refresh` call is simply :meth:`noutrefresh` followed by :func:`doupdate`;

   164    if you have to update multiple windows, you can speed performance and perhaps

   165    reduce screen flicker by issuing :meth:`noutrefresh` calls on all windows,

   166    followed by a single :func:`doupdate`.

   167 

   168 

   169 .. function:: echo()

   170 

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

   172    it is entered.

   173 

   174 

   175 .. function:: endwin()

   176 

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

   178 

   179 

   180 .. function:: erasechar()

   181 

   182    Returns the user's current erase character.  Under Unix operating systems this

   183    is a property of the controlling tty of the curses program, and is not set by

   184    the curses library itself.

   185 

   186 

   187 .. function:: filter()

   188 

   189    The :func:`filter` routine, if used, must be called before :func:`initscr` is

   190    called.  The effect is that, during those calls, LINES is set to 1; the

   191    capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home

   192    string is set to the value of cr. The effect is that the cursor is confined to

   193    the current line, and so are screen updates.  This may be used for enabling

   194    character-at-a-time  line editing without touching the rest of the screen.

   195 

   196 

   197 .. function:: flash()

   198 

   199    Flash the screen.  That is, change it to reverse-video and then change it back

   200    in a short interval.  Some people prefer such as 'visible bell' to the audible

   201    attention signal produced by :func:`beep`.

   202 

   203 

   204 .. function:: flushinp()

   205 

   206    Flush all input buffers.  This throws away any  typeahead  that  has been typed

   207    by the user and has not yet been processed by the program.

   208 

   209 

   210 .. function:: getmouse()

   211 

   212    After :meth:`getch` returns :const:`KEY_MOUSE` to signal a mouse event, this

   213    method should be call to retrieve the queued mouse event, represented as a

   214    5-tuple ``(id, x, y, z, bstate)``. *id* is an ID value used to distinguish

   215    multiple devices, and *x*, *y*, *z* are the event's coordinates.  (*z* is

   216    currently unused.).  *bstate* is an integer value whose bits will be set to

   217    indicate the type of event, and will be the bitwise OR of one or more of the

   218    following constants, where *n* is the button number from 1 to 4:

   219    :const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:`BUTTONn_CLICKED`,

   220    :const:`BUTTONn_DOUBLE_CLICKED`, :const:`BUTTONn_TRIPLE_CLICKED`,

   221    :const:`BUTTON_SHIFT`, :const:`BUTTON_CTRL`, :const:`BUTTON_ALT`.

   222 

   223 

   224 .. function:: getsyx()

   225 

   226    Returns the current coordinates of the virtual screen cursor in y and x.  If

   227    leaveok is currently true, then -1,-1 is returned.

   228 

   229 

   230 .. function:: getwin(file)

   231 

   232    Reads window related data stored in the file by an earlier :func:`putwin` call.

   233    The routine then creates and initializes a new window using that data, returning

   234    the new window object.

   235 

   236 

   237 .. function:: has_colors()

   238 

   239    Returns true if the terminal can display colors; otherwise, it returns false.

   240 

   241 

   242 .. function:: has_ic()

   243 

   244    Returns true if the terminal has insert- and delete- character capabilities.

   245    This function is included for historical reasons only, as all modern software

   246    terminal emulators have such capabilities.

   247 

   248 

   249 .. function:: has_il()

   250 

   251    Returns true if the terminal has insert- and delete-line  capabilities,  or  can

   252    simulate  them  using scrolling regions. This function is included for

   253    historical reasons only, as all modern software terminal emulators have such

   254    capabilities.

   255 

   256 

   257 .. function:: has_key(ch)

   258 

   259    Takes a key value *ch*, and returns true if the current terminal type recognizes

   260    a key with that value.

   261 

   262 

   263 .. function:: halfdelay(tenths)

   264 

   265    Used for half-delay mode, which is similar to cbreak mode in that characters

   266    typed by the user are immediately available to the program. However, after

   267    blocking for *tenths* tenths of seconds, an exception is raised if nothing has

   268    been typed.  The value of *tenths* must be a number between 1 and 255.  Use

   269    :func:`nocbreak` to leave half-delay mode.

   270 

   271 

   272 .. function:: init_color(color_number, r, g, b)

   273 

   274    Changes the definition of a color, taking the number of the color to be changed

   275    followed by three RGB values (for the amounts of red, green, and blue

   276    components).  The value of *color_number* must be between ``0`` and

   277    :const:`COLORS`.  Each of *r*, *g*, *b*, must be a value between ``0`` and

   278    ``1000``.  When :func:`init_color` is used, all occurrences of that color on the

   279    screen immediately change to the new definition.  This function is a no-op on

   280    most terminals; it is active only if :func:`can_change_color` returns ``1``.

   281 

   282 

   283 .. function:: init_pair(pair_number, fg, bg)

   284 

   285    Changes the definition of a color-pair.  It takes three arguments: the number of

   286    the color-pair to be changed, the foreground color number, and the background

   287    color number.  The value of *pair_number* must be between ``1`` and

   288    ``COLOR_PAIRS - 1`` (the ``0`` color pair is wired to white on black and cannot

   289    be changed).  The value of *fg* and *bg* arguments must be between ``0`` and

   290    :const:`COLORS`.  If the color-pair was previously initialized, the screen is

   291    refreshed and all occurrences of that color-pair are changed to the new

   292    definition.

   293 

   294 

   295 .. function:: initscr()

   296 

   297    Initialize the library. Returns a :class:`WindowObject` which represents the

   298    whole screen.

   299 

   300    .. note::

   301 

   302       If there is an error opening the terminal, the underlying curses library may

   303       cause the interpreter to exit.

   304 

   305 

   306 .. function:: isendwin()

   307 

   308    Returns true if :func:`endwin` has been called (that is, the  curses library has

   309    been deinitialized).

   310 

   311 

   312 .. function:: keyname(k)

   313 

   314    Return the name of the key numbered *k*.  The name of a key generating printable

   315    ASCII character is the key's character.  The name of a control-key combination

   316    is a two-character string consisting of a caret followed by the corresponding

   317    printable ASCII character.  The name of an alt-key combination (128-255) is a

   318    string consisting of the prefix 'M-' followed by the name of the corresponding

   319    ASCII character.

   320 

   321 

   322 .. function:: killchar()

   323 

   324    Returns the user's current line kill character. Under Unix operating systems

   325    this is a property of the controlling tty of the curses program, and is not set

   326    by the curses library itself.

   327 

   328 

   329 .. function:: longname()

   330 

   331    Returns a string containing the terminfo long name field describing the current

   332    terminal.  The maximum length of a verbose description is 128 characters.  It is

   333    defined only after the call to :func:`initscr`.

   334 

   335 

   336 .. function:: meta(yes)

   337 

   338    If *yes* is 1, allow 8-bit characters to be input. If *yes* is 0,  allow only

   339    7-bit chars.

   340 

   341 

   342 .. function:: mouseinterval(interval)

   343 

   344    Sets the maximum time in milliseconds that can elapse between press and release

   345    events in order for them to be recognized as a click, and returns the previous

   346    interval value.  The default value is 200 msec, or one fifth of a second.

   347 

   348 

   349 .. function:: mousemask(mousemask)

   350 

   351    Sets the mouse events to be reported, and returns a tuple ``(availmask,

   352    oldmask)``.   *availmask* indicates which of the specified mouse events can be

   353    reported; on complete failure it returns 0.  *oldmask* is the previous value of

   354    the given window's mouse event mask.  If this function is never called, no mouse

   355    events are ever reported.

   356 

   357 

   358 .. function:: napms(ms)

   359 

   360    Sleep for *ms* milliseconds.

   361 

   362 

   363 .. function:: newpad(nlines, ncols)

   364 

   365    Creates and returns a pointer to a new pad data structure with the given number

   366    of lines and columns.  A pad is returned as a window object.

   367 

   368    A pad is like a window, except that it is not restricted by the screen size, and

   369    is not necessarily associated with a particular part of the screen.  Pads can be

   370    used when a large window is needed, and only a part of the window will be on the

   371    screen at one time.  Automatic refreshes of pads (such as from scrolling or

   372    echoing of input) do not occur.  The :meth:`refresh` and :meth:`noutrefresh`

   373    methods of a pad require 6 arguments to specify the part of the pad to be

   374    displayed and the location on the screen to be used for the display. The

   375    arguments are pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol; the p

   376    arguments refer to the upper left corner of the pad region to be displayed and

   377    the s arguments define a clipping box on the screen within which the pad region

   378    is to be displayed.

   379 

   380 

   381 .. function:: newwin([nlines, ncols,] begin_y, begin_x)

   382 

   383    Return a new window, whose left-upper corner is at  ``(begin_y, begin_x)``, and

   384    whose height/width is  *nlines*/*ncols*.

   385 

   386    By default, the window will extend from the  specified position to the lower

   387    right corner of the screen.

   388 

   389 

   390 .. function:: nl()

   391 

   392    Enter newline mode.  This mode translates the return key into newline on input,

   393    and translates newline into return and line-feed on output. Newline mode is

   394    initially on.

   395 

   396 

   397 .. function:: nocbreak()

   398 

   399    Leave cbreak mode.  Return to normal "cooked" mode with line buffering.

   400 

   401 

   402 .. function:: noecho()

   403 

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

   405 

   406 

   407 .. function:: nonl()

   408 

   409    Leave newline mode.  Disable translation of return into newline on input, and

   410    disable low-level translation of newline into newline/return on output (but this

   411    does not change the behavior of ``addch('\n')``, which always does the

   412    equivalent of return and line feed on the virtual screen).  With translation

   413    off, curses can sometimes speed up vertical motion a little; also, it will be

   414    able to detect the return key on input.

   415 

   416 

   417 .. function:: noqiflush()

   418 

   419    When the noqiflush routine is used, normal flush of input and output queues

   420    associated with the INTR, QUIT and SUSP characters will not be done.  You may

   421    want to call :func:`noqiflush` in a signal handler if you want output to

   422    continue as though the interrupt had not occurred, after the handler exits.

   423 

   424 

   425 .. function:: noraw()

   426 

   427    Leave raw mode. Return to normal "cooked" mode with line buffering.

   428 

   429 

   430 .. function:: pair_content(pair_number)

   431 

   432    Returns a tuple ``(fg, bg)`` containing the colors for the requested color pair.

   433    The value of *pair_number* must be between ``1`` and ``COLOR_PAIRS - 1``.

   434 

   435 

   436 .. function:: pair_number(attr)

   437 

   438    Returns the number of the color-pair set by the attribute value *attr*.

   439    :func:`color_pair` is the counterpart to this function.

   440 

   441 

   442 .. function:: putp(string)

   443 

   444    Equivalent to ``tputs(str, 1, putchar)``; emits the value of a specified

   445    terminfo capability for the current terminal.  Note that the output of putp

   446    always goes to standard output.

   447 

   448 

   449 .. function:: qiflush( [flag] )

   450 

   451    If *flag* is false, the effect is the same as calling :func:`noqiflush`. If

   452    *flag* is true, or no argument is provided, the queues will be flushed when

   453    these control characters are read.

   454 

   455 

   456 .. function:: raw()

   457 

   458    Enter raw mode.  In raw mode, normal line buffering and  processing of

   459    interrupt, quit, suspend, and flow control keys are turned off; characters are

   460    presented to curses input functions one by one.

   461 

   462 

   463 .. function:: reset_prog_mode()

   464 

   465    Restores the  terminal  to "program" mode, as previously saved  by

   466    :func:`def_prog_mode`.

   467 

   468 

   469 .. function:: reset_shell_mode()

   470 

   471    Restores the  terminal  to "shell" mode, as previously saved  by

   472    :func:`def_shell_mode`.

   473 

   474 

   475 .. function:: setsyx(y, x)

   476 

   477    Sets the virtual screen cursor to *y*, *x*. If *y* and *x* are both -1, then

   478    leaveok is set.

   479 

   480 

   481 .. function:: setupterm([termstr, fd])

   482 

   483    Initializes the terminal.  *termstr* is a string giving the terminal name; if

   484    omitted, the value of the TERM environment variable will be used.  *fd* is the

   485    file descriptor to which any initialization sequences will be sent; if not

   486    supplied, the file descriptor for ``sys.stdout`` will be used.

   487 

   488 

   489 .. function:: start_color()

   490 

   491    Must be called if the programmer wants to use colors, and before any other color

   492    manipulation routine is called.  It is good practice to call this routine right

   493    after :func:`initscr`.

   494 

   495    :func:`start_color` initializes eight basic colors (black, red,  green, yellow,

   496    blue, magenta, cyan, and white), and two global variables in the :mod:`curses`

   497    module, :const:`COLORS` and :const:`COLOR_PAIRS`, containing the maximum number

   498    of colors and color-pairs the terminal can support.  It also restores the colors

   499    on the terminal to the values they had when the terminal was just turned on.

   500 

   501 

   502 .. function:: termattrs()

   503 

   504    Returns a logical OR of all video attributes supported by the terminal.  This

   505    information is useful when a curses program needs complete control over the

   506    appearance of the screen.

   507 

   508 

   509 .. function:: termname()

   510 

   511    Returns the value of the environment variable TERM, truncated to 14 characters.

   512 

   513 

   514 .. function:: tigetflag(capname)

   515 

   516    Returns the value of the Boolean capability corresponding to the terminfo

   517    capability name *capname*.  The value ``-1`` is returned if *capname* is not a

   518    Boolean capability, or ``0`` if it is canceled or absent from the terminal

   519    description.

   520 

   521 

   522 .. function:: tigetnum(capname)

   523 

   524    Returns the value of the numeric capability corresponding to the terminfo

   525    capability name *capname*.  The value ``-2`` is returned if *capname* is not a

   526    numeric capability, or ``-1`` if it is canceled or absent from the terminal

   527    description.

   528 

   529 

   530 .. function:: tigetstr(capname)

   531 

   532    Returns the value of the string capability corresponding to the terminfo

   533    capability name *capname*.  ``None`` is returned if *capname* is not a string

   534    capability, or is canceled or absent from the terminal description.

   535 

   536 

   537 .. function:: tparm(str[,...])

   538 

   539    Instantiates the string *str* with the supplied parameters, where  *str* should

   540    be a parameterized string obtained from the terminfo  database.  E.g.

   541    ``tparm(tigetstr("cup"), 5, 3)`` could result in  ``'\033[6;4H'``, the exact

   542    result depending on terminal type.

   543 

   544 

   545 .. function:: typeahead(fd)

   546 

   547    Specifies that the file descriptor *fd* be used for typeahead checking.  If *fd*

   548    is ``-1``, then no typeahead checking is done.

   549 

   550    The curses library does "line-breakout optimization" by looking for typeahead

   551    periodically while updating the screen.  If input is found, and it is coming

   552    from a tty, the current update is postponed until refresh or doupdate is called

   553    again, allowing faster response to commands typed in advance. This function

   554    allows specifying a different file descriptor for typeahead checking.

   555 

   556 

   557 .. function:: unctrl(ch)

   558 

   559    Returns a string which is a printable representation of the character *ch*.

   560    Control characters are displayed as a caret followed by the character, for

   561    example as ``^C``. Printing characters are left as they are.

   562 

   563 

   564 .. function:: ungetch(ch)

   565 

   566    Push *ch* so the next :meth:`getch` will return it.

   567 

   568    .. note::

   569 

   570       Only one *ch* can be pushed before :meth:`getch` is called.

   571 

   572 

   573 .. function:: ungetmouse(id, x, y, z, bstate)

   574 

   575    Push a :const:`KEY_MOUSE` event onto the input queue, associating the given

   576    state data with it.

   577 

   578 

   579 .. function:: use_env(flag)

   580 

   581    If used, this function should be called before :func:`initscr` or newterm are

   582    called.  When *flag* is false, the values of lines and columns specified in the

   583    terminfo database will be used, even if environment variables :envvar:`LINES`

   584    and :envvar:`COLUMNS` (used by default) are set, or if curses is running in a

   585    window (in which case default behavior would be to use the window size if

   586    :envvar:`LINES` and :envvar:`COLUMNS` are not set).

   587 

   588 

   589 .. function:: use_default_colors()

   590 

   591    Allow use of default values for colors on terminals supporting this feature. Use

   592    this to support transparency in your application.  The default color is assigned

   593    to the color number -1. After calling this function,  ``init_pair(x,

   594    curses.COLOR_RED, -1)`` initializes, for instance, color pair *x* to a red

   595    foreground color on the default background.

   596 

   597 

   598 .. _curses-window-objects:

   599 

   600 Window Objects

   601 --------------

   602 

   603 Window objects, as returned by :func:`initscr` and :func:`newwin` above, have

   604 the following methods:

   605 

   606 

   607 .. method:: window.addch([y, x,] ch[, attr])

   608 

   609    .. note::

   610 

   611       A *character* means a C character (an ASCII code), rather then a Python

   612       character (a string of length 1). (This note is true whenever the documentation

   613       mentions a character.) The builtin :func:`ord` is handy for conveying strings to

   614       codes.

   615 

   616    Paint character *ch* at ``(y, x)`` with attributes *attr*, overwriting any

   617    character previously painter at that location.  By default, the character

   618    position and attributes are the current settings for the window object.

   619 

   620 

   621 .. method:: window.addnstr([y, x,] str, n[, attr])

   622 

   623    Paint at most *n* characters of the  string *str* at ``(y, x)`` with attributes

   624    *attr*, overwriting anything previously on the display.

   625 

   626 

   627 .. method:: window.addstr([y, x,] str[, attr])

   628 

   629    Paint the string *str* at ``(y, x)`` with attributes *attr*, overwriting

   630    anything previously on the display.

   631 

   632 

   633 .. method:: window.attroff(attr)

   634 

   635    Remove attribute *attr* from the "background" set applied to all writes to the

   636    current window.

   637 

   638 

   639 .. method:: window.attron(attr)

   640 

   641    Add attribute *attr* from the "background" set applied to all writes to the

   642    current window.

   643 

   644 

   645 .. method:: window.attrset(attr)

   646 

   647    Set the "background" set of attributes to *attr*.  This set is initially 0 (no

   648    attributes).

   649 

   650 

   651 .. method:: window.bkgd(ch[, attr])

   652 

   653    Sets the background property of the window to the character *ch*, with

   654    attributes *attr*.  The change is then applied to every character position in

   655    that window:

   656 

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

   658      background attribute.

   659 

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

   661      background character.

   662 

   663 

   664 .. method:: window.bkgdset(ch[, attr])

   665 

   666    Sets the window's background.  A window's background consists of a character and

   667    any combination of attributes.  The attribute part of the background is combined

   668    (OR'ed) with all non-blank characters that are written into the window.  Both

   669    the character and attribute parts of the background are combined with the blank

   670    characters.  The background becomes a property of the character and moves with

   671    the character through any scrolling and insert/delete line/character operations.

   672 

   673 

   674 .. method:: window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])

   675 

   676    Draw a border around the edges of the window. Each parameter specifies  the

   677    character to use for a specific part of the border; see the table below for more

   678    details.  The characters can be specified as integers or as one-character

   679    strings.

   680 

   681    .. note::

   682 

   683       A ``0`` value for any parameter will cause the default character to be used for

   684       that parameter.  Keyword parameters can *not* be used.  The defaults are listed

   685       in this table:

   686 

   687    +-----------+---------------------+-----------------------+

   688    | Parameter | Description         | Default value         |

   689    +===========+=====================+=======================+

   690    | *ls*      | Left side           | :const:`ACS_VLINE`    |

   691    +-----------+---------------------+-----------------------+

   692    | *rs*      | Right side          | :const:`ACS_VLINE`    |

   693    +-----------+---------------------+-----------------------+

   694    | *ts*      | Top                 | :const:`ACS_HLINE`    |

   695    +-----------+---------------------+-----------------------+

   696    | *bs*      | Bottom              | :const:`ACS_HLINE`    |

   697    +-----------+---------------------+-----------------------+

   698    | *tl*      | Upper-left corner   | :const:`ACS_ULCORNER` |

   699    +-----------+---------------------+-----------------------+

   700    | *tr*      | Upper-right corner  | :const:`ACS_URCORNER` |

   701    +-----------+---------------------+-----------------------+

   702    | *bl*      | Bottom-left corner  | :const:`ACS_LLCORNER` |

   703    +-----------+---------------------+-----------------------+

   704    | *br*      | Bottom-right corner | :const:`ACS_LRCORNER` |

   705    +-----------+---------------------+-----------------------+

   706 

   707 

   708 .. method:: window.box([vertch, horch])

   709 

   710    Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* and

   711    bs are *horch*.  The default corner characters are always used by this function.

   712 

   713 

   714 .. method:: window.chgat([y, x, ] [num,] attr)

   715 

   716    Sets the attributes of *num* characters at the current cursor position, or at

   717    position ``(y, x)`` if supplied. If no value of *num* is given or *num* = -1,

   718    the attribute will  be set on all the characters to the end of the line.  This

   719    function does not move the cursor. The changed line will be touched using the

   720    :meth:`touchline` method so that the contents will be redisplayed by the next

   721    window refresh.

   722 

   723 

   724 .. method:: window.clear()

   725 

   726    Like :meth:`erase`, but also causes the whole window to be repainted upon next

   727    call to :meth:`refresh`.

   728 

   729 

   730 .. method:: window.clearok(yes)

   731 

   732    If *yes* is 1, the next call to :meth:`refresh` will clear the window

   733    completely.

   734 

   735 

   736 .. method:: window.clrtobot()

   737 

   738    Erase from cursor to the end of the window: all lines below the cursor are

   739    deleted, and then the equivalent of :meth:`clrtoeol` is performed.

   740 

   741 

   742 .. method:: window.clrtoeol()

   743 

   744    Erase from cursor to the end of the line.

   745 

   746 

   747 .. method:: window.cursyncup()

   748 

   749    Updates the current cursor position of all the ancestors of the window to

   750    reflect the current cursor position of the window.

   751 

   752 

   753 .. method:: window.delch([y, x])

   754 

   755    Delete any character at ``(y, x)``.

   756 

   757 

   758 .. method:: window.deleteln()

   759 

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

   761 

   762 

   763 .. method:: window.derwin([nlines, ncols,] begin_y, begin_x)

   764 

   765    An abbreviation for "derive window", :meth:`derwin` is the same as calling

   766    :meth:`subwin`, except that *begin_y* and *begin_x* are relative to the origin

   767    of the window, rather than relative to the entire screen.  Returns a window

   768    object for the derived window.

   769 

   770 

   771 .. method:: window.echochar(ch[, attr])

   772 

   773    Add character *ch* with attribute *attr*, and immediately  call :meth:`refresh`

   774    on the window.

   775 

   776 

   777 .. method:: window.enclose(y, x)

   778 

   779    Tests whether the given pair of screen-relative character-cell coordinates are

   780    enclosed by the given window, returning true or false.  It is useful for

   781    determining what subset of the screen windows enclose the location of a mouse

   782    event.

   783 

   784 

   785 .. method:: window.erase()

   786 

   787    Clear the window.

   788 

   789 

   790 .. method:: window.getbegyx()

   791 

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

   793 

   794 

   795 .. method:: window.getch([y, x])

   796 

   797    Get a character. Note that the integer returned does *not* have to be in ASCII

   798    range: function keys, keypad keys and so on return numbers higher than 256. In

   799    no-delay mode, -1 is returned if there is  no input.

   800 

   801 

   802 .. method:: window.getkey([y, x])

   803 

   804    Get a character, returning a string instead of an integer, as :meth:`getch`

   805    does. Function keys, keypad keys and so on return a multibyte string containing

   806    the key name.  In no-delay mode, an exception is raised if there is no input.

   807 

   808 

   809 .. method:: window.getmaxyx()

   810 

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

   812 

   813 

   814 .. method:: window.getparyx()

   815 

   816    Returns the beginning coordinates of this window relative to its parent window

   817    into two integer variables y and x.  Returns ``-1,-1`` if this window has no

   818    parent.

   819 

   820 

   821 .. method:: window.getstr([y, x])

   822 

   823    Read a string from the user, with primitive line editing capacity.

   824 

   825 

   826 .. method:: window.getyx()

   827 

   828    Return a tuple ``(y, x)`` of current cursor position  relative to the window's

   829    upper-left corner.

   830 

   831 

   832 .. method:: window.hline([y, x,] ch, n)

   833 

   834    Display a horizontal line starting at ``(y, x)`` with length *n* consisting of

   835    the character *ch*.

   836 

   837 

   838 .. method:: window.idcok(flag)

   839 

   840    If *flag* is false, curses no longer considers using the hardware insert/delete

   841    character feature of the terminal; if *flag* is true, use of character insertion

   842    and deletion is enabled.  When curses is first initialized, use of character

   843    insert/delete is enabled by default.

   844 

   845 

   846 .. method:: window.idlok(yes)

   847 

   848    If called with *yes* equal to 1, :mod:`curses` will try and use hardware line

   849    editing facilities. Otherwise, line insertion/deletion are disabled.

   850 

   851 

   852 .. method:: window.immedok(flag)

   853 

   854    If *flag* is true, any change in the window image automatically causes the

   855    window to be refreshed; you no longer have to call :meth:`refresh` yourself.

   856    However, it may degrade performance considerably, due to repeated calls to

   857    wrefresh.  This option is disabled by default.

   858 

   859 

   860 .. method:: window.inch([y, x])

   861 

   862    Return the character at the given position in the window. The bottom 8 bits are

   863    the character proper, and upper bits are the attributes.

   864 

   865 

   866 .. method:: window.insch([y, x,] ch[, attr])

   867 

   868    Paint character *ch* at ``(y, x)`` with attributes *attr*, moving the line from

   869    position *x* right by one character.

   870 

   871 

   872 .. method:: window.insdelln(nlines)

   873 

   874    Inserts *nlines* lines into the specified window above the current line.  The

   875    *nlines* bottom lines are lost.  For negative *nlines*, delete *nlines* lines

   876    starting with the one under the cursor, and move the remaining lines up.  The

   877    bottom *nlines* lines are cleared.  The current cursor position remains the

   878    same.

   879 

   880 

   881 .. method:: window.insertln()

   882 

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

   884    line.

   885 

   886 

   887 .. method:: window.insnstr([y, x,] str, n [, attr])

   888 

   889    Insert a character string (as many characters as will fit on the line) before

   890    the character under the cursor, up to *n* characters.   If *n* is zero or

   891    negative, the entire string is inserted. All characters to the right of the

   892    cursor are shifted right, with the rightmost characters on the line being lost.

   893    The cursor position does not change (after moving to *y*, *x*, if specified).

   894 

   895 

   896 .. method:: window.insstr([y, x, ] str [, attr])

   897 

   898    Insert a character string (as many characters as will fit on the line) before

   899    the character under the cursor.  All characters to the right of the cursor are

   900    shifted right, with the rightmost characters on the line being lost.  The cursor

   901    position does not change (after moving to *y*, *x*, if specified).

   902 

   903 

   904 .. method:: window.instr([y, x] [, n])

   905 

   906    Returns a string of characters, extracted from the window starting at the

   907    current cursor position, or at *y*, *x* if specified. Attributes are stripped

   908    from the characters.  If *n* is specified, :meth:`instr` returns return a string

   909    at most *n* characters long (exclusive of the trailing NUL).

   910 

   911 

   912 .. method:: window.is_linetouched(line)

   913 

   914    Returns true if the specified line was modified since the last call to

   915    :meth:`refresh`; otherwise returns false.  Raises a :exc:`curses.error`

   916    exception if *line* is not valid for the given window.

   917 

   918 

   919 .. method:: window.is_wintouched()

   920 

   921    Returns true if the specified window was modified since the last call to

   922    :meth:`refresh`; otherwise returns false.

   923 

   924 

   925 .. method:: window.keypad(yes)

   926 

   927    If *yes* is 1, escape sequences generated by some keys (keypad,  function keys)

   928    will be interpreted by :mod:`curses`. If *yes* is 0, escape sequences will be

   929    left as is in the input stream.

   930 

   931 

   932 .. method:: window.leaveok(yes)

   933 

   934    If *yes* is 1, cursor is left where it is on update, instead of being at "cursor

   935    position."  This reduces cursor movement where possible. If possible the cursor

   936    will be made invisible.

   937 

   938    If *yes* is 0, cursor will always be at "cursor position" after an update.

   939 

   940 

   941 .. method:: window.move(new_y, new_x)

   942 

   943    Move cursor to ``(new_y, new_x)``.

   944 

   945 

   946 .. method:: window.mvderwin(y, x)

   947 

   948    Moves the window inside its parent window.  The screen-relative parameters of

   949    the window are not changed.  This routine is used to display different parts of

   950    the parent window at the same physical position on the screen.

   951 

   952 

   953 .. method:: window.mvwin(new_y, new_x)

   954 

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

   956 

   957 

   958 .. method:: window.nodelay(yes)

   959 

   960    If *yes* is ``1``, :meth:`getch` will be non-blocking.

   961 

   962 

   963 .. method:: window.notimeout(yes)

   964 

   965    If *yes* is ``1``, escape sequences will not be timed out.

   966 

   967    If *yes* is ``0``, after a few milliseconds, an escape sequence will not be

   968    interpreted, and will be left in the input stream as is.

   969 

   970 

   971 .. method:: window.noutrefresh()

   972 

   973    Mark for refresh but wait.  This function updates the data structure

   974    representing the desired state of the window, but does not force an update of

   975    the physical screen.  To accomplish that, call  :func:`doupdate`.

   976 

   977 

   978 .. method:: window.overlay(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])

   979 

   980    Overlay the window on top of *destwin*. The windows need not be the same size,

   981    only the overlapping region is copied. This copy is non-destructive, which means

   982    that the current background character does not overwrite the old contents of

   983    *destwin*.

   984 

   985    To get fine-grained control over the copied region, the second form of

   986    :meth:`overlay` can be used. *sminrow* and *smincol* are the upper-left

   987    coordinates of the source window, and the other variables mark a rectangle in

   988    the destination window.

   989 

   990 

   991 .. method:: window.overwrite(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])

   992 

   993    Overwrite the window on top of *destwin*. The windows need not be the same size,

   994    in which case only the overlapping region is copied. This copy is destructive,

   995    which means that the current background character overwrites the old contents of

   996    *destwin*.

   997 

   998    To get fine-grained control over the copied region, the second form of

   999    :meth:`overwrite` can be used. *sminrow* and *smincol* are the upper-left

  1000    coordinates of the source window, the other variables mark a rectangle in the

  1001    destination window.

  1002 

  1003 

  1004 .. method:: window.putwin(file)

  1005 

  1006    Writes all data associated with the window into the provided file object.  This

  1007    information can be later retrieved using the :func:`getwin` function.

  1008 

  1009 

  1010 .. method:: window.redrawln(beg, num)

  1011 

  1012    Indicates that the *num* screen lines, starting at line *beg*, are corrupted and

  1013    should be completely redrawn on the next :meth:`refresh` call.

  1014 

  1015 

  1016 .. method:: window.redrawwin()

  1017 

  1018    Touches the entire window, causing it to be completely redrawn on the next

  1019    :meth:`refresh` call.

  1020 

  1021 

  1022 .. method:: window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol])

  1023 

  1024    Update the display immediately (sync actual screen with previous

  1025    drawing/deleting methods).

  1026 

  1027    The 6 optional arguments can only be specified when the window is a pad created

  1028    with :func:`newpad`.  The additional parameters are needed to indicate what part

  1029    of the pad and screen are involved. *pminrow* and *pmincol* specify the upper

  1030    left-hand corner of the rectangle to be displayed in the pad.  *sminrow*,

  1031    *smincol*, *smaxrow*, and *smaxcol* specify the edges of the rectangle to be

  1032    displayed on the screen.  The lower right-hand corner of the rectangle to be

  1033    displayed in the pad is calculated from the screen coordinates, since the

  1034    rectangles must be the same size.  Both rectangles must be entirely contained

  1035    within their respective structures.  Negative values of *pminrow*, *pmincol*,

  1036    *sminrow*, or *smincol* are treated as if they were zero.

  1037 

  1038 

  1039 .. method:: window.scroll([lines=1])

  1040 

  1041    Scroll the screen or scrolling region upward by *lines* lines.

  1042 

  1043 

  1044 .. method:: window.scrollok(flag)

  1045 

  1046    Controls what happens when the cursor of a window is moved off the edge of the

  1047    window or scrolling region, either as a result of a newline action on the bottom

  1048    line, or typing the last character of the last line.  If *flag* is false, the

  1049    cursor is left on the bottom line.  If *flag* is true, the window is scrolled up

  1050    one line.  Note that in order to get the physical scrolling effect on the

  1051    terminal, it is also necessary to call :meth:`idlok`.

  1052 

  1053 

  1054 .. method:: window.setscrreg(top, bottom)

  1055 

  1056    Set the scrolling region from line *top* to line *bottom*. All scrolling actions

  1057    will take place in this region.

  1058 

  1059 

  1060 .. method:: window.standend()

  1061 

  1062    Turn off the standout attribute.  On some terminals this has the side effect of

  1063    turning off all attributes.

  1064 

  1065 

  1066 .. method:: window.standout()

  1067 

  1068    Turn on attribute *A_STANDOUT*.

  1069 

  1070 

  1071 .. method:: window.subpad([nlines, ncols,] begin_y, begin_x)

  1072 

  1073    Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and

  1074    whose width/height is *ncols*/*nlines*.

  1075 

  1076 

  1077 .. method:: window.subwin([nlines, ncols,] begin_y, begin_x)

  1078 

  1079    Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and

  1080    whose width/height is *ncols*/*nlines*.

  1081 

  1082    By default, the sub-window will extend from the specified position to the lower

  1083    right corner of the window.

  1084 

  1085 

  1086 .. method:: window.syncdown()

  1087 

  1088    Touches each location in the window that has been touched in any of its ancestor

  1089    windows.  This routine is called by :meth:`refresh`, so it should almost never

  1090    be necessary to call it manually.

  1091 

  1092 

  1093 .. method:: window.syncok(flag)

  1094 

  1095    If called with *flag* set to true, then :meth:`syncup` is called automatically

  1096    whenever there is a change in the window.

  1097 

  1098 

  1099 .. method:: window.syncup()

  1100 

  1101    Touches all locations in ancestors of the window that have been changed in  the

  1102    window.

  1103 

  1104 

  1105 .. method:: window.timeout(delay)

  1106 

  1107    Sets blocking or non-blocking read behavior for the window.  If *delay* is

  1108    negative, blocking read is used (which will wait indefinitely for input).  If

  1109    *delay* is zero, then non-blocking read is used, and -1 will be returned by

  1110    :meth:`getch` if no input is waiting.  If *delay* is positive, then

  1111    :meth:`getch` will block for *delay* milliseconds, and return -1 if there is

  1112    still no input at the end of that time.

  1113 

  1114 

  1115 .. method:: window.touchline(start, count[, changed])

  1116 

  1117    Pretend *count* lines have been changed, starting with line *start*.  If

  1118    *changed* is supplied, it specifies whether the affected lines are marked as

  1119    having been changed (*changed*\ =1) or unchanged (*changed*\ =0).

  1120 

  1121 

  1122 .. method:: window.touchwin()

  1123 

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

  1125    optimizations.

  1126 

  1127 

  1128 .. method:: window.untouchwin()

  1129 

  1130    Marks all lines in  the  window  as unchanged since the last call to

  1131    :meth:`refresh`.

  1132 

  1133 

  1134 .. method:: window.vline([y, x,] ch, n)

  1135