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 <curses-window-objects>` 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 <curses-screen-objects>` 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 <curses-screen-objects>`
+ 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 <curses-screen-objects>` 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()
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
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 <window.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 <window.leaveok>` is set ``True``.
.. function:: doupdate()
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 <window.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)
.. versionadded:: next
-
.. function:: key_defined(definition)
Return the key code bound to the escape sequence *definition*, a string,
.. versionadded:: next
-
.. function:: keyok(keycode, enable)
Enable (if *enable* is true) or disable (otherwise) interpretation of the
.. 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)
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)
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 <curses-window-objects>` 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 <curses-window-objects>`, 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)
is to be displayed.
-.. function:: newwin(nlines, ncols)
- newwin(nlines, ncols, begin_y, begin_x)
-
- Return a new :ref:`window <curses-window-objects>`, 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 <curses-screen-objects>` 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 <curses-screen-objects>`
- 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_*
+ <curses-wa-constants>` 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)
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 <curses-screen-objects>` 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 <window.leaveok>` is set ``True``.
+Terminfo database
+~~~~~~~~~~~~~~~~~
.. function:: setupterm(term=None, fd=-1)
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_*
- <curses-wa-constants>` 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
:func:`setupterm` (or :func:`initscr`) must be called first.
-
.. function:: tigetnum(capname)
Return the value of the numeric capability corresponding to the terminfo
:func:`setupterm` (or :func:`initscr`) must be called first.
-
.. function:: tigetstr(capname)
Return the value of the string capability corresponding to the terminfo
:func:`setupterm` (or :func:`initscr`) must be called first.
-
.. function:: tparm(str[, ...])
Instantiate the bytes object *str* with the supplied parameters, where *str* should
: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)
*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*;
.. 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:
the following methods and attributes:
+Adding and inserting text
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
.. method:: window.addch(ch[, attr])
window.addch(y, x, ch[, attr])
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])
.. 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,
.. 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])
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
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` |
+-----------+---------------------+-----------------------+
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
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)
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()
.. 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.
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])
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,
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:
Constants
---------
+General
+~~~~~~~
+
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.
| | 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 |
+=========================+============================================+
| :kbd:`Page Down` | KEY_NPAGE |
+------------------+-----------+
+Alternate character set
+~~~~~~~~~~~~~~~~~~~~~~~~
+
.. _curses-acs-codes:
The following table lists characters from the alternate character set. These are
| .. data:: ACS_VLINE | vertical line |
+------------------------+------------------------------------------+
+Mouse buttons
+~~~~~~~~~~~~~
+
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:
+-------------------------+----------------------------+
projects / thirdparty / Python / cpython.git / commitdiff
