| :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. |
| |
n | The :mod:`curses` module provides an interface to the curses library, the de- |
n | The :mod:`curses` module provides an interface to the curses library, the |
| facto standard for portable advanced terminal handling. |
| 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. |
| |
n | .. 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. |
| |
n | `Curses Programming with Python <http://www.python.org/doc/howto/curses/curses.html>`_ |
n | :ref:`curses-howto` |
| Tutorial material on using curses with Python, by Andrew Kuchling and Eric |
n | Raymond, is available on the Python Web site. |
n | 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 |
| .. 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. |
| |
n | :class:`Textbox` objects have the following methods: |
n | :class:`Textbox` objects have the following methods: |
| |
| |
n | .. method:: Textbox.edit([validator]) |
n | .. method:: edit([validator]) |
| |
n | This is the entry point you will normally use. It accepts editing keystrokes |
n | This is the entry point you will normally use. It accepts editing |
| until one of the termination keystrokes is entered. If *validator* is supplied, |
| keystrokes until one of the termination keystrokes is entered. If |
| it must be a function. It will be called for each keystroke entered with the |
| *validator* is supplied, it must be a function. It will be called for |
| keystroke as a parameter; command dispatch is done on the result. This method |
| each keystroke entered with the keystroke as a parameter; command dispatch |
| returns the window contents as a string; whether blanks in the window are |
| is done on the result. This method returns the window contents as a |
| included is affected by the :attr:`stripspaces` member. |
| string; whether blanks in the window are included is affected by the |
| :attr:`stripspaces` member. |
| |
| |
n | .. method:: Textbox.do_command(ch) |
n | .. method:: do_command(ch) |
| |
n | Process a single command keystroke. Here are the supported special keystrokes: |
n | Process a single command keystroke. Here are the supported special |
| keystrokes: |
| |
n | +------------------+-------------------------------------------+ |
n | +------------------+-------------------------------------------+ |
| | Keystroke | Action | |
| | Keystroke | Action | |
| +==================+===========================================+ |
| +==================+===========================================+ |
| | :kbd:`Control-A` | Go to left edge of window. | |
| | :kbd:`Control-A` | Go to left edge of window. | |
| +------------------+-------------------------------------------+ |
| +------------------+-------------------------------------------+ |
| | :kbd:`Control-B` | Cursor left, wrapping to previous line if | |
| | :kbd:`Control-B` | Cursor left, wrapping to previous line if | |
| | | appropriate. | |
| | | appropriate. | |
| +------------------+-------------------------------------------+ |
| +------------------+-------------------------------------------+ |
| | :kbd:`Control-D` | Delete character under cursor. | |
| | :kbd:`Control-D` | Delete character under cursor. | |
| +------------------+-------------------------------------------+ |
| +------------------+-------------------------------------------+ |
| | :kbd:`Control-E` | Go to right edge (stripspaces off) or end | |
| | :kbd:`Control-E` | Go to right edge (stripspaces off) or end | |
| | | of line (stripspaces on). | |
| | | of line (stripspaces on). | |
| +------------------+-------------------------------------------+ |
| +------------------+-------------------------------------------+ |
| | :kbd:`Control-F` | Cursor right, wrapping to next line when | |
| | :kbd:`Control-F` | Cursor right, wrapping to next line when | |
| | | appropriate. | |
| | | appropriate. | |
| +------------------+-------------------------------------------+ |
| +------------------+-------------------------------------------+ |
| | :kbd:`Control-G` | Terminate, returning the window contents. | |
| | :kbd:`Control-G` | Terminate, returning the window contents. | |
| +------------------+-------------------------------------------+ |
| +------------------+-------------------------------------------+ |
| | :kbd:`Control-H` | Delete character backward. | |
| | :kbd:`Control-H` | Delete character backward. | |
| +------------------+-------------------------------------------+ |
| +------------------+-------------------------------------------+ |
| | :kbd:`Control-J` | Terminate if the window is 1 line, | |
| | :kbd:`Control-J` | Terminate if the window is 1 line, | |
| | | otherwise insert newline. | |
| | | otherwise insert newline. | |
| +------------------+-------------------------------------------+ |
| +------------------+-------------------------------------------+ |
| | :kbd:`Control-K` | If line is blank, delete it, otherwise | |
| | :kbd:`Control-K` | If line is blank, delete it, otherwise | |
| | | clear to end of line. | |
| | | clear to end of line. | |
| +------------------+-------------------------------------------+ |
| +------------------+-------------------------------------------+ |
| | :kbd:`Control-L` | Refresh screen. | |
| | :kbd:`Control-L` | Refresh screen. | |
| +------------------+-------------------------------------------+ |
| +------------------+-------------------------------------------+ |
| | :kbd:`Control-N` | Cursor down; move down one line. | |
| | :kbd:`Control-N` | Cursor down; move down one line. | |
| +------------------+-------------------------------------------+ |
| +------------------+-------------------------------------------+ |
| | :kbd:`Control-O` | Insert a blank line at cursor location. | |
| | :kbd:`Control-O` | Insert a blank line at cursor location. | |
| +------------------+-------------------------------------------+ |
| +------------------+-------------------------------------------+ |
| | :kbd:`Control-P` | Cursor up; move up one line. | |
| | :kbd:`Control-P` | Cursor up; move up one line. | |
| +------------------+-------------------------------------------+ |
| +------------------+-------------------------------------------+ |
| |
n | Move operations do nothing if the cursor is at an edge where the movement is not |
n | Move operations do nothing if the cursor is at an edge where the movement |
| possible. The following synonyms are supported where possible: |
| is not possible. The following synonyms are supported where possible: |
| |
n | +------------------------+------------------+ |
n | +------------------------+------------------+ |
| | Constant | Keystroke | |
| | Constant | Keystroke | |
| +========================+==================+ |
| +========================+==================+ |
| | :const:`KEY_LEFT` | :kbd:`Control-B` | |
| | :const:`KEY_LEFT` | :kbd:`Control-B` | |
| +------------------------+------------------+ |
| +------------------------+------------------+ |
| | :const:`KEY_RIGHT` | :kbd:`Control-F` | |
| | :const:`KEY_RIGHT` | :kbd:`Control-F` | |
| +------------------------+------------------+ |
| +------------------------+------------------+ |
| | :const:`KEY_UP` | :kbd:`Control-P` | |
| | :const:`KEY_UP` | :kbd:`Control-P` | |
| +------------------------+------------------+ |
| +------------------------+------------------+ |
| | :const:`KEY_DOWN` | :kbd:`Control-N` | |
| | :const:`KEY_DOWN` | :kbd:`Control-N` | |
| +------------------------+------------------+ |
| +------------------------+------------------+ |
| | :const:`KEY_BACKSPACE` | :kbd:`Control-h` | |
| | :const:`KEY_BACKSPACE` | :kbd:`Control-h` | |
| +------------------------+------------------+ |
| +------------------------+------------------+ |
| |
n | All other keystrokes are treated as a command to insert the given character and |
n | All other keystrokes are treated as a command to insert the given |
| move right (with line wrapping). |
| character and move right (with line wrapping). |
| |
| |
n | .. method:: Textbox.gather() |
n | .. method:: gather() |
| |
n | This method returns the window contents as a string; whether blanks in the |
n | This method returns the window contents as a string; whether blanks in the |
| window are included is affected by the :attr:`stripspaces` member. |
| window are included is affected by the :attr:`stripspaces` member. |
| |
| |
n | .. attribute:: Textbox.stripspaces |
n | .. attribute:: stripspaces |
| |
t | This data member is a flag which controls the interpretation of blanks in the |
t | This data member is a flag which controls the interpretation of blanks in |
| window. When it is on, trailing blanks on each line are ignored; any cursor |
| the window. When it is on, trailing blanks on each line are ignored; any |
| motion that would land the cursor on a trailing blank goes to the end of that |
| cursor motion that would land the cursor on a trailing blank goes to the |
| line instead, and trailing blanks are stripped when the window contents are |
| end of that line instead, and trailing blanks are stripped when the window |
| gathered. |
| 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> |