Navigation

The 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 Windows, DOS, 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

Whenever the documentation mentions a character it can be specified
as an integer, a one-character Unicode string or a one-byte byte string.

Whenever the documentation mentions a character string it can be specified
as a Unicode string or a byte string.

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
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:

Return the output speed of the terminal in bits per second. On software
terminal emulators it will have a fixed high value. Included for historical
reasons; in former times, it was used to write output loops for time delays and
occasionally to change interfaces depending on the line speed.

Enter cbreak mode. In cbreak mode (sometimes called “rare” mode) normal tty
line buffering is turned off and characters are available to be read one by one.
However, unlike raw mode, special characters (interrupt, quit, suspend, and flow
control) retain their effects on the tty driver and calling program. Calling
first raw() then cbreak() leaves the terminal in cbreak mode.

Return the intensity of the red, green, and blue (RGB) components in the color
color_number, which must be between 0 and COLORS. Return a 3-tuple,
containing the R,G,B values for the given color, which will be between
0 (no component) and 1000 (maximum amount of component).

Return the attribute value for displaying text in the specified color. This
attribute value can be combined with A_STANDOUT, A_REVERSE,
and the other A_* attributes. pair_number() is the counterpart
to this function.

Set the cursor state. visibility can be set to 0, 1, or 2, for invisible,
normal, or very visible. If the terminal supports the visibility requested, return the
previous cursor state; otherwise raise an exception. On many
terminals, the “visible” mode is an underline cursor and the “very visible” mode
is a block cursor.

Save the current terminal mode as the “program” mode, the mode when the running
program is using curses. (Its counterpart is the “shell” mode, for when the
program is not in curses.) Subsequent calls to reset_prog_mode() will
restore this mode.

Save the current terminal mode as the “shell” mode, the mode when the running
program is not using curses. (Its counterpart is the “program” mode, when the
program is using curses capabilities.) Subsequent calls to
reset_shell_mode() will restore this mode.

Update the physical screen. The curses library keeps two data structures, one
representing the current physical screen contents and a virtual screen
representing the desired next state. The doupdate() ground updates the
physical screen to match the virtual screen.

The virtual screen may be updated by a noutrefresh() call after write
operations such as addstr() have been performed on a window. The normal
refresh() call is simply noutrefresh() followed by doupdate();
if you have to update multiple windows, you can speed performance and perhaps
reduce screen flicker by issuing noutrefresh() calls on all windows,
followed by a single doupdate().

Return the user’s current erase character as a one-byte bytes object. Under Unix operating systems this
is a property of the controlling tty of the curses program, and is not set by
the curses library itself.

The filter() routine, if used, must be called before initscr() is
called. The effect is that, during those calls, LINES is set to 1; the
capabilities clear, cup, cud, cud1, cuu1, cuu, vpa are disabled; and the home
string is set to the value of cr. The effect is that the cursor is confined to
the current line, and so are screen updates. This may be used for enabling
character-at-a-time line editing without touching the rest of the screen.

After getch() returns KEY_MOUSE to signal a mouse event, this
method should be call to retrieve the queued mouse event, represented as a
5-tuple (id,x,y,z,bstate). id is an ID value used to distinguish
multiple devices, and x, y, z are the event’s coordinates. (z is
currently unused.) bstate is an integer value whose bits will be set to
indicate the type of event, and will be the bitwise OR of one or more of the
following constants, where n is the button number from 1 to 4:
BUTTONn_PRESSED, BUTTONn_RELEASED, BUTTONn_CLICKED,
BUTTONn_DOUBLE_CLICKED, BUTTONn_TRIPLE_CLICKED,
BUTTON_SHIFT, BUTTON_CTRL, BUTTON_ALT.

Return True if the terminal has insert- and delete-line capabilities, or can
simulate them using scrolling regions. This function is included for
historical reasons only, as all modern software terminal emulators have such
capabilities.

Used for half-delay mode, which is similar to cbreak mode in that characters
typed by the user are immediately available to the program. However, after
blocking for tenths tenths of seconds, raise an exception if nothing has
been typed. The value of tenths must be a number between 1 and 255. Use
nocbreak() to leave half-delay mode.

