This defines which colors to paint for color pair 0. This function
recognizes a special color Color::TerminalDefault, which denotes
the default terminal color.
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.
Set the window’s background. A window’s background consists of a character
and it’s 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.
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, which must be between 0 and COLORS. Return a structure,
containing the R,G,B values for the given color, which will be
between 0 (no component) and 1000 (maximum amount of component).
The copywin() routine provides a finer granularity of control over
the overlay() and overwrite() routines. As in the prefresh()
routine, a rectangle is specified in the destination window, (dmin)
and (dmax), and the upper-left-corner coordinates of the source window,
(smin). If the argument overlay is true, then copying is
non-destructive, as in overlay().
Set the cursor state. visibility can be set to 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 NCurses. (Its counterpart is the “shell”
mode, for when the program is not in NCurses.) 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 NCurses. (Its counterpart is the
“program” mode, when the program is using NCurses capabilities.)
Subsequent calls to reset_shell_mode() will restore this mode.
Permits an application to define keycodes with their corresponding
control strings, so that the NCurses library will interpret them
just as it would the predefined codes in the terminfo database.
The delscreen() routine frees storage associated with the SCREEN
data structure. The endwin() routine does not do this, so delscreen() should
be called after endwin() if a particular SCREEN is no longer needed.
Deletes the named window, freeing all memory associated with it
(it does not actually erase the window’s screen image). Sub-windows
must be deleted before the main window can be deleted.
An abbreviation for “derive window”, derwin() is the same as calling subwin(),
except that origin are relative to the origin of the window, rather than
relative to the entire screen. Return a window object for the derived window.
Update the physical screen. The NCurses 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.
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 NCurses program, and is not set by the NCurses 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.
Flash the screen. That is, change it to reverse-video and then change
it back in a short interval. Some people prefer such as ‘visible bell’
to the audible attention signal produced by beep().
Returns the same attribute data as wattr_get(). However, getattrs()
internally returns an integer (actually a chtype), while wattr_get()
returns the current color pair in a separate parameter. In the
wide-character library configuration, color pairs may not fit into
a chtype, so wattr_get() is the only way to obtain the color information.
Read window related data stored in the file by an earlier putwin() call.
The routine then creates and initializes a new window using that data,
returning the new window object.
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.
Return true if the terminal has insert- and delete-character capabilities.
This function is included for historical reasons only, as all modern
software terminal emulators have such capabilities.
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.
If flag is false, NCurses 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 NCurses 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.
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 two arguments: the number
of the color-pair to be changed, and the foreground and background colors.
The value of color_pair must be between 1 and COLOR_PAIRS - 1 (the 0 color
pair is wired to white on black and cannot be changed).
If the color-pair was previously initialized, the screen is refreshed and
all occurrences of that color-pair are changed to the new definition.
If the intrflush() option is enabled (flag is true), and an interrupt
key is pressed on the keyboard (interrupt, break, quit), all output in the
tty driver queue will be flushed, giving the effect of faster response to
the interrupt, but causing NCurses to have the wrong idea of what is on the
screen. Disabling the option (flag is false) prevents the flush.
The default for the option is inherited from the tty driver settings.
Return the name of the key binding c. 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.
Permits an application to disable specific KeyBinding, rather than use
the keypad function to disable all keycodes. Keys that have been disabled
can be re-enabled.
If flag is true, escape sequences generated by some keys (keypad, function keys)
will be interpreted by NCurses. If flag is false, escape sequences will be left
as is in the input stream.
Return the user’s current line kill character. Under Unix operating
systems this is a property of the controlling tty of the NCurses
program, and is not set by the NCurses library itself.
Return the user’s current line kill character as a wide character.
Under Unix operating systems this is a property of the controlling
tty of the NCurses program, and is not set by the NCurses library itself.
If flag is true, cursor is left where it is on update, instead of being
at “cursor position.” This reduces cursor movement where possible.
If possible the cursor will be made invisible.
Return 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().
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.
Set the attributes of number characters at the position origin.
This routine moves cursor to position origin. The changed line
will be touched using the touchline() method so that the contents
will be redisplayed by the next window refresh().
Return an enum of CharacterResult::Character(WideChar) for most keys, or
a CharacterResult::Key(KeyBinding) for function keys, keypad keys, and
other special keys. In no-delay mode, raise a NCurseswError if there is
no input.
Return an enum of CharacterResult::Character(char) for most keys, or a
CharacterResult::Key(KeyBinding) for function keys, keypad keys, and
other special keys. In no-delay mode, raise a NCurseswError if there is
no input.
Insert a wide string (as many characters as will fit on the line) before the
character at origin, up to number characters. If number 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 origin).
Insert a wide string (as many characters as will fit on the line) before the
character at origin. 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 origin).
Insert a string (as many characters as will fit on the line) before the
character at origin, up to number characters. If number 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 origin).
Insert a string (as many characters as will fit on the line) before the
character at origin. 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 origin).
When creating a new screen, the library uses static variables which have
been preset, e.g. by use_env(), filter() etc. With the screen-pointer
extension, there are situations where it must create a current screen
before the unextended library does. The new_prescr() function is used
internally to handle these cases. It is also provided as an entrypoint
to allow applications to customize the library initialization.
The newpad() routine creates and returns a pointer to a new pad data
structure with the given size. 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 (e.g., from scrolling or echoing
of input) do not occur.
A program that outputs to more than one terminal should use the newterm()
routine for each terminal instead of initscr(). A program that needs to
inspect capabilities, so it can continue to run in a line-oriented mode
if the terminal cannot support a screen-oriented program, would also use
newterm(). The routine newterm() should be called once for each terminal.
It returns a pointer of type SCREEN which should be saved as a reference
to that terminal. newterm’s arguments are:
Enter newline mode. This mode translates the return key into newline on
input, and translates newline into return and line-feed on output.
Newline mode is initially on.
The nofilter() routine cancels the effect of a preceding filter() call.
That allows the caller to initialize a screen on a different device, using
a different value of $TERM. The limitation arises because the filter()
routine modifies the in-memory copy of the terminal information.
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, NCurses 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.
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.
The pecho_wchar() function is the analogous wide-character form of pechochar().
It outputs one character to a pad and immediately refreshes the pad. It does this
by a call to wadd_wch() followed by a call to prefresh().
The pechochar() routine is functionally equivalent to a call to addch()
followed by a call to refresh(), a call to waddch() followed by a call
to wrefresh(), or a call to waddch() followed by a call to prefresh().
The knowledge that only a single character is being output is taken into
consideration and, for non-control characters, a considerable performance
gain might be seen by using these routines instead of their equivalents.
In the case of pechochar(), the last location of the pad on the screen
is reused for the arguments to prefresh().
The pnoutrefresh() routine is analogous to wnoutrefresh() except that they relate
to pads instead of windows. The additional parameters are needed to indicate what part
of the pad and screen are involved.
The prefresh() routine is analogous to wrefresh() except that they relate to pads
instead of windows. The additional parameters are needed to indicate what part of the
pad and screen are involved.
Enter raw mode. In raw mode, normal line buffering and processing of
interrupt, quit, suspend, and flow control keys are turned off;
characters are presented to NCurses input functions one by one.
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 NCurses library that record the
window dimensions (in particular the SIGWINCH handler).
The ripoffline() routine provides access to the same facility that slk_init()
uses to reduce the size of the screen. ripoffline() must be called before
initscr() or newterm() is called.
The scr_init() routine reads in the contents of path and uses them to
initialize the curses data structures about what the terminal currently has
on its screen. If the data is determined to be valid, curses bases its next
update of the screen on this information rather than clearing the screen
and starting from scratch.
The scr_restore() routine sets the virtual screen to the contents of the file
specificed by path, which must have been written using scr_dump(). The next call
to doupdate() restores the physical screen to the way it looked in the
dump file.
The scr_set() routine is a combination of scr_restore() and scr_init().
It tells the program that the information in path is what is currently
on the screen, and also what the program wants on the screen. This can be
thought of as a screen inheritance function.
For positive n, the scrl() routine scroll the window up n lines
(line i+n becomes i); otherwise scroll the window down n lines.
This involves moving the lines in the window character image structure.
The current cursor position is not changed.
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().
The set_term() routine is used to switch between different terminals.
The screen reference new becomes the new current terminal. The previous
terminal is returned by the routine. This is the only routine which
manipulates SCREEN pointers; all other routines affect only the current
terminal.
The slk_init() routine must be called before initscr() or newterm()
is called. initscr() eventually uses a line from stdscr() to emulate
the soft labels, then fmt determines how the labels are arranged on
the screen.
Mark for refresh but wait. This function updates the data structure representing
the desired state of the soft labels, but does not force an update of
the physical screen. To accomplish that, call doupdate().
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().
Return the value of the numeric capability corresponding to the terminfo
capability name capname as an integer or None 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.
Return a string which is a printable representation of the character
c. Control characters are represented as a caret followed by the character,
for example as b’^C’. Printing characters are left as they are.
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 Color::TerminalDefault.
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 NCurses is running
in a window (in which case default behavior would be to use the window
size if LINES and COLUMNS are not set).
Controls whether the calling application is able to use user-defined or
nonstandard names which may be compiled into the terminfo description,
i.e., via the terminfo or termcap interfaces.
Normally these names are available for use, since the essential decision
is made by using the -x option of tic to compile extended terminal
definitions. However you can disable this feature to ensure compatibility
with other implementations of curses.
Determine how to compute terminal size. The use_tioctl() routine,
if used, should be called before initscr() or newterm() are called
(because those compute the screen size).
Manipulate the background of the specified window. The window background is a
character (with rendition). The attribute part of the background is combined
(OR’ed) with all non-blank characters that are written into the window with
waddch(). 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 window’s background. A window’s background consists of a character
and it’s combination of attributes as a complex character. 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.
For positive n, insert n lines into the specified window above the
current line. The n bottom lines are lost. For negative n, delete
n lines (starting with the one under the cursor), and move the
remaining lines up. The bottom n lines are cleared. The current
cursor position remains the same.
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().
Reallocate storage for a NCurses 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.
For positive n, the wscrl() routine scroll the window up n lines
(line i+n becomes i); otherwise scroll the window down n lines.
This involves moving the lines in the window character image structure.
The current cursor position is not changed.
Touch each location in the window that has been touched in any of its
ancestor windows. This routine is called by refresh(), so it should
almost never be necessary to call it manually.
The wtouchln() routine makes n lines in the window, starting at line,
look as if they have (Changed::True) or have not (Changed::False) been
changed since the last call to wrefresh().
The wunctrl() routine returns a wide character string which is a printable
representation of the character ch, ignoring attributes. Control characters
are displayed in the ^X notation. Printing characters are displayed as is.