1:mod:`curses` --- Terminal handling for character-cell displays
2===============================================================
3
4.. module:: curses
5   :synopsis: An interface to the curses library, providing portable
6              terminal handling.
7   :platform: Unix
8
9.. sectionauthor:: Moshe Zadka <[email protected]>
10.. sectionauthor:: Eric Raymond <[email protected]>
11
12**Source code:** :source:`Lib/curses`
13
14--------------
15
16The :mod:`curses` module provides an interface to the curses library, the
17de-facto standard for portable advanced terminal handling.
18
19While curses is most widely used in the Unix environment, versions are available
20for Windows, DOS, and possibly other systems as well.  This extension module is
21designed to match the API of ncurses, an open-source curses library hosted on
22Linux and the BSD variants of Unix.
23
24.. note::
25
26   Whenever the documentation mentions a *character* it can be specified
27   as an integer, a one-character Unicode string or a one-byte byte string.
28
29   Whenever the documentation mentions a *character string* it can be specified
30   as a Unicode string or a byte string.
31
32.. seealso::
33
34   Module :mod:`curses.ascii`
35      Utilities for working with ASCII characters, regardless of your locale settings.
36
37   Module :mod:`curses.panel`
38      A panel stack extension that adds depth to  curses windows.
39
40   Module :mod:`curses.textpad`
41      Editable text widget for curses supporting  :program:`Emacs`\ -like bindings.
42
43   :ref:`curses-howto`
44      Tutorial material on using curses with Python, by Andrew Kuchling and Eric
45      Raymond.
46
47   The :source:`Tools/demo/` directory in the Python source distribution contains
48   some example programs using the curses bindings provided by this module.
49
50
51.. _curses-functions:
52
53Functions
54---------
55
56The module :mod:`curses` defines the following exception:
57
58
59.. exception:: error
60
61   Exception raised when a curses library function returns an error.
62
63.. note::
64
65   Whenever *x* or *y* arguments to a function or a method are optional, they
66   default to the current cursor location. Whenever *attr* is optional, it defaults
67   to :const:`A_NORMAL`.
68
69The module :mod:`curses` defines the following functions:
70
71
72.. function:: baudrate()
73
74   Return the output speed of the terminal in bits per second.  On software
75   terminal emulators it will have a fixed high value. Included for historical
76   reasons; in former times, it was used to  write output loops for time delays and
77   occasionally to change interfaces depending on the line speed.
78
79
80.. function:: beep()
81
82   Emit a short attention sound.
83
84
85.. function:: can_change_color()
86
87   Return ``True`` or ``False``, depending on whether the programmer can change the colors
88   displayed by the terminal.
89
90
91.. function:: cbreak()
92
93   Enter cbreak mode.  In cbreak mode (sometimes called "rare" mode) normal tty
94   line buffering is turned off and characters are available to be read one by one.
95   However, unlike raw mode, special characters (interrupt, quit, suspend, and flow
96   control) retain their effects on the tty driver and calling program.  Calling
97   first :func:`raw` then :func:`cbreak` leaves the terminal in cbreak mode.
98
99
100.. function:: color_content(color_number)
101
102   Return the intensity of the red, green, and blue (RGB) components in the color
103   *color_number*, which must be between ``0`` and ``COLORS - 1``.  Return a 3-tuple,
104   containing the R,G,B values for the given color, which will be between
105   ``0`` (no component) and ``1000`` (maximum amount of component).
106
107
108.. function:: color_pair(pair_number)
109
110   Return the attribute value for displaying text in the specified color pair.
111   Only the first 256 color pairs are supported. This
112   attribute value can be combined with :const:`A_STANDOUT`, :const:`A_REVERSE`,
113   and the other :const:`!A_\*` attributes.  :func:`pair_number` is the counterpart
114   to this function.
115
116
117.. function:: curs_set(visibility)
118
119   Set the cursor state.  *visibility* can be set to ``0``, ``1``, or ``2``, for invisible,
120   normal, or very visible.  If the terminal supports the visibility requested, return the
121   previous cursor state; otherwise raise an exception.  On many
122   terminals, the "visible" mode is an underline cursor and the "very visible" mode
123   is a block cursor.
124
125
126.. function:: def_prog_mode()
127
128   Save the current terminal mode as the "program" mode, the mode when the running
129   program is using curses.  (Its counterpart is the "shell" mode, for when the
130   program is not in curses.)  Subsequent calls to :func:`reset_prog_mode` will
131   restore this mode.
132
133
134.. function:: def_shell_mode()
135
136   Save the current terminal mode as the "shell" mode, the mode when the running
137   program is not using curses.  (Its counterpart is the "program" mode, when the
138   program is using curses capabilities.) Subsequent calls to
139   :func:`reset_shell_mode` will restore this mode.
140
141
142.. function:: delay_output(ms)
143
144   Insert an *ms* millisecond pause in output.
145
146
147.. function:: doupdate()
148
149   Update the physical screen.  The curses library keeps two data structures, one
150   representing the current physical screen contents and a virtual screen
151   representing the desired next state.  The :func:`doupdate` ground updates the
152   physical screen to match the virtual screen.
153
154   The virtual screen may be updated by a :meth:`~window.noutrefresh` call after write
155   operations such as :meth:`~window.addstr` have been performed on a window.  The normal
156   :meth:`~window.refresh` call is simply :meth:`!noutrefresh` followed by :func:`!doupdate`;
157   if you have to update multiple windows, you can speed performance and perhaps
158   reduce screen flicker by issuing :meth:`!noutrefresh` calls on all windows,
159   followed by a single :func:`!doupdate`.
160
161
162.. function:: echo()
163
164   Enter echo mode.  In echo mode, each character input is echoed to the screen as
165   it is entered.
166
167
168.. function:: endwin()
169
170   De-initialize the library, and return terminal to normal status.
171
172
173.. function:: erasechar()
174
175   Return the user's current erase character as a one-byte bytes object.  Under Unix operating systems this
176   is a property of the controlling tty of the curses program, and is not set by
177   the curses library itself.
178
179
180.. function:: filter()
181
182   The :func:`.filter` routine, if used, must be called before :func:`initscr` is
183   called.  The effect is that, during those calls, :envvar:`LINES` is set to ``1``; the
184   capabilities ``clear``, ``cup``, ``cud``, ``cud1``, ``cuu1``, ``cuu``, ``vpa`` are disabled; and the ``home``
185   string is set to the value of ``cr``. The effect is that the cursor is confined to
186   the current line, and so are screen updates.  This may be used for enabling
187   character-at-a-time  line editing without touching the rest of the screen.
188
189
190.. function:: flash()
191
192   Flash the screen.  That is, change it to reverse-video and then change it back
193   in a short interval.  Some people prefer such as 'visible bell' to the audible
194   attention signal produced by :func:`beep`.
195
196
197.. function:: flushinp()
198
199   Flush all input buffers.  This throws away any  typeahead  that  has been typed
200   by the user and has not yet been processed by the program.
201
202
203.. function:: getmouse()
204
205   After :meth:`~window.getch` returns :const:`KEY_MOUSE` to signal a mouse event, this
206   method should be called to retrieve the queued mouse event, represented as a
207   5-tuple ``(id, x, y, z, bstate)``. *id* is an ID value used to distinguish
208   multiple devices, and *x*, *y*, *z* are the event's coordinates.  (*z* is
209   currently unused.)  *bstate* is an integer value whose bits will be set to
210   indicate the type of event, and will be the bitwise OR of one or more of the
211   following constants, where *n* is the button number from 1 to 5:
212   :const:`BUTTONn_PRESSED`, :const:`BUTTONn_RELEASED`, :const:`BUTTONn_CLICKED`,
213   :const:`BUTTONn_DOUBLE_CLICKED`, :const:`BUTTONn_TRIPLE_CLICKED`,
214   :const:`BUTTON_SHIFT`, :const:`BUTTON_CTRL`, :const:`BUTTON_ALT`.
215
216   .. versionchanged:: 3.10
217      The ``BUTTON5_*`` constants are now exposed if they are provided by the
218      underlying curses library.
219
220
221.. function:: getsyx()
222
223   Return the current coordinates of the virtual screen cursor as a tuple
224   ``(y, x)``.  If :meth:`leaveok <window.leaveok>` is currently ``True``, then return ``(-1, -1)``.
225
226
227.. function:: getwin(file)
228
229   Read window related data stored in the file by an earlier :func:`window.putwin` call.
230   The routine then creates and initializes a new window using that data, returning
231   the new window object.
232
233
234.. function:: has_colors()
235
236   Return ``True`` if the terminal can display colors; otherwise, return ``False``.
237
238.. function:: has_extended_color_support()
239
240   Return ``True`` if the module supports extended colors; otherwise, return
241   ``False``. Extended color support allows more than 256 color pairs for
242   terminals that support more than 16 colors (e.g. xterm-256color).
243
244   Extended color support requires ncurses version 6.1 or later.
245
246   .. versionadded:: 3.10
247
248.. function:: has_ic()
249
250   Return ``True`` if the terminal has insert- and delete-character capabilities.
251   This function is included for historical reasons only, as all modern software
252   terminal emulators have such capabilities.
253
254
255.. function:: has_il()
256
257   Return ``True`` if the terminal has insert- and delete-line capabilities, or can
258   simulate  them  using scrolling regions. This function is included for
259   historical reasons only, as all modern software terminal emulators have such
260   capabilities.
261
262
263.. function:: has_key(ch)
264
265   Take a key value *ch*, and return ``True`` if the current terminal type recognizes
266   a key with that value.
267
268
269.. function:: halfdelay(tenths)
270
271   Used for half-delay mode, which is similar to cbreak mode in that characters
272   typed by the user are immediately available to the program. However, after
273   blocking for *tenths* tenths of seconds, raise an exception if nothing has
274   been typed.  The value of *tenths* must be a number between ``1`` and ``255``.  Use
275   :func:`nocbreak` to leave half-delay mode.
276
277
278.. function:: init_color(color_number, r, g, b)
279
280   Change the definition of a color, taking the number of the color to be changed
281   followed by three RGB values (for the amounts of red, green, and blue
282   components).  The value of *color_number* must be between ``0`` and
283   ``COLORS - 1``.  Each of *r*, *g*, *b*, must be a value between ``0`` and
284   ``1000``.  When :func:`init_color` is used, all occurrences of that color on the
285   screen immediately change to the new definition.  This function is a no-op on
286   most terminals; it is active only if :func:`can_change_color` returns ``True``.
287
288
289.. function:: init_pair(pair_number, fg, bg)
290
291   Change the definition of a color-pair.  It takes three arguments: the number of
292   the color-pair to be changed, the foreground color number, and the background
293   color number.  The value of *pair_number* must be between ``1`` and
294   ``COLOR_PAIRS - 1`` (the ``0`` color pair is wired to white on black and cannot
295   be changed).  The value of *fg* and *bg* arguments must be between ``0`` and
296   ``COLORS - 1``, or, after calling :func:`use_default_colors`, ``-1``.
297   If the color-pair was previously initialized, the screen is
298   refreshed and all occurrences of that color-pair are changed to the new
299   definition.
300
301
302.. function:: initscr()
303
304   Initialize the library. Return a :ref:`window <curses-window-objects>` object
305   which represents the whole screen.
306
307   .. note::
308
309      If there is an error opening the terminal, the underlying curses library may
310      cause the interpreter to exit.
311
312
313.. function:: is_term_resized(nlines, ncols)
314
315   Return ``True`` if :func:`resize_term` would modify the window structure,
316   ``False`` otherwise.
317
318
319.. function:: isendwin()
320
321   Return ``True`` if :func:`endwin` has been called (that is, the  curses library has
322   been deinitialized).
323
324
325.. function:: keyname(k)
326
327   Return the name of the key numbered *k* as a bytes object.  The name of a key generating printable
328   ASCII character is the key's character.  The name of a control-key combination
329   is a two-byte bytes object consisting of a caret (``b'^'``) followed by the corresponding
330   printable ASCII character.  The name of an alt-key combination (128--255) is a
331   bytes object consisting of the prefix ``b'M-'`` followed by the name of the corresponding
332   ASCII character.
333
334
335.. function:: killchar()
336
337   Return the user's current line kill character as a one-byte bytes object. Under Unix operating systems
338   this is a property of the controlling tty of the curses program, and is not set
339   by the curses library itself.
340
341
342.. function:: longname()
343
344   Return a bytes object containing the terminfo long name field describing the current
345   terminal.  The maximum length of a verbose description is 128 characters.  It is
346   defined only after the call to :func:`initscr`.
347
348
349.. function:: meta(flag)
350
351   If *flag* is ``True``, allow 8-bit characters to be input.  If
352   *flag* is ``False``,  allow only 7-bit chars.
353
354
355.. function:: mouseinterval(interval)
356
357   Set the maximum time in milliseconds that can elapse between press and release
358   events in order for them to be recognized as a click, and return the previous
359   interval value.  The default value is 200 milliseconds, or one fifth of a second.
360
361
362.. function:: mousemask(mousemask)
363
364   Set the mouse events to be reported, and return a tuple ``(availmask,
365   oldmask)``.   *availmask* indicates which of the specified mouse events can be
366   reported; on complete failure it returns ``0``.  *oldmask* is the previous value of
367   the given window's mouse event mask.  If this function is never called, no mouse
368   events are ever reported.
369
370
371.. function:: napms(ms)
372
373   Sleep for *ms* milliseconds.
374
375
376.. function:: newpad(nlines, ncols)
377
378   Create and return a pointer to a new pad data structure with the given number
379   of lines and columns.  Return a pad as a window object.
380
381   A pad is like a window, except that it is not restricted by the screen size, and
382   is not necessarily associated with a particular part of the screen.  Pads can be
383   used when a large window is needed, and only a part of the window will be on the
384   screen at one time.  Automatic refreshes of pads (such as from scrolling or
385   echoing of input) do not occur.  The :meth:`~window.refresh` and :meth:`~window.noutrefresh`
386   methods of a pad require 6 arguments to specify the part of the pad to be
387   displayed and the location on the screen to be used for the display. The
388   arguments are *pminrow*, *pmincol*, *sminrow*, *smincol*, *smaxrow*, *smaxcol*; the *p*
389   arguments refer to the upper left corner of the pad region to be displayed and
390   the *s* arguments define a clipping box on the screen within which the pad region
391   is to be displayed.
392
393
394.. function:: newwin(nlines, ncols)
395              newwin(nlines, ncols, begin_y, begin_x)
396
397   Return a new :ref:`window <curses-window-objects>`, whose left-upper corner
398   is at  ``(begin_y, begin_x)``, and whose height/width is  *nlines*/*ncols*.
399
400   By default, the window will extend from the  specified position to the lower
401   right corner of the screen.
402
403
404.. function:: nl()
405
406   Enter newline mode.  This mode translates the return key into newline on input,
407   and translates newline into return and line-feed on output. Newline mode is
408   initially on.
409
410
411.. function:: nocbreak()
412
413   Leave cbreak mode.  Return to normal "cooked" mode with line buffering.
414
415
416.. function:: noecho()
417
418   Leave echo mode.  Echoing of input characters is turned off.
419
420
421.. function:: nonl()
422
423   Leave newline mode.  Disable translation of return into newline on input, and
424   disable low-level translation of newline into newline/return on output (but this
425   does not change the behavior of ``addch('\n')``, which always does the
426   equivalent of return and line feed on the virtual screen).  With translation
427   off, curses can sometimes speed up vertical motion a little; also, it will be
428   able to detect the return key on input.
429
430
431.. function:: noqiflush()
432
433   When the :func:`!noqiflush` routine is used, normal flush of input and output queues
434   associated with the ``INTR``, ``QUIT`` and ``SUSP`` characters will not be done.  You may
435   want to call :func:`!noqiflush` in a signal handler if you want output to
436   continue as though the interrupt had not occurred, after the handler exits.
437
438
439.. function:: noraw()
440
441   Leave raw mode. Return to normal "cooked" mode with line buffering.
442
443
444.. function:: pair_content(pair_number)
445
446   Return a tuple ``(fg, bg)`` containing the colors for the requested color pair.
447   The value of *pair_number* must be between ``0`` and ``COLOR_PAIRS - 1``.
448
449
450.. function:: pair_number(attr)
451
452   Return the number of the color-pair set by the attribute value *attr*.
453   :func:`color_pair` is the counterpart to this function.
454
455
456.. function:: putp(str)
457
458   Equivalent to ``tputs(str, 1, putchar)``; emit the value of a specified
459   terminfo capability for the current terminal.  Note that the output of :func:`putp`
460   always goes to standard output.
461
462
463.. function:: qiflush([flag])
464
465   If *flag* is ``False``, the effect is the same as calling :func:`noqiflush`. If
466   *flag* is ``True``, or no argument is provided, the queues will be flushed when
467   these control characters are read.
468
469
470.. function:: raw()
471
472   Enter raw mode.  In raw mode, normal line buffering and  processing of
473   interrupt, quit, suspend, and flow control keys are turned off; characters are
474   presented to curses input functions one by one.
475
476
477.. function:: reset_prog_mode()
478
479   Restore the  terminal  to "program" mode, as previously saved  by
480   :func:`def_prog_mode`.
481
482
483.. function:: reset_shell_mode()
484
485   Restore the  terminal  to "shell" mode, as previously saved  by
486   :func:`def_shell_mode`.
487
488
489.. function:: resetty()
490
491   Restore the state of the terminal modes to what it was at the last call to
492   :func:`savetty`.
493
494
495.. function:: resize_term(nlines, ncols)
496
497   Backend function used by :func:`resizeterm`, performing most of the work;
498   when resizing the windows, :func:`resize_term` blank-fills the areas that are
499   extended.  The calling application should fill in these areas with
500   appropriate data.  The :func:`!resize_term` function attempts to resize all
501   windows.  However, due to the calling convention of pads, it is not possible
502   to resize these without additional interaction with the application.
503
504
505.. function:: resizeterm(nlines, ncols)
506
507   Resize the standard and current windows to the specified dimensions, and
508   adjusts other bookkeeping data used by the curses library that record the
509   window dimensions (in particular the SIGWINCH handler).
510
511
512.. function:: savetty()
513
514   Save the current state of the terminal modes in a buffer, usable by
515   :func:`resetty`.
516
517.. function:: get_escdelay()
518
519   Retrieves the value set by :func:`set_escdelay`.
520
521   .. versionadded:: 3.9
522
523.. function:: set_escdelay(ms)
524
525   Sets the number of milliseconds to wait after reading an escape character,
526   to distinguish between an individual escape character entered on the
527   keyboard from escape sequences sent by cursor and function keys.
528
529   .. versionadded:: 3.9
530
531.. function:: get_tabsize()
532
533   Retrieves the value set by :func:`set_tabsize`.
534
535   .. versionadded:: 3.9
536
537.. function:: set_tabsize(size)
538
539   Sets the number of columns used by the curses library when converting a tab
540   character to spaces as it adds the tab to a window.
541
542   .. versionadded:: 3.9
543
544.. function:: setsyx(y, x)
545
546   Set the virtual screen cursor to *y*, *x*. If *y* and *x* are both ``-1``, then
547   :meth:`leaveok <window.leaveok>` is set ``True``.
548
549
550.. function:: setupterm(term=None, fd=-1)
551
552   Initialize the terminal.  *term* is a string giving
553   the terminal name, or ``None``; if omitted or ``None``, the value of the
554   :envvar:`TERM` environment variable will be used.  *fd* is the
555   file descriptor to which any initialization sequences will be sent; if not
556   supplied or ``-1``, the file descriptor for ``sys.stdout`` will be used.
557
558
559.. function:: start_color()
560
561   Must be called if the programmer wants to use colors, and before any other color
562   manipulation routine is called.  It is good practice to call this routine right
563   after :func:`initscr`.
564
565   :func:`start_color` initializes eight basic colors (black, red,  green, yellow,
566   blue, magenta, cyan, and white), and two global variables in the :mod:`curses`
567   module, :const:`COLORS` and :const:`COLOR_PAIRS`, containing the maximum number
568   of colors and color-pairs the terminal can support.  It also restores the colors
569   on the terminal to the values they had when the terminal was just turned on.
570
571
572.. function:: termattrs()
573
574   Return a logical OR of all video attributes supported by the terminal.  This
575   information is useful when a curses program needs complete control over the
576   appearance of the screen.
577
578
579.. function:: termname()
580
581   Return the value of the environment variable :envvar:`TERM`, as a bytes object,
582   truncated to 14 characters.
583
584
585.. function:: tigetflag(capname)
586
587   Return the value of the Boolean capability corresponding to the terminfo
588   capability name *capname* as an integer.  Return the value ``-1`` if *capname* is not a
589   Boolean capability, or ``0`` if it is canceled or absent from the terminal
590   description.
591
592
593.. function:: tigetnum(capname)
594
595   Return the value of the numeric capability corresponding to the terminfo
596   capability name *capname* as an integer.  Return the value ``-2`` if *capname* is not a
597   numeric capability, or ``-1`` if it is canceled or absent from the terminal
598   description.
599
600
601.. function:: tigetstr(capname)
602
603   Return the value of the string capability corresponding to the terminfo
604   capability name *capname* as a bytes object.  Return ``None`` if *capname*
605   is not a terminfo "string capability", or is canceled or absent from the
606   terminal description.
607
608
609.. function:: tparm(str[, ...])
610
611   Instantiate the bytes object *str* with the supplied parameters, where *str* should
612   be a parameterized string obtained from the terminfo database.  E.g.
613   ``tparm(tigetstr("cup"), 5, 3)`` could result in ``b'\033[6;4H'``, the exact
614   result depending on terminal type.
615
616
617.. function:: typeahead(fd)
618
619   Specify that the file descriptor *fd* be used for typeahead checking.  If *fd*
620   is ``-1``, then no typeahead checking is done.
621
622   The curses library does "line-breakout optimization" by looking for typeahead
623   periodically while updating the screen.  If input is found, and it is coming
624   from a tty, the current update is postponed until refresh or doupdate is called
625   again, allowing faster response to commands typed in advance. This function
626   allows specifying a different file descriptor for typeahead checking.
627
628
629.. function:: unctrl(ch)
630
631   Return a bytes object which is a printable representation of the character *ch*.
632   Control characters are represented as a caret followed by the character, for
633   example as ``b'^C'``. Printing characters are left as they are.
634
635
636.. function:: ungetch(ch)
637
638   Push *ch* so the next :meth:`~window.getch` will return it.
639
640   .. note::
641
642      Only one *ch* can be pushed before :meth:`!getch` is called.
643
644
645.. function:: update_lines_cols()
646
647   Update :envvar:`LINES` and :envvar:`COLS`. Useful for detecting manual screen resize.
648
649   .. versionadded:: 3.5
650
651
652.. function:: unget_wch(ch)
653
654   Push *ch* so the next :meth:`~window.get_wch` will return it.
655
656   .. note::
657
658      Only one *ch* can be pushed before :meth:`!get_wch` is called.
659
660   .. versionadded:: 3.3
661
662
663.. function:: ungetmouse(id, x, y, z, bstate)
664
665   Push a :const:`KEY_MOUSE` event onto the input queue, associating the given
666   state data with it.
667
668
669.. function:: use_env(flag)
670
671   If used, this function should be called before :func:`initscr` or newterm are
672   called.  When *flag* is ``False``, the values of lines and columns specified in the
673   terminfo database will be used, even if environment variables :envvar:`LINES`
674   and :envvar:`COLUMNS` (used by default) are set, or if curses is running in a
675   window (in which case default behavior would be to use the window size if
676   :envvar:`LINES` and :envvar:`COLUMNS` are not set).
677
678
679.. function:: use_default_colors()
680
681   Allow use of default values for colors on terminals supporting this feature. Use
682   this to support transparency in your application.  The default color is assigned
683   to the color number ``-1``. After calling this function,  ``init_pair(x,
684   curses.COLOR_RED, -1)`` initializes, for instance, color pair *x* to a red
685   foreground color on the default background.
686
687
688.. function:: wrapper(func, /, *args, **kwargs)
689
690   Initialize curses and call another callable object, *func*, which should be the
691   rest of your curses-using application.  If the application raises an exception,
692   this function will restore the terminal to a sane state before re-raising the
693   exception and generating a traceback.  The callable object *func* is then passed
694   the main window 'stdscr' as its first argument, followed by any other arguments
695   passed to :func:`!wrapper`.  Before calling *func*, :func:`!wrapper` turns on
696   cbreak mode, turns off echo, enables the terminal keypad, and initializes colors
697   if the terminal has color support.  On exit (whether normally or by exception)
698   it restores cooked mode, turns on echo, and disables the terminal keypad.
699
700
701.. _curses-window-objects:
702
703Window Objects
704--------------
705
706Window objects, as returned by :func:`initscr` and :func:`newwin` above, have
707the following methods and attributes:
708
709
710.. method:: window.addch(ch[, attr])
711            window.addch(y, x, ch[, attr])
712
713   Paint character *ch* at ``(y, x)`` with attributes *attr*, overwriting any
714   character previously painted at that location.  By default, the character
715   position and attributes are the current settings for the window object.
716
717   .. note::
718
719      Writing outside the window, subwindow, or pad raises a :exc:`curses.error`.
720      Attempting to write to the lower right corner of a window, subwindow,
721      or pad will cause an exception to be raised after the character is printed.
722
723
724.. method:: window.addnstr(str, n[, attr])
725            window.addnstr(y, x, str, n[, attr])
726
727   Paint at most *n* characters of the character string *str* at
728   ``(y, x)`` with attributes
729   *attr*, overwriting anything previously on the display.
730
731
732.. method:: window.addstr(str[, attr])
733            window.addstr(y, x, str[, attr])
734
735   Paint the character string *str* at ``(y, x)`` with attributes
736   *attr*, overwriting anything previously on the display.
737
738   .. note::
739
740      * Writing outside the window, subwindow, or pad raises :exc:`curses.error`.
741        Attempting to write to the lower right corner of a window, subwindow,
742        or pad will cause an exception to be raised after the string is printed.
743
744      * A `bug in ncurses <https://bugs.python.org/issue35924>`_, the backend
745        for this Python module, can cause SegFaults when resizing windows. This
746        is fixed in ncurses-6.1-20190511.  If you are stuck with an earlier
747        ncurses, you can avoid triggering this if you do not call :func:`addstr`
748        with a *str* that has embedded newlines.  Instead, call :func:`addstr`
749        separately for each line.
750
751
752.. method:: window.attroff(attr)
753
754   Remove attribute *attr* from the "background" set applied to all writes to the
755   current window.
756
757
758.. method:: window.attron(attr)
759
760   Add attribute *attr* from the "background" set applied to all writes to the
761   current window.
762
763
764.. method:: window.attrset(attr)
765
766   Set the "background" set of attributes to *attr*.  This set is initially
767   ``0`` (no attributes).
768
769
770.. method:: window.bkgd(ch[, attr])
771
772   Set the background property of the window to the character *ch*, with
773   attributes *attr*.  The change is then applied to every character position in
774   that window:
775
776   * The attribute of every character in the window  is changed to the new
777     background attribute.
778
779   * Wherever  the  former background character appears, it is changed to the new
780     background character.
781
782
783.. method:: window.bkgdset(ch[, attr])
784
785   Set the window's background.  A window's background consists of a character and
786   any combination of attributes.  The attribute part of the background is combined
787   (OR'ed) with all non-blank characters that are written into the window.  Both
788   the character and attribute parts of the background are combined with the blank
789   characters.  The background becomes a property of the character and moves with
790   the character through any scrolling and insert/delete line/character operations.
791
792
793.. method:: window.border([ls[, rs[, ts[, bs[, tl[, tr[, bl[, br]]]]]]]])
794
795   Draw a border around the edges of the window. Each parameter specifies  the
796   character to use for a specific part of the border; see the table below for more
797   details.
798
799   .. note::
800
801      A ``0`` value for any parameter will cause the default character to be used for
802      that parameter.  Keyword parameters can *not* be used.  The defaults are listed
803      in this table:
804
805   +-----------+---------------------+-----------------------+
806   | Parameter | Description         | Default value         |
807   +===========+=====================+=======================+
808   | *ls*      | Left side           | :const:`ACS_VLINE`    |
809   +-----------+---------------------+-----------------------+
810   | *rs*      | Right side          | :const:`ACS_VLINE`    |
811   +-----------+---------------------+-----------------------+
812   | *ts*      | Top                 | :const:`ACS_HLINE`    |
813   +-----------+---------------------+-----------------------+
814   | *bs*      | Bottom              | :const:`ACS_HLINE`    |
815   +-----------+---------------------+-----------------------+
816   | *tl*      | Upper-left corner   | :const:`ACS_ULCORNER` |
817   +-----------+---------------------+-----------------------+
818   | *tr*      | Upper-right corner  | :const:`ACS_URCORNER` |
819   +-----------+---------------------+-----------------------+
820   | *bl*      | Bottom-left corner  | :const:`ACS_LLCORNER` |
821   +-----------+---------------------+-----------------------+
822   | *br*      | Bottom-right corner | :const:`ACS_LRCORNER` |
823   +-----------+---------------------+-----------------------+
824
825
826.. method:: window.box([vertch, horch])
827
828   Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* and
829   *bs* are *horch*.  The default corner characters are always used by this function.
830
831
832.. method:: window.chgat(attr)
833            window.chgat(num, attr)
834            window.chgat(y, x, attr)
835            window.chgat(y, x, num, attr)
836
837   Set the attributes of *num* characters at the current cursor position, or at
838   position ``(y, x)`` if supplied. If *num* is not given or is ``-1``,
839   the attribute will be set on all the characters to the end of the line.  This
840   function moves cursor to position ``(y, x)`` if supplied. The changed line
841   will be touched using the :meth:`touchline` method so that the contents will
842   be redisplayed by the next window refresh.
843
844
845.. method:: window.clear()
846
847   Like :meth:`erase`, but also cause the whole window to be repainted upon next
848   call to :meth:`refresh`.
849
850
851.. method:: window.clearok(flag)
852
853   If *flag* is ``True``, the next call to :meth:`refresh` will clear the window
854   completely.
855
856
857.. method:: window.clrtobot()
858
859   Erase from cursor to the end of the window: all lines below the cursor are
860   deleted, and then the equivalent of :meth:`clrtoeol` is performed.
861
862
863.. method:: window.clrtoeol()
864
865   Erase from cursor to the end of the line.
866
867
868.. method:: window.cursyncup()
869
870   Update the current cursor position of all the ancestors of the window to
871   reflect the current cursor position of the window.
872
873
874.. method:: window.delch([y, x])
875
876   Delete any character at ``(y, x)``.
877
878
879.. method:: window.deleteln()
880
881   Delete the line under the cursor. All following lines are moved up by one line.
882
883
884.. method:: window.derwin(begin_y, begin_x)
885            window.derwin(nlines, ncols, begin_y, begin_x)
886
887   An abbreviation for "derive window", :meth:`derwin` is the same as calling
888   :meth:`subwin`, except that *begin_y* and *begin_x* are relative to the origin
889   of the window, rather than relative to the entire screen.  Return a window
890   object for the derived window.
891
892
893.. method:: window.echochar(ch[, attr])
894
895   Add character *ch* with attribute *attr*, and immediately  call :meth:`refresh`
896   on the window.
897
898
899.. method:: window.enclose(y, x)
900
901   Test whether the given pair of screen-relative character-cell coordinates are
902   enclosed by the given window, returning ``True`` or ``False``.  It is useful for
903   determining what subset of the screen windows enclose the location of a mouse
904   event.
905
906   .. versionchanged:: 3.10
907      Previously it returned ``1`` or ``0`` instead of ``True`` or ``False``.
908
909
910.. attribute:: window.encoding
911
912   Encoding used to encode method arguments (Unicode strings and characters).
913   The encoding attribute is inherited from the parent window when a subwindow
914   is created, for example with :meth:`window.subwin`.
915   By default, current locale encoding is used (see :func:`locale.getencoding`).
916
917   .. versionadded:: 3.3
918
919
920.. method:: window.erase()
921
922   Clear the window.
923
924
925.. method:: window.getbegyx()
926
927   Return a tuple ``(y, x)`` of co-ordinates of upper-left corner.
928
929
930.. method:: window.getbkgd()
931
932   Return the given window's current background character/attribute pair.
933
934
935.. method:: window.getch([y, x])
936
937   Get a character. Note that the integer returned does *not* have to be in ASCII
938   range: function keys, keypad keys and so on are represented by numbers higher
939   than 255.  In no-delay mode, return ``-1`` if there is no input, otherwise
940   wait until a key is pressed.
941
942
943.. method:: window.get_wch([y, x])
944
945   Get a wide character. Return a character for most keys, or an integer for
946   function keys, keypad keys, and other special keys.
947   In no-delay mode, raise an exception if there is no input.
948
949   .. versionadded:: 3.3
950
951
952.. method:: window.getkey([y, x])
953
954   Get a character, returning a string instead of an integer, as :meth:`getch`
955   does. Function keys, keypad keys and other special keys return a multibyte
956   string containing the key name.  In no-delay mode, raise an exception if
957   there is no input.
958
959
960.. method:: window.getmaxyx()
961
962   Return a tuple ``(y, x)`` of the height and width of the window.
963
964
965.. method:: window.getparyx()
966
967   Return the beginning coordinates of this window relative to its parent window
968   as a tuple ``(y, x)``.  Return ``(-1, -1)`` if this window has no
969   parent.
970
971
972.. method:: window.getstr()
973            window.getstr(n)
974            window.getstr(y, x)
975            window.getstr(y, x, n)
976
977   Read a bytes object from the user, with primitive line editing capacity.
978
979
980.. method:: window.getyx()
981
982   Return a tuple ``(y, x)`` of current cursor position  relative to the window's
983   upper-left corner.
984
985
986.. method:: window.hline(ch, n)
987            window.hline(y, x, ch, n)
988
989   Display a horizontal line starting at ``(y, x)`` with length *n* consisting of
990   the character *ch*.
991
992
993.. method:: window.idcok(flag)
994
995   If *flag* is ``False``, curses no longer considers using the hardware insert/delete
996   character feature of the terminal; if *flag* is ``True``, use of character insertion
997   and deletion is enabled.  When curses is first initialized, use of character
998   insert/delete is enabled by default.
999
1000
1001.. method:: window.idlok(flag)
1002
1003   If *flag* is ``True``, :mod:`curses` will try and use hardware line
1004   editing facilities. Otherwise, line insertion/deletion are disabled.
1005
1006
1007.. method:: window.immedok(flag)
1008
1009   If *flag* is ``True``, any change in the window image automatically causes the
1010   window to be refreshed; you no longer have to call :meth:`refresh` yourself.
1011   However, it may degrade performance considerably, due to repeated calls to
1012   wrefresh.  This option is disabled by default.
1013
1014
1015.. method:: window.inch([y, x])
1016
1017   Return the character at the given position in the window. The bottom 8 bits are
1018   the character proper, and upper bits are the attributes.
1019
1020
1021.. method:: window.insch(ch[, attr])
1022            window.insch(y, x, ch[, attr])
1023
1024   Paint character *ch* at ``(y, x)`` with attributes *attr*, moving the line from
1025   position *x* right by one character.
1026
1027
1028.. method:: window.insdelln(nlines)
1029
1030   Insert *nlines* lines into the specified window above the current line.  The
1031   *nlines* bottom lines are lost.  For negative *nlines*, delete *nlines* lines
1032   starting with the one under the cursor, and move the remaining lines up.  The
1033   bottom *nlines* lines are cleared.  The current cursor position remains the
1034   same.
1035
1036
1037.. method:: window.insertln()
1038
1039   Insert a blank line under the cursor. All following lines are moved down by one
1040   line.
1041
1042
1043.. method:: window.insnstr(str, n[, attr])
1044            window.insnstr(y, x, str, n[, attr])
1045
1046   Insert a character string (as many characters as will fit on the line) before
1047   the character under the cursor, up to *n* characters.   If *n* is zero or
1048   negative, the entire string is inserted. All characters to the right of the
1049   cursor are shifted right, with the rightmost characters on the line being lost.
1050   The cursor position does not change (after moving to *y*, *x*, if specified).
1051
1052
1053.. method:: window.insstr(str[, attr])
1054            window.insstr(y, x, str[, attr])
1055
1056   Insert a character string (as many characters as will fit on the line) before
1057   the character under the cursor.  All characters to the right of the cursor are
1058   shifted right, with the rightmost characters on the line being lost.  The cursor
1059   position does not change (after moving to *y*, *x*, if specified).
1060
1061
1062.. method:: window.instr([n])
1063            window.instr(y, x[, n])
1064
1065   Return a bytes object of characters, extracted from the window starting at the
1066   current cursor position, or at *y*, *x* if specified. Attributes are stripped
1067   from the characters.  If *n* is specified, :meth:`instr` returns a string
1068   at most *n* characters long (exclusive of the trailing NUL).
1069
1070
1071.. method:: window.is_linetouched(line)
1072
1073   Return ``True`` if the specified line was modified since the last call to
1074   :meth:`refresh`; otherwise return ``False``.  Raise a :exc:`curses.error`
1075   exception if *line* is not valid for the given window.
1076
1077
1078.. method:: window.is_wintouched()
1079
1080   Return ``True`` if the specified window was modified since the last call to
1081   :meth:`refresh`; otherwise return ``False``.
1082
1083
1084.. method:: window.keypad(flag)
1085
1086   If *flag* is ``True``, escape sequences generated by some keys (keypad,  function keys)
1087   will be interpreted by :mod:`curses`. If *flag* is ``False``, escape sequences will be
1088   left as is in the input stream.
1089
1090
1091.. method:: window.leaveok(flag)
1092
1093   If *flag* is ``True``, cursor is left where it is on update, instead of being at "cursor
1094   position."  This reduces cursor movement where possible. If possible the cursor
1095   will be made invisible.
1096
1097   If *flag* is ``False``, cursor will always be at "cursor position" after an update.
1098
1099
1100.. method:: window.move(new_y, new_x)
1101
1102   Move cursor to ``(new_y, new_x)``.
1103
1104
1105.. method:: window.mvderwin(y, x)
1106
1107   Move the window inside its parent window.  The screen-relative parameters of
1108   the window are not changed.  This routine is used to display different parts of
1109   the parent window at the same physical position on the screen.
1110
1111
1112.. method:: window.mvwin(new_y, new_x)
1113
1114   Move the window so its upper-left corner is at ``(new_y, new_x)``.
1115
1116
1117.. method:: window.nodelay(flag)
1118
1119   If *flag* is ``True``, :meth:`getch` will be non-blocking.
1120
1121
1122.. method:: window.notimeout(flag)
1123
1124   If *flag* is ``True``, escape sequences will not be timed out.
1125
1126   If *flag* is ``False``, after a few milliseconds, an escape sequence will not be
1127   interpreted, and will be left in the input stream as is.
1128
1129
1130.. method:: window.noutrefresh()
1131
1132   Mark for refresh but wait.  This function updates the data structure
1133   representing the desired state of the window, but does not force an update of
1134   the physical screen.  To accomplish that, call  :func:`doupdate`.
1135
1136
1137.. method:: window.overlay(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])
1138
1139   Overlay the window on top of *destwin*. The windows need not be the same size,
1140   only the overlapping region is copied. This copy is non-destructive, which means
1141   that the current background character does not overwrite the old contents of
1142   *destwin*.
1143
1144   To get fine-grained control over the copied region, the second form of
1145   :meth:`overlay` can be used. *sminrow* and *smincol* are the upper-left
1146   coordinates of the source window, and the other variables mark a rectangle in
1147   the destination window.
1148
1149
1150.. method:: window.overwrite(destwin[, sminrow, smincol, dminrow, dmincol, dmaxrow, dmaxcol])
1151
1152   Overwrite the window on top of *destwin*. The windows need not be the same size,
1153   in which case only the overlapping region is copied. This copy is destructive,
1154   which means that the current background character overwrites the old contents of
1155   *destwin*.
1156
1157   To get fine-grained control over the copied region, the second form of
1158   :meth:`overwrite` can be used. *sminrow* and *smincol* are the upper-left
1159   coordinates of the source window, the other variables mark a rectangle in the
1160   destination window.
1161
1162
1163.. method:: window.putwin(file)
1164
1165   Write all data associated with the window into the provided file object.  This
1166   information can be later retrieved using the :func:`getwin` function.
1167
1168
1169.. method:: window.redrawln(beg, num)
1170
1171   Indicate that the *num* screen lines, starting at line *beg*, are corrupted and
1172   should be completely redrawn on the next :meth:`refresh` call.
1173
1174
1175.. method:: window.redrawwin()
1176
1177   Touch the entire window, causing it to be completely redrawn on the next
1178   :meth:`refresh` call.
1179
1180
1181.. method:: window.refresh([pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol])
1182
1183   Update the display immediately (sync actual screen with previous
1184   drawing/deleting methods).
1185
1186   The 6 optional arguments can only be specified when the window is a pad created
1187   with :func:`newpad`.  The additional parameters are needed to indicate what part
1188   of the pad and screen are involved. *pminrow* and *pmincol* specify the upper
1189   left-hand corner of the rectangle to be displayed in the pad.  *sminrow*,
1190   *smincol*, *smaxrow*, and *smaxcol* specify the edges of the rectangle to be
1191   displayed on the screen.  The lower right-hand corner of the rectangle to be
1192   displayed in the pad is calculated from the screen coordinates, since the
1193   rectangles must be the same size.  Both rectangles must be entirely contained
1194   within their respective structures.  Negative values of *pminrow*, *pmincol*,
1195   *sminrow*, or *smincol* are treated as if they were zero.
1196
1197
1198.. method:: window.resize(nlines, ncols)
1199
1200   Reallocate storage for a curses window to adjust its dimensions to the
1201   specified values.  If either dimension is larger than the current values, the
1202   window's data is filled with blanks that have the current background
1203   rendition (as set by :meth:`bkgdset`) merged into them.
1204
1205
1206.. method:: window.scroll([lines=1])
1207
1208   Scroll the screen or scrolling region upward by *lines* lines.
1209
1210
1211.. method:: window.scrollok(flag)
1212
1213   Control what happens when the cursor of a window is moved off the edge of the
1214   window or scrolling region, either as a result of a newline action on the bottom
1215   line, or typing the last character of the last line.  If *flag* is ``False``, the
1216   cursor is left on the bottom line.  If *flag* is ``True``, the window is scrolled up
1217   one line.  Note that in order to get the physical scrolling effect on the
1218   terminal, it is also necessary to call :meth:`idlok`.
1219
1220
1221.. method:: window.setscrreg(top, bottom)
1222
1223   Set the scrolling region from line *top* to line *bottom*. All scrolling actions
1224   will take place in this region.
1225
1226
1227.. method:: window.standend()
1228
1229   Turn off the standout attribute.  On some terminals this has the side effect of
1230   turning off all attributes.
1231
1232
1233.. method:: window.standout()
1234
1235   Turn on attribute *A_STANDOUT*.
1236
1237
1238.. method:: window.subpad(begin_y, begin_x)
1239            window.subpad(nlines, ncols, begin_y, begin_x)
1240
1241   Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and
1242   whose width/height is *ncols*/*nlines*.
1243
1244
1245.. method:: window.subwin(begin_y, begin_x)
1246            window.subwin(nlines, ncols, begin_y, begin_x)
1247
1248   Return a sub-window, whose upper-left corner is at ``(begin_y, begin_x)``, and
1249   whose width/height is *ncols*/*nlines*.
1250
1251   By default, the sub-window will extend from the specified position to the lower
1252   right corner of the window.
1253
1254
1255.. method:: window.syncdown()
1256
1257   Touch each location in the window that has been touched in any of its ancestor
1258   windows.  This routine is called by :meth:`refresh`, so it should almost never
1259   be necessary to call it manually.
1260
1261
1262.. method:: window.syncok(flag)
1263
1264   If *flag* is ``True``, then :meth:`syncup` is called automatically
1265   whenever there is a change in the window.
1266
1267
1268.. method:: window.syncup()
1269
1270   Touch all locations in ancestors of the window that have been changed in  the
1271   window.
1272
1273
1274.. method:: window.timeout(delay)
1275
1276   Set blocking or non-blocking read behavior for the window.  If *delay* is
1277   negative, blocking read is used (which will wait indefinitely for input).  If
1278   *delay* is zero, then non-blocking read is used, and :meth:`getch` will
1279   return ``-1`` if no input is waiting.  If *delay* is positive, then
1280   :meth:`getch` will block for *delay* milliseconds, and return ``-1`` if there is
1281   still no input at the end of that time.
1282
1283
1284.. method:: window.touchline(start, count[, changed])
1285
1286   Pretend *count* lines have been changed, starting with line *start*.  If
1287   *changed* is supplied, it specifies whether the affected lines are marked as
1288   having been changed (*changed*\ ``=True``) or unchanged (*changed*\ ``=False``).
1289
1290
1291.. method:: window.touchwin()
1292
1293   Pretend the whole window has been changed, for purposes of drawing
1294   optimizations.
1295
1296
1297.. method:: window.untouchwin()
1298
1299   Mark all lines in  the  window  as unchanged since the last call to
1300   :meth:`refresh`.
1301
1302
1303.. method:: window.vline(ch, n[, attr])
1304            window.vline(y, x, ch, n[, attr])
1305
1306   Display a vertical line starting at ``(y, x)`` with length *n* consisting of the
1307   character *ch* with attributes *attr*.
1308
1309
1310Constants
1311---------
1312
1313The :mod:`curses` module defines the following data members:
1314
1315
1316.. data:: ERR
1317
1318   Some curses routines  that  return  an integer, such as :meth:`~window.getch`, return
1319   :const:`ERR` upon failure.
1320
1321
1322.. data:: OK
1323
1324   Some curses routines  that  return  an integer, such as  :func:`napms`, return
1325   :const:`OK` upon success.
1326
1327
1328.. data:: version
1329.. data:: __version__
1330
1331   A bytes object representing the current version of the module.
1332
1333
1334.. data:: ncurses_version
1335
1336   A named tuple containing the three components of the ncurses library
1337   version: *major*, *minor*, and *patch*.  All values are integers.  The
1338   components can also be accessed by name,  so ``curses.ncurses_version[0]``
1339   is equivalent to ``curses.ncurses_version.major`` and so on.
1340
1341   Availability: if the ncurses library is used.
1342
1343   .. versionadded:: 3.8
1344
1345.. data:: COLORS
1346
1347   The maximum number of colors the terminal can support.
1348
1349.. data:: COLOR_PAIRS
1350
1351   The maximum number of color pairs the terminal can support.
1352
1353Some constants are available to specify character cell attributes.
1354The exact constants available are system dependent.
1355
1356+------------------------+-------------------------------+
1357| Attribute              | Meaning                       |
1358+========================+===============================+
1359| .. data:: A_ALTCHARSET | Alternate character set mode  |
1360+------------------------+-------------------------------+
1361| .. data:: A_BLINK      | Blink mode                    |
1362+------------------------+-------------------------------+
1363| .. data:: A_BOLD       | Bold mode                     |
1364+------------------------+-------------------------------+
1365| .. data:: A_DIM        | Dim mode                      |
1366+------------------------+-------------------------------+
1367| .. data:: A_INVIS      | Invisible or blank mode       |
1368+------------------------+-------------------------------+
1369| .. data:: A_ITALIC     | Italic mode                   |
1370+------------------------+-------------------------------+
1371| .. data:: A_NORMAL     | Normal attribute              |
1372+------------------------+-------------------------------+
1373| .. data:: A_PROTECT    | Protected mode                |
1374+------------------------+-------------------------------+
1375| .. data:: A_REVERSE    | Reverse background and        |
1376|                        | foreground colors             |
1377+------------------------+-------------------------------+
1378| .. data:: A_STANDOUT   | Standout mode                 |
1379+------------------------+-------------------------------+
1380| .. data:: A_UNDERLINE  | Underline mode                |
1381+------------------------+-------------------------------+
1382| .. data:: A_HORIZONTAL | Horizontal highlight          |
1383+------------------------+-------------------------------+
1384| .. data:: A_LEFT       | Left highlight                |
1385+------------------------+-------------------------------+
1386| .. data:: A_LOW        | Low highlight                 |
1387+------------------------+-------------------------------+
1388| .. data:: A_RIGHT      | Right highlight               |
1389+------------------------+-------------------------------+
1390| .. data:: A_TOP        | Top highlight                 |
1391+------------------------+-------------------------------+
1392| .. data:: A_VERTICAL   | Vertical highlight            |
1393+------------------------+-------------------------------+
1394
1395.. versionadded:: 3.7
1396   ``A_ITALIC`` was added.
1397
1398Several constants are available to extract corresponding attributes returned
1399by some methods.
1400
1401+-------------------------+-------------------------------+
1402| Bit-mask                | Meaning                       |
1403+=========================+===============================+
1404|  .. data:: A_ATTRIBUTES | Bit-mask to extract           |
1405|                         | attributes                    |
1406+-------------------------+-------------------------------+
1407|  .. data:: A_CHARTEXT   | Bit-mask to extract a         |
1408|                         | character                     |
1409+-------------------------+-------------------------------+
1410|  .. data:: A_COLOR      | Bit-mask to extract           |
1411|                         | color-pair field information  |
1412+-------------------------+-------------------------------+
1413
1414Keys are referred to by integer constants with names starting with  ``KEY_``.
1415The exact keycaps available are system dependent.
1416
1417.. XXX this table is far too large! should it be alphabetized?
1418
1419+-------------------------+--------------------------------------------+
1420| Key constant            | Key                                        |
1421+=========================+============================================+
1422| .. data:: KEY_MIN       | Minimum key value                          |
1423+-------------------------+--------------------------------------------+
1424| .. data:: KEY_BREAK     | Break key (unreliable)                     |
1425+-------------------------+--------------------------------------------+
1426| .. data:: KEY_DOWN      | Down-arrow                                 |
1427+-------------------------+--------------------------------------------+
1428| .. data:: KEY_UP        | Up-arrow                                   |
1429+-------------------------+--------------------------------------------+
1430| .. data:: KEY_LEFT      | Left-arrow                                 |
1431+-------------------------+--------------------------------------------+
1432| .. data:: KEY_RIGHT     | Right-arrow                                |
1433+-------------------------+--------------------------------------------+
1434| .. data:: KEY_HOME      | Home key (upward+left arrow)               |
1435+-------------------------+--------------------------------------------+
1436| .. data:: KEY_BACKSPACE | Backspace (unreliable)                     |
1437+-------------------------+--------------------------------------------+
1438| .. data:: KEY_F0        | Function keys.  Up to 64 function keys are |
1439|                         | supported.                                 |
1440+-------------------------+--------------------------------------------+
1441| .. data:: KEY_Fn        | Value of function key *n*                  |
1442+-------------------------+--------------------------------------------+
1443| .. data:: KEY_DL        | Delete line                                |
1444+-------------------------+--------------------------------------------+
1445| .. data:: KEY_IL        | Insert line                                |
1446+-------------------------+--------------------------------------------+
1447| .. data:: KEY_DC        | Delete character                           |
1448+-------------------------+--------------------------------------------+
1449| .. data:: KEY_IC        | Insert char or enter insert mode           |
1450+-------------------------+--------------------------------------------+
1451| .. data:: KEY_EIC       | Exit insert char mode                      |
1452+-------------------------+--------------------------------------------+
1453| .. data:: KEY_CLEAR     | Clear screen                               |
1454+-------------------------+--------------------------------------------+
1455| .. data:: KEY_EOS       | Clear to end of screen                     |
1456+-------------------------+--------------------------------------------+
1457| .. data:: KEY_EOL       | Clear to end of line                       |
1458+-------------------------+--------------------------------------------+
1459| .. data:: KEY_SF        | Scroll 1 line forward                      |
1460+-------------------------+--------------------------------------------+
1461| .. data:: KEY_SR        | Scroll 1 line backward (reverse)           |
1462+-------------------------+--------------------------------------------+
1463| .. data:: KEY_NPAGE     | Next page                                  |
1464+-------------------------+--------------------------------------------+
1465| .. data:: KEY_PPAGE     | Previous page                              |
1466+-------------------------+--------------------------------------------+
1467| .. data:: KEY_STAB      | Set tab                                    |
1468+-------------------------+--------------------------------------------+
1469| .. data:: KEY_CTAB      | Clear tab                                  |
1470+-------------------------+--------------------------------------------+
1471| .. data:: KEY_CATAB     | Clear all tabs                             |
1472+-------------------------+--------------------------------------------+
1473| .. data:: KEY_ENTER     | Enter or send (unreliable)                 |
1474+-------------------------+--------------------------------------------+
1475| .. data:: KEY_SRESET    | Soft (partial) reset (unreliable)          |
1476+-------------------------+--------------------------------------------+
1477| .. data:: KEY_RESET     | Reset or hard reset (unreliable)           |
1478+-------------------------+--------------------------------------------+
1479| .. data:: KEY_PRINT     | Print                                      |
1480+-------------------------+--------------------------------------------+
1481| .. data:: KEY_LL        | Home down or bottom (lower left)           |
1482+-------------------------+--------------------------------------------+
1483| .. data:: KEY_A1        | Upper left of keypad                       |
1484+-------------------------+--------------------------------------------+
1485| .. data:: KEY_A3        | Upper right of keypad                      |
1486+-------------------------+--------------------------------------------+
1487| .. data:: KEY_B2        | Center of keypad                           |
1488+-------------------------+--------------------------------------------+
1489| .. data:: KEY_C1        | Lower left of keypad                       |
1490+-------------------------+--------------------------------------------+
1491| .. data:: KEY_C3        | Lower right of keypad                      |
1492+-------------------------+--------------------------------------------+
1493| .. data:: KEY_BTAB      | Back tab                                   |
1494+-------------------------+--------------------------------------------+
1495| .. data:: KEY_BEG       | Beg (beginning)                            |
1496+-------------------------+--------------------------------------------+
1497| .. data:: KEY_CANCEL    | Cancel                                     |
1498+-------------------------+--------------------------------------------+
1499| .. data:: KEY_CLOSE     | Close                                      |
1500+-------------------------+--------------------------------------------+
1501| .. data:: KEY_COMMAND   | Cmd (command)                              |
1502+-------------------------+--------------------------------------------+
1503| .. data:: KEY_COPY      | Copy                                       |
1504+-------------------------+--------------------------------------------+
1505| .. data:: KEY_CREATE    | Create                                     |
1506+-------------------------+--------------------------------------------+
1507| .. data:: KEY_END       | End                                        |
1508+-------------------------+--------------------------------------------+
1509| .. data:: KEY_EXIT      | Exit                                       |
1510+-------------------------+--------------------------------------------+
1511| .. data:: KEY_FIND      | Find                                       |
1512+-------------------------+--------------------------------------------+
1513| .. data:: KEY_HELP      | Help                                       |
1514+-------------------------+--------------------------------------------+
1515| .. data:: KEY_MARK      | Mark                                       |
1516+-------------------------+--------------------------------------------+
1517| .. data:: KEY_MESSAGE   | Message                                    |
1518+-------------------------+--------------------------------------------+
1519| .. data:: KEY_MOVE      | Move                                       |
1520+-------------------------+--------------------------------------------+
1521| .. data:: KEY_NEXT      | Next                                       |
1522+-------------------------+--------------------------------------------+
1523| .. data:: KEY_OPEN      | Open                                       |
1524+-------------------------+--------------------------------------------+
1525| .. data:: KEY_OPTIONS   | Options                                    |
1526+-------------------------+--------------------------------------------+
1527| .. data:: KEY_PREVIOUS  | Prev (previous)                            |
1528+-------------------------+--------------------------------------------+
1529| .. data:: KEY_REDO      | Redo                                       |
1530+-------------------------+--------------------------------------------+
1531| .. data:: KEY_REFERENCE | Ref (reference)                            |
1532+-------------------------+--------------------------------------------+
1533| .. data:: KEY_REFRESH   | Refresh                                    |
1534+-------------------------+--------------------------------------------+
1535| .. data:: KEY_REPLACE   | Replace                                    |
1536+-------------------------+--------------------------------------------+
1537| .. data:: KEY_RESTART   | Restart                                    |
1538+-------------------------+--------------------------------------------+
1539| .. data:: KEY_RESUME    | Resume                                     |
1540+-------------------------+--------------------------------------------+
1541| .. data:: KEY_SAVE      | Save                                       |
1542+-------------------------+--------------------------------------------+
1543| .. data:: KEY_SBEG      | Shifted Beg (beginning)                    |
1544+-------------------------+--------------------------------------------+
1545| .. data:: KEY_SCANCEL   | Shifted Cancel                             |
1546+-------------------------+--------------------------------------------+
1547| .. data:: KEY_SCOMMAND  | Shifted Command                            |
1548+-------------------------+--------------------------------------------+
1549| .. data:: KEY_SCOPY     | Shifted Copy                               |
1550+-------------------------+--------------------------------------------+
1551| .. data:: KEY_SCREATE   | Shifted Create                             |
1552+-------------------------+--------------------------------------------+
1553| .. data:: KEY_SDC       | Shifted Delete char                        |
1554+-------------------------+--------------------------------------------+
1555| .. data:: KEY_SDL       | Shifted Delete line                        |
1556+-------------------------+--------------------------------------------+
1557| .. data:: KEY_SELECT    | Select                                     |
1558+-------------------------+--------------------------------------------+
1559| .. data:: KEY_SEND      | Shifted End                                |
1560+-------------------------+--------------------------------------------+
1561| .. data:: KEY_SEOL      | Shifted Clear line                         |
1562+-------------------------+--------------------------------------------+
1563| .. data:: KEY_SEXIT     | Shifted Exit                               |
1564+-------------------------+--------------------------------------------+
1565| .. data:: KEY_SFIND     | Shifted Find                               |
1566+-------------------------+--------------------------------------------+
1567| .. data:: KEY_SHELP     | Shifted Help                               |
1568+-------------------------+--------------------------------------------+
1569| .. data:: KEY_SHOME     | Shifted Home                               |
1570+-------------------------+--------------------------------------------+
1571| .. data:: KEY_SIC       | Shifted Input                              |
1572+-------------------------+--------------------------------------------+
1573| .. data:: KEY_SLEFT     | Shifted Left arrow                         |
1574+-------------------------+--------------------------------------------+
1575| .. data:: KEY_SMESSAGE  | Shifted Message                            |
1576+-------------------------+--------------------------------------------+
1577| .. data:: KEY_SMOVE     | Shifted Move                               |
1578+-------------------------+--------------------------------------------+
1579| .. data:: KEY_SNEXT     | Shifted Next                               |
1580+-------------------------+--------------------------------------------+
1581| .. data:: KEY_SOPTIONS  | Shifted Options                            |
1582+-------------------------+--------------------------------------------+
1583| .. data:: KEY_SPREVIOUS | Shifted Prev                               |
1584+-------------------------+--------------------------------------------+
1585| .. data:: KEY_SPRINT    | Shifted Print                              |
1586+-------------------------+--------------------------------------------+
1587| .. data:: KEY_SREDO     | Shifted Redo                               |
1588+-------------------------+--------------------------------------------+
1589| .. data:: KEY_SREPLACE  | Shifted Replace                            |
1590+-------------------------+--------------------------------------------+
1591| .. data:: KEY_SRIGHT    | Shifted Right arrow                        |
1592+-------------------------+--------------------------------------------+
1593| .. data:: KEY_SRSUME    | Shifted Resume                             |
1594+-------------------------+--------------------------------------------+
1595| .. data:: KEY_SSAVE     | Shifted Save                               |
1596+-------------------------+--------------------------------------------+
1597| .. data:: KEY_SSUSPEND  | Shifted Suspend                            |
1598+-------------------------+--------------------------------------------+
1599| .. data:: KEY_SUNDO     | Shifted Undo                               |
1600+-------------------------+--------------------------------------------+
1601| .. data:: KEY_SUSPEND   | Suspend                                    |
1602+-------------------------+--------------------------------------------+
1603| .. data:: KEY_UNDO      | Undo                                       |
1604+-------------------------+--------------------------------------------+
1605| .. data:: KEY_MOUSE     | Mouse event has occurred                   |
1606+-------------------------+--------------------------------------------+
1607| .. data:: KEY_RESIZE    | Terminal resize event                      |
1608+-------------------------+--------------------------------------------+
1609| .. data:: KEY_MAX       | Maximum key value                          |
1610+-------------------------+--------------------------------------------+
1611
1612On VT100s and their software emulations, such as X terminal emulators, there are
1613normally at least four function keys (:const:`KEY_F1 <KEY_Fn>`, :const:`KEY_F2 <KEY_Fn>`,
1614:const:`KEY_F3 <KEY_Fn>`, :const:`KEY_F4 <KEY_Fn>`) available, and the arrow keys mapped to
1615:const:`KEY_UP`, :const:`KEY_DOWN`, :const:`KEY_LEFT` and :const:`KEY_RIGHT` in
1616the obvious way.  If your machine has a PC keyboard, it is safe to expect arrow
1617keys and twelve function keys (older PC keyboards may have only ten function
1618keys); also, the following keypad mappings are standard:
1619
1620+------------------+-----------+
1621| Keycap           | Constant  |
1622+==================+===========+
1623| :kbd:`Insert`    | KEY_IC    |
1624+------------------+-----------+
1625| :kbd:`Delete`    | KEY_DC    |
1626+------------------+-----------+
1627| :kbd:`Home`      | KEY_HOME  |
1628+------------------+-----------+
1629| :kbd:`End`       | KEY_END   |
1630+------------------+-----------+
1631| :kbd:`Page Up`   | KEY_PPAGE |
1632+------------------+-----------+
1633| :kbd:`Page Down` | KEY_NPAGE |
1634+------------------+-----------+
1635
1636The following table lists characters from the alternate character set. These are
1637inherited from the VT100 terminal, and will generally be  available on software
1638emulations such as X terminals.  When there is no graphic available, curses
1639falls back on a crude printable ASCII approximation.
1640
1641.. note::
1642
1643   These are available only after :func:`initscr` has  been called.
1644
1645+------------------------+------------------------------------------+
1646| ACS code               | Meaning                                  |
1647+========================+==========================================+
1648| .. data:: ACS_BBSS     | alternate name for upper right corner    |
1649+------------------------+------------------------------------------+
1650| .. data:: ACS_BLOCK    | solid square block                       |
1651+------------------------+------------------------------------------+
1652| .. data:: ACS_BOARD    | board of squares                         |
1653+------------------------+------------------------------------------+
1654| .. data:: ACS_BSBS     | alternate name for horizontal line       |
1655+------------------------+------------------------------------------+
1656| .. data:: ACS_BSSB     | alternate name for upper left corner     |
1657+------------------------+------------------------------------------+
1658| .. data:: ACS_BSSS     | alternate name for top tee               |
1659+------------------------+------------------------------------------+
1660| .. data:: ACS_BTEE     | bottom tee                               |
1661+------------------------+------------------------------------------+
1662| .. data:: ACS_BULLET   | bullet                                   |
1663+------------------------+------------------------------------------+
1664| .. data:: ACS_CKBOARD  | checker board (stipple)                  |
1665+------------------------+------------------------------------------+
1666| .. data:: ACS_DARROW   | arrow pointing down                      |
1667+------------------------+------------------------------------------+
1668| .. data:: ACS_DEGREE   | degree symbol                            |
1669+------------------------+------------------------------------------+
1670| .. data:: ACS_DIAMOND  | diamond                                  |
1671+------------------------+------------------------------------------+
1672| .. data:: ACS_GEQUAL   | greater-than-or-equal-to                 |
1673+------------------------+------------------------------------------+
1674| .. data:: ACS_HLINE    | horizontal line                          |
1675+------------------------+------------------------------------------+
1676| .. data:: ACS_LANTERN  | lantern symbol                           |
1677+------------------------+------------------------------------------+
1678| .. data:: ACS_LARROW   | left arrow                               |
1679+------------------------+------------------------------------------+
1680| .. data:: ACS_LEQUAL   | less-than-or-equal-to                    |
1681+------------------------+------------------------------------------+
1682| .. data:: ACS_LLCORNER | lower left-hand corner                   |
1683+------------------------+------------------------------------------+
1684| .. data:: ACS_LRCORNER | lower right-hand corner                  |
1685+------------------------+------------------------------------------+
1686| .. data:: ACS_LTEE     | left tee                                 |
1687+------------------------+------------------------------------------+
1688| .. data:: ACS_NEQUAL   | not-equal sign                           |
1689+------------------------+------------------------------------------+
1690| .. data:: ACS_PI       | letter pi                                |
1691+------------------------+------------------------------------------+
1692| .. data:: ACS_PLMINUS  | plus-or-minus sign                       |
1693+------------------------+------------------------------------------+
1694| .. data:: ACS_PLUS     | big plus sign                            |
1695+------------------------+------------------------------------------+
1696| .. data:: ACS_RARROW   | right arrow                              |
1697+------------------------+------------------------------------------+
1698| .. data:: ACS_RTEE     | right tee                                |
1699+------------------------+------------------------------------------+
1700| .. data:: ACS_S1       | scan line 1                              |
1701+------------------------+------------------------------------------+
1702| .. data:: ACS_S3       | scan line 3                              |
1703+------------------------+------------------------------------------+
1704| .. data:: ACS_S7       | scan line 7                              |
1705+------------------------+------------------------------------------+
1706| .. data:: ACS_S9       | scan line 9                              |
1707+------------------------+------------------------------------------+
1708| .. data:: ACS_SBBS     | alternate name for lower right corner    |
1709+------------------------+------------------------------------------+
1710| .. data:: ACS_SBSB     | alternate name for vertical line         |
1711+------------------------+------------------------------------------+
1712| .. data:: ACS_SBSS     | alternate name for right tee             |
1713+------------------------+------------------------------------------+
1714| .. data:: ACS_SSBB     | alternate name for lower left corner     |
1715+------------------------+------------------------------------------+
1716| .. data:: ACS_SSBS     | alternate name for bottom tee            |
1717+------------------------+------------------------------------------+
1718| .. data:: ACS_SSSB     | alternate name for left tee              |
1719+------------------------+------------------------------------------+
1720| .. data:: ACS_SSSS     | alternate name for crossover or big plus |
1721+------------------------+------------------------------------------+
1722| .. data:: ACS_STERLING | pound sterling                           |
1723+------------------------+------------------------------------------+
1724| .. data:: ACS_TTEE     | top tee                                  |
1725+------------------------+------------------------------------------+
1726| .. data:: ACS_UARROW   | up arrow                                 |
1727+------------------------+------------------------------------------+
1728| .. data:: ACS_ULCORNER | upper left corner                        |
1729+------------------------+------------------------------------------+
1730| .. data:: ACS_URCORNER | upper right corner                       |
1731+------------------------+------------------------------------------+
1732| .. data:: ACS_VLINE    | vertical line                            |
1733+------------------------+------------------------------------------+
1734
1735The following table lists mouse button constants used by :meth:`getmouse`:
1736
1737+----------------------------------+---------------------------------------------+
1738| Mouse button constant            | Meaning                                     |
1739+==================================+=============================================+
1740| .. data:: BUTTONn_PRESSED        | Mouse button *n* pressed                    |
1741+----------------------------------+---------------------------------------------+
1742| .. data:: BUTTONn_RELEASED       | Mouse button *n* released                   |
1743+----------------------------------+---------------------------------------------+
1744| .. data:: BUTTONn_CLICKED        | Mouse button *n* clicked                    |
1745+----------------------------------+---------------------------------------------+
1746| .. data:: BUTTONn_DOUBLE_CLICKED | Mouse button *n* double clicked             |
1747+----------------------------------+---------------------------------------------+
1748| .. data:: BUTTONn_TRIPLE_CLICKED | Mouse button *n* triple clicked             |
1749+----------------------------------+---------------------------------------------+
1750| .. data:: BUTTON_SHIFT           | Shift was down during button state change   |
1751+----------------------------------+---------------------------------------------+
1752| .. data:: BUTTON_CTRL            | Control was down during button state change |
1753+----------------------------------+---------------------------------------------+
1754| .. data:: BUTTON_ALT             | Control was down during button state change |
1755+----------------------------------+---------------------------------------------+
1756
1757   .. versionchanged:: 3.10
1758      The ``BUTTON5_*`` constants are now exposed if they are provided by the
1759      underlying curses library.
1760
1761The following table lists the predefined colors:
1762
1763+-------------------------+----------------------------+
1764| Constant                | Color                      |
1765+=========================+============================+
1766| .. data:: COLOR_BLACK   | Black                      |
1767+-------------------------+----------------------------+
1768| .. data:: COLOR_BLUE    | Blue                       |
1769+-------------------------+----------------------------+
1770| .. data:: COLOR_CYAN    | Cyan (light greenish blue) |
1771+-------------------------+----------------------------+
1772| .. data:: COLOR_GREEN   | Green                      |
1773+-------------------------+----------------------------+
1774| .. data:: COLOR_MAGENTA | Magenta (purplish red)     |
1775+-------------------------+----------------------------+
1776| .. data:: COLOR_RED     | Red                        |
1777+-------------------------+----------------------------+
1778| .. data:: COLOR_WHITE   | White                      |
1779+-------------------------+----------------------------+
1780| .. data:: COLOR_YELLOW  | Yellow                     |
1781+-------------------------+----------------------------+
1782
1783
1784:mod:`curses.textpad` --- Text input widget for curses programs
1785===============================================================
1786
1787.. module:: curses.textpad
1788   :synopsis: Emacs-like input editing in a curses window.
1789.. moduleauthor:: Eric Raymond <[email protected]>
1790.. sectionauthor:: Eric Raymond <[email protected]>
1791
1792
1793The :mod:`curses.textpad` module provides a :class:`Textbox` class that handles
1794elementary text editing in a curses window, supporting a set of keybindings
1795resembling those of Emacs (thus, also of Netscape Navigator, BBedit 6.x,
1796FrameMaker, and many other programs).  The module also provides a
1797rectangle-drawing function useful for framing text boxes or for other purposes.
1798
1799The module :mod:`curses.textpad` defines the following function:
1800
1801
1802.. function:: rectangle(win, uly, ulx, lry, lrx)
1803
1804   Draw a rectangle.  The first argument must be a window object; the remaining
1805   arguments are coordinates relative to that window.  The second and third
1806   arguments are the y and x coordinates of the upper left hand corner of the
1807   rectangle to be drawn; the fourth and fifth arguments are the y and x
1808   coordinates of the lower right hand corner. The rectangle will be drawn using
1809   VT100/IBM PC forms characters on terminals that make this possible (including
1810   xterm and most other software terminal emulators).  Otherwise it will be drawn
1811   with ASCII  dashes, vertical bars, and plus signs.
1812
1813
1814.. _curses-textpad-objects:
1815
1816Textbox objects
1817---------------
1818
1819You can instantiate a :class:`Textbox` object as follows:
1820
1821
1822.. class:: Textbox(win)
1823
1824   Return a textbox widget object.  The *win* argument should be a curses
1825   :ref:`window <curses-window-objects>` object in which the textbox is to
1826   be contained. The edit cursor of the textbox is initially located at the
1827   upper left hand corner of the containing window, with coordinates ``(0, 0)``.
1828   The instance's :attr:`stripspaces` flag is initially on.
1829
1830   :class:`Textbox` objects have the following methods:
1831
1832
1833   .. method:: edit([validator])
1834
1835      This is the entry point you will normally use.  It accepts editing
1836      keystrokes until one of the termination keystrokes is entered.  If
1837      *validator* is supplied, it must be a function.  It will be called for
1838      each keystroke entered with the keystroke as a parameter; command dispatch
1839      is done on the result. This method returns the window contents as a
1840      string; whether blanks in the window are included is affected by the
1841      :attr:`stripspaces` attribute.
1842
1843
1844   .. method:: do_command(ch)
1845
1846      Process a single command keystroke.  Here are the supported special
1847      keystrokes:
1848
1849      +------------------+-------------------------------------------+
1850      | Keystroke        | Action                                    |
1851      +==================+===========================================+
1852      | :kbd:`Control-A` | Go to left edge of window.                |
1853      +------------------+-------------------------------------------+
1854      | :kbd:`Control-B` | Cursor left, wrapping to previous line if |
1855      |                  | appropriate.                              |
1856      +------------------+-------------------------------------------+
1857      | :kbd:`Control-D` | Delete character under cursor.            |
1858      +------------------+-------------------------------------------+
1859      | :kbd:`Control-E` | Go to right edge (stripspaces off) or end |
1860      |                  | of line (stripspaces on).                 |
1861      +------------------+-------------------------------------------+
1862      | :kbd:`Control-F` | Cursor right, wrapping to next line when  |
1863      |                  | appropriate.                              |
1864      +------------------+-------------------------------------------+
1865      | :kbd:`Control-G` | Terminate, returning the window contents. |
1866      +------------------+-------------------------------------------+
1867      | :kbd:`Control-H` | Delete character backward.                |
1868      +------------------+-------------------------------------------+
1869      | :kbd:`Control-J` | Terminate if the window is 1 line,        |
1870      |                  | otherwise insert newline.                 |
1871      +------------------+-------------------------------------------+
1872      | :kbd:`Control-K` | If line is blank, delete it, otherwise    |
1873      |                  | clear to end of line.                     |
1874      +------------------+-------------------------------------------+
1875      | :kbd:`Control-L` | Refresh screen.                           |
1876      +------------------+-------------------------------------------+
1877      | :kbd:`Control-N` | Cursor down; move down one line.          |
1878      +------------------+-------------------------------------------+
1879      | :kbd:`Control-O` | Insert a blank line at cursor location.   |
1880      +------------------+-------------------------------------------+
1881      | :kbd:`Control-P` | Cursor up; move up one line.              |
1882      +------------------+-------------------------------------------+
1883
1884      Move operations do nothing if the cursor is at an edge where the movement
1885      is not possible.  The following synonyms are supported where possible:
1886
1887      +--------------------------------+------------------+
1888      | Constant                       | Keystroke        |
1889      +================================+==================+
1890      | :const:`~curses.KEY_LEFT`      | :kbd:`Control-B` |
1891      +--------------------------------+------------------+
1892      | :const:`~curses.KEY_RIGHT`     | :kbd:`Control-F` |
1893      +--------------------------------+------------------+
1894      | :const:`~curses.KEY_UP`        | :kbd:`Control-P` |
1895      +--------------------------------+------------------+
1896      | :const:`~curses.KEY_DOWN`      | :kbd:`Control-N` |
1897      +--------------------------------+------------------+
1898      | :const:`~curses.KEY_BACKSPACE` | :kbd:`Control-h` |
1899      +--------------------------------+------------------+
1900
1901      All other keystrokes are treated as a command to insert the given
1902      character and move right (with line wrapping).
1903
1904
1905   .. method:: gather()
1906
1907      Return the window contents as a string; whether blanks in the
1908      window are included is affected by the :attr:`stripspaces` member.
1909
1910
1911   .. attribute:: stripspaces
1912
1913      This attribute is a flag which controls the interpretation of blanks in
1914      the window.  When it is on, trailing blanks on each line are ignored; any
1915      cursor motion that would land the cursor on a trailing blank goes to the
1916      end of that line instead, and trailing blanks are stripped when the window
1917      contents are gathered.
1918