Change the definition of a color, taking the number of the color to be changed
followed by three RGB values (for the amounts of red, green, and blue
components). The value of color_number must be between 0 and
COLORS. Each of r, g, b, must be a value between 0 and
1000. When init_color() is used, all occurrences of that color on the
screen immediately change to the new definition. This function is a no-op on
most terminals; it is active only if can_change_color() returns True.

Change the definition of a color-pair. It takes three arguments: the number of
the color-pair to be changed, the foreground color number, and the background
color number. The value of pair_number must be between 1 and
COLOR_PAIRS-1 (the 0 color pair is wired to white on black and cannot
be changed). The value of fg and bg arguments must be between 0 and
COLORS. If the color-pair was previously initialized, the screen is
refreshed and all occurrences of that color-pair are changed to the new
definition.

Return the name of the key numbered k as a bytes object. The name of a key generating printable
ASCII character is the key’s character. The name of a control-key combination
is a two-byte bytes object consisting of a caret (b'^') followed by the corresponding
printable ASCII character. The name of an alt-key combination (128–255) is a
bytes object consisting of the prefix b'M-' followed by the name of the corresponding
ASCII character.

Return the user’s current line kill character as a one-byte bytes object. Under Unix operating systems
this is a property of the controlling tty of the curses program, and is not set
by the curses library itself.

Return a bytes object containing the terminfo long name field describing the current
terminal. The maximum length of a verbose description is 128 characters. It is
defined only after the call to initscr().

Set the maximum time in milliseconds that can elapse between press and release
events in order for them to be recognized as a click, and return the previous
interval value. The default value is 200 msec, or one fifth of a second.

Set the mouse events to be reported, and return a tuple (availmask,oldmask). availmask indicates which of the specified mouse events can be
reported; on complete failure it returns 0. oldmask is the previous value of
the given window’s mouse event mask. If this function is never called, no mouse
events are ever reported.

Create and return a pointer to a new pad data structure with the given number
of lines and columns. Return a pad as a window object.

A pad is like a window, except that it is not restricted by the screen size, and
is not necessarily associated with a particular part of the screen. Pads can be
used when a large window is needed, and only a part of the window will be on the
screen at one time. Automatic refreshes of pads (such as from scrolling or
echoing of input) do not occur. The refresh() and noutrefresh()
methods of a pad require 6 arguments to specify the part of the pad to be
displayed and the location on the screen to be used for the display. The
arguments are pminrow, pmincol, sminrow, smincol, smaxrow, smaxcol; the p
arguments refer to the upper left corner of the pad region to be displayed and
the s arguments define a clipping box on the screen within which the pad region
is to be displayed.

Leave newline mode. Disable translation of return into newline on input, and
disable low-level translation of newline into newline/return on output (but this
does not change the behavior of addch('\n'), which always does the
equivalent of return and line feed on the virtual screen). With translation
off, curses can sometimes speed up vertical motion a little; also, it will be
able to detect the return key on input.

When the noqiflush() routine is used, normal flush of input and output queues
associated with the INTR, QUIT and SUSP characters will not be done. You may
want to call noqiflush() in a signal handler if you want output to
continue as though the interrupt had not occurred, after the handler exits.

Backend function used by resizeterm(), performing most of the work;
when resizing the windows, resize_term() blank-fills the areas that are
extended. The calling application should fill in these areas with
appropriate data. The resize_term() function attempts to resize all
windows. However, due to the calling convention of pads, it is not possible
to resize these without additional interaction with the application.

Resize the standard and current windows to the specified dimensions, and
adjusts other bookkeeping data used by the curses library that record the
window dimensions (in particular the SIGWINCH handler).

Initialize the terminal. term is a string giving
the terminal name, or None; if omitted or None, the value of the
TERM environment variable will be used. fd is the
file descriptor to which any initialization sequences will be sent; if not
supplied or -1, the file descriptor for sys.stdout will be used.

Must be called if the programmer wants to use colors, and before any other color
manipulation routine is called. It is good practice to call this routine right
after initscr().

start_color() initializes eight basic colors (black, red, green, yellow,
blue, magenta, cyan, and white), and two global variables in the curses
module, COLORS and COLOR_PAIRS, containing the maximum number
of colors and color-pairs the terminal can support. It also restores the colors
on the terminal to the values they had when the terminal was just turned on.

Return the value of the Boolean capability corresponding to the terminfo
capability name capname as an integer. Return the value -1 if capname is not a
Boolean capability, or 0 if it is canceled or absent from the terminal
description.

