* Change the definition of the color-pair ``0`` to ``(fg, bg)``.
+ This is an ncurses extension.
+
.. versionadded:: 3.14
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).
+ ``0`` (no component) and ``1000`` (maximum amount of component). Raise an
+ exception if the color is not supported.
.. function:: color_pair(pair_number)
Update the physical screen. The curses library keeps two data structures, one
representing the current physical screen contents and a virtual screen
- representing the desired next state. The :func:`doupdate` ground updates the
+ representing the desired next state. The :func:`doupdate` function updates the
physical screen to match the virtual screen.
The virtual screen may be updated by a :meth:`~window.noutrefresh` call after write
.. function:: filter()
The :func:`.filter` routine, if used, must be called before :func:`initscr` is
- called. The effect is that, during those calls, :envvar:`LINES` is set to ``1``; the
+ 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
.. function:: getwin(file)
- Read window related data stored in the file by an earlier :func:`window.putwin` call.
+ 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 new window object. The *file* argument must be a file object opened for
+ reading in binary mode.
.. function:: has_colors()
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()
Set the maximum time in milliseconds that can elapse between press and release
events in order for them to be recognized as a click, and return the previous
- interval value. The default value is 200 milliseconds, or one fifth of a second.
+ 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:: 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 given window's mouse event mask. If this function is never called, no mouse
+ the mouse event mask. If this function is never called, no mouse
events are ever reported.
right corner of the screen.
-.. function:: nl()
+.. 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()
terminfo capability for the current terminal. Note that the output of :func:`putp`
always goes to standard output.
+ :func:`setupterm` (or :func:`initscr`) must be called first.
+
.. function:: qiflush([flag])
file descriptor to which any initialization sequences will be sent; if not
supplied or ``-1``, the file descriptor for ``sys.stdout`` will be used.
+ Raise a :exc:`curses.error` if the terminal could not be found or its
+ terminfo database entry could not be read. If the terminal has already
+ been initialized, this function has no effect.
+
.. function:: start_color()
Boolean capability, or ``0`` if it is canceled or absent from the terminal
description.
+ :func:`setupterm` (or :func:`initscr`) must be called first.
+
.. function:: tigetnum(capname)
numeric capability, or ``-1`` if it is canceled or absent from the terminal
description.
+ :func:`setupterm` (or :func:`initscr`) must be called first.
+
.. function:: tigetstr(capname)
is not a terminfo "string capability", or is canceled or absent from the
terminal description.
+ :func:`setupterm` (or :func:`initscr`) must be called first.
+
.. function:: tparm(str[, ...])
Instantiate the bytes object *str* with the supplied parameters, where *str* should
be a parameterized string obtained from the terminfo database. E.g.
``tparm(tigetstr("cup"), 5, 3)`` could result in ``b'\033[6;4H'``, the exact
- result depending on terminal type.
+ result depending on terminal type. Up to nine integer parameters may be supplied.
+
+ :func:`setupterm` (or :func:`initscr`) must be called first.
.. function:: typeahead(fd)
Attempting to write to the lower right corner of a window, subwindow,
or pad will cause an exception to be raised after the string is printed.
- * A `bug in ncurses <https://bugs.python.org/issue35924>`_, the backend
- for this Python module, can cause SegFaults when resizing windows. This
- is fixed in ncurses-6.1-20190511. If you are stuck with an earlier
- ncurses, you can avoid triggering this if you do not call :func:`addstr`
- with a *str* that has embedded newlines. Instead, call :func:`addstr`
- separately for each line.
+ * A bug in ncurses, the backend for this Python module, could cause
+ segfaults when resizing windows. This was fixed in ncurses-6.1-20190511.
+ If you are stuck with an earlier ncurses, you can avoid triggering it by
+ not calling :meth:`!addstr` with a *str* that has embedded newlines;
+ instead, call :meth:`!addstr` separately for each line.
.. method:: window.attroff(attr)
.. method:: window.delch([y, x])
- Delete any character at ``(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()
window.getstr(y, x, n)
Read a bytes object from the user, with primitive line editing capacity.
+ At most *n* characters are read (2047 by default).
The maximum value for *n* is 2047.
.. versionchanged:: 3.14
upper-left corner.
-.. method:: window.hline(ch, n)
- window.hline(y, x, ch, n)
+.. 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*.
+ the character *ch* with attributes *attr*. The line stops at the right edge
+ of the window if fewer than *n* cells are available.
.. method:: window.idcok(flag)
.. method:: window.idlok(flag)
- If *flag* is ``True``, :mod:`!curses` will try and use hardware line
- editing facilities. Otherwise, line insertion/deletion are disabled.
+ If *flag* is ``True``, :mod:`!curses` will try to use hardware line
+ editing facilities. Otherwise, curses will not use them.
.. method:: window.immedok(flag)
.. method:: window.insch(ch[, attr])
window.insch(y, x, ch[, attr])
- Paint character *ch* at ``(y, x)`` with attributes *attr*, moving the line from
- position *x* right by one character.
+ 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.
.. method:: window.insdelln(nlines)
window.instr(y, x[, n])
Return a bytes object of characters, extracted from the window starting at the
- current cursor position, or at *y*, *x* if specified. Attributes are stripped
+ 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.
.. method:: window.leaveok(flag)
If *flag* is ``True``, cursor is left where it is on update, instead of being at "cursor
- position." This reduces cursor movement where possible. If possible the cursor
- will be made invisible.
+ position." This reduces cursor movement where possible.
If *flag* is ``False``, cursor will always be at "cursor position" after an update.
Move the window so its upper-left corner is at ``(new_y, new_x)``.
+ 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.nodelay(flag)
.. 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`.
+ 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`.
+
.. method:: window.overlay(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])
Update the display immediately (sync actual screen with previous
drawing/deleting methods).
- The 6 optional arguments can only be specified when the window is a pad created
- with :func:`newpad`. The additional parameters are needed to indicate what part
+ 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-hand corner of the rectangle to be displayed in the pad. *sminrow*,
*smincol*, *smaxrow*, and *smaxcol* specify the edges of the rectangle to be
.. method:: window.scroll([lines=1])
- Scroll the screen or scrolling region upward by *lines* lines.
+ 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.scrollok(flag)
.. method:: window.subpad(begin_y, begin_x)
window.subpad(nlines, ncols, begin_y, begin_x)
- Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and
- whose width/height is *ncols*/*nlines*.
+ 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.subwin(begin_y, begin_x)
window.subwin(nlines, ncols, begin_y, begin_x)
- Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and
- whose width/height is *ncols*/*nlines*.
+ 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.
+----------------------------------+---------------------------------------------+
| .. data:: BUTTON_CTRL | Control was down during button state change |
+----------------------------------+---------------------------------------------+
-| .. data:: BUTTON_ALT | Control was down during button state change |
+| .. data:: BUTTON_ALT | Alt was down during button state change |
+----------------------------------+---------------------------------------------+
.. versionchanged:: 3.10
You can instantiate a :class:`Textbox` object as follows:
-.. class:: Textbox(win)
+.. class:: Textbox(win, insert_mode=False)
Return a textbox widget object. The *win* argument should be a curses
:ref:`window <curses-window-objects>` object in which the textbox is to
- be contained. The edit cursor of the textbox is initially located at the
+ be contained. If *insert_mode* is true, the textbox inserts typed
+ characters, shifting existing text to the right, rather than overwriting it.
+ The edit cursor of the textbox is initially located at the
upper left hand corner of the containing window, with coordinates ``(0, 0)``.
The instance's :attr:`stripspaces` flag is initially on.
:class:`Textbox` objects have the following methods:
- .. method:: edit([validator])
+ .. method:: edit(validate=None)
This is the entry point you will normally use. It accepts editing
keystrokes until one of the termination keystrokes is entered. If
- *validator* is supplied, it must be a function. It will be called for
+ *validate* is supplied, it must be a function. It will be called for
each keystroke entered with the keystroke as a parameter; command dispatch
- is done on the result. This method returns the window contents as a
+ is done on the result. If it returns a false value, the keystroke is
+ ignored. This method returns the window contents as a
string; whether blanks in the window are included is affected by the
:attr:`stripspaces` attribute.
.. method:: do_command(ch)
- Process a single command keystroke. Here are the supported special
- keystrokes:
+ Process a single command keystroke. Returns ``1`` to continue editing,
+ or ``0`` if a termination keystroke was processed. Here are the supported
+ special keystrokes:
+------------------+-------------------------------------------+
| Keystroke | Action |
| :kbd:`Control-H` | Delete character backward. |
+------------------+-------------------------------------------+
| :kbd:`Control-J` | Terminate if the window is 1 line, |
- | | otherwise insert newline. |
+ | | otherwise move to the start of the next |
+ | | line. |
+------------------+-------------------------------------------+
| :kbd:`Control-K` | If line is blank, delete it, otherwise |
| | clear to end of line. |
projects / thirdparty / Python / cpython.git / commitdiff
