From bc0841336a224ce721526c5dac9ef7f939f4f27f Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Mon, 29 Jun 2026 16:15:02 +0300 Subject: [PATCH] gh-152584: Reorganize the curses documentation into topic subsections (GH-152583) Reorganize the curses documentation into topic subsections Group the module-level functions, window methods and constants by topic instead of presenting them as flat alphabetical lists, following the categories used by the ncurses manual pages. Co-authored-by: Claude Opus 4.8 --- Doc/library/curses.rst | 2188 +++++++++++++++++++--------------------- 1 file changed, 1062 insertions(+), 1126 deletions(-) diff --git a/Doc/library/curses.rst b/Doc/library/curses.rst index 86be23c93101..76967b88482c 100644 --- a/Doc/library/curses.rst +++ b/Doc/library/curses.rst @@ -68,94 +68,81 @@ The module :mod:`!curses` defines the following exception: The module :mod:`!curses` defines the following functions: -.. function:: assume_default_colors(fg, bg, /) - - Allow use of default values for colors on terminals supporting this feature. - Use this to support transparency in your application. - - * Assign terminal default foreground/background colors to color number ``-1``. - So ``init_pair(x, COLOR_RED, -1)`` will initialize pair *x* as red - on default background and ``init_pair(x, -1, COLOR_BLUE)`` will - initialize pair *x* as default foreground on blue. - - * Change the definition of the color-pair ``0`` to ``(fg, bg)``. - - This is an ncurses extension. - - .. versionadded:: 3.14 - +Initialization and termination +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -.. function:: alloc_pair(fg, bg) - - Allocate a color pair for foreground color *fg* and background color *bg*, - and return its number. If a color pair for the same combination of colors - already exists, return its number. Otherwise allocate a new color pair and - return its number. - - This function is only available if Python was built against a wide-character - version of the underlying curses library with extended-color support (see - :func:`has_extended_color_support`). +.. function:: initscr() - .. versionadded:: next + Initialize the library. Return a :ref:`window ` object + which represents the whole screen. + .. note:: -.. function:: baudrate() + If there is an error opening the terminal, the underlying curses library may + cause the interpreter to exit. - 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. +.. function:: endwin() + De-initialize the library, and return terminal to normal status. -.. function:: beep() +.. function:: isendwin() - Emit a short attention sound. + Return ``True`` if :func:`endwin` has been called (that is, the curses library has + been deinitialized). +.. function:: newterm(type=None, fd=None, infd=None, /) -.. function:: can_change_color() + Initialize a new terminal in addition to the one initialized by + :func:`initscr`, + and return a :ref:`screen ` for it. + This allows a program to drive more than one terminal. - Return ``True`` or ``False``, depending on whether the programmer can change the colors - displayed by the terminal. + *type* is the terminal name, as in :func:`setupterm`; + if ``None``, the value of the :envvar:`TERM` environment variable is used. + *fd* and *infd* are the output and input files for the terminal: + either a file object or a file descriptor. + They default to :data:`sys.stdout` and :data:`sys.stdin`. + The new screen becomes the current one. + Use :func:`set_term` to switch between screens. -.. function:: cbreak() + .. versionadded:: next - 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 :func:`raw` then :func:`cbreak` leaves the terminal in cbreak mode. +.. function:: new_prescr() + Return a new :ref:`screen ` + that can be used to call functions that affect global state + before :func:`initscr` or :func:`newterm` is called. -.. function:: color_content(color_number) + Availability: if the underlying curses library provides ``new_prescr()``. - 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). Raise an - exception if the color is not supported. + .. versionadded:: next +.. function:: set_term(screen, /) -.. function:: color_pair(pair_number) + Make *screen*, a :ref:`screen ` returned by + :func:`newterm`, the current terminal, + and return the previously current screen. + Returns ``None`` if the previous screen was the one created by + :func:`initscr`. - Return the attribute value for displaying text in the specified color pair. - Only color pairs that fit in the color-pair field of the returned value can - be represented (usually the first 256); a larger *pair_number* raises - :exc:`OverflowError` rather than being silently masked to a different pair. - Use :meth:`~window.color_set` or :meth:`~window.attr_set` to display higher - pairs. This attribute value can be combined with :const:`A_STANDOUT`, - :const:`A_REVERSE`, and the other :const:`!A_\*` attributes. - :func:`pair_number` is the counterpart to this function. + .. versionadded:: next +.. function:: wrapper(func, /, *args, **kwargs) -.. function:: curs_set(visibility) + 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 :func:`!wrapper`. Before calling *func*, :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. - 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. +Terminal mode control +~~~~~~~~~~~~~~~~~~~~~ .. function:: def_prog_mode() @@ -164,7 +151,6 @@ The module :mod:`!curses` defines the following functions: program is not in curses.) Subsequent calls to :func:`reset_prog_mode` will restore this mode. - .. function:: def_shell_mode() Save the current terminal mode as the "shell" mode, the mode when the running @@ -172,11 +158,43 @@ The module :mod:`!curses` defines the following functions: program is using curses capabilities.) Subsequent calls to :func:`reset_shell_mode` will restore this mode. +.. function:: reset_prog_mode() -.. function:: delay_output(ms) + Restore the terminal to "program" mode, as previously saved by + :func:`def_prog_mode`. - Insert an *ms* millisecond pause in output. +.. function:: reset_shell_mode() + + Restore the terminal to "shell" mode, as previously saved by + :func:`def_shell_mode`. + +.. function:: savetty() + + Save the current state of the terminal modes in a buffer, usable by + :func:`resetty`. + +.. function:: resetty() + Restore the state of the terminal modes to what it was at the last call to + :func:`savetty`. + +.. function:: curs_set(visibility) + + 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. + +.. function:: getsyx() + + Return the current coordinates of the virtual screen cursor as a tuple + ``(y, x)``. If :meth:`leaveok ` is currently ``True``, then return ``(-1, -1)``. + +.. function:: setsyx(y, x) + + Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both ``-1``, then + :meth:`leaveok ` is set ``True``. .. function:: doupdate() @@ -193,165 +211,186 @@ The module :mod:`!curses` defines the following functions: followed by a single :func:`!doupdate`. -.. function:: echo() +Input options +~~~~~~~~~~~~~ - Enter echo mode. In echo mode, each character input is echoed to the screen as - it is entered. +.. function:: cbreak() + Enter cbreak mode. In cbreak mode (sometimes called "rare" mode) normal tty + line buffering is turned off and characters are available to be read one by one. + However, unlike raw mode, special characters (interrupt, quit, suspend, and flow + control) retain their effects on the tty driver and calling program. Calling + first :func:`raw` then :func:`cbreak` leaves the terminal in cbreak mode. -.. function:: endwin() +.. function:: nocbreak() - De-initialize the library, and return terminal to normal status. + Leave cbreak mode. Return to normal "cooked" mode with line buffering. +.. function:: echo() -.. function:: erasechar() + Enter echo mode. In echo mode, each character input is echoed to the screen as + it is entered. - Return the user's current erase character as a raw byte, a :class:`bytes` - object of length 1. See also :func:`erasewchar`. +.. function:: noecho() + Leave echo mode. Echoing of input characters is turned off. -.. function:: erasewchar() +.. function:: raw() - Return the user's current erase character as a one-character :class:`str`. - 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. + 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. - .. versionadded:: next +.. function:: noraw() + Leave raw mode. Return to normal "cooked" mode with line buffering. -.. function:: filter() +.. function:: halfdelay(tenths) - The :func:`.filter` routine, if used, must be called before :func:`initscr` is - called. The effect is that, during the initialization, :envvar:`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. + 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 + :func:`nocbreak` to leave half-delay mode. +.. function:: meta(flag) -.. function:: nofilter() + If *flag* is ``True``, allow 8-bit characters to be input. If + *flag* is ``False``, allow only 7-bit chars. - Undo the effect of a previous :func:`.filter` call. - Like :func:`.filter`, it must be called before :func:`initscr` (or - :func:`newterm`) so that the next initialization uses the full screen - again. +.. function:: nl(flag=True) - Availability: if the underlying curses library provides ``nofilter()``. + 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. - .. versionadded:: next + If *flag* is ``False``, the effect is the same as calling :func:`nonl`. +.. function:: nonl() -.. function:: find_pair(fg, bg) + 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. - Return the number of a color pair for foreground color *fg* and background - color *bg*, or ``-1`` if no color pair for this combination of colors has - been allocated. +.. function:: intrflush(flag) - This function is only available if Python was built against a wide-character - version of the underlying curses library with extended-color support (see - :func:`has_extended_color_support`). + If *flag* is ``True``, pressing an interrupt key (interrupt, break, or quit) + will flush all output in the terminal driver queue. If *flag* is ``False``, + no flushing is done. - .. versionadded:: next +.. function:: qiflush([flag]) + If *flag* is ``False``, the effect is the same as calling :func:`noqiflush`. If + *flag* is ``True``, or no argument is provided, the queues will be flushed when + these control characters are read. -.. function:: flash() +.. function:: noqiflush() - 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 :func:`beep`. + When the :func:`!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 :func:`!noqiflush` in a signal handler if you want output to + continue as though the interrupt had not occurred, after the handler exits. +.. function:: typeahead(fd) -.. function:: flushinp() + Specify that the file descriptor *fd* be used for typeahead checking. If *fd* + is ``-1``, then no typeahead checking is done. - 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. + 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. +.. function:: is_cbreak() -.. function:: free_pair(pair_number) + Return ``True`` if cbreak mode (see :func:`cbreak`) is enabled, + ``False`` otherwise. + Availability: ncurses 6.5 or later. - Free the color pair *pair_number*, which must have been allocated by - :func:`alloc_pair`. The pair must not be in use. + .. versionadded:: next - This function is only available if Python was built against a wide-character - version of the underlying curses library with extended-color support (see - :func:`has_extended_color_support`). +.. function:: is_echo() - .. versionadded:: next + Return ``True`` if echo mode (see :func:`echo`) is enabled, + ``False`` otherwise. + Availability: ncurses 6.5 or later. + .. versionadded:: next -.. function:: getmouse() +.. function:: is_nl() - After :meth:`~window.getch` returns :const:`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: - :const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:`BUTTONn_CLICKED`, - :const:`BUTTONn_DOUBLE_CLICKED`, :const:`BUTTONn_TRIPLE_CLICKED`, - :const:`BUTTON_SHIFT`, :const:`BUTTON_CTRL`, :const:`BUTTON_ALT`. + Return ``True`` if nl mode (see :func:`nl`) is enabled, ``False`` otherwise. + Availability: ncurses 6.5 or later. - .. versionchanged:: 3.10 - The ``BUTTON5_*`` constants are now exposed if they are provided by the - underlying curses library. + .. versionadded:: next +.. function:: is_raw() -.. function:: getsyx() + Return ``True`` if raw mode (see :func:`raw`) is enabled, + ``False`` otherwise. + Availability: ncurses 6.5 or later. - Return the current coordinates of the virtual screen cursor as a tuple - ``(y, x)``. If :meth:`leaveok ` is currently ``True``, then return ``(-1, -1)``. + .. versionadded:: next -.. function:: getwin(file) +Keyboard input +~~~~~~~~~~~~~~ - Read window-related data stored in the file by an earlier :meth:`window.putwin` call. - The routine then creates and initializes a new window using that data, returning - the new window object. The *file* argument must be a file object opened for - reading in binary mode. +.. function:: ungetch(ch) + Push *ch* so the next :meth:`~window.getch` or :meth:`~window.get_wch` will + return it. -.. function:: has_colors() + *ch* may be an integer (a key code or character code), a byte, or a string of + length 1. A one-character string is pushed like :func:`unget_wch`; on a + narrow build it must encode to a single byte. - Return ``True`` if the terminal can display colors; otherwise, return ``False``. + .. note:: -.. function:: has_extended_color_support() + Only one *ch* can be pushed before :meth:`!getch` is called. - 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 (for example, xterm-256color). + .. versionchanged:: next + A one-character string argument is no longer required to encode to a single + byte, except on a narrow build. - Extended color support requires ncurses version 6.1 or later. +.. function:: unget_wch(ch) - .. versionadded:: 3.10 + Push *ch* so the next :meth:`~window.get_wch` will return it. -.. function:: has_ic() + .. note:: - 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. + Only one *ch* can be pushed before :meth:`!get_wch` is called. + .. versionadded:: 3.3 -.. function:: has_il() + .. versionchanged:: next + Also available on a narrow build, where *ch* must encode to a single byte + (an 8-bit locale). - 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. +.. function:: flushinp() + Flush all input buffers. This throws away any typeahead that has been typed + by the user and has not yet been processed by the program. .. function:: has_key(ch) Take a key value *ch*, and return ``True`` if the current terminal type recognizes a key with that value. +.. function:: keyname(k) -.. function:: has_mouse() - - Return ``True`` if the mouse driver has been successfully initialized. - - .. versionadded:: next + 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. + Raise a :exc:`ValueError` if *k* is negative. .. function:: define_key(definition, keycode) @@ -365,7 +404,6 @@ The module :mod:`!curses` defines the following functions: .. versionadded:: next - .. function:: key_defined(definition) Return the key code bound to the escape sequence *definition*, a string, @@ -374,7 +412,6 @@ The module :mod:`!curses` defines the following functions: .. versionadded:: next - .. function:: keyok(keycode, enable) Enable (if *enable* is true) or disable (otherwise) interpretation of the @@ -384,14 +421,86 @@ The module :mod:`!curses` defines the following functions: .. versionadded:: next -.. function:: halfdelay(tenths) +Mouse +~~~~~ - 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 - :func:`nocbreak` to leave half-delay mode. +.. function:: getmouse() + + After :meth:`~window.getch` returns :const:`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: + :const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:`BUTTONn_CLICKED`, + :const:`BUTTONn_DOUBLE_CLICKED`, :const:`BUTTONn_TRIPLE_CLICKED`, + :const:`BUTTON_SHIFT`, :const:`BUTTON_CTRL`, :const:`BUTTON_ALT`. + + .. versionchanged:: 3.10 + The ``BUTTON5_*`` constants are now exposed if they are provided by the + underlying curses library. + +.. function:: ungetmouse(id, x, y, z, bstate) + + Push a :const:`KEY_MOUSE` event onto the input queue, associating the given + state data with it. + +.. function:: mousemask(mousemask) + + 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 mouse event mask. If this function is never called, no mouse + events are ever reported. + +.. function:: mouseinterval(interval) + + 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 166 milliseconds, or one sixth of a second. + Use a negative *interval* to obtain the interval value without changing it. + +.. function:: has_mouse() + + Return ``True`` if the mouse driver has been successfully initialized. + + .. versionadded:: next + + +Color +~~~~~ + +.. function:: start_color() + + Must be called if the programmer wants to use colors, and before any other color + manipulation routine is called. It is good practice to call this routine right + after :func:`initscr`. + + :func:`start_color` initializes eight basic colors (black, red, green, yellow, + blue, magenta, cyan, and white), and two global variables in the :mod:`!curses` + module, :const:`COLORS` and :const:`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. + +.. function:: has_colors() + + Return ``True`` if the terminal can display colors; otherwise, return ``False``. + +.. function:: 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 (for example, xterm-256color). + + Extended color support requires ncurses version 6.1 or later. + + .. versionadded:: 3.10 + +.. function:: can_change_color() + Return ``True`` or ``False``, depending on whether the programmer can change the colors + displayed by the terminal. .. function:: init_color(color_number, r, g, b) @@ -403,6 +512,13 @@ The module :mod:`!curses` defines the following functions: screen immediately change to the new definition. This function is a no-op on most terminals; it is active only if :func:`can_change_color` returns ``True``. +.. function:: color_content(color_number) + + 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). Raise an + exception if the color is not supported. .. function:: init_pair(pair_number, fg, bg) @@ -418,133 +534,106 @@ The module :mod:`!curses` defines the following functions: refreshed and all occurrences of that color-pair are changed to the new definition. +.. function:: pair_content(pair_number) -.. function:: initscr() - - Initialize the library. Return a :ref:`window ` object - which represents the whole screen. - - .. note:: + 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``. - If there is an error opening the terminal, the underlying curses library may - cause the interpreter to exit. +.. function:: color_pair(pair_number) + Return the attribute value for displaying text in the specified color pair. + Only color pairs that fit in the color-pair field of the returned value can + be represented (usually the first 256); a larger *pair_number* raises + :exc:`OverflowError` rather than being silently masked to a different pair. + Use :meth:`~window.color_set` or :meth:`~window.attr_set` to display higher + pairs. This attribute value can be combined with :const:`A_STANDOUT`, + :const:`A_REVERSE`, and the other :const:`!A_\*` attributes. + :func:`pair_number` is the counterpart to this function. -.. function:: intrflush(flag) +.. function:: pair_number(attr) - If *flag* is ``True``, pressing an interrupt key (interrupt, break, or quit) - will flush all output in the terminal driver queue. If *flag* is ``False``, - no flushing is done. + Return the number of the color-pair set by the attribute value *attr*. + :func:`color_pair` is the counterpart to this function. +.. function:: use_default_colors() -.. function:: is_cbreak() + Equivalent to ``assume_default_colors(-1, -1)``. - Return ``True`` if cbreak mode (see :func:`cbreak`) is enabled, - ``False`` otherwise. - Availability: ncurses 6.5 or later. +.. function:: assume_default_colors(fg, bg, /) - .. versionadded:: next + Allow use of default values for colors on terminals supporting this feature. + Use this to support transparency in your application. + * Assign terminal default foreground/background colors to color number ``-1``. + So ``init_pair(x, COLOR_RED, -1)`` will initialize pair *x* as red + on default background and ``init_pair(x, -1, COLOR_BLUE)`` will + initialize pair *x* as default foreground on blue. -.. function:: is_echo() + * Change the definition of the color-pair ``0`` to ``(fg, bg)``. - Return ``True`` if echo mode (see :func:`echo`) is enabled, - ``False`` otherwise. - Availability: ncurses 6.5 or later. + This is an ncurses extension. - .. versionadded:: next + .. versionadded:: 3.14 +.. function:: alloc_pair(fg, bg) -.. function:: is_nl() + Allocate a color pair for foreground color *fg* and background color *bg*, + and return its number. If a color pair for the same combination of colors + already exists, return its number. Otherwise allocate a new color pair and + return its number. - Return ``True`` if nl mode (see :func:`nl`) is enabled, ``False`` otherwise. - Availability: ncurses 6.5 or later. + This function is only available if Python was built against a wide-character + version of the underlying curses library with extended-color support (see + :func:`has_extended_color_support`). .. versionadded:: next +.. function:: free_pair(pair_number) -.. function:: is_raw() + Free the color pair *pair_number*, which must have been allocated by + :func:`alloc_pair`. The pair must not be in use. - Return ``True`` if raw mode (see :func:`raw`) is enabled, - ``False`` otherwise. - Availability: ncurses 6.5 or later. + This function is only available if Python was built against a wide-character + version of the underlying curses library with extended-color support (see + :func:`has_extended_color_support`). .. versionadded:: next +.. function:: find_pair(fg, bg) -.. function:: is_term_resized(nlines, ncols) - - Return ``True`` if :func:`resize_term` would modify the window structure, - ``False`` otherwise. - - -.. function:: isendwin() - - Return ``True`` if :func:`endwin` has been called (that is, the curses library has - been deinitialized). - - -.. function:: keyname(k) - - 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. - - Raise a :exc:`ValueError` if *k* is negative. - - -.. function:: killchar() - - Return the user's current line kill character as a raw byte, a :class:`bytes` - object of length 1. See also :func:`killwchar`. - - -.. function:: killwchar() + Return the number of a color pair for foreground color *fg* and background + color *bg*, or ``-1`` if no color pair for this combination of colors has + been allocated. - Return the user's current line kill character as a one-character :class:`str`. - 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. + This function is only available if Python was built against a wide-character + version of the underlying curses library with extended-color support (see + :func:`has_extended_color_support`). .. versionadded:: next +.. function:: reset_color_pairs() -.. function:: longname() - - 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 :func:`initscr`. - - -.. function:: meta(flag) - - If *flag* is ``True``, allow 8-bit characters to be input. If - *flag* is ``False``, allow only 7-bit chars. - - -.. function:: mouseinterval(interval) - - 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 166 milliseconds, or one sixth of a second. - Use a negative *interval* to obtain the interval value without changing it. + Discard all color-pair definitions, releasing the color pairs allocated by + :func:`init_pair` and :func:`alloc_pair`. + This function is only available if Python was built against a wide-character + version of the underlying curses library with extended-color support (see + :func:`has_extended_color_support`). -.. function:: mousemask(mousemask) + .. versionadded:: next - 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 mouse event mask. If this function is never called, no mouse - events are ever reported. +Windows and pads +~~~~~~~~~~~~~~~~ -.. function:: napms(ms) +.. function:: newwin(nlines, ncols) + newwin(nlines, ncols, begin_y, begin_x) - Sleep for *ms* milliseconds. + Return a new :ref:`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. .. function:: newpad(nlines, ncols) @@ -564,152 +653,147 @@ The module :mod:`!curses` defines the following functions: is to be displayed. -.. function:: newwin(nlines, ncols) - newwin(nlines, ncols, begin_y, begin_x) - - Return a new :ref:`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. - +Saving and restoring +~~~~~~~~~~~~~~~~~~~~ -.. function:: newterm(type=None, fd=None, infd=None, /) +.. function:: getwin(file) - Initialize a new terminal in addition to the one initialized by - :func:`initscr`, - and return a :ref:`screen ` for it. - This allows a program to drive more than one terminal. + Read window-related data stored in the file by an earlier :meth:`window.putwin` call. + The routine then creates and initializes a new window using that data, returning + the new window object. The *file* argument must be a file object opened for + reading in binary mode. - *type* is the terminal name, as in :func:`setupterm`; - if ``None``, the value of the :envvar:`TERM` environment variable is used. - *fd* and *infd* are the output and input files for the terminal: - either a file object or a file descriptor. - They default to :data:`sys.stdout` and :data:`sys.stdin`. +.. function:: scr_dump(filename) - The new screen becomes the current one. - Use :func:`set_term` to switch between screens. + Write the current contents of the virtual screen to *filename*, which may be + a string or a :term:`path-like object`. The file can later be read by + :func:`scr_restore`, :func:`scr_init` or :func:`scr_set`. This is the + whole-screen counterpart of :meth:`window.putwin`. .. versionadded:: next +.. function:: scr_restore(filename) -.. function:: new_prescr() - - Return a new :ref:`screen ` - that can be used to call functions that affect global state - before :func:`initscr` or :func:`newterm` is called. - - Availability: if the underlying curses library provides ``new_prescr()``. + Set the virtual screen to the contents of *filename*, which must have been + written by :func:`scr_dump`. The next call to :func:`doupdate` or + :meth:`window.refresh` restores the screen to those contents. .. versionadded:: next +.. function:: scr_init(filename) -.. function:: nl(flag=True) - - 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. - - If *flag* is ``False``, the effect is the same as calling :func:`nonl`. - - -.. function:: nocbreak() - - Leave cbreak mode. Return to normal "cooked" mode with line buffering. - - -.. function:: noecho() + Initialize the assumed contents of the terminal from *filename*, which must + have been written by :func:`scr_dump`. Use it when the terminal already + displays those contents, for example after another program has drawn the + screen, so that curses does not redraw what is already there. - Leave echo mode. Echoing of input characters is turned off. + .. versionadded:: next +.. function:: scr_set(filename) -.. function:: nonl() + Use *filename*, which must have been written by :func:`scr_dump`, as both + the virtual screen and the assumed terminal contents. This combines the + effects of :func:`scr_restore` and :func:`scr_init`. - 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. + .. versionadded:: next -.. function:: noqiflush() +Querying the terminal +~~~~~~~~~~~~~~~~~~~~~ - When the :func:`!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 :func:`!noqiflush` in a signal handler if you want output to - continue as though the interrupt had not occurred, after the handler exits. +.. function:: baudrate() + 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. -.. function:: noraw() +.. function:: erasechar() - Leave raw mode. Return to normal "cooked" mode with line buffering. + Return the user's current erase character as a raw byte, a :class:`bytes` + object of length 1. See also :func:`erasewchar`. +.. function:: erasewchar() -.. function:: pair_content(pair_number) + Return the user's current erase character as a one-character :class:`str`. + 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. - 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``. + .. versionadded:: next +.. function:: killchar() -.. function:: pair_number(attr) + Return the user's current line kill character as a raw byte, a :class:`bytes` + object of length 1. See also :func:`killwchar`. - Return the number of the color-pair set by the attribute value *attr*. - :func:`color_pair` is the counterpart to this function. +.. function:: killwchar() + Return the user's current line kill character as a one-character :class:`str`. + 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. -.. function:: putp(str) + .. versionadded:: next - Equivalent to ``tputs(str, 1, putchar)``; emit the value of a specified - terminfo capability for the current terminal. Note that the output of :func:`putp` - always goes to standard output. +.. function:: termname() - :func:`setupterm` (or :func:`initscr`) must be called first. + Return the value of the environment variable :envvar:`TERM`, as a bytes object, + truncated to 14 characters. +.. function:: longname() -.. function:: qiflush([flag]) + 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 :func:`initscr`. - If *flag* is ``False``, the effect is the same as calling :func:`noqiflush`. If - *flag* is ``True``, or no argument is provided, the queues will be flushed when - these control characters are read. +.. function:: termattrs() + 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. -.. function:: raw() +.. function:: term_attrs() - 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. + Like :func:`termattrs`, but return the attributes as :ref:`WA_* + ` values rather than ``A_*`` values. + .. versionadded:: next -.. function:: reset_color_pairs() +.. function:: has_ic() - Discard all color-pair definitions, releasing the color pairs allocated by - :func:`init_pair` and :func:`alloc_pair`. + 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. - This function is only available if Python was built against a wide-character - version of the underlying curses library with extended-color support (see - :func:`has_extended_color_support`). +.. function:: has_il() - .. versionadded:: next + 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. -.. function:: reset_prog_mode() +Bell and screen flash +~~~~~~~~~~~~~~~~~~~~~ - Restore the terminal to "program" mode, as previously saved by - :func:`def_prog_mode`. +.. function:: beep() + Emit a short attention sound. -.. function:: reset_shell_mode() +.. function:: flash() - Restore the terminal to "shell" mode, as previously saved by - :func:`def_shell_mode`. + 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 :func:`beep`. -.. function:: resetty() +Terminal resizing +~~~~~~~~~~~~~~~~~ - Restore the state of the terminal modes to what it was at the last call to - :func:`savetty`. +.. function:: resizeterm(nlines, ncols) + 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). .. function:: resize_term(nlines, ncols) @@ -720,96 +804,21 @@ The module :mod:`!curses` defines the following functions: windows. However, due to the calling convention of pads, it is not possible to resize these without additional interaction with the application. +.. function:: is_term_resized(nlines, ncols) -.. function:: resizeterm(nlines, ncols) + Return ``True`` if :func:`resize_term` would modify the window structure, + ``False`` otherwise. - 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). - - -.. function:: savetty() - - Save the current state of the terminal modes in a buffer, usable by - :func:`resetty`. - -.. function:: scr_dump(filename) - - Write the current contents of the virtual screen to *filename*, which may be - a string or a :term:`path-like object`. The file can later be read by - :func:`scr_restore`, :func:`scr_init` or :func:`scr_set`. This is the - whole-screen counterpart of :meth:`window.putwin`. - - .. versionadded:: next - -.. function:: scr_restore(filename) - - Set the virtual screen to the contents of *filename*, which must have been - written by :func:`scr_dump`. The next call to :func:`doupdate` or - :meth:`window.refresh` restores the screen to those contents. - - .. versionadded:: next - -.. function:: scr_init(filename) - - Initialize the assumed contents of the terminal from *filename*, which must - have been written by :func:`scr_dump`. Use it when the terminal already - displays those contents, for example after another program has drawn the - screen, so that curses does not redraw what is already there. - - .. versionadded:: next - -.. function:: scr_set(filename) - - Use *filename*, which must have been written by :func:`scr_dump`, as both - the virtual screen and the assumed terminal contents. This combines the - effects of :func:`scr_restore` and :func:`scr_init`. - - .. versionadded:: next - -.. function:: get_escdelay() - - Retrieves the value set by :func:`set_escdelay`. - - .. versionadded:: 3.9 - -.. function:: set_escdelay(ms) - - 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. - - .. versionadded:: 3.9 - -.. function:: get_tabsize() - - Retrieves the value set by :func:`set_tabsize`. - - .. versionadded:: 3.9 - -.. function:: set_tabsize(size) - - 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. - - .. versionadded:: 3.9 - - -.. function:: set_term(screen, /) - - Make *screen*, a :ref:`screen ` returned by - :func:`newterm`, the current terminal, - and return the previously current screen. - Returns ``None`` if the previous screen was the one created by - :func:`initscr`. +.. function:: update_lines_cols() - .. versionadded:: next + Update the :const:`LINES` and :const:`COLS` module variables. + Useful for detecting manual screen resize. -.. function:: setsyx(y, x) + .. versionadded:: 3.5 - Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both ``-1``, then - :meth:`leaveok ` is set ``True``. +Terminfo database +~~~~~~~~~~~~~~~~~ .. function:: setupterm(term=None, fd=-1) @@ -823,41 +832,6 @@ The module :mod:`!curses` defines the following functions: terminfo database entry could not be read. If the terminal has already been initialized, this function has no effect. - -.. function:: start_color() - - Must be called if the programmer wants to use colors, and before any other color - manipulation routine is called. It is good practice to call this routine right - after :func:`initscr`. - - :func:`start_color` initializes eight basic colors (black, red, green, yellow, - blue, magenta, cyan, and white), and two global variables in the :mod:`!curses` - module, :const:`COLORS` and :const:`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. - - -.. function:: termattrs() - - 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. - - -.. function:: term_attrs() - - Like :func:`termattrs`, but return the attributes as :ref:`WA_* - ` values rather than ``A_*`` values. - - .. versionadded:: next - - -.. function:: termname() - - Return the value of the environment variable :envvar:`TERM`, as a bytes object, - truncated to 14 characters. - - .. function:: tigetflag(capname) Return the value of the Boolean capability corresponding to the terminfo @@ -867,7 +841,6 @@ The module :mod:`!curses` defines the following functions: :func:`setupterm` (or :func:`initscr`) must be called first. - .. function:: tigetnum(capname) Return the value of the numeric capability corresponding to the terminfo @@ -877,7 +850,6 @@ The module :mod:`!curses` defines the following functions: :func:`setupterm` (or :func:`initscr`) must be called first. - .. function:: tigetstr(capname) Return the value of the string capability corresponding to the terminfo @@ -887,7 +859,6 @@ The module :mod:`!curses` defines the following functions: :func:`setupterm` (or :func:`initscr`) must be called first. - .. function:: tparm(str[, ...]) Instantiate the bytes object *str* with the supplied parameters, where *str* should @@ -897,18 +868,17 @@ The module :mod:`!curses` defines the following functions: :func:`setupterm` (or :func:`initscr`) must be called first. +.. function:: putp(str) -.. function:: typeahead(fd) + Equivalent to ``tputs(str, 1, putchar)``; emit the value of a specified + terminfo capability for the current terminal. Note that the output of :func:`putp` + always goes to standard output. - Specify that the file descriptor *fd* be used for typeahead checking. If *fd* - is ``-1``, then no typeahead checking is done. + :func:`setupterm` (or :func:`initscr`) must be called first. - 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. +Utilities +~~~~~~~~~ .. function:: unctrl(ch) @@ -916,7 +886,6 @@ The module :mod:`!curses` defines the following functions: *ch* cannot be a character that does not fit in a single byte; use :func:`wunctrl` for those. - .. function:: wunctrl(ch) Return a string which is a printable representation of the character *ch*; @@ -928,81 +897,69 @@ The module :mod:`!curses` defines the following functions: .. versionadded:: next +.. function:: filter() -.. function:: ungetch(ch) - - Push *ch* so the next :meth:`~window.getch` or :meth:`~window.get_wch` will - return it. - - *ch* may be an integer (a key code or character code), a byte, or a string of - length 1. A one-character string is pushed like :func:`unget_wch`; on a - narrow build it must encode to a single byte. - - .. note:: - - Only one *ch* can be pushed before :meth:`!getch` is called. - - .. versionchanged:: next - A one-character string argument is no longer required to encode to a single - byte, except on a narrow build. - - -.. function:: update_lines_cols() + The :func:`.filter` routine, if used, must be called before :func:`initscr` is + called. The effect is that, during the initialization, :envvar:`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. - Update the :const:`LINES` and :const:`COLS` module variables. - Useful for detecting manual screen resize. +.. function:: nofilter() - .. versionadded:: 3.5 + Undo the effect of a previous :func:`.filter` call. + Like :func:`.filter`, it must be called before :func:`initscr` (or + :func:`newterm`) so that the next initialization uses the full screen + again. + Availability: if the underlying curses library provides ``nofilter()``. -.. function:: unget_wch(ch) + .. versionadded:: next - Push *ch* so the next :meth:`~window.get_wch` will return it. +.. function:: use_env(flag) - .. note:: + If used, this function should be called before :func:`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 :envvar:`LINES` + and :envvar:`COLUMNS` (used by default) are set, or if curses is running in a + window (in which case default behavior would be to use the window size if + :envvar:`LINES` and :envvar:`COLUMNS` are not set). - Only one *ch* can be pushed before :meth:`!get_wch` is called. +.. function:: get_escdelay() - .. versionadded:: 3.3 + Retrieves the value set by :func:`set_escdelay`. - .. versionchanged:: next - Also available on a narrow build, where *ch* must encode to a single byte - (an 8-bit locale). + .. versionadded:: 3.9 +.. function:: set_escdelay(ms) -.. function:: ungetmouse(id, x, y, z, bstate) + 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. - Push a :const:`KEY_MOUSE` event onto the input queue, associating the given - state data with it. + .. versionadded:: 3.9 +.. function:: get_tabsize() -.. function:: use_env(flag) + Retrieves the value set by :func:`set_tabsize`. - If used, this function should be called before :func:`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 :envvar:`LINES` - and :envvar:`COLUMNS` (used by default) are set, or if curses is running in a - window (in which case default behavior would be to use the window size if - :envvar:`LINES` and :envvar:`COLUMNS` are not set). + .. versionadded:: 3.9 +.. function:: set_tabsize(size) -.. function:: use_default_colors() + 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. - Equivalent to ``assume_default_colors(-1, -1)``. + .. versionadded:: 3.9 +.. function:: napms(ms) -.. function:: wrapper(func, /, *args, **kwargs) + Sleep for *ms* milliseconds. - 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 :func:`!wrapper`. Before calling *func*, :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. +.. function:: delay_output(ms) + Insert an *ms* millisecond pause in output. .. _curses-window-objects: @@ -1015,6 +972,9 @@ Window objects the following methods and attributes: +Adding and inserting text +~~~~~~~~~~~~~~~~~~~~~~~~~ + .. method:: window.addch(ch[, attr]) window.addch(y, x, ch[, attr]) @@ -1036,18 +996,6 @@ Window objects by combining characters, instead of only a single character, or as a :class:`complexchar` cell. - -.. method:: window.addnstr(str, n[, attr]) - 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. - - .. versionchanged:: next - *str* may now also be a :class:`complexstr`; see :meth:`addstr`. - - .. method:: window.addstr(str[, attr]) window.addstr(y, x, str[, attr]) @@ -1074,25 +1022,240 @@ Window objects .. versionchanged:: next *str* may now also be a :class:`complexstr`, as described above. +.. method:: window.addnstr(str, n[, attr]) + window.addnstr(y, x, str, n[, attr]) -.. method:: window.attroff(attr) + Paint at most *n* characters of the character string *str* at + ``(y, x)`` with attributes + *attr*, overwriting anything previously on the display. - Remove attribute *attr* from the "background" set applied to all writes to the - current window. + .. versionchanged:: next + *str* may now also be a :class:`complexstr`; see :meth:`addstr`. +.. method:: window.echochar(ch[, attr]) -.. method:: window.attron(attr) + Add character *ch* with attribute *attr*, and immediately call :meth:`refresh` + on the window. - Add attribute *attr* to the "background" set applied to all writes to the + .. versionchanged:: next + Wide and combining characters, and :class:`complexchar` cells, are now + accepted. + +.. method:: window.insch(ch[, attr]) + window.insch(y, x, ch[, attr]) + + Insert character *ch* with attributes *attr* before the character under the + cursor, or at ``(y, x)`` if specified. All characters to the right of the + cursor are shifted one position right, with the rightmost character on the + line being lost. The cursor position does not change. + + .. versionchanged:: next + Wide and combining characters, and :class:`complexchar` cells, are now + accepted. + +.. method:: window.insstr(str[, attr]) + 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). + + *str* may also be a :class:`complexstr`, in which case each cell carries its + own attributes and color pair, so *attr* must not be given. + + .. versionchanged:: next + *str* may now also be a :class:`complexstr`, as described above. + +.. method:: window.insnstr(str, n[, attr]) + 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). + + .. versionchanged:: next + *str* may now also be a :class:`complexstr`; see :meth:`insstr`. + + +Deleting and inserting lines +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. method:: window.delch([y, x]) + + Delete the character under the cursor, or at ``(y, x)`` if specified. All + characters to the right on the same line are shifted one position left. + +.. method:: window.deleteln() + + Delete the line under the cursor. All following lines are moved up by one line. + +.. method:: window.insertln() + + Insert a blank line under the cursor. All following lines are moved down by one + line. + +.. method:: window.insdelln(nlines) + + 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. + + +Reading input +~~~~~~~~~~~~~ + +.. method:: window.getch([y, x]) + + 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. + A multibyte character is returned as its encoded bytes one at a time; use + :meth:`get_wch` to read it as a single character. + +.. method:: window.get_wch([y, x]) + + Get a wide character. Return a character for most keys, or an integer for + function keys, keypad keys, and other special keys. Unlike :meth:`getch`, an + ordinary key is returned as a one-character :class:`str`. + In no-delay mode, raise an exception if there is no input. + + .. versionadded:: 3.3 + + .. versionchanged:: next + Also available on a narrow build, where only a character representable as a + single byte (an 8-bit locale) can be returned. + +.. method:: window.getkey([y, x]) + + Get a character, returning a string instead of an integer, as :meth:`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. + +.. method:: window.getstr() + window.getstr(n) + window.getstr(y, x) + window.getstr(y, x, n) + + Read a bytes object from the user, with primitive line editing capacity. + At most *n* characters are read; + *n* defaults to and cannot exceed 2047. + A multibyte character is returned as its encoded bytes; use :meth:`get_wstr` + to read the input as a :class:`str`. + + .. versionchanged:: 3.14 + The maximum value for *n* was increased from 1023 to 2047. + +.. method:: window.get_wstr() + window.get_wstr(n) + window.get_wstr(y, x) + window.get_wstr(y, x, n) + + Read a string from the user, with primitive line editing capacity. + Unlike :meth:`getstr`, it can return characters that are not representable in + the window's encoding. + At most *n* characters are read; *n* defaults to and cannot exceed 2047. + + .. versionadded:: next + +.. method:: window.getdelay() + + Return the window's read timeout in milliseconds, + as set by :meth:`nodelay` or :meth:`timeout`: + ``-1`` for blocking, ``0`` for non-blocking, + or a positive number of milliseconds. + + .. versionadded:: next + + +Reading window contents +~~~~~~~~~~~~~~~~~~~~~~~ + +.. method:: window.inch([y, x]) + + Return the character at the given position in the window. + The bottom 8 bits are the character proper and the upper bits are the attributes; + extract them with the :data:`A_CHARTEXT` and :data:`A_ATTRIBUTES` bit-masks, + and the color pair with :func:`pair_number`. + It cannot represent a cell holding combining characters, a character that does + not fit in a single byte, or a color pair outside the :func:`color_pair` + range; use :meth:`in_wch` for those, which returns it as a :class:`complexchar`. + +.. method:: window.in_wch([y, x]) + + Return the complex character at the given position in the window as a + :class:`complexchar`. Unlike :meth:`inch`, the returned object carries the + cell's text (a spacing character optionally followed by combining characters) + together with its attributes and color pair. + + .. versionadded:: next + +.. method:: window.instr([n]) + 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, and stopping at the end + of the line. Attributes and color information are stripped + from the characters. If *n* is specified, :meth:`instr` returns a string + at most *n* characters long (exclusive of the trailing NUL). + The maximum value for *n* is 2047. + A character not representable in the window's encoding cannot be returned; + use :meth:`in_wstr` for those. + + .. versionchanged:: 3.14 + The maximum value for *n* was increased from 1023 to 2047. + +.. method:: window.in_wstr([n]) + window.in_wstr(y, x[, n]) + + Return a string of characters, extracted from the window starting at the + current cursor position, or at *y*, *x* if specified. Unlike :meth:`instr`, + it can return characters that are not representable in the window's encoding. + Attributes and color information are stripped from the characters. The + maximum value for *n* is 2047. + + .. versionadded:: next + +.. method:: window.in_wchstr([n]) + window.in_wchstr(y, x[, n]) + + Return a :class:`complexstr` of the styled cells extracted from the window + starting at the current cursor position, or at *y*, *x* if specified, and + stopping at the end of the line. This is the variant of :meth:`instr` and + :meth:`in_wstr` that *keeps* each cell's attributes and color pair (those + methods strip the rendition). If *n* is specified, at most *n* cells are + returned. The maximum value for *n* is 2047. + + The result can be written back unchanged with :meth:`addstr` (a read and a + re-write is a round-trip that preserves every cell's rendition). + + .. versionadded:: next + + +Attributes +~~~~~~~~~~ + +.. method:: window.attroff(attr) + + Remove attribute *attr* from the "background" set applied to all writes to the current window. +.. method:: window.attron(attr) + + Add attribute *attr* to the "background" set applied to all writes to the + current window. .. method:: window.attrset(attr) Set the "background" set of attributes to *attr*. This set is initially ``0`` (no attributes). - .. method:: window.attr_get() Return the window's current rendition as a ``(attrs, pair)`` tuple, @@ -1106,41 +1269,60 @@ Window objects .. versionadded:: next - .. method:: window.attr_set(attr, pair=0) Set the window's rendition to the attributes *attr* and the color pair *pair*. .. versionadded:: next - .. method:: window.attr_on(attr) Turn on the attributes *attr* without affecting any others. .. versionadded:: next - .. method:: window.attr_off(attr) Turn off the attributes *attr* without affecting any others. .. versionadded:: next - .. method:: window.color_set(pair) Set the window's color pair to *pair*, leaving the other attributes unchanged. .. versionadded:: next - .. method:: window.getattrs() Return the window's current attributes. .. versionadded:: next +.. method:: window.standout() + + Turn on attribute *A_STANDOUT*. + +.. method:: window.standend() + + Turn off the standout attribute. On some terminals this has the side effect of + turning off all attributes. + +.. method:: window.chgat(attr) + 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 :meth:`touchline` method so that the contents will + be redisplayed by the next window refresh. + + +Background +~~~~~~~~~~ .. method:: window.bkgd(ch[, attr]) @@ -1158,7 +1340,6 @@ Window objects Wide and combining characters, and :class:`complexchar` cells, are now accepted. - .. method:: window.bkgdset(ch[, attr]) Set the window's background. A window's background consists of a character and @@ -1172,21 +1353,62 @@ Window objects Wide and combining characters, and :class:`complexchar` cells, are now accepted. +.. method:: window.getbkgd() -.. method:: window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]]) + Return the given window's current background character/attribute pair. + Its components can be extracted like those of :meth:`inch`. + It cannot represent a background set with a wide character or with a color + pair outside the :func:`color_pair` range; use :meth:`getbkgrnd` for those. - 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. +.. method:: window.getbkgrnd() - .. note:: + Return the given window's current background as a :class:`complexchar`. + Unlike :meth:`getbkgd`, the returned object carries the background character + together with its attributes and color pair, and the color pair is not limited + to the value that fits in a :func:`color_pair`. - 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: + .. versionadded:: next - +-----------+---------------------+-----------------------+ - | Parameter | Description | Default value | + +Clearing and erasing +~~~~~~~~~~~~~~~~~~~~ + +.. method:: window.erase() + + Clear the window. + +.. method:: window.clear() + + Like :meth:`erase`, but also cause the whole window to be repainted upon next + call to :meth:`refresh`. + +.. method:: window.clrtobot() + + Erase from cursor to the end of the window: all lines below the cursor are + deleted, and then the equivalent of :meth:`clrtoeol` is performed. + +.. method:: window.clrtoeol() + + Erase from cursor to the end of the line. + + +Borders and lines +~~~~~~~~~~~~~~~~~ + +.. method:: 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 | :const:`ACS_VLINE` | +-----------+---------------------+-----------------------+ @@ -1210,7 +1432,6 @@ Window objects accepted. A single call cannot mix them with integer or byte characters. - .. method:: window.box([vertch, horch]) Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* and @@ -1221,59 +1442,73 @@ Window objects accepted. A single call cannot mix them with integer or byte characters. +.. method:: window.hline(ch, n[, attr]) + window.hline(y, x, ch, n[, attr]) -.. method:: window.chgat(attr) - window.chgat(num, attr) - window.chgat(y, x, attr) - window.chgat(y, x, num, attr) + Display a horizontal line starting at ``(y, x)`` with length *n* consisting of + the character *ch* with attributes *attr*. The line stops at the right edge + of the window if fewer than *n* cells are available. - 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 :meth:`touchline` method so that the contents will - be redisplayed by the next window refresh. + .. versionchanged:: next + Wide and combining characters, and :class:`complexchar` cells, are now + accepted. +.. method:: window.vline(ch, n[, attr]) + window.vline(y, x, ch, n[, attr]) -.. method:: window.clear() + Display a vertical line starting at ``(y, x)`` with length *n* consisting of the + character *ch* with attributes *attr*. - Like :meth:`erase`, but also cause the whole window to be repainted upon next - call to :meth:`refresh`. + .. versionchanged:: next + Wide and combining characters, and :class:`complexchar` cells, are now + accepted. -.. method:: window.clearok(flag) +Cursor position and window geometry +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - If *flag* is ``True``, the next call to :meth:`refresh` will clear the window - completely. +.. method:: window.move(new_y, new_x) + Move cursor to ``(new_y, new_x)``. -.. method:: window.clrtobot() +.. method:: window.getyx() - Erase from cursor to the end of the window: all lines below the cursor are - deleted, and then the equivalent of :meth:`clrtoeol` is performed. + Return a tuple ``(y, x)`` of current cursor position relative to the window's + upper-left corner. +.. method:: window.getbegyx() -.. method:: window.clrtoeol() + Return a tuple ``(y, x)`` of coordinates of upper-left corner. - Erase from cursor to the end of the line. +.. method:: window.getmaxyx() + Return a tuple ``(y, x)`` of the height and width of the window. -.. method:: window.cursyncup() +.. method:: window.getparyx() - Update the current cursor position of all the ancestors of the window to - reflect the current cursor position of the window. + 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. +.. method:: window.getparent() -.. method:: window.delch([y, x]) + Return the parent window of this subwindow, + or ``None`` if this window is not a subwindow. - Delete the character under the cursor, or at ``(y, x)`` if specified. All - characters to the right on the same line are shifted one position left. + .. versionadded:: next -.. method:: window.deleteln() +Creating and resizing windows +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Delete the line under the cursor. All following lines are moved up by one line. +.. method:: window.subwin(begin_y, begin_x) + window.subwin(nlines, ncols, begin_y, begin_x) + Return a sub-window, whose upper-left corner is at the screen-relative + coordinates ``(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. .. method:: window.derwin(begin_y, begin_x) window.derwin(nlines, ncols, begin_y, begin_x) @@ -1283,6 +1518,13 @@ Window objects of the window, rather than relative to the entire screen. Return a window object for the derived window. +.. method:: window.subpad(begin_y, begin_x) + window.subpad(nlines, ncols, begin_y, begin_x) + + Return a sub-pad, whose upper-left corner is at ``(begin_y, begin_x)``, and + whose width/height is *ncols*/*nlines*. The coordinates are relative to the + parent pad (unlike :meth:`subwin`, which uses screen coordinates). This + method is only available for pads created with :func:`newpad`. .. method:: window.dupwin() @@ -1294,475 +1536,148 @@ Window objects .. versionadded:: next +.. method:: window.mvwin(new_y, new_x) -.. method:: window.echochar(ch[, attr]) - - Add character *ch* with attribute *attr*, and immediately call :meth:`refresh` - on the window. - - .. versionchanged:: next - Wide and combining characters, and :class:`complexchar` cells, are now - accepted. - - -.. method:: window.enclose(y, x) - - 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. - - .. versionchanged:: 3.10 - Previously it returned ``1`` or ``0`` instead of ``True`` or ``False``. - - -.. method:: window.mouse_trafo(y, x, to_screen) - - Convert between window-relative and screen-relative (``stdscr``-relative) character-cell coordinates. - If *to_screen* is true, convert the window-relative coordinates *y*, *x* to screen-relative coordinates; - otherwise convert in the opposite direction. - The two coordinate systems differ when lines are reserved on the screen, for example for soft labels. - - Return the converted coordinates as a ``(y, x)`` tuple, or ``None`` if they lie outside the window. - - .. versionadded:: next - - -.. attribute:: window.encoding - - 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 :meth:`window.subwin`. - By default, current locale encoding is used (see :func:`locale.getencoding`). + Move the window so its upper-left corner is at ``(new_y, new_x)``. - .. versionadded:: 3.3 + Moving the window so that any part of it would be off the screen is an error: + the window is not moved and :exc:`curses.error` is raised. +.. method:: window.mvderwin(y, x) -.. method:: window.erase() + 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. - Clear the window. +.. method:: window.resize(nlines, ncols) + 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 :meth:`bkgdset`) merged into them. -.. method:: window.getbegyx() - Return a tuple ``(y, x)`` of coordinates of upper-left corner. +Refreshing and redrawing +~~~~~~~~~~~~~~~~~~~~~~~~ +.. method:: window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol]) -.. method:: window.getbkgd() + Update the display immediately (sync actual screen with previous + drawing/deleting methods). - Return the given window's current background character/attribute pair. - Its components can be extracted like those of :meth:`inch`. - It cannot represent a background set with a wide character or with a color - pair outside the :func:`color_pair` range; use :meth:`getbkgrnd` for those. + The 6 arguments can only be specified, and are then required, when the window + is a pad created with :func:`newpad`. The additional parameters are needed to indicate what part + of the pad and screen are involved. *pminrow* and *pmincol* specify the + upper-left 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 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. +.. method:: window.noutrefresh() + window.noutrefresh(pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) -.. method:: window.getbkgrnd() + 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 :func:`doupdate`. - Return the given window's current background as a :class:`complexchar`. - Unlike :meth:`getbkgd`, the returned object carries the background character - together with its attributes and color pair, and the color pair is not limited - to the value that fits in a :func:`color_pair`. + The 6 arguments can only be specified, and are then required, when the window + is a pad created with :func:`newpad`; they have the same meaning as for + :meth:`refresh`. - .. versionadded:: next +.. method:: window.redrawln(beg, num) + Indicate that the *num* screen lines, starting at line *beg*, are corrupted and + should be completely redrawn on the next :meth:`refresh` call. -.. method:: window.getch([y, x]) +.. method:: window.redrawwin() - 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. - A multibyte character is returned as its encoded bytes one at a time; use - :meth:`get_wch` to read it as a single character. + Touch the entire window, causing it to be completely redrawn on the next + :meth:`refresh` call. -.. method:: window.get_wch([y, x]) +Output options +~~~~~~~~~~~~~~ - Get a wide character. Return a character for most keys, or an integer for - function keys, keypad keys, and other special keys. Unlike :meth:`getch`, an - ordinary key is returned as a one-character :class:`str`. - In no-delay mode, raise an exception if there is no input. +.. method:: window.clearok(flag) - .. versionadded:: 3.3 + If *flag* is ``True``, the next call to :meth:`refresh` will clear the window + completely. - .. versionchanged:: next - Also available on a narrow build, where only a character representable as a - single byte (an 8-bit locale) can be returned. +.. method:: window.idlok(flag) + If *flag* is ``True``, :mod:`!curses` will try to use hardware line + editing facilities. Otherwise, curses will not use them. -.. method:: window.getdelay() +.. method:: window.idcok(flag) - Return the window's read timeout in milliseconds, - as set by :meth:`nodelay` or :meth:`timeout`: - ``-1`` for blocking, ``0`` for non-blocking, - or a positive number of milliseconds. + 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. - .. versionadded:: next +.. method:: window.immedok(flag) + If *flag* is ``True``, any change in the window image automatically causes the + window to be refreshed; you no longer have to call :meth:`refresh` yourself. + However, it may degrade performance considerably, due to repeated calls to + wrefresh. This option is disabled by default. -.. method:: window.getkey([y, x]) +.. method:: window.leaveok(flag) - Get a character, returning a string instead of an integer, as :meth:`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. + 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 *flag* is ``False``, cursor will always be at "cursor position" after an update. -.. method:: window.getmaxyx() +.. method:: window.scrollok(flag) - Return a tuple ``(y, x)`` of the height and width of the window. - - -.. method:: window.getparent() - - Return the parent window of this subwindow, - or ``None`` if this window is not a subwindow. - - .. versionadded:: next - - -.. method:: window.getparyx() - - 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. - - -.. method:: window.getscrreg() - - Return a tuple ``(top, bottom)`` of the window's current scrolling region, - as set by :meth:`setscrreg`. - - .. versionadded:: next - - -.. method:: window.getstr() - window.getstr(n) - window.getstr(y, x) - window.getstr(y, x, n) - - Read a bytes object from the user, with primitive line editing capacity. - At most *n* characters are read; - *n* defaults to and cannot exceed 2047. - A multibyte character is returned as its encoded bytes; use :meth:`get_wstr` - to read the input as a :class:`str`. - - .. versionchanged:: 3.14 - The maximum value for *n* was increased from 1023 to 2047. - - -.. method:: window.get_wstr() - window.get_wstr(n) - window.get_wstr(y, x) - window.get_wstr(y, x, n) - - Read a string from the user, with primitive line editing capacity. - Unlike :meth:`getstr`, it can return characters that are not representable in - the window's encoding. - At most *n* characters are read; *n* defaults to and cannot exceed 2047. - - .. versionadded:: next - - -.. method:: window.getyx() - - Return a tuple ``(y, x)`` of current cursor position relative to the window's - upper-left corner. - - -.. method:: window.hline(ch, n[, attr]) - window.hline(y, x, ch, n[, attr]) - - Display a horizontal line starting at ``(y, x)`` with length *n* consisting of - the character *ch* with attributes *attr*. The line stops at the right edge - of the window if fewer than *n* cells are available. - - .. versionchanged:: next - Wide and combining characters, and :class:`complexchar` cells, are now - accepted. - - -.. method:: window.idcok(flag) - - 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. - - -.. method:: window.idlok(flag) - - If *flag* is ``True``, :mod:`!curses` will try to use hardware line - editing facilities. Otherwise, curses will not use them. - - -.. method:: window.immedok(flag) - - If *flag* is ``True``, any change in the window image automatically causes the - window to be refreshed; you no longer have to call :meth:`refresh` yourself. - However, it may degrade performance considerably, due to repeated calls to - wrefresh. This option is disabled by default. - - -.. method:: window.inch([y, x]) - - Return the character at the given position in the window. - The bottom 8 bits are the character proper and the upper bits are the attributes; - extract them with the :data:`A_CHARTEXT` and :data:`A_ATTRIBUTES` bit-masks, - and the color pair with :func:`pair_number`. - It cannot represent a cell holding combining characters, a character that does - not fit in a single byte, or a color pair outside the :func:`color_pair` - range; use :meth:`in_wch` for those, which returns it as a :class:`complexchar`. - - -.. method:: window.in_wch([y, x]) - - Return the complex character at the given position in the window as a - :class:`complexchar`. Unlike :meth:`inch`, the returned object carries the - cell's text (a spacing character optionally followed by combining characters) - together with its attributes and color pair. - - .. versionadded:: next - - -.. method:: window.insch(ch[, attr]) - window.insch(y, x, ch[, attr]) - - Insert character *ch* with attributes *attr* before the character under the - cursor, or at ``(y, x)`` if specified. All characters to the right of the - cursor are shifted one position right, with the rightmost character on the - line being lost. The cursor position does not change. - - .. versionchanged:: next - Wide and combining characters, and :class:`complexchar` cells, are now - accepted. - - -.. method:: window.insdelln(nlines) - - 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. - - -.. method:: window.insertln() - - Insert a blank line under the cursor. All following lines are moved down by one - line. - - -.. method:: window.insnstr(str, n[, attr]) - 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). - - .. versionchanged:: next - *str* may now also be a :class:`complexstr`; see :meth:`insstr`. - - -.. method:: window.insstr(str[, attr]) - 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). - - *str* may also be a :class:`complexstr`, in which case each cell carries its - own attributes and color pair, so *attr* must not be given. - - .. versionchanged:: next - *str* may now also be a :class:`complexstr`, as described above. - - -.. method:: window.instr([n]) - 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, and stopping at the end - of the line. Attributes and color information are stripped - from the characters. If *n* is specified, :meth:`instr` returns a string - at most *n* characters long (exclusive of the trailing NUL). - The maximum value for *n* is 2047. - A character not representable in the window's encoding cannot be returned; - use :meth:`in_wstr` for those. - - .. versionchanged:: 3.14 - The maximum value for *n* was increased from 1023 to 2047. - - -.. method:: window.in_wstr([n]) - window.in_wstr(y, x[, n]) - - Return a string of characters, extracted from the window starting at the - current cursor position, or at *y*, *x* if specified. Unlike :meth:`instr`, - it can return characters that are not representable in the window's encoding. - Attributes and color information are stripped from the characters. The - maximum value for *n* is 2047. - - .. versionadded:: next - - -.. method:: window.in_wchstr([n]) - window.in_wchstr(y, x[, n]) - - Return a :class:`complexstr` of the styled cells extracted from the window - starting at the current cursor position, or at *y*, *x* if specified, and - stopping at the end of the line. This is the variant of :meth:`instr` and - :meth:`in_wstr` that *keeps* each cell's attributes and color pair (those - methods strip the rendition). If *n* is specified, at most *n* cells are - returned. The maximum value for *n* is 2047. - - The result can be written back unchanged with :meth:`addstr` (a read and a - re-write is a round-trip that preserves every cell's rendition). - - .. versionadded:: next - - -.. method:: window.is_cleared() - - Return the current value set by :meth:`clearok`. - - .. versionadded:: next - - -.. method:: window.is_idcok() - - Return the current value set by :meth:`idcok`. - - .. versionadded:: next - - -.. method:: window.is_idlok() - - Return the current value set by :meth:`idlok`. - - .. versionadded:: next - - -.. method:: window.is_immedok() - - Return the current value set by :meth:`immedok`. - - .. versionadded:: next - - -.. method:: window.is_keypad() - - Return the current value set by :meth:`keypad`. - - .. versionadded:: next - - -.. method:: window.is_leaveok() - - Return the current value set by :meth:`leaveok`. - - .. versionadded:: next - - -.. method:: window.is_linetouched(line) - - Return ``True`` if the specified line was modified since the last call to - :meth:`refresh`; otherwise return ``False``. Raise a :exc:`curses.error` - exception if *line* is not valid for the given window. - - -.. method:: window.is_nodelay() - - Return the current value set by :meth:`nodelay`. - - .. versionadded:: next - - -.. method:: window.is_notimeout() - - Return the current value set by :meth:`notimeout`. - - .. versionadded:: next - - -.. method:: window.is_pad() - - Return ``True`` if the window is a pad created by :func:`newpad`. - - .. versionadded:: next - - -.. method:: window.is_scrollok() - - Return the current value set by :meth:`scrollok`. - - .. versionadded:: next - - -.. method:: window.is_subwin() - - Return ``True`` if the window is a subwindow created by :meth:`subwin` - or :meth:`derwin`. - - .. versionadded:: next - - -.. method:: window.is_syncok() - - Return the current value set by :meth:`syncok`. - - .. versionadded:: next - - -.. method:: window.is_wintouched() - - Return ``True`` if the specified window was modified since the last call to - :meth:`refresh`; otherwise return ``False``. - - -.. method:: window.keypad(flag) - - If *flag* is ``True``, escape sequences generated by some keys (keypad, function keys) - will be interpreted by :mod:`!curses`. If *flag* is ``False``, escape sequences will be - left as is in the input stream. - - -.. method:: window.leaveok(flag) + 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 :meth:`idlok`. - If *flag* is ``True``, cursor is left where it is on update, instead of being at "cursor - position." This reduces cursor movement where possible. +.. method:: window.scroll([lines=1]) - If *flag* is ``False``, cursor will always be at "cursor position" after an update. + Scroll the screen or scrolling region. Scroll upward by *lines* lines if + *lines* is positive, or downward if it is negative. Scrolling has no effect + unless it has been enabled for the window with :meth:`scrollok`. +.. method:: window.setscrreg(top, bottom) -.. method:: window.move(new_y, new_x) + Set the scrolling region from line *top* to line *bottom*. All scrolling actions + will take place in this region. - Move cursor to ``(new_y, new_x)``. +.. method:: window.getscrreg() + Return a tuple ``(top, bottom)`` of the window's current scrolling region, + as set by :meth:`setscrreg`. -.. method:: window.mvderwin(y, x) + .. versionadded:: next - 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. +.. method:: window.syncok(flag) + If *flag* is ``True``, then :meth:`syncup` is called automatically + whenever there is a change in the window. -.. method:: window.mvwin(new_y, new_x) - Move the window so its upper-left corner is at ``(new_y, new_x)``. +Input options +~~~~~~~~~~~~~ - Moving the window so that any part of it would be off the screen is an error: - the window is not moved and :exc:`curses.error` is raised. +.. method:: window.keypad(flag) + If *flag* is ``True``, escape sequences generated by some keys (keypad, function keys) + will be interpreted by :mod:`!curses`. If *flag* is ``False``, escape sequences will be + left as is in the input stream. .. method:: window.nodelay(flag) If *flag* is ``True``, :meth:`getch` will be non-blocking. - .. method:: window.notimeout(flag) If *flag* is ``True``, escape sequences will not be timed out. @@ -1770,18 +1685,18 @@ Window objects 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. +.. method:: window.timeout(delay) -.. method:: window.noutrefresh() - window.noutrefresh(pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol) - - 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 :func:`doupdate`. + 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 :meth:`getch` will + return ``-1`` if no input is waiting. If *delay* is positive, then + :meth:`getch` will block for *delay* milliseconds, and return ``-1`` if there is + still no input at the end of that time. - The 6 arguments can only be specified, and are then required, when the window - is a pad created with :func:`newpad`; they have the same meaning as for - :meth:`refresh`. +Overlapping and touch +~~~~~~~~~~~~~~~~~~~~~ .. method:: window.overlay(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol]) @@ -1795,7 +1710,6 @@ Window objects coordinates of the source window, and the other variables mark a rectangle in the destination window. - .. method:: window.overwrite(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol]) Overwrite the window on top of *destwin*. The windows need not be the same size, @@ -1808,173 +1722,179 @@ Window objects coordinates of the source window, the other variables mark a rectangle in the destination window. +.. method:: window.touchline(start, count[, changed]) -.. method:: window.putwin(file) + 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``). - Write all data associated with the window into the provided file object. This - information can be later retrieved using the :func:`getwin` function. +.. method:: window.touchwin() + Pretend the whole window has been changed, for purposes of drawing + optimizations. -.. method:: window.redrawln(beg, num) +.. method:: window.untouchwin() - Indicate that the *num* screen lines, starting at line *beg*, are corrupted and - should be completely redrawn on the next :meth:`refresh` call. + Mark all lines in the window as unchanged since the last call to + :meth:`refresh`. +.. method:: window.syncup() -.. method:: window.redrawwin() + Touch all locations in ancestors of the window that have been changed in the + window. - Touch the entire window, causing it to be completely redrawn on the next - :meth:`refresh` call. +.. method:: window.syncdown() + Touch each location in the window that has been touched in any of its ancestor + windows. This routine is called by :meth:`refresh`, so it should almost never + be necessary to call it manually. -.. method:: window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol]) +.. method:: window.cursyncup() - Update the display immediately (sync actual screen with previous - drawing/deleting methods). + Update the current cursor position of all the ancestors of the window to + reflect the current cursor position of the window. - The 6 arguments can only be specified, and are then required, when the window - is a pad created with :func:`newpad`. The additional parameters are needed to indicate what part - of the pad and screen are involved. *pminrow* and *pmincol* specify the - upper-left 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 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. +Coordinate conversion +~~~~~~~~~~~~~~~~~~~~~ -.. method:: window.resize(nlines, ncols) +.. method:: window.enclose(y, x) - 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 :meth:`bkgdset`) merged into them. + 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. + .. versionchanged:: 3.10 + Previously it returned ``1`` or ``0`` instead of ``True`` or ``False``. -.. method:: window.scroll([lines=1]) +.. method:: window.mouse_trafo(y, x, to_screen) - Scroll the screen or scrolling region. Scroll upward by *lines* lines if - *lines* is positive, or downward if it is negative. Scrolling has no effect - unless it has been enabled for the window with :meth:`scrollok`. + Convert between window-relative and screen-relative (``stdscr``-relative) character-cell coordinates. + If *to_screen* is true, convert the window-relative coordinates *y*, *x* to screen-relative coordinates; + otherwise convert in the opposite direction. + The two coordinate systems differ when lines are reserved on the screen, for example for soft labels. + Return the converted coordinates as a ``(y, x)`` tuple, or ``None`` if they lie outside the window. -.. method:: window.scrollok(flag) + .. versionadded:: next - 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 :meth:`idlok`. +Other +~~~~~ -.. method:: window.setscrreg(top, bottom) +.. attribute:: window.encoding - Set the scrolling region from line *top* to line *bottom*. All scrolling actions - will take place in this region. + 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 :meth:`window.subwin`. + By default, current locale encoding is used (see :func:`locale.getencoding`). + .. versionadded:: 3.3 -.. method:: window.standend() +.. method:: window.putwin(file) - Turn off the standout attribute. On some terminals this has the side effect of - turning off all attributes. + Write all data associated with the window into the provided file object. This + information can be later retrieved using the :func:`getwin` function. +.. method:: window.use(func, /, *args, **kwargs) -.. method:: window.standout() + Call ``func(window, *args, **kwargs)`` with the lock of the window held, + and return its result. + This provides automatic protection for the window + against concurrent access from another thread. - Turn on attribute *A_STANDOUT*. + Availability: if the underlying curses library provides ``use_window()``. + .. versionadded:: next -.. method:: window.subpad(begin_y, begin_x) - window.subpad(nlines, ncols, begin_y, begin_x) - Return a sub-pad, whose upper-left corner is at ``(begin_y, begin_x)``, and - whose width/height is *ncols*/*nlines*. The coordinates are relative to the - parent pad (unlike :meth:`subwin`, which uses screen coordinates). This - method is only available for pads created with :func:`newpad`. +State queries +~~~~~~~~~~~~~ +.. method:: window.is_cleared() -.. method:: window.subwin(begin_y, begin_x) - window.subwin(nlines, ncols, begin_y, begin_x) + Return the current value set by :meth:`clearok`. - Return a sub-window, whose upper-left corner is at the screen-relative - coordinates ``(begin_y, begin_x)``, and whose width/height is *ncols*/*nlines*. + .. versionadded:: next - By default, the sub-window will extend from the specified position to the lower - right corner of the window. +.. method:: window.is_idcok() + Return the current value set by :meth:`idcok`. -.. method:: window.syncdown() + .. versionadded:: next - Touch each location in the window that has been touched in any of its ancestor - windows. This routine is called by :meth:`refresh`, so it should almost never - be necessary to call it manually. +.. method:: window.is_idlok() + Return the current value set by :meth:`idlok`. -.. method:: window.syncok(flag) + .. versionadded:: next - If *flag* is ``True``, then :meth:`syncup` is called automatically - whenever there is a change in the window. +.. method:: window.is_immedok() + Return the current value set by :meth:`immedok`. -.. method:: window.syncup() + .. versionadded:: next - Touch all locations in ancestors of the window that have been changed in the - window. +.. method:: window.is_keypad() + Return the current value set by :meth:`keypad`. -.. method:: window.timeout(delay) + .. versionadded:: next - 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 :meth:`getch` will - return ``-1`` if no input is waiting. If *delay* is positive, then - :meth:`getch` will block for *delay* milliseconds, and return ``-1`` if there is - still no input at the end of that time. +.. method:: window.is_leaveok() + Return the current value set by :meth:`leaveok`. -.. method:: window.touchline(start, count[, changed]) + .. versionadded:: next - 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``). +.. method:: window.is_linetouched(line) + Return ``True`` if the specified line was modified since the last call to + :meth:`refresh`; otherwise return ``False``. Raise a :exc:`curses.error` + exception if *line* is not valid for the given window. -.. method:: window.touchwin() +.. method:: window.is_nodelay() - Pretend the whole window has been changed, for purposes of drawing - optimizations. + Return the current value set by :meth:`nodelay`. + .. versionadded:: next -.. method:: window.untouchwin() +.. method:: window.is_notimeout() - Mark all lines in the window as unchanged since the last call to - :meth:`refresh`. + Return the current value set by :meth:`notimeout`. + .. versionadded:: next -.. method:: window.use(func, /, *args, **kwargs) +.. method:: window.is_pad() - Call ``func(window, *args, **kwargs)`` with the lock of the window held, - and return its result. - This provides automatic protection for the window - against concurrent access from another thread. + Return ``True`` if the window is a pad created by :func:`newpad`. - Availability: if the underlying curses library provides ``use_window()``. + .. versionadded:: next + +.. method:: window.is_scrollok() + + Return the current value set by :meth:`scrollok`. .. versionadded:: next +.. method:: window.is_subwin() -.. method:: window.vline(ch, n[, attr]) - window.vline(y, x, ch, n[, attr]) + Return ``True`` if the window is a subwindow created by :meth:`subwin` + or :meth:`derwin`. - Display a vertical line starting at ``(y, x)`` with length *n* consisting of the - character *ch* with attributes *attr*. + .. versionadded:: next - .. versionchanged:: next - Wide and combining characters, and :class:`complexchar` cells, are now - accepted. +.. method:: window.is_syncok() + + Return the current value set by :meth:`syncok`. + + .. versionadded:: next + +.. method:: window.is_wintouched() + Return ``True`` if the specified window was modified since the last call to + :meth:`refresh`; otherwise return ``False``. .. _curses-screen-objects: @@ -2115,6 +2035,9 @@ Complex character objects Constants --------- +General +~~~~~~~ + The :mod:`!curses` module defines the following data members: @@ -2171,6 +2094,9 @@ The :mod:`!curses` module defines the following data members: :func:`resize_term`. +Attributes +~~~~~~~~~~ + Some constants are available to specify character cell attributes. The exact constants available are system dependent. @@ -2250,11 +2176,12 @@ by some methods. | | color-pair field information | +-------------------------+-------------------------------+ +Keys +~~~~ + Keys are referred to by integer constants with names starting with ``KEY_``. The exact keycaps available are system dependent. -.. XXX this table is far too large! should it be alphabetized? - +-------------------------+--------------------------------------------+ | Key constant | Key | +=========================+============================================+ @@ -2472,6 +2399,9 @@ keys); also, the following keypad mappings are standard: | :kbd:`Page Down` | KEY_NPAGE | +------------------+-----------+ +Alternate character set +~~~~~~~~~~~~~~~~~~~~~~~~ + .. _curses-acs-codes: The following table lists characters from the alternate character set. These are @@ -2573,6 +2503,9 @@ falls back on a crude printable ASCII approximation. | .. data:: ACS_VLINE | vertical line | +------------------------+------------------------------------------+ +Mouse buttons +~~~~~~~~~~~~~ + The following table lists mouse button constants used by :meth:`getmouse`: +----------------------------------+---------------------------------------------+ @@ -2599,6 +2532,9 @@ The following table lists mouse button constants used by :meth:`getmouse`: The ``BUTTON5_*`` constants are now exposed if they are provided by the underlying curses library. +Colors +~~~~~~ + The following table lists the predefined colors: +-------------------------+----------------------------+ -- 2.47.3