Source

sphinx / Doc-3k / library / curses.rst

:mod:`curses` --- Terminal handling for character-cell displays

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.

Functions

The module :mod:`curses` defines the following exception:

Note

Whenever x or y arguments to a function or a method are optional, they default to the current cursor location. Whenever attr is optional, it defaults to :const:`A_NORMAL`.

The module :mod:`curses` defines the following functions:

Window Objects

Window objects, as returned by :func:`initscr` and :func:`newwin` above, have the following methods:

  • 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

    background character.

Constants

The :mod:`curses` module defines the following data members:

Several constants are available to specify character cell attributes:

Attribute Meaning
A_ALTCHARSET Alternate character set mode.
A_BLINK Blink mode.
A_BOLD Bold mode.
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.

Key constant Key
KEY_MIN Minimum key value
KEY_BREAK Break key (unreliable)
KEY_DOWN Down-arrow
KEY_UP Up-arrow
KEY_LEFT Left-arrow
KEY_RIGHT Right-arrow
KEY_HOME Home key (upward+left arrow)
KEY_BACKSPACE Backspace (unreliable)
KEY_F0 Function keys. Up to 64 function keys are supported.
KEY_Fn Value of function key n
KEY_DL Delete line
KEY_IL Insert line
KEY_DC Delete character
KEY_IC Insert char or enter insert mode
KEY_EIC Exit insert char mode
KEY_CLEAR Clear screen
KEY_EOS Clear to end of screen
KEY_EOL Clear to end of line
KEY_SF Scroll 1 line forward
KEY_SR Scroll 1 line backward (reverse)
KEY_NPAGE Next page
KEY_PPAGE Previous page
KEY_STAB Set tab
KEY_CTAB Clear tab
KEY_CATAB Clear all tabs
KEY_ENTER Enter or send (unreliable)
KEY_SRESET Soft (partial) reset (unreliable)
KEY_RESET Reset or hard reset (unreliable)
KEY_PRINT Print
KEY_LL Home down or bottom (lower left)
KEY_A1 Upper left of keypad
KEY_A3 Upper right of keypad
KEY_B2 Center of keypad
KEY_C1 Lower left of keypad
KEY_C3 Lower right of keypad
KEY_BTAB Back tab
KEY_BEG Beg (beginning)
KEY_CANCEL Cancel
KEY_CLOSE Close
KEY_COMMAND Cmd (command)
KEY_COPY Copy
KEY_CREATE Create
KEY_END End
KEY_EXIT Exit
KEY_FIND Find
KEY_HELP Help
KEY_MARK Mark
KEY_MESSAGE Message
KEY_MOVE Move
KEY_NEXT Next
KEY_OPEN Open
KEY_OPTIONS Options
KEY_PREVIOUS Prev (previous)
KEY_REDO Redo
KEY_REFERENCE Ref (reference)
KEY_REFRESH Refresh
KEY_REPLACE Replace
KEY_RESTART Restart
KEY_RESUME Resume
KEY_SAVE Save
KEY_SBEG Shifted Beg (beginning)
KEY_SCANCEL Shifted Cancel
KEY_SCOMMAND Shifted Command
KEY_SCOPY Shifted Copy
KEY_SCREATE Shifted Create
KEY_SDC Shifted Delete char
KEY_SDL Shifted Delete line
KEY_SELECT Select
KEY_SEND Shifted End
KEY_SEOL Shifted Clear line
KEY_SEXIT Shifted Dxit
KEY_SFIND Shifted Find
KEY_SHELP Shifted Help
KEY_SHOME Shifted Home
KEY_SIC Shifted Input
KEY_SLEFT Shifted Left arrow
KEY_SMESSAGE Shifted Message
KEY_SMOVE Shifted Move
KEY_SNEXT Shifted Next
KEY_SOPTIONS Shifted Options
KEY_SPREVIOUS Shifted Prev
KEY_SPRINT Shifted Print
KEY_SREDO Shifted Redo
KEY_SREPLACE Shifted Replace
KEY_SRIGHT Shifted Right arrow
KEY_SRSUME Shifted Resume
KEY_SSAVE Shifted Save
KEY_SSUSPEND Shifted Suspend
KEY_SUNDO Shifted Undo
KEY_SUSPEND Suspend
KEY_UNDO Undo
KEY_MOUSE Mouse event has occurred
KEY_RESIZE Terminal resize event
KEY_MAX Maximum key value

