Introduction to XSI Curses Interface
The X/Open Group has identified a strong need for a generic terminal
interface for applications that wish to be independent of terminal
hardware and connection method.
This interface should allow the attachment of character and
block-oriented terminals. Furthermore, it should not put any
constraints on how the terminals are attached (e.g., Local Area
Networks, PADs on X.25, etc.).
The curses library interfaces provides the user with a method of
updating screens with reasonable optimisation.
The X/Open group has found it impossible to define a totally portable
set of curses interface routines that cover asynchronous, networked,
and synchronous terminals. The functions are oriented towards locally
connected asynchronous terminals. For such terminals, applications
conforming to this interface are portable. The interface routines
curses may, however, also be used with synchronous and networked
terminals, provided the restrictions below are considered.
These functions have been included been included in the X/Open
definition in the "optional" category. This means that although they
are likely to appear on many X/Open compliant systems, they are not
guaranteed to be on all systems. Where they are supported, they will
conform to the given definition.
-------------------------------------------------------------------------
Synchronous and Networked Asynchronous Terminals
These notes indicate to the application writer some considerations to be
borne in mind when driving synchronous, networked asynchronous (NWA) or
non-standard directly connected asynchronous terminals.
Such terminals are often used in a mainframe environment and
communicatie to the host in block mode. That is, the user types
characters at the terminal then presses a special key to initiate
transmission of the characters to the host.
Frequently, although it may be possible to send arbitrary sized blocks
to the host, it may not be possible or desireable to cause a character
to be transmitted with only a single keystroke.
This can cause severe problems to an application wishing to make use of
single character input.
OUTPUT
The curses package can be used in the normal way for all operations
pertaining to output to the terminal, with the possible exception that
on some terminals the refresh() routine may have to redraw the entire
screen contents in order to perform any update.
If it is additionally necessary to clear the screen before each such
operation, the result could be unacceptable.
INPUT
Because of the nature of operation of synchronous (block-mode) and NWA
terminals, it may not be possible to support all or any of the curses
input functions. In particular, the following points should be noted:
* Single-character input may not be possible. It may be necessary to
press a special key to cause all characters typed at the terminal to
be transmitted to the host.
* It may not be possible to disable echo. Character echo may be
performed directly by the terminal. On terminals that behave this
way, any curses application that performs input should be aware that
any characters type will appear on the screen wherever the cursor is
positioned. This may not necessarily correspond to the position of the
cursor in the window.
-------------------------------------------------------------------------
Data Types and the <curses.h> Header
The data types supported by curses are described in this section.
As the library supports a procedural interface to the data types, actual
structure contents are not described. All curses data are manipulated
using the routines provided.
THE <curses.h> HEADER
The <curses.h> header defines various constants and declares the data
types that are available to the application.
DATA TYPES
The following data types are declared:
WINDOW * pointer to screen representation
SCREEN * pointer to terminal descriptor
bool boolean data type
chtype representation of a character in a window
The actual WINDOW and SCREEN objects used to store information are
created by the corresponding routines and a pointer to them is provided.
All manipulation is through that pointer.
CONSTANTS
The following constants are defined.
GENERAL
COLS number of columns on terminal screen
ERR value returned on error condition
FALSE boolean false value
LINES number of lines on terminal screen
OK value returned on successful completion
NULL zero pointer value
TRUE boolean true value
VIDEO ATTRIBUTES
A_BLINK blinking
A_BOLD extra bright or bold
A_DIM half bright
A_REVERSE reverse video
A_STANDOUT terminal's best highlighting mode
A_UNDERLINE underlining
A_ATTRIBUTES bit-mask to extract attributes
A_CHARTEXT bit-mask to extract a character
Normally, attributres are a property of the character.
INPUT VALUES
The following constants might be returned by getch() if keypad() has
been enabled. Note that not all of these may be supported on a
particular terminal if the terminal does not transmit a unique code when
the key is pressed or the definition for the key is not present in the
underlying table of terminal capabilities.
KEY_BREAK break key
KEY_DOWN the four arrow keys
KEY_UP
KEY_LEFT
KEY_RIGHT
KEY_HOME home key (upward+left arrow)
KEY_BACKSPACE backspace
KEY_F0 function keys; space for 64 keys is reserved
KEY_F(n) (KEY_F0+(n))
KEY_DL delete line
KEY_IL insert line
KEY_DC delete character
KEY_IC insert character
KEY_EIC exit insert character mode
KEY_CLEAR clear screen
KEY_EOS clear to end of screen
KEY_EOL clear to end of line
KEY_SF scroll 1 line forwards
KEY_SR scroll 1 line backwards (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
KEY_SRESET soft (partial) reset
KEY_RESET reset or hard reset
KEY_PRINT print or copy
KEY_LL home down or bottom (lower left)
KEY_A1 upper left of virtual keypad
KEY_A3 upper right of virtual keypad
KEY_B2 centre of virtual keypad
KEY_C1 lower left of virtual keypad
KEY_C3 lower right of virtual keypad
The virtual keypad is arranged like this:
A1 up A3
left B2 right
C1 down C3
FUNCTIONS
The following table lists each curses routine and the name of the
manual page on which it is described.
Functions from the X/Open curses standard -- complete, except
for getch() and ungetch(), which are implemented as macros for
DOS compatibility:
Curses Function Manual Page Name
addch addch
addchnstr addchstr
addchstr addchstr
addnstr addstr
addstr addstr
attroff attr
attron attr
attrset attr
attr_get attr
attr_off attr
attr_on attr
attr_set attr
baudrate termattr
beep beep
bkgd bkgd
bkgdset bkgd
border border
box border
can_change_color color
cbreak inopts
chgat attr
clearok outopts
clear clear
clrtobot clear
clrtoeol clear
color_content color
color_set attr
copywin overlay
curs_set kernel
def_prog_mode kernel
def_shell_mode kernel
del_curterm terminfo
delay_output util
delch delch
deleteln deleteln
delscreen initscr
delwin window
derwin window
doupdate refresh
dupwin window
echochar addch
echo inopts
endwin initscr
erasechar termattr
erase clear
filter util
flash beep
flushinp getch
getbkgd bkgd
getnstr getstr
getstr getstr
getwin scr_dump
halfdelay inopts
has_colors color
has_ic termattr
has_il termattr
hline border
idcok outopts
idlok outopts
immedok outopts
inchnstr inchstr
inchstr inchstr
inch inch
init_color color
init_pair color
initscr initscr
innstr instr
insch insch
insdelln deleteln
insertln deleteln
insnstr innstr
insstr innstr
instr instr
intrflush inopts
isendwin initscr
is_linetouched touch
is_wintouched touch
keyname keyname
keypad inopts
killchar termattr
leaveok outopts
longname termattr
meta inopts
move move
mvaddch addch
mvaddchnstr addchstr
mvaddchstr addchstr
mvaddnstr addstr
mvaddstr addstr
mvchgat attr
mvcur terminfo
mvdelch delch
mvderwin window
mvgetch getch
mvgetnstr getstr
mvgetstr getstr
mvhline border
mvinch inch
mvinchnstr inchstr
mvinchstr inchstr
mvinnstr instr
mvinsch insch
mvinsnstr insstr
mvinsstr insstr
mvinstr instr
mvprintw printw
mvscanw scanw
mvvline border
mvwaddchnstr addchstr
mvwaddchstr addchstr
mvwaddch addch
mvwaddnstr addstr
mvwaddstr addstr
mvwchgat attr
mvwdelch delch
mvwgetch getch
mvwgetnstr getstr
mvwgetstr getstr
mvwhline border
mvwinchnstr inchstr
mvwinchstr inchstr
mvwinch inch
mvwinnstr instr
mvwinsch insch
mvwinsnstr insstr
mvwinsstr insstr
mvwinstr instr
mvwin window
mvwprintw printw
mvwscanw scanw
mvwvline border
napms kernel
newpad pad
newterm initscr
newwin window
nl inopts
nocbreak inopts
nodelay inopts
noecho inopts
nonl inopts
noqiflush inopts
noraw inopts
notimeout inopts
overlay overlay
overwrite overlay
pair_content color
pechochar pad
pnoutrefresh pad
prefresh pad
printw printw
putp terminfo
putwin scr_dump
qiflush inopts
raw inopts
redrawwin refresh
refresh refresh
reset_prog_mode kernel
reset_shell_mode kernel
resetty kernel
restartterm terminfo
ripoffline kernel
savetty kernel
scanw scanw
scr_dump scr_dump
scr_init scr_dump
scr_restore scr_dump
scr_set scr_dump
scrl scroll
scroll scroll
scrollok outopts
set_term initscr
setscrreg outopts
setterm terminfo
setupterm terminfo
slk_attroff slk
slk_attr_off slk
slk_attron slk
slk_attr_on slk
slk_attrset slk
slk_attr_set slk
slk_clear slk
slk_color slk
slk_init slk
slk_label slk
slk_noutrefresh slk
slk_refresh slk
slk_restore slk
slk_set slk
slk_touch slk
standend attr
standout attr
start_color color
subpad pad
subwin window
syncok window
termattrs termattrs
term_attrs termattrs
termname termattrs
tgetent termcap
tgetflag termcap
tgetnum termcap
tgetstr termcap
tgoto termcap
tigetflag terminfo
tigetnum terminfo
tigetstr terminfo
timeout inopts
touchline touch
touchwin touch
tparm terminfo
tputs terminfo
typeahead inopts
untouchwin touch
use_env util
vidattr terminfo
vid_attr terminfo
vidputs terminfo
vid_puts terminfo
vline border
vw_printw printw
vwprintw printw
vw_scanw scanw
vwscanw scanw
waddchnstr addchstr
waddchstr addchstr
waddch addch
waddnstr addstr
waddstr addstr
wattroff attr
wattron attr
wattrset attr
wattr_get attr
wattr_off attr
wattr_on attr
wattr_set attr
wbkgdset bkgd
wbkgd bkgd
wborder border
wchgat attr
wclear clear
wclrtobot clear
wclrtoeol clear
wcolor_set attr
wcursyncup window
wdelch delch
wdeleteln deleteln
wechochar addch
werase clear
wgetch getch
wgetnstr getstr
wgetstr getstr
whline border
winchnstr inchstr
winchstr inchstr
winch inch
winnstr instr
winsch insch
winsdelln deleteln
winsertln deleteln
winsnstr insstr
winsstr insstr
winstr instr
wmove move
wnoutrefresh refresh
wprintw printw
wredrawln refresh
wrefresh refresh
wscanw scanw
wscrl scroll
wsetscrreg outopts
wstandend attr
wstandout attr
wsyncdown window
wsyncup window
wtimeout inopts
wtouchln touch
wvline border
Wide-character functions from the X/Open standard -- these are
only available when PDCurses is built with PDC_WIDE defined, and
the prototypes are only available from curses.h when PDC_WIDE is
defined before its inclusion in your app:
addnwstr addstr
addwstr addstr
add_wch addch
add_wchnstr addchstr
add_wchstr addchstr
border_set border
box_set border
echo_wchar addch
erasewchar termattr
getbkgrnd bkgd
getcchar util
getn_wstr getstr
get_wch getch
get_wstr getstr
hline_set border
innwstr instr
ins_nwstr insstr
ins_wch insch
ins_wstr insstr
inwstr instr
in_wch inch
in_wchnstr inchstr
in_wchstr inchstr
key_name keyname
killwchar termattr
mvaddnwstr addstr
mvaddwstr addstr
mvadd_wch addch
mvadd_wchnstr addchstr
mvadd_wchstr addchstr
mvgetn_wstr getstr
mvget_wch getch
mvget_wstr getstr
mvhline_set border
mvinnwstr instr
mvins_nwstr insstr
mvins_wch insch
mvins_wstr insstr
mvinwstr instr
mvwaddnwstr addstr
mvwaddwstr addstr
mvwadd_wch addch
mvwadd_wchnstr addchstr
mvwadd_wchstr addchstr
mvwgetn_wstr getstr
mvwget_wch getch
mvwget_wstr getstr
mvwhline_set border
mvwinnwstr instr
mvwins_nwstr insstr
mvwins_wch insch
mvwins_wstr insstr
mvwin_wch inch
mvwin_wchnstr inchstr
mvwin_wchstr inchstr
mvwinwstr instr
mvwvline_set border
pecho_wchar pad
setcchar util
slk_wset slk
unget_wch getch
vline_set border
waddnwstr addstr
waddwstr addstr
wadd_wch addch
wadd_wchnstr addchstr
wadd_wchstr addchstr
wbkgrnd bkgd
wbkgrndset bkgd
wborder_set border
wecho_wchar addch
wgetbkgrnd bkgd
wgetn_wstr getstr
wget_wch getch
wget_wstr getstr
whline_set border
winnwstr instr
wins_nwstr insstr
wins_wch insch
wins_wstr insstr
winwstr instr
win_wch inch
win_wchnstr inchstr
win_wchstr inchstr
wunctrl util
wvline_set border
Quasi-standard functions, from Sys V or BSD curses:
getattrs attr
getbegx getyx
getbegy getyx
getmaxx getyx
getmaxy getyx
getparx getyx
getparx getyx
traceoff debug
traceon debug
unctrl util
Classic PDCurses mouse functions, based on Sys V:
mouse_set mouse
mouse_on mouse
mouse_off mouse
request_mouse_pos mouse
map_button mouse
wmouse_position mouse
getmouse mouse
getbmap mouse
Functions from ncurses:
assume_default_colors color
curses_version initscr
has_key util
use_default_colors color
wresize window
mouseinterval mouse
mousemask mouse
mouse_trafo mouse
nc_getmouse mouse
ungetmouse mouse
wenclose mouse
wmouse_trafo mouse
PDCurses-specific functions -- avoid these in code that's
intended to be portable:
addrawch addch
insrawch insch
is_termresized initscr
mvaddrawch addch
mvdeleteln deleteln
mvinsertln deleteln
mvinsrawch insch
mvwaddrawch addch
mvwdeleteln deleteln
mvwinsertln deleteln
mvwinsrawch insch
raw_output outopts
resize_term initscr
resize_window window
waddrawch addch
winsrawch insch
wordchar termattr
PDC_debug debug
PDC_ungetch getch
PDC_set_blink pdcsetsc
PDC_set_line_color color
PDC_set_title pdcsetsc
PDC_clearclipboard pdcclip
PDC_freeclipboard pdcclip
PDC_getclipboard pdcclip
PDC_setclipboard pdcclip
PDC_get_input_fd pdckbd
PDC_get_key_modifiers getch
PDC_return_key_modifiers getch
PDC_save_key_modifiers getch
Functions specific to the X11 port of PDCurses:
Xinitscr initscr
XCursesExit -
sb_init sb
sb_set_horz sb
sb_set_vert sb
sb_get_horz sb
sb_get_vert sb
sb_refresh sb
--------------------------------------------------------------------------
Curses Overview
The X/Open Curses Interface Definition describes a set of C-Language
functions that provide screen-handling and updating, which are
collectively known as the curses library.
The curses library permits manipulation of data structures called
windows which may be thought of as two-dimensional arrays of
characters representing all or part of a terminal's screen. The
windows are manipulated using a procedural interface described
elsewhere. The curses package maintains a record of what characters
are on the screen. At the most basic level, manipulation is done with
the routines move() and addch() which are used to "move" the curses
around and add characters to the default window, stdscr, which
represents the whole screen.
An application may use these routines to add data to the window in any
convenient order. Once all data have been added, the routine
refresh() is called. The package then determines what changes have
been made which affect the screen. The screen contents are then
changed to reflect those characters now in the window. using a
sequence of operations optimised for the type of terminal in use.
At a higher level routines combining the actions of move() and addch()
are defined, as are routines to add whole strings and to perform
format conversions in the manner of printf().
Interfaces are alse defined to erase the entire window and to specify
the attributes of individual characters in the winodw. Attributes
such as inverse video, underline and blink can be used on a
per-character basis.
New windows can be created by allowing the application to build
several images of the screen and display the appropriate one very
quickly. New windows are created using the routine newwin(). For
each routine that manipulates the default window, stdscr, there is a
corresponding routine prefixed with w to manipulate the contents of a
specified window; for example, move() and wmove(). In fact, move(...)
is functionally equivalent to wmove( stdscr, ...). This is similar to
the interface offered by printf(...) and fprintf(stdout, ...).
Windows do not have to correspond to the entire screen. It is
possible to create smaller windows, and also to indicate that the
window is only partially visible on the screen. Furthermore, large
windows or pads, which are bigger than the actual screen size, may be
created.
The routine newterm() may be called to "open" additional terminals by
large applications wishing to manipulate several terminals at once.
The set_term() function is used to select the terminal whose screen is
to be updated by the next refresh().
Interfaces are also defined to allow input character manipulation and
to disable and enable many input attributes: character echo, single
character input with or without signal processing (cbreak or raw
modes), carriage returns mapping to newlines, screen scrolling, etc.
--------------------------------------------------------------------------
.......PDCurses Definitions and Variables:
PDCurses definitions list: (Only define those needed)
DOS True if compiling for DOS.
OS2 True if compiling for OS/2.
WIN32 True if compiling for Windows.
XCURSES True if compiling for X11.
PDCurses portable platform definitions list:
PDC_BUILD Defines API build version.
PDCURSES Enables access to PDCurses-only routines.
XOPEN Always true.
SYSVcurses True if you are compiling for SYSV portability.
BSDcurses True if you are compiling for BSD portability.
--------------------------------------------------------------------------
PDCurses Text Attributes:
Originally, PDCurses used a short (16 bits) for its chtype. To include
color, a number of things had to be sacrificed from the strict Unix and
System V support. The main problem was fitting all character attributes
and color into an unsigned char (all 8 bits!).
Today, PDCurses by default uses a long (32 bits) for its chtype, as in
System V. The short chtype is still available, by undefining CHTYPE_LONG
and rebuilding the library.
The following is the structure of a win->_attrs chtype:
short form:
-------------------------------------------------
|15|14|13|12|11|10| 9| 8| 7| 6| 5| 4| 3| 2| 1| 0|
-------------------------------------------------
color number | attrs | character eg 'a'
The available non-color attributes are bold, reverse and blink. Others
have no effect. The high order char is an index into an array of
physical colors (defined in color.c) -- 32 foreground/background color
pairs (5 bits) plus 3 bits for other attributes.
long form:
----------------------------------------------------------------------------
|31|30|29|28|27|26|25|24|23|22|21|20|19|18|17|16|15|14|13|12|..| 3| 2| 1| 0|
----------------------------------------------------------------------------
color number | modifiers | character eg 'a'
The available non-color attributes are bold, underline, invisible,
right-line, left-line, protect, reverse and blink. 256 color pairs (8
bits), 8 bits for other attributes, and 16 bits for character data.
--------------------------------------------------------------------------
.......PDCurses Functions:
Name: addch
Synopsis:
int addch(const chtype ch);
int waddch(WINDOW *win, const chtype ch);
int mvaddch(int y, int x, const chtype ch);
int mvwaddch(WINDOW *win, int y, int x, const chtype ch);
int echochar(const chtype ch);
int wechochar(WINDOW *win, const chtype ch);
int addrawch(chtype ch);
int waddrawch(WINDOW *win, chtype ch);
int mvaddrawch(int y, int x, chtype ch);
int mvwaddrawch(WINDOW *win, int y, int x, chtype ch);
int add_wch(const cchar_t *wch);
int wadd_wch(WINDOW *win, const cchar_t *wch);
int mvadd_wch(int y, int x, const cchar_t *wch);
int mvwadd_wch(WINDOW *win, int y, int x, const cchar_t *wch);
int echo_wchar(const cchar_t *wch);
int wecho_wchar(WINDOW *win, const cchar_t *wch);
Description:
addch() inserts the character ch into the default window
(stdscr) at the current cursor position, and the window cursor
is advanced. The character is of the type chtype, containing
both data and attributes. add_wch() is the wide-character
version, taking a pointer to a cchar_t.
waddch() is like addch(), but also lets you specify the window.
(This is in fact the core output routine.) wadd_wch() is the
wide version.
mvaddch() moves the cursor to the specified (y, x) position, and
inserts the character ch into stdscr. mvadd_wch() is the
wide version.
mvwaddch() moves the cursor to the specified position and
inserts the character ch into the specified window. mvwadd_wch()
is the wide version.
echochar() inserts the character ch into stdscr at the current
cursor position and calls refresh(). echo_wchar() is the wide
version.
wechochar() inserts the character ch into the specified window
and calls wrefresh(). wecho_wchar() is the wide version.
addrawch(), waddrawch(), mvaddrawch() and mvwaddrawch() are
PDCurses-specific wrappers for addch() etc. that disable the
translation of control characters.
All these routines are similar to putchar(). The following
applies to all:
If the cursor moves on to the right margin, an automatic newline
is performed. If scrollok is enabled, and a character is added
to the bottom right corner of the screen, the scrolling region
will be scrolled up one line. If scrolling is not allowed, ERR
will be returned.
If ch is a tab, newline, or backspace, the cursor will be moved
appropriately within the window. If ch is a newline, the
clrtoeol routine is called before the cursor is moved to the
beginning of the next line. If newline mapping is off, the
cursor will be moved to the next line, but the x coordinate will
be unchanged. If ch is a tab the cursor is moved to the next
tab position within the window. If ch is another control
character, it will be drawn in the ^X notation. Calling the
inch() routine after adding a control character returns the
representation of the control character, not the control
character.
Video attributes can be combined with a character by ORing them
into the parameter. Text, including attributes, can be copied
from one place to another by using inch() and addch().
Note that in PDCurses, for now, a cchar_t and a chtype are the
same. The text field is 16 bits wide, and is treated as Unicode
(UCS-2) when PDCurses is built with wide-character support
(define PDC_WIDE). So, in functions that take a chtype, like
addch(), both the wide and narrow versions will handle Unicode.
But for portability, you should use the wide functions.
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
addch Y Y Y
waddch Y Y Y
mvaddch Y Y Y
mvwaddch Y Y Y
echochar Y - 3.0
wechochar Y - 3.0
addrawch - - -
waddrawch - - -
mvaddrawch - - -
mvwaddrawch - - -
add_wch Y
wadd_wch Y
mvadd_wch Y
mvwadd_wch Y
echo_wchar Y
wecho_wchar Y
--------------------------------------------------------------------------
Name: addchstr
Synopsis:
int addchstr(const chtype *ch);
int addchnstr(const chtype *ch, int n);
int waddchstr(WINDOW *win, const chtype *ch);
int waddchnstr(WINDOW *win, const chtype *ch, int n);
int mvaddchstr(int y, int x, const chtype *ch);
int mvaddchnstr(int y, int x, const chtype *ch, int n);
int mvwaddchstr(WINDOW *, int y, int x, const chtype *ch);
int mvwaddchnstr(WINDOW *, int y, int x, const chtype *ch, int n);
int add_wchstr(const cchar_t *wch);
int add_wchnstr(const cchar_t *wch, int n);
int wadd_wchstr(WINDOW *win, const cchar_t *wch);
int wadd_wchnstr(WINDOW *win, const cchar_t *wch, int n);
int mvadd_wchstr(int y, int x, const cchar_t *wch);
int mvadd_wchnstr(int y, int x, const cchar_t *wch, int n);
int mvwadd_wchstr(WINDOW *win, int y, int x, const cchar_t *wch);
int mvwadd_wchnstr(WINDOW *win, int y, int x, const cchar_t *wch,
int n);
Description:
These routines write a chtype or cchar_t string directly into
the window structure, starting at the current or specified
position. The four routines with n as the last argument copy at
most n elements, but no more than will fit on the line. If n =
-1 then the whole string is copied, up to the maximum number
that will fit on the line.
The cursor position is not advanced. These routines do not check
for newline or other special characters, nor does any line
wrapping occur.
Return Value:
All functions return OK or ERR.
Portability X/Open BSD SYS V
addchstr Y - 4.0
waddchstr Y - 4.0
mvaddchstr Y - 4.0
mvwaddchstr Y - 4.0
addchnstr Y - 4.0
waddchnstr Y - 4.0
mvaddchnstr Y - 4.0
mvwaddchnstr Y - 4.0
add_wchstr Y
wadd_wchstr Y
mvadd_wchstr Y
mvwadd_wchstr Y
add_wchnstr Y
wadd_wchnstr Y
mvadd_wchnstr Y
mvwadd_wchnstr Y
--------------------------------------------------------------------------
Name: addstr
Synopsis:
int addstr(const char *str);
int addnstr(const char *str, int n);
int waddstr(WINDOW *win, const char *str);
int waddnstr(WINDOW *win, const char *str, int n);
int mvaddstr(int y, int x, const char *str);
int mvaddnstr(int y, int x, const char *str, int n);
int mvwaddstr(WINDOW *win, int y, int x, const char *str);
int mvwaddnstr(WINDOW *win, int y, int x, const char *str, int n);
int addwstr(const wchar_t *wstr);
int addnwstr(const wchar_t *wstr, int n);
int waddwstr(WINDOW *win, const wchar_t *wstr);
int waddnwstr(WINDOW *win, const wchar_t *wstr, int n);
int mvaddwstr(int y, int x, const wchar_t *wstr);
int mvaddnwstr(int y, int x, const wchar_t *wstr, int n);
int mvwaddwstr(WINDOW *win, int y, int x, const wchar_t *wstr);
int mvwaddnwstr(WINDOW *win, int y, int x, const wchar_t *wstr, int n);
Description:
These routines write all the characters of the null-terminated
string str or wstr on the given window. The functionality is
equivalent to calling waddch() once for each character in the
string. The routines with n as the last argument write at most
n characters; if n is negative, then the entire string will be
added.
Return Value:
All functions return OK or ERR.
Portability X/Open BSD SYS V
addstr Y Y Y
waddstr Y Y Y
mvaddstr Y Y Y
mvwaddstr Y Y Y
addnstr Y - 4.0
waddnstr Y - 4.0
mvaddnstr Y - 4.0
mvwaddnstr Y - 4.0
addwstr Y
waddwstr Y
mvaddwstr Y
mvwaddwstr Y
addnwstr Y
waddnwstr Y
mvaddnwstr Y
mvwaddnwstr Y
--------------------------------------------------------------------------
Name: attr
Synopsis:
int attroff(chtype attrs);
int wattroff(WINDOW *win, chtype attrs);
int attron(chtype attrs);
int wattron(WINDOW *win, chtype attrs);
int attrset(chtype attrs);
int wattrset(WINDOW *win, chtype attrs);
int standend(void);
int wstandend(WINDOW *win);
int standout(void);
int wstandout(WINDOW *win);
int color_set(short color_pair, void *opts);
int wcolor_set(WINDOW *win, short color_pair, void *opts);
int attr_get(attr_t *attrs, short *color_pair, void *opts);
int attr_off(attr_t attrs, void *opts);
int attr_on(attr_t attrs, void *opts);
int attr_set(attr_t attrs, short color_pair, void *opts);
int wattr_get(WINDOW *win, attr_t *attrs, short *color_pair,
void *opts);
int wattr_off(WINDOW *win, attr_t attrs, void *opts);
int wattr_on(WINDOW *win, attr_t attrs, void *opts);
int wattr_set(WINDOW *win, attr_t attrs, short color_pair,
void *opts);
int chgat(int n, attr_t attr, short color, const void *opts);
int mvchgat(int y, int x, int n, attr_t attr, short color,
const void *opts);
int mvwchgat(WINDOW *win, int y, int x, int n, attr_t attr,
short color, const void *opts);
int wchgat(WINDOW *win, int n, attr_t attr, short color,
const void *opts);
chtype getattrs(WINDOW *win);
Description:
These functions manipulate the current attributes and/or colors
of the named window. These attributes can be any combination
of A_STANDOUT, A_REVERSE, A_BOLD, A_DIM, A_BLINK, A_UNDERLINE.
These constants are defined in <curses.h> and can be combined
with the bitwise-OR operator (|).
The current attributes 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 the 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 characters put on the
screen.
The attrset() function sets the current attributes of the given
window to attrs. The attroff() function turns off the named
attributes without turning on or off any other attributes. The
attron() function turns on the named attributes without affecting
any others. The color_set() function sets the window color to
the value of color_pair.
The standout() function is the same as attron(A_STANDOUT).
The standend() function is the same as attrset(A_NORMAL); that
is, it turns off all attributes.
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
attroff Y Y Y
wattroff Y Y Y
attron Y Y Y
wattron Y Y Y
attrset Y Y Y
wattrset Y Y Y
standend Y Y Y
wstandend Y Y Y
standout Y Y Y
wstandout Y Y Y
color_set Y
wcolor_set Y
attr_get Y
wattr_get Y
attr_on Y
wattr_on Y
attr_off Y
wattr_off Y
attr_set Y
wattr_set Y
chgat Y
wchgat Y
mvchgat Y
mvwchgat Y
getattrs -
--------------------------------------------------------------------------
Name: beep
Synopsis:
int beep(void);
int flash(void);
Description:
These routines are used to signal the terminal user. The beep()
function will sound the audible bell on the terminal, if possible
and if not, will flash the screen (visible bell).
The flash() function will flash the screen.
Return Value:
These functions return OK.
Portability X/Open BSD SYS V
beep Y Y Y
flash Y Y Y
--------------------------------------------------------------------------
Name: bkgd
Synopsis:
int bkgd(chtype ch);
void bkgdset(chtype ch);
chtype getbkgd(WINDOW *win);
int wbkgd(WINDOW *win, chtype ch);
void wbkgdset(WINDOW *win, chtype ch);
int bkgrnd(const cchar_t *wch);
void bkgrndset(const cchar_t *wch);
int getbkgrnd(cchar_t *wch);
int wbkgrnd(WINDOW *win, const cchar_t *wch);
void wbkgrndset(WINDOW *win, const cchar_t *wch);
int wgetbkgrnd(WINDOW *win, cchar_t *wch);
Description:
The bkgdset() and wbkgdset() routines manipulate the backgound
of the named window. Background is a chtype consisting of any
combination of attributes and 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. To the extent possible
on a particular terminal, the attribute part of the background
is displayed as the graphic rendition of the character put on
the screen.
The bkgd() and wbkgd() routines combine the new background with
every position in the window. Background is any combination of
attributes and a character. Only the attribute part is used to
set the background of non-blank characters, while both character
and attributes are used for blank positions. To the extent
possible on a particular terminal, the attribute part of the
background is displayed as the graphic rendition of the
character put on the screen.
The attributes that are defined with the attrset()/attron() set
of functions take precedence over the background attributes if
there is a conflict (e.g., different color pairs).
Return Value:
bkgd() and wbkgd() return OK, unless the window is NULL, in
which case they return ERR.
Portability X/Open BSD SYS V
bkgd Y - 4.0
bkgdset Y - 4.0
getbkgd Y
wbkgd Y - 4.0
wbkgdset Y - 4.0
bkgrnd Y
bkgrndset Y
getbkgrnd Y
wbkgrnd Y
wbkgrndset Y
wgetbkgrnd Y
--------------------------------------------------------------------------
Name: border
Synopsis:
int border(chtype ls, chtype rs, chtype ts, chtype bs, chtype tl,
chtype tr, chtype bl, chtype br);
int wborder(WINDOW *win, chtype ls, chtype rs, chtype ts,
chtype bs, chtype tl, chtype tr, chtype bl, chtype br);
int box(WINDOW *win, chtype verch, chtype horch);
int hline(chtype ch, int n);
int vline(chtype ch, int n);
int whline(WINDOW *win, chtype ch, int n);
int wvline(WINDOW *win, chtype ch, int n);
int mvhline(int y, int x, chtype ch, int n);
int mvvline(int y, int x, chtype ch, int n);
int mvwhline(WINDOW *win, int y, int x, chtype ch, int n);
int mvwvline(WINDOW *win, int y, int x, chtype ch, int n);
int border_set(const cchar_t *ls, const cchar_t *rs,
const cchar_t *ts, const cchar_t *bs,
const cchar_t *tl, const cchar_t *tr,
const cchar_t *bl, const cchar_t *br);
int wborder_set(WINDOW *win, const cchar_t *ls, const cchar_t *rs,
const cchar_t *ts, const cchar_t *bs,
const cchar_t *tl, const cchar_t *tr,
const cchar_t *bl, const cchar_t *br);
int box_set(WINDOW *win, const cchar_t *verch, const cchar_t *horch);
int hline_set(const cchar_t *wch, int n);
int vline_set(const cchar_t *wch, int n);
int whline_set(WINDOW *win, const cchar_t *wch, int n);
int wvline_set(WINDOW *win, const cchar_t *wch, int n);
int mvhline_set(int y, int x, const cchar_t *wch, int n);
int mvvline_set(int y, int x, const cchar_t *wch, int n);
int mvwhline_set(WINDOW *win, int y, int x, const cchar_t *wch, int n);
int mvwvline_set(WINDOW *win, int y, int x, const cchar_t *wch, int n);
Description:
border(), wborder(), and box() draw a border around the edge of
the window. If any argument is zero, an appropriate default is
used:
ls left side of border ACS_VLINE
rs right side of border ACS_VLINE
ts top side of border ACS_HLINE
bs bottom side of border ACS_HLINE
tl top left corner of border ACS_ULCORNER
tr top right corner of border ACS_URCORNER
bl bottom left corner of border ACS_BLCORNER
br bottom right corner of border ACS_BLCORNER
hline() and whline() draw a horizontal line, using ch, starting
from the current cursor position. The cursor position does not
change. The line is at most n characters long, or as many as
will fit in the window.
vline() and wvline() draw a vertical line, using ch, starting
from the current cursor position. The cursor position does not
change. The line is at most n characters long, or as many as
will fit in the window.
Return Value:
These functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
border Y - 4.0
wborder Y - 4.0
box Y Y Y
hline Y - 4.0
vline Y - 4.0
whline Y - 4.0
wvline Y - 4.0
mvhline Y
mvvline Y
mvwhline Y
mvwvline Y
border_set Y
wborder_set Y
box_set Y
hline_set Y
vline_set Y
whline_set Y
wvline_set Y
mvhline_set Y
mvvline_set Y
mvwhline_set Y
mvwvline_set Y
--------------------------------------------------------------------------
Name: clear
Synopsis:
int clear(void);
int wclear(WINDOW *win);
int erase(void);
int werase(WINDOW *win);
int clrtobot(void);
int wclrtobot(WINDOW *win);
int clrtoeol(void);
int wclrtoeol(WINDOW *win);
Description:
erase() and werase() copy blanks to every position of the
window.
clear() and wclear() are similar to erase() and werase(), except
they also call clearok() to ensure that the the screen is
cleared on the next call to wrefresh() for that window.
clrtobot() and wclrtobot() clear the screen from the current
cursor position to the end of the window.
clrtoeol() and wclrtoeol() clear the screen from the current
cursor position to the end of the current line.
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
clear Y Y Y
wclear Y Y Y
erase Y Y Y
werase Y Y Y
clrtobot Y Y Y
wclrtobot Y Y Y
clrtoeol Y Y Y
wclrtoeol Y Y Y
--------------------------------------------------------------------------
Name: color
Synopsis:
int start_color(void);
int init_pair(short pair, short fg, short bg);
int init_color(short color, short red, short green, short blue);
bool has_colors(void);
bool can_change_color(void);
int color_content(short color, short *red, short *green, short *blue);
int pair_content(short pair, short *fg, short *bg);
int assume_default_colors(int f, int b);
int use_default_colors(void);
int PDC_set_line_color(short color);
Description:
To use these routines, start_color() must be called, usually
immediately after initscr(). Colors are always used in pairs
refered to as color-pairs. A color-pair consists of a foreground
color and a background color. A color-pair is initialized with
init_pair(). After it has been initialized, COLOR_PAIR(n) can be
used like any other video attribute.
start_color() initializes eight basic colors (black, red, green,
yellow, blue, magenta, cyan, and white), and two global
variables; COLORS and COLOR_PAIRS (respectively defining the
maximum number of colors and color-pairs the terminal is capable
of displaying).
init_pair() changes the definitions of a color-pair. The routine
takes three arguments: the number of the color-pair to be
redefined, and the new values of the foreground and background
colors. The value of color-pair must be between 0 and
COLOR_PAIRS - 1, inclusive. The values of foreground and
background must be between 0 and COLORS - 1, inclusive. If the
color pair was previously initialized, the screen is refreshed
and all occurrences of that color-pair are changed to the new
definition.
has_colors() indicates if the terminal supports, and can
maniplulate color. It returns TRUE or FALSE.
can_change_color() indicates if the terminal has the capability
to change the definition of its colors.
pair_content() is used to determine what the colors of a given
color-pair consist of.
assume_default_colors() and use_default_colors() emulate the
ncurses extensions of the same names. assume_default_colors(f,
b) is essentially the same as init_pair(0, f, b) (which isn't
allowed); it redefines the default colors. use_default_colors()
allows the use of -1 as a foreground or background color with
init_pair(), and calls assume_default_colors(-1, -1); -1
represents the foreground or background color that the terminal
had at startup. If the environment variable PDC_ORIGINAL_COLORS
is set at the time start_color() is called, that's equivalent to
calling use_default_colors().
PDC_set_line_color() is used to set the color, globally, for
the color of the lines drawn for the attributes: A_UNDERLINE,
A_OVERLINE, A_LEFTLINE and A_RIGHTLINE. A value of -1 (the
default) indicates that the current foreground color should be
used.
NOTE: COLOR_PAIR() and PAIR_NUMBER() are implemented as macros.
Return Value:
All functions return OK on success and ERR on error, except for
has_colors() and can_change_colors(), which return TRUE or FALSE.
Portability X/Open BSD SYS V
start_color Y - 3.2
init_pair Y - 3.2
init_color Y - 3.2
has_colors Y - 3.2
can_change_color Y - 3.2
color_content Y - 3.2
pair_content Y - 3.2
assume_default_colors - - -
use_default_colors - - -
PDC_set_line_color - - -
--------------------------------------------------------------------------
Name: debug
Synopsis:
void traceon(void);
void traceoff(void);
void PDC_debug(const char *, ...);
Description:
traceon() and traceoff() toggle the recording of debugging
information to the file "trace". Although not standard, similar
functions are in some other curses implementations.
PDC_debug() is the function that writes to the file, based on
whether traceon() has been called. It's used from the PDC_LOG()
macro.
Portability X/Open BSD SYS V
traceon - - -
traceoff - - -
PDC_debug - - -
--------------------------------------------------------------------------
Name: delch
Synopsis:
int delch(void);
int wdelch(WINDOW *win);
int mvdelch(int y, int x);
int mvwdelch(WINDOW *win, int y, int x);
Description:
The character under the cursor in the window is deleted. All
characters to the right on the same line are moved to the left
one position and the last character on the line is filled with
a blank. The cursor position does not change (after moving to
y, x if coordinates are specified).
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
delch Y Y Y
wdelch Y Y Y
mvdelch Y Y Y
mvwdelch Y Y Y
--------------------------------------------------------------------------
Name: deleteln
Synopsis:
int deleteln(void);
int wdeleteln(WINDOW *win);
int insdelln(int n);
int winsdelln(WINDOW *win, int n);
int insertln(void);
int winsertln(WINDOW *win);
int mvdeleteln(int y, int x);
int mvwdeleteln(WINDOW *win, int y, int x);
int mvinsertln(int y, int x);
int mvwinsertln(WINDOW *win, int y, int x);
Description:
With the deleteln() and wdeleteln() functions, 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.
With the insertln() and winsertn() functions, a blank line is
inserted above the current line and the bottom line is lost.
mvdeleteln(), mvwdeleteln(), mvinsertln() and mvwinsertln()
allow moving the cursor and inserting/deleting in one call.
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
deleteln Y Y Y
wdeleteln Y Y Y
mvdeleteln - - -
mvwdeleteln - - -
insdelln Y - 4.0
winsdelln Y - 4.0
insertln Y Y Y
winsertln Y Y Y
mvinsertln - - -
mvwinsertln - - -
--------------------------------------------------------------------------
Name: getch
Synopsis:
int getch(void);
int wgetch(WINDOW *win);
int mvgetch(int y, int x);
int mvwgetch(WINDOW *win, int y, int x);
int ungetch(int ch);
int flushinp(void);
int get_wch(wint_t *wch);
int wget_wch(WINDOW *win, wint_t *wch);
int mvget_wch(int y, int x, wint_t *wch);
int mvwget_wch(WINDOW *win, int y, int x, wint_t *wch);
int unget_wch(const wchar_t wch);
unsigned long PDC_get_key_modifiers(void);
int PDC_save_key_modifiers(bool flag);
int PDC_return_key_modifiers(bool flag);
Description:
With the getch(), wgetch(), mvgetch(), and mvwgetch() functions,
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 or after the first
newline. Unless noecho() has been set, the character will also
be echoed into the designated window.
If keypad() is TRUE, and a function key is pressed, the token for
that function key will be returned instead of the raw characters.
Possible function keys are defined in <curses.h> with integers
beginning with 0401, whose names begin with KEY_.
If nodelay(win, TRUE) has been called on the window and no input
is waiting, the value ERR is returned.
The ungetch() function places ch back onto the input queue to be
returned by the next call to wgetch().
The flushinp() routine throws away any type-ahead that has been
typed by the user and has not yet been read by the program.
PDC_get_key_modifiers() returns the keyboard modifiers (shift,
control, alt, numlock) effective at the time of the last getch()
call, if PDC_save_key_modifiers(TRUE) has been called before the
getch(). Use the macros PDC_KEY_MODIFIER_* to determine which
modifier(s) were set. PDC_return_key_modifiers() tells getch()
to return modifier keys pressed alone as keystrokes (KEY_ALT_L,
etc.). These may not work on all platforms.
NOTE: getch() and ungetch() are implemented as macros, to avoid
conflict with many DOS compiler's runtime libraries.
Return Value:
These functions return ERR or the value of the character, meta
character or function key token.
Portability X/Open BSD SYS V
getch Y Y Y
wgetch Y Y Y
mvgetch Y Y Y
mvwgetch Y Y Y
ungetch Y Y Y
flushinp Y Y Y
get_wch Y
wget_wch Y
mvget_wch Y
mvwget_wch Y
unget_wch Y
PDC_get_key_modifiers - - -
--------------------------------------------------------------------------
Name: getstr
Synopsis:
int getstr(char *str);
int wgetstr(WINDOW *win, char *str);
int mvgetstr(int y, int x, char *str);
int mvwgetstr(WINDOW *win, int y, int x, char *str);
int getnstr(char *str, int n);
int wgetnstr(WINDOW *win, char *str, int n);
int mvgetnstr(int y, int x, char *str, int n);
int mvwgetnstr(WINDOW *win, int y, int x, char *str, int n);
int get_wstr(wint_t *wstr);
int wget_wstr(WINDOW *win, wint_t *wstr);
int mvget_wstr(int y, int x, wint_t *wstr);
int mvwget_wstr(WINDOW *win, int, int, wint_t *wstr);
int getn_wstr(wint_t *wstr, int n);
int wgetn_wstr(WINDOW *win, wint_t *wstr, int n);
int mvgetn_wstr(int y, int x, wint_t *wstr, int n);
int mvwgetn_wstr(WINDOW *win, int y, int x, wint_t *wstr, int n);
Description:
The effect of getstr() is as though a series of calls to getch()
were made, until a newline or carriage return is received. The
resulting value is placed in the area pointed to by *str. The
erase and kill characters are interpreted, as well as any
special keys, such as function keys.
With wgetnstr(), a series of characters are read until a newline
or carriage return is received. The resulting value is placed
in the area pointed to by the character pointer str. The erase
and kill characters are interpreted. This differs from
wgetstr() in that the number of characters read is limited by a
passed argument.
WARNING: There is no way to know how long the buffer passed to
wgetstr() is, so use wgetnstr() to avoid buffer overflows.
Return Value:
This functions return ERR on failure or any other value on
success.
Portability X/Open BSD SYS V
getstr Y Y Y
wgetstr Y Y Y
mvgetstr Y Y Y
mvwgetstr Y Y Y
getnstr Y - 4.0
wgetnstr Y - 4.0
mvgetnstr Y - -
mvwgetnstr Y - -
get_wstr Y
wget_wstr Y
mvget_wstr Y
mvwget_wstr Y
getn_wstr Y
wgetn_wstr Y
mvgetn_wstr Y
mvwgetn_wstr Y
--------------------------------------------------------------------------
Name: getyx
Synopsis:
void getyx(WINDOW *win, int y, int x);
void getparyx(WINDOW *win, int y, int x);
void getbegyx(WINDOW *win, int y, int x);
void getmaxyx(WINDOW *win, int y, int x);
int getbegy(WINDOW *win);
int getbegx(WINDOW *win);
int getcury(WINDOW *win);
int getcurx(WINDOW *win);
int getpary(WINDOW *win);
int getparx(WINDOW *win);
int getmaxy(WINDOW *win);
int getmaxx(WINDOW *win);
Description:
With the getyx() macro, the cursor position of the window is
placed in the two integer variables y and x. getbegyx() and
getmaxyx() return the current beginning coordinates and size of
the specified window respectively. getparyx() returns the
beginning coordinates of the parent's window if the specified
window is a sub-window otherwise -1 is returned. These functions
are implemented as macros.
The functions getbegy(), getbegx(), getcurx(), getcury(),
getmaxy(), getmaxx(), getpary(), and getparx() return the
appropriate coordinate or size values, or ERR in the case of a
NULL window.
Portability X/Open BSD SYS V
getyx Y Y Y
getparyx - - 4.0
getbegyx - - 3.0
getmaxyx - - 3.0
getbegy - - -
getbegx - - -
getcury - - -
getcurx - - -
getpary - - -
getparx - - -
getmaxy - - -
getmaxx - - -
--------------------------------------------------------------------------
Name: inch
Synopsis:
chtype inch(void);
chtype winch(WINDOW *win);
chtype mvinch(int y, int x);
chtype mvwinch(WINDOW *win, int y, int x);
int in_wch(cchar_t *wcval);
int win_wch(WINDOW *win, cchar_t *wcval);
int mvin_wch(int y, int x, cchar_t *wcval);
int mvwin_wch(WINDOW *win, int y, int x, cchar_t *wcval);
Description:
The inch() functions retrieve the character and attribute from
the current or specified window position, in the form of a
chtype. If a NULL window is specified, (chtype)ERR is returned.
The in_wch() functions are the wide-character versions; instead
of returning a chtype, they store a cchar_t at the address
specified by wcval, and return OK or ERR. (No value is stored
when ERR is returned.) Note that in PDCurses, chtype and cchar_t
are the same.
Portability X/Open BSD SYS V
inch Y Y Y
winch Y Y Y
mvinch Y Y Y
mvwinch Y Y Y
in_wch Y
win_wch Y
mvin_wch Y
mvwin_wch Y
--------------------------------------------------------------------------
Name: inchstr
Synopsis:
int inchstr(chtype *ch);
int inchnstr(chtype *ch, int n);
int winchstr(WINDOW *win, chtype *ch);
int winchnstr(WINDOW *win, chtype *ch, int n);
int mvinchstr(int y, int x, chtype *ch);
int mvinchnstr(int y, int x, chtype *ch, int n);
int mvwinchstr(WINDOW *, int y, int x, chtype *ch);
int mvwinchnstr(WINDOW *, int y, int x, chtype *ch, int n);
int in_wchstr(cchar_t *wch);
int in_wchnstr(cchar_t *wch, int n);
int win_wchstr(WINDOW *win, cchar_t *wch);
int win_wchnstr(WINDOW *win, cchar_t *wch, int n);
int mvin_wchstr(int y, int x, cchar_t *wch);
int mvin_wchnstr(int y, int x, cchar_t *wch, int n);
int mvwin_wchstr(WINDOW *win, int y, int x, cchar_t *wch);
int mvwin_wchnstr(WINDOW *win, int y, int x, cchar_t *wch, int n);
Description:
These routines read a chtype or cchar_t string from the window,
starting at the current or specified position, and ending at the
right margin, or after n elements, whichever is less.
Return Value:
All functions return the number of elements read, or ERR on
error.
Portability X/Open BSD SYS V
inchstr Y - 4.0
winchstr Y - 4.0
mvinchstr Y - 4.0
mvwinchstr Y - 4.0
inchnstr Y - 4.0
winchnstr Y - 4.0
mvinchnstr Y - 4.0
mvwinchnstr Y - 4.0
in_wchstr Y
win_wchstr Y
mvin_wchstr Y
mvwin_wchstr Y
in_wchnstr Y
win_wchnstr Y
mvin_wchnstr Y
mvwin_wchnstr Y
--------------------------------------------------------------------------
Name: initscr
Synopsis:
WINDOW *initscr(void);
WINDOW *Xinitscr(int argc, char *argv[]);
int endwin(void);
bool isendwin(void);
SCREEN *newterm(char *type, FILE *outfd, FILE *infd);
SCREEN *set_term(SCREEN *new);
void delscreen(SCREEN *sp);
int resize_term(int nlines, int ncols);
bool is_termresized(void);
const char *curses_version(void);
Description:
The first curses routine called should be initscr(). This will
determine the terminal type and initialize all curses data
structures. The initscr() function also arranges that the first
call to refresh() will clear the screen. If errors occur,
initscr() will write an appropriate error message to standard
error and exit.
A program should always call endwin() before exiting or
escaping from curses mode temporarily. This routine will
restore tty modes, move the cursor to the lower left corner
of the screen and reset the terminal into the proper non-visual
mode. To resume curses after a temporary escape, call refresh()
or doupdate().
The isendwin() function returns TRUE if endwin() has been called
without any subsequent calls to wrefresh(), and FALSE otherwise.
In some implementations of curses, newterm() allows the use of
multiple terminals. Here, it's just an alternative interface for
initscr(). It always returns SP, or NULL.
set_term() does nothing meaningful in PDCurses, but is included
for compatibility with other curses implementations.
resize_term() is effectively two functions: When called with
nonzero values for nlines and ncols, it attempts to resize the
screen to the given size. When called with (0, 0), it merely
adjusts the internal structures to match the current size after
the screen is resized by the user. On the currently supported
platforms, this functionality is mutually exclusive: X11 allows
user resizing, while DOS, OS/2 and Win32 allow programmatic
resizing. If you want to support user resizing, you should check
for getch() returning KEY_RESIZE, and/or call is_termresized()
at appropriate times; if either condition occurs, call
resize_term(0, 0). Then, with either user or programmatic
resizing, you'll have to resize any windows you've created, as
appropriate; resize_term() only handles stdscr and curscr.
is_termresized() returns TRUE if the curses screen has been
resized by the user, and a call to resize_term() is needed.
Checking for KEY_RESIZE is generally preferable, unless you're
not handling the keyboard.
curses_version() returns a string describing the version of
PDCurses.
Return Value:
All functions return NULL on error, except endwin(), which
returns ERR on error.
Portability X/Open BSD SYS V
initscr Y Y Y
endwin Y Y Y
isendwin Y - 3.0
newterm Y - Y
set_term Y - Y
delscreen Y - 4.0
resize_term - - -
is_termresized - - -
curses_version - - -
--------------------------------------------------------------------------
Name: inopts
Synopsis:
int cbreak(void);
int nocbreak(void);
int echo(void);
int noecho(void);
int halfdelay(int tenths);
int intrflush(WINDOW *win, bool bf);
int keypad(WINDOW *win, bool bf);
int meta(WINDOW *win, bool bf);
int nl(void);
int nonl(void);
int nodelay(WINDOW *win, bool bf);
int notimeout(WINDOW *win, bool bf);
int raw(void);
int noraw(void);
void noqiflush(void);
void qiflush(void);
void timeout(int delay);
void wtimeout(WINDOW *win, int delay);
int typeahead(int fildes);
Description:
cbreak() and nocbreak() put the terminal into and out of cbreak
mode. In cbreak mode, characters typed by the user are
immediately available to the program and erase/kill character
processing is not performed. When out of cbreak mode, the
terminal driver will buffer characters typed until a newline or
carriage return is typed. Interrupt and flow control characters
are unaffected by this mode. Initially the terminal may or may
not need be in cbreak mode.
echo() and noecho() control whether typed characters are echoed
by the input routine. Initially, input characters are echoed.
Subsequent calls to echo() and noecho() do not flush type-ahead.
halfdelay() is similar to cbreak(), but allows for a time limit
to be specified, in tenths of a second. This causes getch() to
block for that period before returning ERR if no key has been
received. tenths must be between 1 and 255.
The keypad() function changes the keypad option of the user's
terminal. If enabled (bf is TRUE), the user can press a function
key (such as the left arrow key) and getch() will return a
single value that represents the KEY_LEFT function key.
If disabled, nothing will be returned.
The nodelay() function controls whether wgetch() is a
non-blocking call. If the option is enabled, and no input is
ready, wgetch() will return ERR. If disabled, wgetch() will hang
until input is ready.
The nl() function enables the translation of a carriage return
into a newline on input. The nonl() function disables it.
Initially, the translation does occur.
With raw() and noraw(), the terminal in 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 INTR, QUIT,
SUSP, and STOP characters are passed through without being
interpreted, and without generating a signal. The behaviour of
the BREAK key depends on other parameters of the terminal drive
that are not set by curses.
In PDCurses, the meta() function sets raw mode on or off.
The timeout() and wtimeout() functions set blocking or
non-blocking reads for the specified window. The delay is
measured in milliseconds. If it's negative, a blocking read is
used; if zero, then non-blocking reads are done -- if no input
is waiting, ERR is returned immediately. If the delay is
positive, the read blocks for the delay period; if the period
expires, ERR is returned.
intrflush(), notimeout(), noqiflush(), qiflush() and typeahead()
do nothing in PDCurses, but are included for compatibility with
other curses implementations.
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
cbreak Y Y Y
nocbreak Y Y Y
echo Y Y Y
noecho Y Y Y
halfdelay Y - Y
intrflush Y - Y
keypad Y - Y
meta Y - Y
nl Y Y Y
nonl Y Y Y
nodelay Y - Y
notimeout Y - Y
raw Y Y Y
noraw Y Y Y
noqiflush Y - Y
qiflush Y - Y
timeout Y - Y
wtimeout Y - Y
typeahead Y - Y
--------------------------------------------------------------------------
Name: insch
Synopsis:
int insch(chtype ch);
int winsch(WINDOW *win, chtype ch);
int mvinsch(int y, int x, chtype ch);
int mvwinsch(WINDOW *win, int y, int x, chtype ch);
int insrawch(chtype ch);
int winsrawch(WINDOW *win, chtype ch);
int mvinsrawch(int y, int x, chtype ch);
int mvwinsrawch(WINDOW *win, int y, int x, chtype ch);
int ins_wch(const cchar_t *wch);
int wins_wch(WINDOW *win, const cchar_t *wch);
int mvins_wch(int y, int x, const cchar_t *wch);
int mvwins_wch(WINDOW *win, int y, int x, const cchar_t *wch);
Description:
The insch() functions insert a chtype into the window at the
current or specified cursor position. The cursor is NOT
advanced. A newline is equivalent to clrtoeol(); tabs are
expanded; other control characters are converted as with
unctrl().
The ins_wch() functions are the wide-character
equivalents, taking cchar_t pointers rather than chtypes.
Video attributes can be combined with a character by ORing
them into the parameter. Text, including attributes, can be
copied from one place to another using inch() and insch().
insrawch() etc. are PDCurses-specific wrappers for insch() etc.
that disable the translation of control characters.
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
insch Y Y Y
winsch Y Y Y
mvinsch Y Y Y
mvwinsch Y Y Y
insrawch - - -
winsrawch - - -
ins_wch Y
wins_wch Y
mvins_wch Y
mvwins_wch Y
--------------------------------------------------------------------------
Name: insstr
Synopsis:
int insstr(const char *str);
int insnstr(const char *str, int n);
int winsstr(WINDOW *win, const char *str);
int winsnstr(WINDOW *win, const char *str, int n);
int mvinsstr(int y, int x, const char *str);
int mvinsnstr(int y, int x, const char *str, int n);
int mvwinsstr(WINDOW *win, int y, int x, const char *str);
int mvwinsnstr(WINDOW *win, int y, int x, const char *str, int n);
int ins_wstr(const wchar_t *wstr);
int ins_nwstr(const wchar_t *wstr, int n);
int wins_wstr(WINDOW *win, const wchar_t *wstr);
int wins_nwstr(WINDOW *win, const wchar_t *wstr, int n);
int mvins_wstr(int y, int x, const wchar_t *wstr);
int mvins_nwstr(int y, int x, const wchar_t *wstr, int n);
int mvwins_wstr(WINDOW *win, int y, int x, const wchar_t *wstr);
int mvwins_nwstr(WINDOW *win, int y, int x, const wchar_t *wstr, int n);
Description:
With these routines, a character string (as many characters as
will fit on the line) is inserted before the character under
the cursor. All characters to the right of the cursor are moved
to the right, with the possibility of the rightmost characters
on the line being lost. The cursor position does not change
(after moving to y, x, if specified). The routines with n as
the last argument insert at most n characters; if n is
negative, then the entire string is inserted.
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
insstr Y - 4.0
winsstr Y - 4.0
mvinsstr Y - 4.0
mvwinsstr Y - 4.0
insnstr Y - 4.0
winsnstr Y - 4.0
mvinsnstr Y - 4.0
mvwinsnstr Y - 4.0
ins_wstr Y
wins_wstr Y
mvins_wstr Y
mvwins_wstr Y
ins_nwstr Y
wins_nwstr Y
mvins_nwstr Y
mvwins_nwstr Y
--------------------------------------------------------------------------
Name: instr
Synopsis:
int instr(char *str);
int innstr(char *str, int n);
int winstr(WINDOW *win, char *str);
int winnstr(WINDOW *win, char *str, int n);
int mvinstr(int y, int x, char *str);
int mvinnstr(int y, int x, char *str, int n);
int mvwinstr(WINDOW *win, int y, int x, char *str);
int mvwinnstr(WINDOW *win, int y, int x, char *str, int n);
int inwstr(wchar_t *wstr);
int innwstr(wchar_t *wstr, int n);
int winwstr(WINDOW *win, wchar_t *wstr);
int winnwstr(WINDOW *win, wchar_t *wstr, int n);
int mvinwstr(int y, int x, wchar_t *wstr);
int mvinnwstr(int y, int x, wchar_t *wstr, int n);
int mvwinwstr(WINDOW *win, int y, int x, wchar_t *wstr);
int mvwinnwstr(WINDOW *win, int y, int x, wchar_t *wstr, int n);
Description:
These functions take characters (or wide characters) from the
current or specified position in the window, and return them as
a string in str (or wstr). Attributes are ignored. The functions
with n as the last argument return a string at most n characters
long.
Return Value:
Upon successful completion, innstr(), mvinnstr(), mvwinnstr()
and winnstr() return the number of characters actually read into
the string; instr(), mvinstr(), mvwinstr() and winstr() return
OK. Otherwise, all these functions return ERR.
Portability X/Open BSD SYS V
instr Y - 4.0
winstr Y - 4.0
mvinstr Y - 4.0
mvwinstr Y - 4.0
innstr Y - 4.0
winnstr Y - 4.0
mvinnstr Y - 4.0
mvwinnstr Y - 4.0
inwstr Y
winwstr Y
mvinwstr Y
mvwinwstr Y
innwstr Y
winnwstr Y
mvinnwstr Y
mvwinnwstr Y
--------------------------------------------------------------------------
Name: kernel
Synopsis:
int def_prog_mode(void);
int def_shell_mode(void);
int reset_prog_mode(void);
int reset_shell_mode(void);
int resetty(void);
int savetty(void);
void getsyx(int y, int x);
void setsyx(int y, int x);
int ripoffline(int line, int (*init)(WINDOW *, int));
int curs_set(int visibility);
int napms(int ms);
Description:
def_prog_mode() and def_shell_mode() save the current terminal
modes as the "program" (in curses) or "shell" (not in curses)
state for use by the reset_prog_mode() and reset_shell_mode()
functions. This is done automatically by initscr().
reset_prog_mode() and reset_shell_mode() restore the terminal to
"program" (in curses) or "shell" (not in curses) state. These
are done automatically by endwin() and doupdate() after an
endwin(), so they would normally not be called before these
functions.
savetty() and resetty() save and restore the state of the
terminal modes. savetty() saves the current state in a buffer,
and resetty() restores the state to what it was at the last call
to savetty().
getsyx() obtains the coordinates of the virtual screen cursor.
If leaveok() is currently TRUE, then -1, -1 is returned. If
lines have been removed from the top of the screen with
ripoffline(), then getsyx() includes those lines, so y and x
should only be used by setyx(). setyx() sets the cursor position
of the virtual screen to the y,x coordinates. If y, x are -1,
-1, leaveok() is set TRUE. The getsyx() and setsyx() routines
are designed to be used by a library routine that manipulates
curses windows, but does not want to change the position of the
cursor.
Note that getsyx() and setsyx() are defined as macros only.
curs_set() alters the appearance of the text cursor. A value of
0 for visibility makes the cursor disappear; a value of 1 makes
the cursor appear "normal" (usually an underline) and 2 makes
the cursor "highly visible" (usually a block).
ripoffline() allows the user to reduce the size of stdscr by 1
line. If the value of line is positive, the line is removed
from the top of the screen; negative from the bottom. Up to 5
lines can be ripped off stdscr by calling ripoffline()
consecutively. The function argument, init, is called from
within initscr() or newterm(), so ripoffline() must be called
before either of these functions. The init function is passed a
pointer to a 1 line WINDOW, and the width of the window. Calling
ripoffline() with a NULL initialise function pointer is not
advised.
The napms() function suspends the program for the specified
number of milliseconds.
FYI: It is unclear whether savetty() and resetty() are meant to
duplicate reset_prog_mode() and reset_shell_mode(), or be a
backing store type of operation. At this time, they're
implemented similarly to the reset_*_mode() routines.
Return Value:
All functions return OK on success and ERR on error, except
curs_set(), which returns the previous visibility.
Portability X/Open BSD SYS V
def_prog_mode Y Y Y
def_shell_mode Y Y Y
reset_prog_mode Y Y Y
reset_shell_mode Y Y Y
resetty Y Y Y
savetty Y Y Y
getsyx - - 3.0
setsyx - - 3.0
ripoffline Y - 3.0
curs_set Y - 3.0
napms Y Y Y
--------------------------------------------------------------------------
Name: util
Synopsis:
char *keyname(int key);
char *key_name(wchar_t c);
Description:
keyname() returns a string corresponding to the argument key.
key may be any key returned by wgetch().
key_name() is the wide-character version. It takes a wchar_t
parameter, but still returns a char *.
Portability X/Open BSD SYS V
keyname Y - 3.0
key_name Y
--------------------------------------------------------------------------
Name: mouse
Synopsis:
int mouse_set(unsigned long mbe);
int mouse_on(unsigned long mbe);
int mouse_off(unsigned long mbe);
int request_mouse_pos(void);
int map_button(unsigned long button);
void wmouse_position(WINDOW *win, int *y, int *x);
unsigned long getmouse(void);
unsigned long getbmap(void);
int mouseinterval(int wait);
bool wenclose(const WINDOW *win, int y, int x);
bool wmouse_trafo(const WINDOW *win, int *y, int *x, bool to_screen);
bool mouse_trafo(int *y, int *x, bool to_screen);
mmask_t mousemask(mmask_t mask, mmask_t *oldmask);
int nc_getmouse(MEVENT *event);
int ungetmouse(MEVENT *event);
Description:
As of PDCurses 3.0, there are two separate mouse interfaces: the
classic interface, which is based on the undocumented Sys V
mouse functions; and an ncurses-compatible interface. Both are
active at all times, and you can mix and match functions from
each, though it's not recommended. The ncurses interface is
essentially an emulation layer built on top of the classic
interface; it's here to allow easier porting of ncurses apps.
The classic interface: mouse_set(), mouse_on(), mouse_off(),
request_mouse_pos(), map_button(), wmouse_position(),
getmouse(), and getbmap(). An application using this interface
would start by calling mouse_set() or mouse_on() with a non-zero
value, often ALL_MOUSE_EVENTS. Then it would check for a
KEY_MOUSE return from getch(). If found, it would call
request_mouse_pos() to get the current mouse status.
mouse_set(), mouse_on() and mouse_off() are analagous to
attrset(), attron() and attroff(). These functions set the
mouse button events to trap. The button masks used in these
functions are defined in curses.h and can be or'ed together.
They are the group of masks starting with BUTTON1_RELEASED.
request_mouse_pos() requests curses to fill in the Mouse_status
structure with the current state of the mouse.
map_button() enables the specified mouse action to activate the
Soft Label Keys if the action occurs over the area of the screen
where the Soft Label Keys are displayed. The mouse actions are
defined in curses.h in the group that starts with BUTTON_RELEASED.
wmouse_position() determines if the current mouse position is
within the window passed as an argument. If the mouse is
outside the current window, -1 is returned in the y and x
arguments; otherwise the y and x coordinates of the mouse
(relative to the top left corner of the window) are returned in
y and x.
getmouse() returns the current status of the trapped mouse
buttons as set by mouse_set() or mouse_on().
getbmap() returns the current status of the button action used
to map a mouse action to the Soft Label Keys as set by the
map_button() function.
The ncurses interface: mouseinterval(), wenclose(),
wmouse_trafo(), mouse_trafo(), mousemask(), nc_getmouse(), and
ungetmouse(). A typical application using this interface would
start by calling mousemask() with a non-zero value, often
ALL_MOUSE_EVENTS. Then it would check for a KEY_MOUSE return
from getch(). If found, it would call nc_getmouse() to get the
current mouse status.
mouseinterval() sets the timeout for a mouse click. On all
current platforms, PDCurses receives mouse button press and
release events, but must synthesize click events. It does this
by checking whether a release event is queued up after a press
event. If it gets a press event, and there are no more events
waiting, it will wait for the timeout interval, then check again
for a release. A press followed by a release is reported as
BUTTON_CLICKED; otherwise it's passed through as BUTTON_PRESSED.
The default timeout is 150ms; valid values are 0 (no clicks
reported) through 1000ms. In x11, the timeout can also be set
via the clickPeriod resource. The return value from
mouseinterval() is the old timeout. To check the old value
without setting a new one, call it with a parameter of -1. Note
that although there's no classic equivalent for this function
(apart from the clickPeriod resource), the value set applies in
both interfaces.
wenclose() reports whether the given screen-relative y, x
coordinates fall within the given window.
wmouse_trafo() converts between screen-relative and window-
relative coordinates. A to_screen parameter of TRUE means to
convert from window to screen; otherwise the reverse. The
function returns FALSE if the coordinates aren't within the
window, or if any of the parameters are NULL. The coordinates
have been converted when the function returns TRUE.
mouse_trafo() is the stdscr version of wmouse_trafo().
mousemask() is nearly equivalent to mouse_set(), but instead of
OK/ERR, it returns the value of the mask after setting it. (This
isn't necessarily the same value passed in, since the mask could
be altered on some platforms.) And if the second parameter is a
non-null pointer, mousemask() stores the previous mask value
there. Also, since the ncurses interface doesn't work with
PDCurses' BUTTON_MOVED events, mousemask() filters them out.
nc_getmouse() returns the current mouse status in an MEVENT
struct. This is equivalent to ncurses' getmouse(), renamed to
avoid conflict with PDCurses' getmouse(). But if you define
NCURSES_MOUSE_VERSION (preferably as 2) before including
curses.h, it defines getmouse() to nc_getmouse(), along with a
few other redefintions needed for compatibility with ncurses
code. nc_getmouse() calls request_mouse_pos(), which (not
getmouse()) is the classic equivalent.
ungetmouse() is the mouse equivalent of ungetch(). However,
PDCurses doesn't maintain a queue of mouse events; only one can
be pushed back, and it can overwrite or be overwritten by real
mouse events.
Portability X/Open BSD SYS V
mouse_set - - 4.0
mouse_on - - 4.0
mouse_off - - 4.0
request_mouse_pos - - 4.0
map_button - - 4.0
wmouse_position - - 4.0
getmouse - - 4.0
getbmap - - 4.0
mouseinterval - - -
wenclose - - -
wmouse_trafo - - -
mouse_trafo - - -
mousemask - - -
nc_getmouse - - -
ungetmouse - - -
--------------------------------------------------------------------------
Name: move
Synopsis:
int move(int y, int x);
int wmove(WINDOW *win, int y, int x);
Description:
The cursor associated with the window is moved to the given
location. 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).
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
move Y Y Y
wmove Y Y Y
--------------------------------------------------------------------------
Name: outopts
Synopsis:
int clearok(WINDOW *win, bool bf);
int idlok(WINDOW *win, bool bf);
void idcok(WINDOW *win, bool bf);
void immedok(WINDOW *win, bool bf);
int leaveok(WINDOW *win, bool bf);
int setscrreg(int top, int bot);
int wsetscrreg(WINDOW *win, int top, int bot);
int scrollok(WINDOW *win, bool bf);
int raw_output(bool bf);
Description:
With clearok(), if bf is TRUE, the next call to wrefresh() with
this window will clear the screen completely and redraw the
entire screen.
The immedok() routine, called with a second argument of TRUE,
causes an automatic wrefrsh() to be called on the window every
time a change is made to that window, due to calls like;
waddch(), wclrtoeol(), etc... Not surprisingly, this causes a
severe performance overhead.
Normally, the hardware cursor is left at the location of the
window being refreshed. leaveok() allows the cursor to be
left wherever the update happens to leave it. It is useful
for applications where the cursor is not used, since it reduces
the need for cursor motions. If possible, the cursor is made
invisible when this option is enabled.
The setscrreg() and wsetscrreg() functions allow the user to set
a software scrolling region in a window. The parameters 'top'
and 'bot' are the line numbers of the top and bottom margin of
the scrolling region. (Line 0 is the top line of the window.)
If this option and scrollok() are enabled, an attempt to move
off the bottom margin will cause all lines in the scrolling
region to scroll up one line. Only the text of the window is
scrolled.
idlok() and idcok() do nothing in PDCurses, but are provided for
compatibility with other curses implementations.
raw_output() enables the output of raw characters using the
'standard' *add* and *ins* curses functions (that is, it
disables translation of control characters).
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
clearok Y Y Y
idlok Y Y Y
idcok Y - 4.0
immedok Y - 4.0
leaveok Y Y Y
setscrreg Y Y Y
wsetscrreg Y Y Y
scrollok Y Y Y
raw_output - - -
--------------------------------------------------------------------------
Name: overlay
Synopsis:
int overlay(const WINDOW *src_w, WINDOW *dst_w)
int overwrite(const WINDOW *src_w, WINDOW *dst_w)
int copywin(const WINDOW *src_w, WINDOW *dst_w, int src_tr,
int src_tc, int dst_tr, int dst_tc, int dst_br,
int dst_bc, bool overlay)
Description:
overlay() and overwrite() overlay src_w on top of dst_w; that
is, all text in src_w is copied into dst_w. The windows src_w
and dst_w are not required to be the same size. Those characters
in the source window that intersect with characters in the
destination window are copied to the destination window, so that
the characters appear in the same physical position on the
screen. The difference between the two functions is that
overlay() is non-destructive (blanks are not copied) while
overwrite() is destructive (blanks are copied).
copywin() is similar to overwrite() and overlay(), but copywin()
does not require that the two windows overlap. The arguments
src_tc and src_tr specify the top left corner of the region to
be copied to the destination window. The arguments dst_tc,
dst_tr, dst_br, dst_bc specify the region within the destination
window to where the copy is made. The argument overlay, if TRUE,
indicates that the copy is done non-destructively (as in
overlay()). Blanks in the source window are not copied to the
destination window. When overlay is FALSE, (as in overwrite()),
the copy is destructive; blanks are copied to the destination
window.
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
overlay Y Y Y
overwrite Y Y Y
copywin Y - 3.0
--------------------------------------------------------------------------
Name: pad
Synopsis:
WINDOW *newpad(int nlines, int ncols);
WINDOW *subpad(WINDOW *orig, int nlines, int ncols,
int begy, int begx);
int prefresh(WINDOW *win, int py, int px, int sy1, int sx1,
int sy2, int sx2);
int pnoutrefresh(WINDOW *w, int py, int px, int sy1, int sx1,
int sy2, int sx2);
int pechochar(WINDOW *pad, chtype ch);
int pecho_wchar(WINDOW *pad, const cchar_t *wch);
Description:
newpad() creates a new pad data structure. A pad is a special
case of a window, which is not restricted by the screen size,
and is not necessarily associated with a particular part of the
screen. A pad can be used when a large window is needed, and
only a part of the window will be on the screen at one tme.
Automatic refreshes of pads (e.g., from scrolling or echoing of
input) do not occur. It is not legal to call refresh() with a
pad as an argument; the routines prefresh() or pnoutrefresh()
should be called instead. Note that these routines require
additional parameters to specify the part of the pad to be
displayed and the location on the screen to be used for display.
subpad() creates a new sub-pad within a pad. The dimensions of
the sub-pad are nlines lines and ncols columns. The sub-pad is
at position (begy, begx) in the the parent pad. This position
is relative to the pad, and not to the screen as with subwin.
The sub-pad is made in the middle of the pad orig, so that
changes made to either pad will affect both. When using this
routine, it will often be necessary to call touchwin() before
calling prefresh().
prefresh() copies the specified pad to the physical terminal
screen. It takes account of what is already displayed on the
screen to optimize cursor movement. pnoutrefresh() copies the
named pad to the virtual screen. It then compares the virtual
screen with the physical screen and performs the actual update.
These routines are analogous to wrefresh() and wnoutrefresh(),
just with pads instead of windows. Additional parameters are
also needed to indicate what part of the pad and screen are
involved. The upper left corner of the part of the pad to be
displayed is specified by py and px. The coordinates sy1, sx1,
sy2, and sx2 specify the edges of the screen rectangle that will
contain the selected part of the pad.
The lower right corner of the pad rectangle to be displayed is
calculated from the screen co-ordinates. This ensures that the
screen rectangle and the pad rectangle are the same size. Both
rectangles must be entirely contained within their respective
structures.
pechochar() is functionally equivalent to addch() followed by
a call to prefresh().
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
newpad Y - Y
subpad Y - Y
prefresh Y - Y
pnoutrefresh Y - Y
pechochar Y - 3.0
pecho_wchar Y
--------------------------------------------------------------------------
Name: printw
Synopsis:
int printw(const char *fmt, ...);
int wprintw(WINDOW *win, const char *fmt, ...);
int mvprintw(int y, int x, const char *fmt, ...);
int mvwprintw(WINDOW *win, int y, int x, const char *fmt,...);
int vwprintw(WINDOW *win, const char *fmt, va_list varglist);
int vw_printw(WINDOW *win, const char *fmt, va_list varglist);
Description:
The printw() functions add a formatted string to the window at
the current or specified cursor position. The format strings are
the same as used in the standard C library's printf(). (printw()
can be used as a drop-in replacement for printf().)
Return Value:
All functions return the number of characters printed, or
ERR on error.
Portability X/Open BSD SYS V
printw Y Y Y
wprintw Y Y Y
mvprintw Y Y Y
mvwprintw Y Y Y
vwprintw Y - 4.0
vw_printw Y
--------------------------------------------------------------------------
Name: refresh
Synopsis:
int refresh(void);
int wrefresh(WINDOW *win);
int wnoutrefresh(WINDOW *win);
int doupdate(void);
int redrawwin(WINDOW *win);
int wredrawln(WINDOW *win, int beg_line, int num_lines);
Description:
wrefresh() copies the named window to the physical terminal
screen, taking into account what is already there in order to
optimize cursor movement. refresh() does the same, using stdscr.
These routines must be called to get any output on the terminal,
as other routines only manipulate data structures. Unless
leaveok() has been enabled, the physical cursor of the terminal
is left at the location of the window's cursor.
wnoutrefresh() and doupdate() allow multiple updates with more
efficiency than wrefresh() alone. wrefresh() works by first
calling wnoutrefresh(), which copies the named window to the
virtual screen. It then calls doupdate(), which compares the
virtual screen to the physical screen and does the actual
update. 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
wnoutrefresh() for each window, it is then possible to call
doupdate() only once.
In PDCurses, redrawwin() is equivalent to touchwin(), and
wredrawln() is the same as touchline(). In some other curses
implementations, there's a subtle distinction, but it has no
meaning in PDCurses.
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
refresh Y Y Y
wrefresh Y Y Y
wnoutrefresh Y Y Y
doupdate Y Y Y
redrawwin Y - 4.0
wredrawln Y - 4.0
--------------------------------------------------------------------------
Name: scanw
Synopsis:
int scanw(const char *fmt, ...);
int wscanw(WINDOW *win, const char *fmt, ...);
int mvscanw(int y, int x, const char *fmt, ...);
int mvwscanw(WINDOW *win, int y, int x, const char *fmt, ...);
int vwscanw(WINDOW *win, const char *fmt, va_list varglist);
int vw_scanw(WINDOW *win, const char *fmt, va_list varglist);
Description:
These routines correspond to scanf(). scanw() reads input from
the default window; wscanw() from the specified window.
mvscanw() and mvwscanw() move the cursor to the specified
position before reading.
wgetstr() is called to get a string from the window, and the
resulting line is used as input for the scan. All character
interpretation is carried out according to the scanf() function
rules.
Return Value:
Upon successful completion, the scanw, mvscanw, mvwscanw and
wscanw functions return the number of items successfully
matched. On end-of-file, they return EOF. Otherwise they
return ERR.
Portability X/Open BSD SYS V
scanw Y Y Y
wscanw Y Y Y
mvscanw Y Y Y
mvwscanw Y Y Y
vwscanw Y - 4.0
vw_scanw Y
--------------------------------------------------------------------------
Name: scr_dump
Synopsis:
int putwin(WINDOW *win, FILE *filep);
WINDOW *getwin(FILE *filep);
int scr_dump(const char *filename);
int scr_init(const char *filename);
int scr_restore(const char *filename);
int scr_set(const char *filename);
Description:
getwin() reads window-related data previously stored in a file
by putwin(). It then creates and initialises a new window using
that data.
putwin() writes all data associated with a window into a file,
using an unspecified format. This information can be retrieved
later using getwin().
scr_dump() writes the current contents of the virtual screen to
the file named by filename in an unspecified format.
scr_restore() function sets the virtual screen to the contents
of the file named by filename, which must have been written
using scr_dump(). The next refresh operation restores the screen
to the way it looked in the dump file.
In PDCurses, scr_init() does nothing, and scr_set() is a synonym
for scr_restore(). Also, scr_dump() and scr_restore() save and
load from curscr. This differs from some other implementations,
where scr_init() works with curscr, and scr_restore() works with
newscr; but the effect should be the same. (PDCurses has no
newscr.)
Return Value:
On successful completion, getwin() returns a pointer to the
window it created. Otherwise, it returns a null pointer. Other
functions return OK or ERR.
Portability X/Open BSD Sys V
putwin Y
getwin Y
scr_dump Y
scr_init Y
scr_restore Y
scr_set Y
--------------------------------------------------------------------------
Name: scroll
Synopsis:
int scroll(WINDOW *win);
int scrl(int n);
int wscrl(WINDOW *win, int n);
Description:
scroll() causes the window to scroll up one line. This involves
moving the lines in the window data strcture.
With a positive n, scrl() and wscrl() scroll the window up n
lines (line i + n becomes i); otherwise they scroll the window
down n lines.
For these functions to work, scrolling must be enabled via
scrollok(). Note also that scrolling is not allowed if the
supplied window is a pad.
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
scroll Y Y Y
scrl Y - 4.0
wscrl Y - 4.0
--------------------------------------------------------------------------
Name: slk
Synopsis:
int slk_init(int fmt);
int slk_set(int labnum, const char *label, int justify);
int slk_refresh(void);
int slk_noutrefresh(void);
char *slk_label(int labnum);
int slk_clear(void);
int slk_restore(void);
int slk_touch(void);
int slk_attron(const chtype attrs);
int slk_attr_on(const attr_t attrs, void *opts);
int slk_attrset(const chtype attrs);
int slk_attr_set(const attr_t attrs, short color_pair, void *opts);
int slk_attroff(const chtype attrs);
int slk_attr_off(const attr_t attrs, void *opts);
int slk_color(short color_pair);
int slk_wset(int labnum, const wchar_t *label, int justify);
int PDC_mouse_in_slk(int y, int x);
void PDC_slk_free(void);
void PDC_slk_initialize(void);
Description:
These functions manipulate a window that contain Soft Label Keys
(SLK). To use the SLK functions, a call to slk_init() must be
made BEFORE initscr() or newterm(). slk_init() removes 1 or 2
lines from the useable screen, depending on the format selected.
The line(s) removed from the screen are used as a separate
window, in which SLKs are displayed.
slk_init() requires a single parameter which describes the
format of the SLKs as follows:
0 3-2-3 format
1 4-4 format
2 4-4-4 format (ncurses extension)
3 4-4-4 format with index line (ncurses extension)
2 lines used
55 5-5 format (pdcurses format)
The functions slk_refresh(), slk_noutrefresh() and slk_touch()
are analagous to refresh(), noutrefresh() and touch() functions.
Return Value:
All functions return OK on success and ERR on error.
Portability X/Open BSD SYS V
slk_init Y - Y
slk_set Y - Y
slk_refresh Y - Y
slk_noutrefresh Y - Y
slk_label Y - Y
slk_clear Y - Y
slk_restore Y - Y
slk_touch Y - Y
slk_attron Y - Y
slk_attrset Y - Y
slk_attroff Y - Y
slk_attr_on Y
slk_attr_set Y
slk_attr_off Y
slk_wset Y
PDC_mouse_in_slk - - -
PDC_slk_free - - -
PDC_slk_initialize - - -
--------------------------------------------------------------------------
Name: termattr
Synopsis:
int baudrate(void);
char erasechar(void);
bool has_ic(void);
bool has_il(void);
char killchar(void);
char *longname(void);
chtype termattrs(void);
attr_t term_attrs(void);
char *termname(void);
int erasewchar(wchar_t *ch);
int killwchar(wchar_t *ch);
char wordchar(void);
Description:
baudrate() is supposed to return the output speed of the
terminal. In PDCurses, it simply returns INT_MAX.
has_ic and has_il() return TRUE. These functions have meaning in
some other implementations of curses.
erasechar() and killchar() return ^H and ^U, respectively -- the
ERASE and KILL characters. In other curses implementations,
these may vary by terminal type. erasewchar() and killwchar()
are the wide-character versions; they take a pointer to a
location in which to store the character, and return OK or ERR.
longname() returns a pointer to a static area containing a
verbose description of the current terminal. The maximum length
of the string is 128 characters. It is defined only after the
call to initscr() or newterm().
termname() returns a pointer to a static area containing a
short description of the current terminal (14 characters).
termattrs() returns a logical OR of all video attributes
supported by the terminal.
wordchar() is a PDCurses extension of the concept behind the
functions erasechar() and killchar(), returning the "delete
word" character, ^W.
Portability X/Open BSD SYS V
baudrate Y Y Y
erasechar Y Y Y
has_ic Y Y Y
has_il Y Y Y
killchar Y Y Y
longname Y Y Y
termattrs Y Y Y
termname Y Y Y
erasewchar Y
killwchar Y
term_attrs Y
wordchar - - -
--------------------------------------------------------------------------
Name: terminfo
Synopsis:
int mvcur(int oldrow, int oldcol, int newrow, int newcol);
int del_curterm(TERMINAL *);
int putp(const char *);
int restartterm(char *, int, int *);
TERMINAL *set_curterm(TERMINAL *);
int setupterm(char *, int, int *);
int tgetent(char *, const char *);
int tgetflag(char *);
int tgetnum(char *);
char *tgetstr(char *, char **);
char *tgoto(char *, int, int);
int tigetflag(char *);
int tigetnum(char *);
char *tigetstr(char *);
char *tparm(char *,long, long, long, long, long, long, long,
long, long);
int tputs(const char *, int, int (*)(int));
int vidattr(chtype attr);
int vid_attr(attr_t attr, short color_pair, void *opt);
int vidputs(chtype attr, int (*putfunc)(int));
int vid_puts(attr_t attr, short color_pair, void *opt,
int (*putfunc)(int));
Description:
mvcur() lets you move the physical cursor without updating any
window cursor positions. It returns OK or ERR.
The rest of these functions are currently implemented as stubs,
returning the appropriate errors and doing nothing else.
Portability X/Open BSD SYS V
mvcur Y Y Y
--------------------------------------------------------------------------
Name: touch
Synopsis:
int touchwin(WINDOW *win);
int touchline(WINDOW *win, int start, int count);
int untouchwin(WINDOW *win);
int wtouchln(WINDOW *win, int y, int n, int changed);
bool is_linetouched(WINDOW *win, int line);
bool is_wintouched(WINDOW *win);
Description:
touchwin() and touchline() throw away all information about
which parts of the window have been touched, pretending that the
entire window has been drawn on. This is sometimes necessary
when using overlapping windows, since a change to one window
will affect the other window, but the records of which lines
have been changed in the other window will not reflect the
change.
untouchwin() marks all lines in the window as unchanged since
the last call to wrefresh().
wtouchln() makes n lines in the window, starting at line y, look
as if they have (changed == 1) or have not (changed == 0) been
changed since the last call to wrefresh().
is_linetouched() returns TRUE if the specified line in the
specified window has been changed since the last call to
wrefresh().
is_wintouched() returns TRUE if the specified window
has been changed since the last call to wrefresh().
Return Value:
All functions return OK on success and ERR on error except
is_wintouched() and is_linetouched().
Portability X/Open BSD SYS V
touchwin Y Y Y
touchline Y - 3.0
untouchwin Y - 4.0
wtouchln Y Y Y
is_linetouched Y - 4.0
is_wintouched Y - 4.0
--------------------------------------------------------------------------
Name: util
Synopsis:
char *unctrl(chtype c);
void filter(void);
void use_env(bool x);
int delay_output(int ms);
int getcchar(const cchar_t *wcval, wchar_t *wch, attr_t *attrs,
short *color_pair, void *opts);
int setcchar(cchar_t *wcval, const wchar_t *wch, const attr_t attrs,
short color_pair, const void *opts);
wchar_t *wunctrl(cchar_t *wc);
Description:
unctrl() expands the text portion of the chtype c into a
printable string. Control characters are changed to the "^X"
notation; others are passed through. wunctrl() is the wide-
character version of the function.
delay_output() inserts an ms millisecond pause in output. On
some systems, this has no effect.
getcchar() works in two modes: When wch is not NULL, it reads
the cchar_t pointed to by wcval and stores the attributes in
attrs, the color pair in color_pair, and the text in the
wide-character string wch. When wch is NULL, getcchar() merely
returns the number of wide characters in wcval. In either mode,
the opts argument is unused.
setcchar constructs a cchar_t at wcval from the wide-character
text at wch, the attributes in attr and the color pair in
color_pair. The opts argument is unused.
filter() and use_env() are no-ops on PDCurses.
Currently, the length returned by getcchar() is always 1 or 0.
Similarly, setcchar() will only take the first wide character
from wch, and ignore any others that it "should" take (i.e.,
combining characters). Nor will it correctly handle any
character outside the basic multilingual plane (UCS-2).
Return Value:
unctrl() and wunctrl() return NULL on failure. delay_output()
always returns OK.
getcchar() returns the number of wide characters wcval points to
when wch is NULL; when it's not, getcchar() returns OK or ERR.
setcchar() returns OK or ERR.
Portability X/Open BSD SYS V
unctrl Y Y Y
filter Y - 3.0
use_env Y - 4.0
delay_output Y Y Y
getcchar Y
setcchar Y
wunctrl Y
--------------------------------------------------------------------------
Name: window
Synopsis:
WINDOW *newwin(int nlines, int ncols, int begy, int begx);
WINDOW *derwin(WINDOW* orig, int nlines, int ncols,
int begy, int begx);
WINDOW *subwin(WINDOW* orig, int nlines, int ncols,
int begy, int begx);
WINDOW *dupwin(WINDOW *win);
int delwin(WINDOW *win);
int mvwin(WINDOW *win, int y, int x);
int mvderwin(WINDOW *win, int pary, int parx);
int syncok(WINDOW *win, bool bf);
void wsyncup(WINDOW *win);
void wcursyncup(WINDOW *win);
void wsyncdown(WINDOW *win);
WINDOW *resize_window(WINDOW *win, int nlines, int ncols);
int wresize(WINDOW *win, int nlines, int ncols);
WINDOW *PDC_makelines(WINDOW *win);
WINDOW *PDC_makenew(int nlines, int ncols, int begy, int begx);
void PDC_sync(WINDOW *win);
Description:
newwin() creates a new window with the given number of lines,
nlines and columns, ncols. The upper left corner of the window
is at line begy, column begx. If either nlines or ncols is zero,
they will be defaulted to LINES - begy and COLS - begx. A new
full-screen window is created by calling newwin(0, 0, 0, 0).
delwin() deletes the named window, freeing all memory associated
with it. In the case of overlapping windows, subwindows should
be deleted before the main window.
mvwin() moves the window so that the upper left-hand corner is
at position (y,x). If the move would cause the window to be off
the screen, it is an error and the window is not moved. Moving
subwindows is allowed, but should be avoided. (I don't know why?)
subwin() creates a new sub-window within a window. The
dimensions of the sub-window are nlines lines and ncols columns.
The sub-window is at position (begy, begx) on the screen. This
position is relative to the screen, and not to the window orig.
The sub-window is made in the middle of the window orig, so that
changes made to either window will affect both. When using this
routine, it will often be necessary to call touchwin() before
calling wrefresh().
derwin() is the same as subwin(), except that begy and begx are
relative to the origin of the window orig rather than the
screen. There is no difference between subwindows and derived
windows.
mvderwin() moves a derived window (or subwindow) 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.
dupwin() creates an exact duplicate of the window win.
wsyncup() causes a touchwin() of all of the window's parents.
If wsyncok() is called with a second argument of TRUE, this
causes a wsyncup() to be called every time the window is
changed.
wcursyncup() causes the current cursor position of all of a
window's ancestors to reflect the current cursor position of the
current window.
wsyncdown() causes a touchwin() of the current window if any of
its parent's windows have been touched.
resize_window() allows the user to resize an existing window. It
returns the pointer to the new window, or NULL on failure.
wresize() is an ncurses-compatible wrapper for resize_window().
Note that, unlike ncurses, it will NOT process any subwindows of
the window. (However, you still can call it _on_ subwindows.) It
returns OK or ERR.
PDC_makenew() allocates all data for a new WINDOW * except the
actual lines themselves. If it's unable to allocate memory for
the window structure, it will free all allocated memory and
return a NULL pointer.
PDC_makelines() allocates the memory for the lines.
PDC_sync() handles wrefresh() and wsyncup() calls when a window
is changed.
Return Value:
newwin(), subwin(), derwin() and dupwin() return a pointer
to the new window, or NULL on failure. delwin(), mvwin(),
mvderwin() and syncok() return OK or ERR. wsyncup(),
wcursyncup() and wsyncdown() return nothing.
Errors:
It is an error to call resize_window() before calling initscr().
Also, an error will be generated if we fail to create a newly
sized replacement window for curscr, or stdscr. This could
happen when increasing the window size. NOTE: If this happens,
the previously successfully allocated windows are left alone;
i.e., the resize is NOT cancelled for those windows.
Portability X/Open BSD SYS V
newwin Y Y Y
delwin Y Y Y
mvwin Y Y Y
subwin Y Y Y
derwin Y - Y
mvderwin Y - Y
dupwin Y - 4.0
wsyncup Y - 4.0
syncok Y - 4.0
wcursyncup Y - 4.0
wsyncdown Y - 4.0
resize_window - - -
wresize - - -
PDC_makelines - - -
PDC_makenew - - -
PDC_sync - - -
--------------------------------------------------------------------------
.......PDCurses Private Functions:
.......PDCurses Panel Functions:
Name: panel
Synopsis:
int bottom_panel(PANEL *pan);
int del_panel(PANEL *pan);
int hide_panel(PANEL *pan);
int move_panel(PANEL *pan, int starty, int startx);
PANEL *new_panel(WINDOW *win);
PANEL *panel_above(const PANEL *pan);
PANEL *panel_below(const PANEL *pan);
int panel_hidden(const PANEL *pan);
const void *panel_userptr(const PANEL *pan);
WINDOW *panel_window(const PANEL *pan);
int replace_panel(PANEL *pan, WINDOW *win);
int set_panel_userptr(PANEL *pan, const void *uptr);
int show_panel(PANEL *pan);
int top_panel(PANEL *pan);
void update_panels(void);
Description:
The panel library is built using the curses library, and any
program using panels routines must call one of the curses
initialization routines such as initscr(). A program using these
routines must be linked with the panels and curses libraries.
The header <panel.h> includes the header <curses.h>.
The panels package gives the applications programmer a way to
have depth relationships between curses windows; a curses window
is associated with every panel. The panels routines allow curses
windows to overlap without making visible the overlapped
portions of underlying windows. The initial curses window,
stdscr, lies beneath all panels. The set of currently visible
panels is the 'deck' of panels.
The panels package allows the applications programmer to create
panels, fetch and set their associated windows, shuffle panels
in the deck, and manipulate panels in other ways.
bottom_panel() places pan at the bottom of the deck. The size,
location and contents of the panel are unchanged.
del_panel() deletes pan, but not its associated winwow.
hide_panel() removes a panel from the deck and thus hides it
from view.
move_panel() move() the curses window associated with pan, so
that its upper lefthand corner is at the supplied coordinates.
(Do not use mvwin() on the window.)
new_panel() creates a new panel associated with win and returns
the panel pointer. The new panel is placed at the top of the
deck.
panel_above() returns a pointer to the panel in the deck above
pan, or NULL if pan is the top panel. If the value of pan passed
is NULL, this function returns a pointer to the bottom panel in
the deck.
panel_below() returns a pointer to the panel in the deck below
pan, or NULL if pan is the bottom panel. If the value of pan
passed is NULL, this function returns a pointer to the top panel
in the deck.
panel_hidden() returns OK if pan is hidden and ERR if it is not.
panel_userptr() - Each panel has a user pointer available for
maintaining relevant information. This function returns a
pointer to that information previously set up by
set_panel_userptr().
panel_window() returns a pointer to the curses window associated
with the panel.
replace_panel() replaces the current window of pan with win.
set_panel_userptr() - Each panel has a user pointer available
for maintaining relevant information. This function sets the
value of that information.
show_panel() makes a previously hidden panel visible and places
it back in the deck on top.
top_panel() places pan on the top of the deck. The size,
location and contents of the panel are unchanged.
update_panels() refreshes the virtual screen to reflect the
depth relationships between the panels in the deck. The user
must use doupdate() to refresh the physical screen.
Return Value:
Each routine that returns a pointer to an object returns NULL if
an error occurs. Each panel routine that returns an integer,
returns OK if it executes successfully and ERR if it does not.
Portability X/Open BSD SYS V
bottom_panel - - Y
del_panel - - Y
hide_panel - - Y
move_panel - - Y
new_panel - - Y
panel_above - - Y
panel_below - - Y
panel_hidden - - Y
panel_userptr - - Y
panel_window - - Y
replace_panel - - Y
set_panel_userptr - - Y
show_panel - - Y
top_panel - - Y
update_panels - - Y
Credits:
Original Author - Warren Tucker N4HGF
{gatech,emory}!n4hgf!wht -or- wht@n4hgf.Mt-Park.GA.US
--------------------------------------------------------------------------