Return the value of the numeric capability corresponding to the terminfo
capability name capname as an integer. Return the value -2 if capname is not a
numeric capability, or -1 if it is canceled or absent from the terminal
description.

Return the value of the string capability corresponding to the terminfo
capability name capname as a bytes object. Return None if capname
is not a terminfo “string capability”, or is canceled or absent from the
terminal description.

Instantiate the bytes object str with the supplied parameters, where str should
be a parameterized string obtained from the terminfo database. E.g.
tparm(tigetstr("cup"),5,3) could result in b'\033[6;4H', the exact
result depending on terminal type.

Specify that the file descriptor fd be used for typeahead checking. If fd
is -1, then no typeahead checking is done.

The curses library does “line-breakout optimization” by looking for typeahead
periodically while updating the screen. If input is found, and it is coming
from a tty, the current update is postponed until refresh or doupdate is called
again, allowing faster response to commands typed in advance. This function
allows specifying a different file descriptor for typeahead checking.

Return a bytes object which is a printable representation of the character ch.
Control characters are represented as a caret followed by the character, for
example as b'^C'. Printing characters are left as they are.

If used, this function should be called before initscr() or newterm are
called. When flag is False, the values of lines and columns specified in the
terminfo database will be used, even if environment variables LINES
and COLUMNS (used by default) are set, or if curses is running in a
window (in which case default behavior would be to use the window size if
LINES and COLUMNS are not set).

Allow use of default values for colors on terminals supporting this feature. Use
this to support transparency in your application. The default color is assigned
to the color number -1. After calling this function, init_pair(x,curses.COLOR_RED,-1) initializes, for instance, color pair x to a red
foreground color on the default background.

Initialize curses and call another callable object, func, which should be the
rest of your curses-using application. If the application raises an exception,
this function will restore the terminal to a sane state before re-raising the
exception and generating a traceback. The callable object func is then passed
the main window ‘stdscr’ as its first argument, followed by any other arguments
passed to wrapper(). Before calling 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.

Paint character ch at (y,x) with attributes attr, overwriting any
character previously painter at that location. By default, the character
position and attributes are the current settings for the window object.

Note

Writing outside the window, subwindow, or pad raises a curses.error.
Attempting to write to the lower right corner of a window, subwindow,
or pad will cause an exception to be raised after the character is printed.

Paint the character string str at (y,x) with attributes
attr, overwriting anything previously on the display.

Note

Writing outside the window, subwindow, or pad raises curses.error.
Attempting to write to the lower right corner of a window, subwindow,
or pad will cause an exception to be raised after the string is printed.

Set 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.

Set the attributes of num characters at the current cursor position, or at
position (y,x) if supplied. If num is not given or is -1,
the attribute will be set on all the characters to the end of the line. This
function moves cursor to position (y,x) if supplied. The changed line
will be touched using the touchline() method so that the contents will
be redisplayed by the next window refresh.

An abbreviation for “derive window”, derwin() is the same as calling
subwin(), except that begin_y and begin_x are relative to the origin
of the window, rather than relative to the entire screen. Return a window
object for the derived window.

Test whether the given pair of screen-relative character-cell coordinates are
enclosed by the given window, returning True or False. It is useful for
determining what subset of the screen windows enclose the location of a mouse
event.

Encoding used to encode method arguments (Unicode strings and characters).
The encoding attribute is inherited from the parent window when a subwindow
is created, for example with window.subwin(). By default, the locale
encoding is used (see locale.getpreferredencoding()).

Get a character. Note that the integer returned does not have to be in ASCII
range: function keys, keypad keys and so on are represented by numbers higher
than 255. In no-delay mode, return -1 if there is no input, otherwise
wait until a key is pressed.

Get a character, returning a string instead of an integer, as getch()
does. Function keys, keypad keys and other special keys return a multibyte
string containing the key name. In no-delay mode, raise an exception if
there is no input.

If flag is False, curses no longer considers using the hardware insert/delete
character feature of the terminal; if flag is True, use of character insertion
and deletion is enabled. When curses is first initialized, use of character
insert/delete is enabled by default.

If flag is True, any change in the window image automatically causes the
window to be refreshed; you no longer have to call refresh() yourself.
However, it may degrade performance considerably, due to repeated calls to
wrefresh. This option is disabled by default.

