FUNCTIONS
USED IN LYNX OF <CURSES.H>
addch(ch)
waddch(win, ch)
mvaddch(y, x, ch)
mvwaddch(win, y, x, ch)
The
character ch is put into the window at
the current cursor position of the window and the position of the window cursor
is advanced. Its function is similar to that of putchar().
At the right margin, an automatic newline is performed. At the bottom of the
scrolling region, if scrollok() is
enabled, the scrolling region will be scrolled up one line.
If
ch is a TAB, NEWLINE, or backspace,
the cursor will be moved appropriately within the window. A NEWLINE also does a cIrtoeol()
before moving. TAB characters are
considered to be at every eighth column, lf ch
is another control character; it will be drawn in the CTRL-X notation. (Calling winch()
after adding a control character will not return the control character, but
instead will return the representation of the control character.) Video
attributes can be combined with a character by or/-ing them into the parameter.
This will result in these attributes also being set. The intent here is that
text, including attributes, can be copied from one place to another using inch()
and addch().
addstr(str)
waddstr(win,
str)
mvwaddstr(win,
y, x, str)
mvaddstr(y,
x, str)
These
routines write all the characters of the null-terminated character string str
on the given window. This is equivalent to calling waddch() once for each character in the string.
Note: addstr(), mvaddstr(), and mvwaddstr() are macros.
beep()
flash()
These routines are used to signal the
terminal user. beep() will sound the
audible alarm on the terminal, if possible, and if not, will flash the screen
(visible bell), if that is possible. flash() will flash the screen, and if that is not possible, will
sound the audible signal. If neither signal is possible, nothing will happen.
Nearly all terminals have an audible signal (bell or beep) but only some can
flash the screen.
WINDOW
*initscr()
The
first routine called should almost always be initscr().
The exceptions are slk_init(), filter(), and ripoffline().
This will determine the terminal type and initialize all curses data structures.
initscr() also arranges that the first
call to refresb() will clear the
screen. If errors occur, initscr()
will write an appropriate error message to standard error and exit; otherwise, a
pointer to stdscr is returned. If the program wants an indication of error
conditions, newterm() should be used
instead of initscr(). initscr()
should only be called once per application.
idlok
(win, bf)
If enabled (bf is TRUE), curses will
consider using the hardware "insert/delete-line" feature of terminals
so equipped. If disabled (bf is FALSE), curses will very seldom use this
feature. The "insert/delete-character" feature is always considered.
This option should be enabled only if your application needs
"insert/delete-line", for example, for a screen editor. It is disabled
by default because
"insert/delete-line" tends to be visually annoying when used in
applications where it is not really needed. If "insert/delete-line"
cannot be used, curses will redraw the changed portions of all lines.
nl()
nonl()
These
routines control whether NEWLINE is translated into RETURN and LINEFEED on
output, and whether RETURN is translated into NEWLINE on input. Initially, the
translations do occur. By disabling these translations using nonl(),
curses is able to make better use of the linefeed capability, resulting in
faster cursor motion.
inch()
winch(win)
mvinch(y,
x)
mvwinch(win,
y, x)
The
character, of type chtype, at the
current position in the named window is returned. If any attributes are set for
that position, their values will be OR'ed into the value returned. The
predefined constants A_CHARTEXT and A_ATTRIBUTES,
defined in <curses.h>,
can be used with the C logical AND (&) operator to extract the character or
attributes alone.
Note:
inch(), winch(), mvinch(), and mvwinch()
are macros.
raw()
noraw()
The
terminal is placed into or out of RAW
mode. RAW mode is similar to CBREAK
mode, in that characters typed are immediately passed through to the user
program. The differences are that in RAW mode, the interrupt, quit, suspend, and
flow control characters are passed through un-interpreted, instead of generating
a signal. RAW mode also causes 8-bit input and output. The behavior of the BREAK
key depends on other bits in the terminal driver that are not set by curses.
WINDOW AND PAD MANIPULATION
refresh()
wrefresh(win)
These
routines (or prefresh(), pnoutrefresh(),
wnoutrefresh(), or
doupdate()) must be called to write output to the terminal, as most other
routines merely manipulate data structures. wrefresh()
copies the named window to the physical terminal screen, taking into account
what is already there in order to minimize the amount of information that's sent
to the terminal (called optimization), refresh()
does the same thing, except it uses
stdscr as a default window.
Unless leaveok() has been
enabled, the physical cursor of the terminals left at the location of the
window's cursor. The number of characters output to the terminal is returned.
Note:
refresh() is a macro.
cIrtoeol()
wclrtoeol(win)
The
current line to the right of the cursor, inclusive, is erased.
Note:
cIrtoeol() is a macro.
deleteIn()
wdeletein(win)
The
line under the cursor in the window is deleted. All lines below the current line
are moved up one line. The bottom line of the window is cleared. The cursor
position does not change. This does not imply use of the hardware "deleteline"
feature.
Note:
deleteIn() is a macro.
move(y,
x)
wmove(win,
y, x)
The
cursor associated with the window is moved to line (row) y, (column) x. This
does not move the physical cursor of the terminal until refresh()
is called. The position specified is relative to the upper left corner of the
window, which is (0, 0).
Note:
move() is a macro.
cbreak()
nocbreak()
These
two routines put the terminal into and out of CBREAK
mode, respectively. In CBREAK mode, characters typed by the user are immediately
available to the program and erase/kill character processing is not performed.
When in NOCBREAK mode, the tty
driver will buffer characters typed until a NEWLINE or RETURN is typed.
Interrupt and flow-control characters are unaffected by this mode. Initially the
terminal may or may not be in CBREAK mode, as it is inherited, therefore, a
program should call cbreak() or nocbreak()
explicitly. Most interactive programs using curses will set CBREAK mode
scr_dump(filename)
The
current contents of the virtual screen are written to the file filename.
scr_restore(filename)
The
virtual screen is set to the contents of filename, which must be written using scr_dump(filename).
The next call to doupdate() will
restore the screen to what it
looked like in the dumped file.
napms(ms)
Sleep for ms milliseconds.
echo()
noecho()
These
routines control whether characters typed by the user are echoed by getch()
as they are typed. Echoing by the tty
driver is always disabled, but initially getch()
is in ECHO mode, so characters typed
are echoed. Authors of
most
interactive programs prefer to do their own echoing in a controlled area of the
screen, or not to echo at all, so they disable echoing by calling noecho().
delay_output(ms)
Insert an ms millisecond pause in the output. It is not recommended that this routine be used extensively, because padding characters are used rather than a processor pause.
insertln()
winsertln(win)
A
blank line is inserted above the current line and the bottom line is lost. This
does not imply use of the hardware "insert-line" feature.
Note:
insertln() is a macro.
COLOR-RELATED MACROS
The
following color-related macros are defined;
COLOR_BLACK
COLOR_BLUE
COLOR_GREEN
COLOR_CYAN
COLOR_RED
COLOR_MAGENTA
COLOR_YELLOW
COLOR_WHITE
keypad(stdscr,
TRUE); /* enable keyboard mapping */
To
enable support for function-key mapping.
doupdate()
wnoutrefresh(win)
These
two functions allow multiple updates with more efficiency than wrefresh().
To use them, it is important to understand how curses
work. In addition to all the window structures, curses keeps two data structures
representing the terminal screen: a physical screen, describing what is actually
on the screen, and a virtual screen, describing what the programmer wants to
have on the screen, wrefresh() works
by first copying the named window to the virtual screen (wnoutrefresh()),
and then calling the routine to update the screen (doupdate()). If the programmer wishes to output several windows at
once, a series of calls to wrefresh()
will result in alternating calls to wnoutrefresh()
and doupdate(), causing several
bursts of output to the screen. By calling wnoutrefresh()
for each window, it is then possible to call doupdate() once, resulting in only one burst of output, with fewer
total characters transmitted (this also avoids a visually annoying flicker at
each update.
delch()
These
routine delete characters also operate on a character level (that is, at the
character boundaries). The character at the cursor is deleted, no matter which
column of the character the cursor points to. Before deletion, the cursor moves
to the first column of the character.
WINDOW
*newwin (nlines, ncols, begin_y, begin_x)
Create
and return a pointer to a new window with the given number of lines (or rows), nlines,
and columns, ncols. The upper left
comer of the window is at line begin_y,
columns begin_x. If either nlines or
ncols is 0, they will be set to the value of lines-begin_y and cols-begin
x. A new full-screen window is created by calling newwin(0, 0, 0, 0).
box(win,
vertch, horch)
A
box is drawn around the edge of the window, win,
vertch
and horch
are the characters the box is to be drawn with. If vertch and horch are 0, then
appropriate default characters, ACS_VLINE
and ACS_HLINE, will be used.
Note:
vertch and horch
are actually of type chtype, not
characters
delch()
wdelch(win)
mvdelch(y,
x)
mvwdelch
(win, y, x)
The
character under the cursor in the window is deleted. All characters to the right
on the same lme are moved to the left one position and the last char- acter on
the line is filled with a blank. The cursor position does not change (after
moving to (y, x), if specified). This does not imply use of the hardware
"delete-character" feature.
Note:
delch(), mvdelch(),
and mvwdelch() are macros.
getch()
wgetch
(win)
mvgetch(y,
x)
mvwgetch(win,
y, x)
A
character is read from the terminal associated with the window. In NODELAY mode,
if there is no input waiting, the value ERR is returned. In DELAY mode, the
program will hang until the system passes text through to the program. Depending
on the setting of cbreak(), this will be after one character (CBREAK mode), or after
the first newline (NOC-BREAK mode). In HALF-DELAY mode, the program will hang
until a character] is typed or the specified timeout has been reached. Unless noecho()
has been set, the character will also be echoed into the designated window. No refresh() will occur between the move() and the getch()
done within the routines mvgetch() and
mvwgetch(). When using getch(),
wgetch(), mvgetch(), or mvwgetch(),
do not set both NOCBREAK mode (nocbreak())
and ECHO mode (echo()) at the same
time. Depending on the state of the terminal driver when each character is
typed, the program may produce undesirable results. If keypad(win,
TRUE) has been called, and a function key
is pressed, the toker for that function key will be returned instead of the raw
characters.
wnoutrefresh(win)
doupdate()
These
two routines allow multiple updates to the physical terminal screen with more
efficiency than wrefresh() alone. How this is accomplished is described in the next
paragraph. curses keeps two data structures representing the terminal
screen: a physical terminal screen, describing what is actually on the screen,
and a virtual terminal screen, describing what the programmer wants to have on
the screen, wrefresh() works by first
calling wnoutrefresh(), which copies
the named window to the virtual screen, and then by calling doupdate(),
which compares the virtual screen to the physical screen and does the actual
update. If the programmer wishes to output several windows at once, a series of
calls to wrefresh() will result in
alternating calls to wnoutrefresh()
and doupdate(), causing several bursts
of output to the screen. By first calling wnoutrefesh()
for each window, it is then possible to call doupdate() once, resulting in only one burst of output, with
probably fewer total characters transmitted and certainly less processor time
used.
attroff(attrs)
attron(attrs)
attrset(attrs)
standend(
)
standout()
These
routines manipulate the current attributes of the named window. These attributes
can be any combination of A_STANDOUT,
A_REVERSE, A_BOLD, A_DIM,
A_BLINK, A_UNDERLINE, and
A_ALTCHARSET. The current attribute
of a window are applied to all characters that are written into the window with waddch().
Attributes are a property of the character, and move with a character through
any scrolling and insert/delete line/character operations. To the extent
possible on the particular terminal, they will be displayed as the graphic
rendition of the characters put on the screen.
attrset(attrs):
sets the current attributes of the
given window to attrs.
attroff(attrs) turns
off the
named attributes
without turning
on or off the named other attributes, attron(attrs) turns on the named attributes without affecting any
others, standout() is the same as (attron(A_STANDOUT))
. standend( ) is the same as attrset(O), that is, it turns off all attributes.
Note ; attrs is actually of type chtype,
nor a character.
Note
: attroff () , attron()
, attrset() , standout() ,
are macros.
ZAP works