--- rest25/library/curses.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/curses.rst	2009-04-05 05:02:09.000000000 +0900
@@ -2,51 +2,64 @@
 :mod:`curses` --- Terminal handling for character-cell displays
 ===============================================================
 
 .. module:: curses
    :synopsis: An interface to the curses library, providing portable terminal handling.
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 .. sectionauthor:: Eric Raymond <esr@thyrsus.com>
 
 
 .. versionchanged:: 1.6
    Added support for the ``ncurses`` library and converted to a package.
 
-The :mod:`curses` module provides an interface to the curses library, the de-
-facto standard for portable advanced terminal handling.
+The :mod:`curses` module provides an interface to the curses library, the
+de-facto standard for portable advanced terminal handling.
 
 While curses is most widely used in the Unix environment, versions are available
 for DOS, OS/2, and possibly other systems as well.  This extension module is
 designed to match the API of ncurses, an open-source curses library hosted on
 Linux and the BSD variants of Unix.
 
+.. note::
+
+   Since version 5.4, the ncurses library decides how to interpret non-ASCII data
+   using the ``nl_langinfo`` function.  That means that you have to call
+   :func:`locale.setlocale` in the application and encode Unicode strings
+   using one of the system's available encodings.  This example uses the
+   system's default encoding::
+
+      import locale
+      locale.setlocale(locale.LC_ALL, '')
+      code = locale.getpreferredencoding()
+
+   Then use *code* as the encoding for :meth:`str.encode` calls.
 
 .. seealso::
 
    Module :mod:`curses.ascii`
       Utilities for working with ASCII characters, regardless of your locale settings.
 
    Module :mod:`curses.panel`
       A panel stack extension that adds depth to  curses windows.
 
    Module :mod:`curses.textpad`
       Editable text widget for curses supporting  :program:`Emacs`\ -like bindings.
 
    Module :mod:`curses.wrapper`
       Convenience function to ensure proper terminal setup and resetting on
       application entry and exit.
 
-   `Curses Programming with Python <http://www.python.org/doc/howto/curses/curses.html>`_
+   :ref:`curses-howto`
       Tutorial material on using curses with Python, by Andrew Kuchling and Eric
-      Raymond, is available on the Python Web site.
+      Raymond.
 
    The :file:`Demo/curses/` directory in the Python source distribution contains
    some example programs using the curses bindings provided by this module.
 
 
 .. _curses-functions:
 
 Functions
 ---------
 
 The module :mod:`curses` defines the following exception:
 
@@ -632,28 +645,28 @@
 .. method:: window.attrset(attr)
 
    Set the "background" set of attributes to *attr*.  This set is initially 0 (no
    attributes).
 
 
 .. method:: window.bkgd(ch[, attr])
 
    Sets the background property of the window to the character *ch*, with
    attributes *attr*.  The change is then applied to every character position in
    that window:
 
-* The attribute of every character in the window  is changed to the new
+   * The attribute of every character in the window  is changed to the new
      background attribute.
 
