@@ -30,6 +30,8 @@ Linux and the BSD variants of Unix.
3030
3131 Whenever the documentation mentions a *character * it can be specified
3232 as an integer, a one-character Unicode string or a one-byte byte string.
33+ An integer is the code of a single encoded byte, optionally combined with
34+ attributes and a color pair, as returned by :meth: `window.inch `.
3335
3436 Whenever the documentation mentions a *character string * it can be specified
3537 as a Unicode string or a byte string.
@@ -505,8 +507,8 @@ The module :mod:`!curses` defines the following functions:
505507.. function :: putp(str)
506508
507509 Equivalent to ``tputs(str, 1, putchar) ``; emit the value of a specified
508- terminfo capability for the current terminal. Note that the output of :func: ` putp `
509- always goes to standard output.
510+ terminfo capability, a bytes object, for the current terminal.
511+ Note that the output of :func: ` putp ` always goes to standard output.
510512
511513 :func: `setupterm ` (or :func: `initscr `) must be called first.
512514
@@ -677,7 +679,7 @@ The module :mod:`!curses` defines the following functions:
677679.. function :: tparm(str[, ...])
678680
679681 Instantiate the bytes object *str * with the supplied parameters, where *str * should
680- be a parameterized string obtained from the terminfo database. For example,
682+ be a parameterized byte string obtained from the terminfo database. For example,
681683 ``tparm(tigetstr("cup"), 5, 3) `` could result in ``b'\033[6;4H' ``, the exact
682684 result depending on terminal type. Up to nine integer parameters may be supplied.
683685
@@ -698,7 +700,8 @@ The module :mod:`!curses` defines the following functions:
698700
699701.. function :: unctrl(ch)
700702
701- Return a bytes object which is a printable representation of the character *ch *.
703+ Return a bytes object which is a printable representation of the character *ch *;
704+ any attributes and color pair are ignored.
702705 Control characters are represented as a caret followed by the character, for
703706 example as ``b'^C' ``. Printing characters are left as they are.
704707
@@ -707,6 +710,9 @@ The module :mod:`!curses` defines the following functions:
707710
708711 Push *ch * so the next :meth: `~window.getch ` will return it.
709712
713+ *ch * may be an integer (a key code or the code of an encoded byte), a byte,
714+ or a string of length 1 which encodes to a single byte.
715+
710716 .. note ::
711717
712718 Only one *ch * can be pushed before :meth: `!getch ` is called.
@@ -724,6 +730,9 @@ The module :mod:`!curses` defines the following functions:
724730
725731 Push *ch * so the next :meth: `~window.get_wch ` will return it.
726732
733+ *ch * may be an integer (a character code, not a key code) or a string of
734+ length 1.
735+
727736 .. note ::
728737
729738 Only one *ch * can be pushed before :meth: `!get_wch ` is called.
@@ -1004,27 +1013,58 @@ Window objects
10041013
10051014.. method :: window.getch([y, x])
10061015
1007- Get a character. Note that the integer returned does *not * have to be in ASCII
1008- range: function keys, keypad keys and so on are represented by numbers higher
1009- than 255. In no-delay mode, return ``-1 `` if there is no input, otherwise
1010- wait until a key is pressed.
1016+ Read a key press, after moving the cursor to *y *, *x * if specified,
1017+ and return it as an integer.
1018+ The window is refreshed first if it is not a pad and was modified since
1019+ the last refresh.
1020+ Wait until a key is pressed, or return ``-1 `` if the read is non-blocking
1021+ or times out (see :meth: `nodelay ` and :meth: `timeout `).
1022+
1023+ An ordinary key is returned as the code of a single byte of its encoding
1024+ in the current locale,
1025+ so a character encoded with several bytes takes several calls.
1026+ For example, in a UTF-8 locale ``'é' `` is read as ``195 ``, then ``169 ``.
1027+ Use :meth: `get_wch ` to read it as a single character.
1028+
1029+ In keypad mode (see :meth: `keypad `) function keys and other special keys
1030+ are returned as one of the :ref: `KEY_* constants <curses-key-constants >`,
1031+ which cannot be mistaken for an ordinary key.
1032+ Otherwise, or if their escape sequence does not arrive in time
1033+ (see :meth: `notimeout ` and :func: `set_escdelay `),
1034+ their bytes are returned one at a time.
1035+
1036+ In echo mode (see :func: `echo `) the key is added to the window as by
1037+ :meth: `addch `; special keys are not echoed.
10111038
10121039
10131040.. method :: window.get_wch([y, x])
10141041
1015- Get a wide character. Return a character for most keys, or an integer for
1016- function keys, keypad keys, and other special keys.
1017- In no-delay mode, raise an exception if there is no input.
1042+ Read a key press, after moving the cursor to *y *, *x * if specified,
1043+ and return it as a one-character :class: `str `.
1044+ The window is refreshed first if it is not a pad and was modified since
1045+ the last refresh.
1046+ Wait until a key is pressed, or raise :exc: `error ` if the read is
1047+ non-blocking or times out (see :meth: `nodelay ` and :meth: `timeout `).
1048+
1049+ In keypad mode (see :meth: `keypad `) function keys and other special keys
1050+ are returned as one of the :ref: `KEY_* constants <curses-key-constants >`,
1051+ an integer.
1052+ Otherwise, or if their escape sequence does not arrive in time
1053+ (see :meth: `notimeout ` and :func: `set_escdelay `),
1054+ their characters are returned one at a time.
1055+
1056+ In echo mode (see :func: `echo `) the key is added to the window as by
1057+ :meth: `addch `; special keys are not echoed.
10181058
10191059 .. versionadded :: 3.3
10201060
10211061
10221062.. method :: window.getkey([y, x])
10231063
1024- Get a character, returning a string instead of an integer, as :meth: ` getch `
1025- does. Function keys, keypad keys and other special keys return a multibyte
1026- string containing the key name. In no-delay mode, raise an exception if
1027- there is no input.
1064+ Read a key press as :meth: ` getch ` does, but return it as a :class: ` str `:
1065+ an ordinary key as a one-character string, the byte decoded as Latin-1,
1066+ and a special key as its name, such as `` 'KEY_UP' `` (see :func: ` keyname `).
1067+ Raise :exc: ` error ` instead of returning `` -1 `` if there is no input.
10281068
10291069
10301070.. method :: window.getmaxyx()
@@ -1044,8 +1084,11 @@ Window objects
10441084 window.getstr(y, x)
10451085 window.getstr(y, x, n)
10461086
1047- Read a bytes object from the user, with primitive line editing capacity.
1048- At most *n * characters are read;
1087+ Read a line of input from the user, with primitive line editing capacity,
1088+ after moving the cursor to *y *, *x * if specified.
1089+ Return it as a bytes object, in the encoding of the current locale
1090+ and without the terminating newline.
1091+ At most *n * bytes are read;
10491092 *n * defaults to and cannot exceed 2047.
10501093
10511094 .. versionchanged :: 3.14
@@ -1147,12 +1190,11 @@ Window objects
11471190.. method :: window.instr([n])
11481191 window.instr(y, x[, n])
11491192
1150- Return a bytes object of characters, extracted from the window starting at the
1151- current cursor position, or at *y *, *x * if specified, and stopping at the end
1152- of the line. Attributes and color information are stripped
1153- from the characters. If *n * is specified, :meth: `instr ` returns a string
1154- at most *n * characters long (exclusive of the trailing NUL).
1155- The maximum value for *n * is 2047.
1193+ Read the text of the window from the current cursor position,
1194+ or from *y *, *x * if specified, to the end of the line,
1195+ and return it as a bytes object, in the encoding of the current locale.
1196+ Attributes and color pairs are stripped.
1197+ At most *n * bytes are read; *n * defaults to and cannot exceed 2047.
11561198
11571199 .. versionchanged :: 3.14
11581200 The maximum value for *n * was increased from 1023 to 2047.
@@ -1176,6 +1218,8 @@ Window objects
11761218 If *flag * is ``True ``, escape sequences generated by some keys (keypad, function keys)
11771219 will be interpreted by :mod: `!curses `. If *flag * is ``False ``, escape sequences will be
11781220 left as is in the input stream.
1221+ Keypad mode is disabled by default, but :func: `wrapper ` enables it for the
1222+ main window.
11791223
11801224
11811225.. method :: window.leaveok(flag)
@@ -1528,6 +1572,8 @@ by some methods.
15281572| | color-pair field information |
15291573+-------------------------+-------------------------------+
15301574
1575+ .. _curses-key-constants :
1576+
15311577Keys are referred to by integer constants with names starting with ``KEY_ ``.
15321578The exact keycaps available are system dependent.
15331579
![pydoc-zh-tw[bot]](https://avatars.githubusercontent.com/in/137018?v=4&size=40){kind=avatar}
0 commit comments