Insert nlines lines into the specified window above the current line. The
nlines bottom lines are lost. For negative nlines, delete nlines lines
starting with the one under the cursor, and move the remaining lines up. The
bottom nlines lines are cleared. The current cursor position remains the
same.

Insert a character string (as many characters as will fit on the line) before
the character under the cursor, up to n characters. If n is zero or
negative, the entire string is inserted. All characters to the right of the
cursor are shifted right, with the rightmost characters on the line being lost.
The cursor position does not change (after moving to y, x, if specified).

Insert a character string (as many characters as will fit on the line) before
the character under the cursor. All characters to the right of the cursor are
shifted right, with the rightmost characters on the line being lost. The cursor
position does not change (after moving to y, x, if specified).

Return a bytes object of characters, extracted from the window starting at the
current cursor position, or at y, x if specified. Attributes are stripped
from the characters. If n is specified, instr() returns a string
at most n characters long (exclusive of the trailing NUL).

Move the window inside its parent window. The screen-relative parameters of
the window are not changed. This routine is used to display different parts of
the parent window at the same physical position on the screen.

Mark for refresh but wait. This function updates the data structure
representing the desired state of the window, but does not force an update of
the physical screen. To accomplish that, call doupdate().

Overlay the window on top of destwin. The windows need not be the same size,
only the overlapping region is copied. This copy is non-destructive, which means
that the current background character does not overwrite the old contents of
destwin.

To get fine-grained control over the copied region, the second form of
overlay() can be used. sminrow and smincol are the upper-left
coordinates of the source window, and the other variables mark a rectangle in
the destination window.

Overwrite the window on top of destwin. The windows need not be the same size,
in which case only the overlapping region is copied. This copy is destructive,
which means that the current background character overwrites the old contents of
destwin.

To get fine-grained control over the copied region, the second form of
overwrite() can be used. sminrow and smincol are the upper-left
coordinates of the source window, the other variables mark a rectangle in the
destination window.

The 6 optional arguments can only be specified when the window is a pad created
with 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.

Reallocate storage for a curses window to adjust its dimensions to the
specified values. If either dimension is larger than the current values, the
window’s data is filled with blanks that have the current background
rendition (as set by bkgdset()) merged into them.

Control 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 idlok().

Set 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 getch() will
return -1 if no input is waiting. If delay is positive, then
getch() will block for delay milliseconds, and return -1 if there is
still no input at the end of that time.

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=True) or unchanged (changed=False).

A bytes object representing the current version of the module. Also available as
__version__.

Some constants are available to specify character cell attributes.
The exact constants available are system dependent.

Attribute

Meaning

A_ALTCHARSET

Alternate character set mode

A_BLINK

Blink mode

A_BOLD

Bold mode

A_DIM

Dim mode

A_INVIS

Invisible or blank mode

A_NORMAL

Normal attribute

A_PROTECT

Protected mode

A_REVERSE

Reverse background and
foreground colors

A_STANDOUT

Standout mode

A_UNDERLINE

Underline mode

A_HORIZONTAL

Horizontal highlight

A_LEFT

Left highlight

A_LOW

Low highlight

A_RIGHT

Right highlight

A_TOP

Top highlight

A_VERTICAL

Vertical highlight

A_CHARTEXT

Bit-mask to extract a
character

Several constants are available to extract corresponding attributes returned
by some methods.

Bit-mask

Meaning

A_ATTRIBUTES

Bit-mask to extract
attributes

A_CHARTEXT

Bit-mask to extract a
character

A_COLOR

Bit-mask to extract
color-pair field information

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 Exit

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 (KEY_F1, KEY_F2,
KEY_F3, KEY_F4) available, and the arrow keys mapped to
KEY_UP, KEY_DOWN, KEY_LEFT and 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

Insert

KEY_IC

Delete

KEY_DC

Home

KEY_HOME

End

KEY_END

Page Up

KEY_PPAGE

Page Down

KEY_NPAGE

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.

The curses.textpad module provides a 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.

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
xterm and most other software terminal emulators). Otherwise it will be drawn
with ASCII dashes, vertical bars, and plus signs.

Return a textbox widget object. The win argument should be a curses
window object 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 stripspaces flag is initially on.

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
stripspaces attribute.

This attribute 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.