-* Wherever  the  former background character appears, it is changed to the new
+   * Wherever  the  former background character appears, it is changed to the new
      background character.
 
 
 .. method:: window.bkgdset(ch[, attr])
 
    Sets the window's background.  A window's background consists of a character and
    any combination of attributes.  The attribute part of the background is combined
    (OR'ed) with all non-blank characters that are written into the window.  Both
    the character and attribute parts of the background are combined with the blank
    characters.  The background becomes a property of the character and moves with
    the character through any scrolling and insert/delete line/character operations.
 
@@ -689,24 +702,34 @@
    | *bl*      | Bottom-left corner  | :const:`ACS_LLCORNER` |
    +-----------+---------------------+-----------------------+
    | *br*      | Bottom-right corner | :const:`ACS_LRCORNER` |
    +-----------+---------------------+-----------------------+
 
 
 .. method:: window.box([vertch, horch])
 
    Similar to :meth:`border`, but both *ls* and *rs* are *vertch* and both *ts* and
    bs are *horch*.  The default corner characters are always used by this function.
 
 
+.. method:: window.chgat([y, x, ] [num,] attr)
+
+   Sets the attributes of *num* characters at the current cursor position, or at
+   position ``(y, x)`` if supplied. If no value of *num* is given or *num* = -1,
+   the attribute will  be set on all the characters to the end of the line.  This
+   function does not move the cursor. The changed line will be touched using the
+   :meth:`touchline` method so that the contents will be redisplayed by the next
+   window refresh.
+
+
 .. method:: window.clear()
 
    Like :meth:`erase`, but also causes the whole window to be repainted upon next
    call to :meth:`refresh`.
 
 
 .. method:: window.clearok(yes)
 
    If *yes* is 1, the next call to :meth:`refresh` will clear the window
    completely.
 
 
@@ -1004,25 +1027,25 @@
    The 6 optional arguments can only be specified when the window is a pad created
    with :func:`newpad`.  The additional parameters are needed to indicate what part
    of the pad and screen are involved. *pminrow* and *pmincol* specify the upper
    left-hand corner of the rectangle to be displayed in the pad.  *sminrow*,
    *smincol*, *smaxrow*, and *smaxcol* specify the edges of the rectangle to be
    displayed on the screen.  The lower right-hand corner of the rectangle to be
    displayed in the pad is calculated from the screen coordinates, since the
    rectangles must be the same size.  Both rectangles must be entirely contained
    within their respective structures.  Negative values of *pminrow*, *pmincol*,
    *sminrow*, or *smincol* are treated as if they were zero.
 
 
-.. method:: window.scroll([lines\ ``= 1``])
+.. method:: window.scroll([lines=1])
 
    Scroll the screen or scrolling region upward by *lines* lines.
 
 
 .. method:: window.scrollok(flag)
 
    Controls what happens when the cursor of a window is moved off the edge of the
    window or scrolling region, either as a result of a newline action on the bottom
    line, or typing the last character of the last line.  If *flag* is false, the
    cursor is left on the bottom line.  If *flag* is true, the window is scrolled up
    one line.  Note that in order to get the physical scrolling effect on the
    terminal, it is also necessary to call :meth:`idlok`.
@@ -1080,27 +1103,29 @@
 
 
 .. method:: window.timeout(delay)
 
    Sets blocking or non-blocking read behavior for the window.  If *delay* is
    negative, blocking read is used (which will wait indefinitely for input).  If
    *delay* is zero, then non-blocking read is used, and -1 will be returned by
    :meth:`getch` if no input is waiting.  If *delay* is positive, then
    :meth:`getch` will block for *delay* milliseconds, and return -1 if there is
    still no input at the end of that time.
 
 
-.. method:: window.touchline(start, count)
+.. method:: window.touchline(start, count[, changed])
 
-   Pretend *count* lines have been changed, starting with line *start*.
+   Pretend *count* lines have been changed, starting with line *start*.  If
+   *changed* is supplied, it specifies whether the affected lines are marked as
+   having been changed (*changed*\ =1) or unchanged (*changed*\ =0).
 
 
 .. method:: window.touchwin()
 
    Pretend the whole window has been changed, for purposes of drawing
    optimizations.
 
 
 .. method:: window.untouchwin()
 
    Marks all lines in  the  window  as unchanged since the last call to
    :meth:`refresh`.
@@ -1149,26 +1174,25 @@
 | ``A_DIM``        | Dim mode.                     |
 +------------------+-------------------------------+
 | ``A_NORMAL``     | Normal attribute.             |
 +------------------+-------------------------------+
 | ``A_STANDOUT``   | Standout mode.                |
 +------------------+-------------------------------+
 | ``A_UNDERLINE``  | Underline mode.               |
 +------------------+-------------------------------+
 
 Keys are referred to by integer constants with names starting with  ``KEY_``.
 The exact keycaps available are system dependent.
 
-.. % XXX this table is far too large!
-.. % XXX should this table be alphabetized?
+.. XXX this table is far too large! should it be alphabetized?
 
 +-------------------+--------------------------------------------+
 | Key constant      | Key                                        |
 +===================+============================================+
 | ``KEY_MIN``       | Minimum key value                          |
 +-------------------+--------------------------------------------+
 | ``KEY_BREAK``     | Break key (unreliable)                     |
 +-------------------+--------------------------------------------+
 | ``KEY_DOWN``      | Down-arrow                                 |
 +-------------------+--------------------------------------------+
 | ``KEY_UP``        | Up-arrow                                   |
 +-------------------+--------------------------------------------+
@@ -1505,26 +1529,26 @@
 
 .. module:: curses.textpad
    :synopsis: Emacs-like input editing in a curses window.
 .. moduleauthor:: Eric Raymond <esr@thyrsus.com>
 .. sectionauthor:: Eric Raymond <esr@thyrsus.com>
 
 
 .. versionadded:: 1.6
 
 The :mod:`curses.textpad` module provides a :class:`Textbox` class that handles
 elementary text editing in a curses window, supporting a set of keybindings
 resembling those of Emacs (thus, also of Netscape Navigator, BBedit 6.x,
-FrameMaker, and many other programs).  The module also provides a rectangle-
-drawing function useful for framing text boxes or for other purposes.
+FrameMaker, and many other programs).  The module also provides a
+rectangle-drawing function useful for framing text boxes or for other purposes.
 
 The module :mod:`curses.textpad` defines the following function:
 
 
 .. function:: rectangle(win, uly, ulx, lry, lrx)
 
    Draw a rectangle.  The first argument must be a window object; the remaining
    arguments are coordinates relative to that window.  The second and third
    arguments are the y and x coordinates of the upper left hand corner of the
    rectangle to be drawn; the fourth and fifth arguments are the y and x
    coordinates of the lower right hand corner. The rectangle will be drawn using
    VT100/IBM PC forms characters on terminals that make this possible (including
@@ -1539,110 +1563,112 @@
 
 You can instantiate a :class:`Textbox` object as follows:
 
 
 .. class:: Textbox(win)
 
    Return a textbox widget object.  The *win* argument should be a curses
    :class:`WindowObject` in which the textbox is to be contained. The edit cursor
    of the textbox is initially located at the upper left hand corner of the
    containing window, with coordinates ``(0, 0)``. The instance's
    :attr:`stripspaces` flag is initially on.
 
-:class:`Textbox` objects have the following methods:
+   :class:`Textbox` objects have the following methods:
 
 
-.. method:: Textbox.edit([validator])
+   .. method:: edit([validator])
 
-   This is the entry point you will normally use.  It accepts editing keystrokes
-   until one of the termination keystrokes is entered.  If *validator* is supplied,
-   it must be a function.  It will be called for each keystroke entered with the
-   keystroke as a parameter; command dispatch is done on the result. This method
-   returns the window contents as a string; whether blanks in the window are
-   included is affected by the :attr:`stripspaces` member.
+      This is the entry point you will normally use.  It accepts editing
+      keystrokes until one of the termination keystrokes is entered.  If
+      *validator* is supplied, it must be a function.  It will be called for
+      each keystroke entered with the keystroke as a parameter; command dispatch
+      is done on the result. This method returns the window contents as a
+      string; whether blanks in the window are included is affected by the
+      :attr:`stripspaces` member.
+
+
-
-
-.. method:: Textbox.do_command(ch)
-
+   .. method:: do_command(ch)
+
-   Process a single command keystroke.  Here are the supported special keystrokes:
+      Process a single command keystroke.  Here are the supported special
+      keystrokes:
+
-
-   +------------------+-------------------------------------------+
-   | Keystroke        | Action                                    |
-   +==================+===========================================+
+      +------------------+-------------------------------------------+
+      | Keystroke        | Action                                    |
+      +==================+===========================================+
-   | :kbd:`Control-A` | Go to left edge of window.                |
-   +------------------+-------------------------------------------+
-   | :kbd:`Control-B` | Cursor left, wrapping to previous line if |
-   |                  | appropriate.                              |
-   +------------------+-------------------------------------------+
-   | :kbd:`Control-D` | Delete character under cursor.            |
-   +------------------+-------------------------------------------+
-   | :kbd:`Control-E` | Go to right edge (stripspaces off) or end |
-   |                  | of line (stripspaces on).                 |
-   +------------------+-------------------------------------------+
-   | :kbd:`Control-F` | Cursor right, wrapping to next line when  |
-   |                  | appropriate.                              |
-   +------------------+-------------------------------------------+
-   | :kbd:`Control-G` | Terminate, returning the window contents. |
-   +------------------+-------------------------------------------+
+      | :kbd:`Control-A` | Go to left edge of window.                |
+      +------------------+-------------------------------------------+
+      | :kbd:`Control-B` | Cursor left, wrapping to previous line if |
+      |                  | appropriate.                              |
+      +------------------+-------------------------------------------+
+      | :kbd:`Control-D` | Delete character under cursor.            |
+      +------------------+-------------------------------------------+
+      | :kbd:`Control-E` | Go to right edge (stripspaces off) or end |
+      |                  | of line (stripspaces on).                 |
+      +------------------+-------------------------------------------+
+      | :kbd:`Control-F` | Cursor right, wrapping to next line when  |
+      |                  | appropriate.                              |
+      +------------------+-------------------------------------------+
+      | :kbd:`Control-G` | Terminate, returning the window contents. |
+      +------------------+-------------------------------------------+
-   | :kbd:`Control-H` | Delete character backward.                |
-   +------------------+-------------------------------------------+
-   | :kbd:`Control-J` | Terminate if the window is 1 line,        |
-   |                  | otherwise insert newline.                 |
-   +------------------+-------------------------------------------+
-   | :kbd:`Control-K` | If line is blank, delete it, otherwise    |
-   |                  | clear to end of line.                     |
-   +------------------+-------------------------------------------+
+      | :kbd:`Control-H` | Delete character backward.                |
+      +------------------+-------------------------------------------+
+      | :kbd:`Control-J` | Terminate if the window is 1 line,        |
+      |                  | otherwise insert newline.                 |
+      +------------------+-------------------------------------------+
+      | :kbd:`Control-K` | If line is blank, delete it, otherwise    |
+      |                  | clear to end of line.                     |
+      +------------------+-------------------------------------------+
-   | :kbd:`Control-L` | Refresh screen.                           |
-   +------------------+-------------------------------------------+
-   | :kbd:`Control-N` | Cursor down; move down one line.          |
-   +------------------+-------------------------------------------+
-   | :kbd:`Control-O` | Insert a blank line at cursor location.   |
-   +------------------+-------------------------------------------+
-   | :kbd:`Control-P` | Cursor up; move up one line.              |
-   +------------------+-------------------------------------------+
+      | :kbd:`Control-L` | Refresh screen.                           |
+      +------------------+-------------------------------------------+
+      | :kbd:`Control-N` | Cursor down; move down one line.          |
+      +------------------+-------------------------------------------+
+      | :kbd:`Control-O` | Insert a blank line at cursor location.   |
+      +------------------+-------------------------------------------+
+      | :kbd:`Control-P` | Cursor up; move up one line.              |
+      +------------------+-------------------------------------------+
-
-   Move operations do nothing if the cursor is at an edge where the movement is not
-   possible.  The following synonyms are supported where possible:
+
+      Move operations do nothing if the cursor is at an edge where the movement
+      is not possible.  The following synonyms are supported where possible:
+
-
-   +------------------------+------------------+
-   | Constant               | Keystroke        |
-   +========================+==================+
-   | :const:`KEY_LEFT`      | :kbd:`Control-B` |
-   +------------------------+------------------+
-   | :const:`KEY_RIGHT`     | :kbd:`Control-F` |
-   +------------------------+------------------+
-   | :const:`KEY_UP`        | :kbd:`Control-P` |
-   +------------------------+------------------+
-   | :const:`KEY_DOWN`      | :kbd:`Control-N` |
-   +------------------------+------------------+
-   | :const:`KEY_BACKSPACE` | :kbd:`Control-h` |
-   +------------------------+------------------+
+      +------------------------+------------------+
+      | Constant               | Keystroke        |
+      +========================+==================+
+      | :const:`KEY_LEFT`      | :kbd:`Control-B` |
+      +------------------------+------------------+
+      | :const:`KEY_RIGHT`     | :kbd:`Control-F` |
+      +------------------------+------------------+
+      | :const:`KEY_UP`        | :kbd:`Control-P` |
+      +------------------------+------------------+
+      | :const:`KEY_DOWN`      | :kbd:`Control-N` |
+      +------------------------+------------------+
+      | :const:`KEY_BACKSPACE` | :kbd:`Control-h` |
+      +------------------------+------------------+
-
-   All other keystrokes are treated as a command to insert the given character and
-   move right (with line wrapping).
+      All other keystrokes are treated as a command to insert the given
+      character and move right (with line wrapping).
+
-
-.. method:: Textbox.gather()
-
-   This method returns the window contents as a string; whether blanks in the
-   window are included is affected by the :attr:`stripspaces` member.
+   .. method:: gather()
+
+      This method returns the window contents as a string; whether blanks in the
+      window are included is affected by the :attr:`stripspaces` member.
+
+
-
-
-.. attribute:: Textbox.stripspaces
-
-   This data member is a flag which controls the interpretation of blanks in the
-   window.  When it is on, trailing blanks on each line are ignored; any cursor
-   motion that would land the cursor on a trailing blank goes to the end of that
-   line instead, and trailing blanks are stripped when the window contents are
-   gathered.
+
+   .. attribute:: stripspaces
+
+      This data member is a flag which controls the interpretation of blanks in
+      the window.  When it is on, trailing blanks on each line are ignored; any
+      cursor motion that would land the cursor on a trailing blank goes to the
+      end of that line instead, and trailing blanks are stripped when the window
+      contents are gathered.
 
 
 :mod:`curses.wrapper` --- Terminal handler for curses programs
 ==============================================================
 
 .. module:: curses.wrapper
    :synopsis: Terminal configuration wrapper for curses programs.
 .. moduleauthor:: Eric Raymond <esr@thyrsus.com>
 .. sectionauthor:: Eric Raymond <esr@thyrsus.com>
 
 
 .. versionadded:: 1.6