On VT100s and their software emulations, such as X terminal emulators, there are normally at least four function keys (:const:`KEY_F1`, :const:`KEY_F2`, :const:`KEY_F3`, :const:`KEY_F4`) available, and the arrow keys mapped to :const:`KEY_UP`, :const:`KEY_DOWN`, :const:`KEY_LEFT` and :const:`KEY_RIGHT` in the obvious way. If your machine has a PC keyboard, it is safe to expect arrow keys and twelve function keys (older PC keyboards may have only ten function keys); also, the following keypad mappings are standard:

Keycap Constant
:kbd:`Insert` KEY_IC
:kbd:`Delete` KEY_DC
:kbd:`Home` KEY_HOME
:kbd:`End` KEY_END
:kbd:`Page Up` KEY_NPAGE
:kbd:`Page Down` KEY_PPAGE

The following table lists characters from the alternate character set. These are inherited from the VT100 terminal, and will generally be available on software emulations such as X terminals. When there is no graphic available, curses falls back on a crude printable ASCII approximation.

Note

These are available only after :func:`initscr` has been called.

ACS code Meaning
ACS_BBSS alternate name for upper right corner
ACS_BLOCK solid square block
ACS_BOARD board of squares
ACS_BSBS alternate name for horizontal line
ACS_BSSB alternate name for upper left corner
ACS_BSSS alternate name for top tee
ACS_BTEE bottom tee
ACS_BULLET bullet
ACS_CKBOARD checker board (stipple)
ACS_DARROW arrow pointing down
ACS_DEGREE degree symbol
ACS_DIAMOND diamond
ACS_GEQUAL greater-than-or-equal-to
ACS_HLINE horizontal line
ACS_LANTERN lantern symbol
ACS_LARROW left arrow
ACS_LEQUAL less-than-or-equal-to
ACS_LLCORNER lower left-hand corner
ACS_LRCORNER lower right-hand corner
ACS_LTEE left tee
ACS_NEQUAL not-equal sign
ACS_PI letter pi
ACS_PLMINUS plus-or-minus sign
ACS_PLUS big plus sign
ACS_RARROW right arrow
ACS_RTEE right tee
ACS_S1 scan line 1
ACS_S3 scan line 3
ACS_S7 scan line 7
ACS_S9 scan line 9
ACS_SBBS alternate name for lower right corner
ACS_SBSB alternate name for vertical line
ACS_SBSS alternate name for right tee
ACS_SSBB alternate name for lower left corner
ACS_SSBS alternate name for bottom tee
ACS_SSSB alternate name for left tee
ACS_SSSS alternate name for crossover or big plus
ACS_STERLING pound sterling
ACS_TTEE top tee
ACS_UARROW up arrow
ACS_ULCORNER upper left corner
ACS_URCORNER upper right corner
ACS_VLINE vertical line

The following table lists the predefined colors:

Constant Color
COLOR_BLACK Black
COLOR_BLUE Blue
COLOR_CYAN Cyan (light greenish blue)
COLOR_GREEN Green
COLOR_MAGENTA Magenta (purplish red)
COLOR_RED Red
COLOR_WHITE White
COLOR_YELLOW Yellow

:mod:`curses.textpad` --- Text input widget for curses programs

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.

The module :mod:`curses.textpad` defines the following function:

Textbox objects

You can instantiate a :class:`Textbox` object as follows:

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:

:mod:`curses.wrapper` --- Terminal handler for curses programs

This module supplies one function, :func:`wrapper`, which runs another function which should be the rest of your curses-using application. If the application raises an exception, :func:`wrapper` will restore the terminal to a sane state before re-raising the exception and generating a traceback.

Before calling the hook function, :func:`wrapper` turns on cbreak mode, turns off echo, enables the terminal keypad, and initializes colors if the terminal has color support. On exit (whether normally or by exception) it restores cooked mode, turns on echo, and disables the terminal keypad.

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.