rest25/library/curses.rst => rest262/library/curses.rst
6   :synopsis: An interface to the curses library, providing portable terminal handling.
7.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
8.. sectionauthor:: Eric Raymond <esr@thyrsus.com>
9
10
11.. versionchanged:: 1.6
12   Added support for the ``ncurses`` library and converted to a package.
13
n14-The :mod:`curses` module provides an interface to the curses library, the de-
n14+The :mod:`curses` module provides an interface to the curses library, the
15-facto standard for portable advanced terminal handling.
15+de-facto standard for portable advanced terminal handling.
16
17While curses is most widely used in the Unix environment, versions are available
18for DOS, OS/2, and possibly other systems as well.  This extension module is
19designed to match the API of ncurses, an open-source curses library hosted on
20Linux and the BSD variants of Unix.
21
n22+.. note::
23+ 
24+   Since version 5.4, the ncurses library decides how to interpret non-ASCII data
25+   using the ``nl_langinfo`` function.  That means that you have to call
26+   :func:`locale.setlocale` in the application and encode Unicode strings
27+   using one of the system's available encodings.  This example uses the
28+   system's default encoding::
29+ 
30+      import locale
31+      locale.setlocale(locale.LC_ALL, '')
32+      code = locale.getpreferredencoding()
33+ 
34+   Then use *code* as the encoding for :meth:`str.encode` calls.
22
23.. seealso::
24
25   Module :mod:`curses.ascii`
26      Utilities for working with ASCII characters, regardless of your locale settings.
27
28   Module :mod:`curses.panel`
29      A panel stack extension that adds depth to  curses windows.
30
31   Module :mod:`curses.textpad`
32      Editable text widget for curses supporting  :program:`Emacs`\ -like bindings.
33
34   Module :mod:`curses.wrapper`
35      Convenience function to ensure proper terminal setup and resetting on
36      application entry and exit.
37
n38-   `Curses Programming with Python <http://www.python.org/doc/howto/curses/curses.html>`_
n51+   :ref:`curses-howto`
39      Tutorial material on using curses with Python, by Andrew Kuchling and Eric
n40-      Raymond, is available on the Python Web site.
n53+      Raymond.
41
42   The :file:`Demo/curses/` directory in the Python source distribution contains
43   some example programs using the curses bindings provided by this module.
44
45
46.. _curses-functions:
47
48Functions
636
637
638.. method:: window.bkgd(ch[, attr])
639
640   Sets the background property of the window to the character *ch*, with
641   attributes *attr*.  The change is then applied to every character position in
642   that window:
643
n644-* The attribute of every character in the window  is changed to the new
n657+   * The attribute of every character in the window  is changed to the new
645     background attribute.
646
n647-* Wherever  the  former background character appears, it is changed to the new
n660+   * Wherever  the  former background character appears, it is changed to the new
648     background character.
649
650
651.. method:: window.bkgdset(ch[, attr])
652
653   Sets the window's background.  A window's background consists of a character and
654   any combination of attributes.  The attribute part of the background is combined
655   (OR'ed) with all non-blank characters that are written into the window.  Both
693
694
695.. method:: window.box([vertch, horch])
696
697   Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* and
698   bs are *horch*.  The default corner characters are always used by this function.
699
700
n714+.. method:: window.chgat([y, x, ] [num,] attr)
715+ 
716+   Sets the attributes of *num* characters at the current cursor position, or at
717+   position ``(y, x)`` if supplied. If no value of *num* is given or *num* = -1,
718+   the attribute will  be set on all the characters to the end of the line.  This
719+   function does not move the cursor. The changed line will be touched using the
720+   :meth:`touchline` method so that the contents will be redisplayed by the next
721+   window refresh.
722+ 
723+ 
701.. method:: window.clear()
702
703   Like :meth:`erase`, but also causes the whole window to be repainted upon next
704   call to :meth:`refresh`.
705
706
707.. method:: window.clearok(yes)
708
1008   *smincol*, *smaxrow*, and *smaxcol* specify the edges of the rectangle to be
1009   displayed on the screen.  The lower right-hand corner of the rectangle to be
1010   displayed in the pad is calculated from the screen coordinates, since the
1011   rectangles must be the same size.  Both rectangles must be entirely contained
1012   within their respective structures.  Negative values of *pminrow*, *pmincol*,
1013   *sminrow*, or *smincol* are treated as if they were zero.
1014
1015
n1016-.. method:: window.scroll([lines\ ``= 1``])
n1039+.. method:: window.scroll([lines=1])
1017
1018   Scroll the screen or scrolling region upward by *lines* lines.
1019
1020
1021.. method:: window.scrollok(flag)
1022
1023   Controls what happens when the cursor of a window is moved off the edge of the
1024   window or scrolling region, either as a result of a newline action on the bottom
1084   Sets blocking or non-blocking read behavior for the window.  If *delay* is
1085   negative, blocking read is used (which will wait indefinitely for input).  If
1086   *delay* is zero, then non-blocking read is used, and -1 will be returned by
1087   :meth:`getch` if no input is waiting.  If *delay* is positive, then
1088   :meth:`getch` will block for *delay* milliseconds, and return -1 if there is
1089   still no input at the end of that time.
1090
1091
n1092-.. method:: window.touchline(start, count)
n1115+.. method:: window.touchline(start, count[, changed])
1093
n1094-   Pretend *count* lines have been changed, starting with line *start*.
n1117+   Pretend *count* lines have been changed, starting with line *start*.  If
1118+   *changed* is supplied, it specifies whether the affected lines are marked as
1119+   having been changed (*changed*\ =1) or unchanged (*changed*\ =0).
1095
1096
1097.. method:: window.touchwin()
1098
1099   Pretend the whole window has been changed, for purposes of drawing
1100   optimizations.
1101
1102
1153| ``A_STANDOUT``   | Standout mode.                |
1154+------------------+-------------------------------+
1155| ``A_UNDERLINE``  | Underline mode.               |
1156+------------------+-------------------------------+
1157
1158Keys are referred to by integer constants with names starting with  ``KEY_``.
1159The exact keycaps available are system dependent.
1160
n1161-.. % XXX this table is far too large!
n1186+.. XXX this table is far too large! should it be alphabetized?
1162-.. % XXX should this table be alphabetized?
1163
1164+-------------------+--------------------------------------------+
1165| Key constant      | Key                                        |
1166+===================+============================================+
1167| ``KEY_MIN``       | Minimum key value                          |
1168+-------------------+--------------------------------------------+
1169| ``KEY_BREAK``     | Break key (unreliable)                     |
1170+-------------------+--------------------------------------------+
1509.. sectionauthor:: Eric Raymond <esr@thyrsus.com>
1510
1511
1512.. versionadded:: 1.6
1513
1514The :mod:`curses.textpad` module provides a :class:`Textbox` class that handles
1515elementary text editing in a curses window, supporting a set of keybindings
1516resembling those of Emacs (thus, also of Netscape Navigator, BBedit 6.x,
n1517-FrameMaker, and many other programs).  The module also provides a rectangle-
n1541+FrameMaker, and many other programs).  The module also provides a
1518-drawing function useful for framing text boxes or for other purposes.
1542+rectangle-drawing function useful for framing text boxes or for other purposes.
1519
1520The module :mod:`curses.textpad` defines the following function:
1521
1522
1523.. function:: rectangle(win, uly, ulx, lry, lrx)
1524
1525   Draw a rectangle.  The first argument must be a window object; the remaining
1526   arguments are coordinates relative to that window.  The second and third
1543.. class:: Textbox(win)
1544
1545   Return a textbox widget object.  The *win* argument should be a curses
1546   :class:`WindowObject` in which the textbox is to be contained. The edit cursor
1547   of the textbox is initially located at the upper left hand corner of the
1548   containing window, with coordinates ``(0, 0)``. The instance's
1549   :attr:`stripspaces` flag is initially on.
1550
n1551-:class:`Textbox` objects have the following methods:
n1575+   :class:`Textbox` objects have the following methods:
1552
1553
n1554-.. method:: Textbox.edit([validator])
n1578+   .. method:: edit([validator])
1555
n1556-   This is the entry point you will normally use.  It accepts editing keystrokes
n1580+      This is the entry point you will normally use.  It accepts editing
1557-   until one of the termination keystrokes is entered.  If *validator* is supplied,
1581+      keystrokes until one of the termination keystrokes is entered.  If
1558-   it must be a function.  It will be called for each keystroke entered with the
1582+      *validator* is supplied, it must be a function.  It will be called for
1559-   keystroke as a parameter; command dispatch is done on the result. This method
1583+      each keystroke entered with the keystroke as a parameter; command dispatch
1560-   returns the window contents as a string; whether blanks in the window are
1584+      is done on the result. This method returns the window contents as a
1561-   included is affected by the :attr:`stripspaces` member.
1585+      string; whether blanks in the window are included is affected by the
1586+      :attr:`stripspaces` member.
1562
1563
n1564-.. method:: Textbox.do_command(ch)
n1589+   .. method:: do_command(ch)
1565
n1566-   Process a single command keystroke.  Here are the supported special keystrokes:
n1591+      Process a single command keystroke.  Here are the supported special
1592+      keystrokes:
1567
n1568-   +------------------+-------------------------------------------+
n1594+      +------------------+-------------------------------------------+
1569-   | Keystroke        | Action                                    |
1595+      | Keystroke        | Action                                    |
1570-   +==================+===========================================+
1596+      +==================+===========================================+
1571-   | :kbd:`Control-A` | Go to left edge of window.                |
1597+      | :kbd:`Control-A` | Go to left edge of window.                |
1572-   +------------------+-------------------------------------------+
1598+      +------------------+-------------------------------------------+
1573-   | :kbd:`Control-B` | Cursor left, wrapping to previous line if |
1599+      | :kbd:`Control-B` | Cursor left, wrapping to previous line if |
1574-   |                  | appropriate.                              |
1600+      |                  | appropriate.                              |
1575-   +------------------+-------------------------------------------+
1601+      +------------------+-------------------------------------------+
1576-   | :kbd:`Control-D` | Delete character under cursor.            |
1602+      | :kbd:`Control-D` | Delete character under cursor.            |
1577-   +------------------+-------------------------------------------+
1603+      +------------------+-------------------------------------------+
1578-   | :kbd:`Control-E` | Go to right edge (stripspaces off) or end |
1604+      | :kbd:`Control-E` | Go to right edge (stripspaces off) or end |
1579-   |                  | of line (stripspaces on).                 |
1605+      |                  | of line (stripspaces on).                 |
1580-   +------------------+-------------------------------------------+
1606+      +------------------+-------------------------------------------+
1581-   | :kbd:`Control-F` | Cursor right, wrapping to next line when  |
1607+      | :kbd:`Control-F` | Cursor right, wrapping to next line when  |
1582-   |                  | appropriate.                              |
1608+      |                  | appropriate.                              |
1583-   +------------------+-------------------------------------------+
1609+      +------------------+-------------------------------------------+
1584-   | :kbd:`Control-G` | Terminate, returning the window contents. |
1610+      | :kbd:`Control-G` | Terminate, returning the window contents. |
1585-   +------------------+-------------------------------------------+
1611+      +------------------+-------------------------------------------+
1586-   | :kbd:`Control-H` | Delete character backward.                |
1612+      | :kbd:`Control-H` | Delete character backward.                |
1587-   +------------------+-------------------------------------------+
1613+      +------------------+-------------------------------------------+
1588-   | :kbd:`Control-J` | Terminate if the window is 1 line,        |
1614+      | :kbd:`Control-J` | Terminate if the window is 1 line,        |
1589-   |                  | otherwise insert newline.                 |
1615+      |                  | otherwise insert newline.                 |
1590-   +------------------+-------------------------------------------+
1616+      +------------------+-------------------------------------------+
1591-   | :kbd:`Control-K` | If line is blank, delete it, otherwise    |
1617+      | :kbd:`Control-K` | If line is blank, delete it, otherwise    |
1592-   |                  | clear to end of line.                     |
1618+      |                  | clear to end of line.                     |
1593-   +------------------+-------------------------------------------+
1619+      +------------------+-------------------------------------------+
1594-   | :kbd:`Control-L` | Refresh screen.                           |
1620+      | :kbd:`Control-L` | Refresh screen.                           |
1595-   +------------------+-------------------------------------------+
1621+      +------------------+-------------------------------------------+
1596-   | :kbd:`Control-N` | Cursor down; move down one line.          |
1622+      | :kbd:`Control-N` | Cursor down; move down one line.          |
1597-   +------------------+-------------------------------------------+
1623+      +------------------+-------------------------------------------+
1598-   | :kbd:`Control-O` | Insert a blank line at cursor location.   |
1624+      | :kbd:`Control-O` | Insert a blank line at cursor location.   |
1599-   +------------------+-------------------------------------------+
1625+      +------------------+-------------------------------------------+
1600-   | :kbd:`Control-P` | Cursor up; move up one line.              |
1626+      | :kbd:`Control-P` | Cursor up; move up one line.              |
1601-   +------------------+-------------------------------------------+
1627+      +------------------+-------------------------------------------+
1602
n1603-   Move operations do nothing if the cursor is at an edge where the movement is not
n1629+      Move operations do nothing if the cursor is at an edge where the movement
1604-   possible.  The following synonyms are supported where possible:
1630+      is not possible.  The following synonyms are supported where possible:
1605
n1606-   +------------------------+------------------+
n1632+      +------------------------+------------------+
1607-   | Constant               | Keystroke        |
1633+      | Constant               | Keystroke        |
1608-   +========================+==================+
1634+      +========================+==================+
1609-   | :const:`KEY_LEFT`      | :kbd:`Control-B` |
1635+      | :const:`KEY_LEFT`      | :kbd:`Control-B` |
1610-   +------------------------+------------------+
1636+      +------------------------+------------------+
1611-   | :const:`KEY_RIGHT`     | :kbd:`Control-F` |
1637+      | :const:`KEY_RIGHT`     | :kbd:`Control-F` |
1612-   +------------------------+------------------+
1638+      +------------------------+------------------+
1613-   | :const:`KEY_UP`        | :kbd:`Control-P` |
1639+      | :const:`KEY_UP`        | :kbd:`Control-P` |
1614-   +------------------------+------------------+
1640+      +------------------------+------------------+
1615-   | :const:`KEY_DOWN`      | :kbd:`Control-N` |
1641+      | :const:`KEY_DOWN`      | :kbd:`Control-N` |
1616-   +------------------------+------------------+
1642+      +------------------------+------------------+
1617-   | :const:`KEY_BACKSPACE` | :kbd:`Control-h` |
1643+      | :const:`KEY_BACKSPACE` | :kbd:`Control-h` |
1618-   +------------------------+------------------+
1644+      +------------------------+------------------+
1619
n1620-   All other keystrokes are treated as a command to insert the given character and
n1646+      All other keystrokes are treated as a command to insert the given
1621-   move right (with line wrapping).
1647+      character and move right (with line wrapping).
1622
1623
n1624-.. method:: Textbox.gather()
n1650+   .. method:: gather()
1625
n1626-   This method returns the window contents as a string; whether blanks in the
n1652+      This method returns the window contents as a string; whether blanks in the
1627-   window are included is affected by the :attr:`stripspaces` member.
1653+      window are included is affected by the :attr:`stripspaces` member.
1628
1629
n1630-.. attribute:: Textbox.stripspaces
n1656+   .. attribute:: stripspaces
1631
t1632-   This data member is a flag which controls the interpretation of blanks in the
t1658+      This data member is a flag which controls the interpretation of blanks in
1633-   window.  When it is on, trailing blanks on each line are ignored; any cursor
1659+      the window.  When it is on, trailing blanks on each line are ignored; any
1634-   motion that would land the cursor on a trailing blank goes to the end of that
1660+      cursor motion that would land the cursor on a trailing blank goes to the
1635-   line instead, and trailing blanks are stripped when the window contents are
1661+      end of that line instead, and trailing blanks are stripped when the window
1636-   gathered.
1662+      contents are gathered.
1637
1638
1639:mod:`curses.wrapper` --- Terminal handler for curses programs
1640==============================================================
1641
1642.. module:: curses.wrapper
1643   :synopsis: Terminal configuration wrapper for curses programs.
1644.. moduleauthor:: Eric Raymond <esr@thyrsus.com>
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op