EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
-------------------------------------------------------------------------------
extended curses library
PURPOSE
Controls cursor movement and windowing.
LIBRARY
Extended Curses Library (libcur.a)
SYNTAX
#include <cur01.h>
DESCRIPTION
The Extended Curses subroutines control input and output to a workstation,
performing optimized cursor movement, windowing, and other functions. This
package is based on the curses subroutine package, which is included in most
UNIX-compatible systems. The curses subroutines are also included in AIX for
complete compatibility with existing programs (see "curses"). However, curses
and Extended Curses cannot both be used by the same program.
The enhancements provided by Extended Curses include:
o A wider range of display attributes
o Generalized drawing of boxes
o Terminal-independent input data processing
o Extended window control
o Pane, panel, and field concepts
o Support for extended characters
o Handling of locator input.
TERMINOLOGY
window The internal representation of what a portion of the display may
look like at some point in time. Windows can be any size from
the entire display screen to a single character.
screen A window that is large as the display screen. A screen named
stdscr is automatically provided.
terminal Sometimes called a terminal screen. A special screen that is the
Extended Curses package's understanding of what the workstation's
display screen currently looks like. The terminal screen is
identified by a window named curscr, which should not be accessed
directly by the user. Instead, changes should be made to stdscr
(or a user-defined screen) and then refresh (or wrefresh) should
be called to update the terminal.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 1
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
presentation space
The array that contains the data and attributes associated with a
window.
pane An area of the display that shows all or part of the data
contained in a presentation space associated with that pane.
active pane The pane in which the text cursor is positioned. A pane must be
active before you can do input.
panel A group of one or more panes that are treated as a unit. The
panes of a panel are displayed together, erased together, and
usually represent a unit of information to a person using the
application. A panel is represented on the display as a
rectangular area that is tiled (completely filled) with panes.
field An area in a presentation space into which the program accepts
input.
extended character
A character other than 7-bit ASCII that can be represented in
either 1 or 2 bytes. (See "data stream.")
NLSCHAR Represents an mbchar_t (unsigned long) character stored in four
bytes. It is used for both interface data (arguments to library
functions) and internal representation of a character.
When a double display width character needs to be displayed where only a single
display width space is available, then a partial-character indicator is
displayed instead. The partial-character indicator is the @ (at sign), and it
is represented by the constant pd_char.
See the discussion of Extended Curses in AIX Programming Tools and Interfaces,
and "Introduction to International Character Support" in Managing the AIX
Operating System for more detailed information about these concepts.
LINKING THE EXTENDED CURSES ROUTINES
The Extended Curses routines also call terminfo subroutines, which are located
in the Curses Library (libcurses.a). Therefore, compile programs that use
Extended Curses routines with the flags -lcur and -lcurses.
HEADER FILES
o The cur00.h header file replaces curses.h when converting programs that use
the original curses package to Extended Curses.
o All of the routines require the cur01.h header file.
o The key codes returned by getch are defined in cur02.h.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 2
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
o The cur03.h header file defines attribute priority codes, and is not needed
by application programs.
o The unctrl routine requires cur04.h.
o The routines that manage panes and panels (the routines whose names begin
with ec) also require the cur05.h header file.
NAMING CONVENTIONS
The new routines added to the original curses package begin with the letters
ec.
Many routines operate on stdscr, the standard screen, by default.
Corresponding routines that allow you to specify a window have the same name,
prefixed with the letter w. For example, addch adds a character to stdscr,
while waddch allows you to specify the window. Sometimes a routine beginning
with p also exists, such as paddch, which allows you to specify a pane.
Some routines also allow you to specify cursor movement with the action to be
performed. These routines have a prefix of mv. Thus, addch becomes mvaddch,
waddch becomes mvwaddch, and paddch becomes mvpaddch. Each of these routines
is equivalent to calling move or wmove before performing the operation.
The various prefixed forms of the routines are implemented as macros. In each
case, the routine beginning with w is the base subroutine from which the others
are defined.
PARAMETERS
The following declarations serve for all of the routines:
char ch *string;
NLSCHAR xc;
int line, col, firstline, firstcol;
int numlines, numcols, numchars, length, mode;
bool boolf;
WINDOW *win, *win1, *win2, *oldwin, *newwin;
PANE *pane;
PANEL *panel;
RETURN VALUES
Unless otherwise noted, each routine returns a value of type int that is either
OK (indicating successful completion) or ERR (if an error is encountered).
THE EXTENDED CURSES ROUTINES
The Extended Curses routines are listed here alphabetically, except that
routines with w, p, and mv prefixes are listed with the corresponding routine
that does not have these prefixes.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 3
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
addch (xc)
waddch (win, xc)
paddch (pane, xc)
mvaddch (line, col, xc)
mvwaddch (win, line, col, xc)
mvpaddch (pane, line, col, xc)
The xc parameter is a value of type NLSCHAR.
The addch routine adds the NLSCHAR specified by the xc parameter on the
window at the current (line, col) coordinates. paddch adds the character
to the presentation space for the pane specified by the pane parameter.
If the character is "'\n'" (new-line character), the line is cleared to
the end, and the current (line, col) coordinates are changed to the
beginning of the next line. A "'\r'" (return character) moves the
current position to the beginning of the current line on the window. A
"'\t'" (tab character) is expanded into spaces in the normal tabstop
positions of every eighth column.
Adding a character to the lower right corner of a window that includes
the lower right corner of the display causes many terminals to scroll the
entire display image up one line. If adding a character or a character
attribute causes such scrolling to occur, addch makes the change on the
window but does not mark it for wrefresh purposes; addch returns the
value ERR.
A double display width character must be added to addch in a single call.
If adding a character would cause that character to split across two
lines, the system appends a blank to the end of the current line and adds
the entire character at the beginning of the following line. If an added
character overwrites half an existing two-byte character, the system
replaces the remaining half of that existing character with a blank.
addstr (string)
waddstr (win, string)
paddstr (pane, string)
mvaddstr (line, col, string)
mvwaddstr (win, line, col, string)
mvpaddstr (pane, line, col, string)
The addstr routine adds the string pointed to by the string parameter on
the window at the current (line, col) coordinates. The string can
contain single-shift control codes.
Upon successful completion, addstr returns OK and the current (line, col)
coordinates point to the location just beyond the end of the string. The
addstr routine returns ERR if an attempt is made to add a character to
the lower right corner of a window that includes the lower right corner
of the display. In this case, addstr writes as much of the string on the
window as possible.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 4
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
waddfld (win, string, length, numlines, numcols, mode, xc)
The waddfld routine adds data to a field within a window. The current
coordinates specify the upper-left corner of the field in the window.
The numlines and numcols parameters specify the number of lines and
columns in the field, respectively. The length parameter specifies the
length of the data. The mode parameter specifies the attribute for the
field output. The xc parameter specifies the NLSCHAR that is used to
fill the remainder of the field after the data has been added to it. The
xc parameter must be in single display width; otherwise ERR is returned.
If the string contains a "'\n'" (new-line character), the fill character
is added to the remainder of the columns on that line of the field, and
the remainder of the data is added starting at the first column of the
next line of the field. A "'\r'" (return character) changes the current
position to the beginning column of the field. A "'\t'" (tab character)
is expanded with fill characters up to the next normal tabstop position
within the field.
The waddfld routine follows the same rules as addch for adding double
display width characters.
beep ( )
The beep routine sounds the speaker or bell at the workstation.
box (win, System V, hor)
NLSCHAR System V, hor;
The box routine draws a box around the window specified by the win
parameter. box uses the NLSCHAR specified by the System V parameter to
draw the vertical sides of the box, and the NLSCHAR specified by the hor
parameter for drawing the horizontal lines and corners.
If the window includes the lower right corner of the display and scrollok
is not set, then the lower right corner of the box is not shown on the
window, and the box routine returns ERR.
The box routine is a macro that invokes superbox.
cbox (win)
The cbox routine draws a box around the window specified by the win
parameter. The characters used are those defined in /usr/lib/terminfo
(type 1 box characters) or defaulted during the initialization.
The cbox routine is implemented as a macro that invokes superbox.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 5
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
The cbox routine returns ERR if the window includes the lower right
corner of the display and scrollok is not set on.
chgat (numchars, mode)
wchgat (win, numchars, mode)
pchgat (pane, numchars, mode)
mvchgat (line, col, numchars, mode)
mvwchgat (win, line, col, numchars, mode)
mvpchgat (pane, line, col, numchars, mode)
The chgat routine changes the attributes of the next numchars characters
on the window starting from the current (line, col) coordinates. The
attributes are changed to the attributes specified by the mode parameter.
This routine does not wrap around to the next line; however, specifying a
value for the numchars parameter that would cause a line wrap is not an
error.
The mode parameter is one or more of the attributes defined by the global
attribute variables. More than one attribute may be specified by
logically ORing them together. The following example changes the
attributes of the next 10 characters to bold blue characters on a black
background:
chgat (10, BOLD | F_BLUE | B_BLACK)
The range of columns to be changed should include entire characters. The
numchars variable refers to the number of single or double width display
characters. If the current (line, col) position is on the second column
of a double display width character, clearing begins at position col
"-1".
The chgat routine returns ERR if the change forces scrolling and scrollok
is not set on for the window.
clear ( )
wclear (win)
The clear routine resets the entire stdscr window to blank characters.
clear sets the current (line, col) coordinates to (0, 0).
clearok (scr, boolf)
WINDOW *scr;
The clearok routine sets the clear flag for the screen specified by the
scr parameter. If the boolf parameter is TRUE, the screen is cleared on
the next call to refresh or wrefresh. If the boolf parameter is FALSE,
the screen is not cleared on the next call to refresh or wrefresh. This
only works on screens, and, unlike clear, does not alter the contents of
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 6
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
the screen. If the scr parameter is curscr, the next refresh will cause
a clear-screen, even if the window passed to refresh is not a screen.
The clearok routine returns ERR if the window is not a full-screen
window.
clrtobot ( )
wclrtobot (win)
The clrtobot routine erases the window from the current (line, col)
coordinates to the bottom. clrtobot leaves the current (line, col)
coordinates unchanged. This does not force a clear-screen sequence on
the next refresh. If the current (line, col) position is on the second
column of a double display width character, clearing begins at position
col "-1".
The clrtobot routine always returns the value OK.
clrtoeol ( )
wclrtoeol (win)
The clrtoeol routine clears the window from the current (line, col)
coordinates to the end of the current line. The current (line, col)
coordinates are not changed. If the current (line, col) position is on
the second column of a double display width character, clearing begins at
position col "-1".
The clrtoeol routine always returns the value OK.
colorend ( )
wcolorend (win)
The colorend routine returns the terminal to NORMAL mode. By default,
NORMAL is usually defined as (F_WHITE | B_BLACK).
The colorend routine is a macro that invokes xstandend.
The colorend routine always returns the value OK.
colorout (mode)
wcolorout (win, mode)
The colorout routine sets the current standout bit-pattern of the window
(win"->"_csbp) to the attribute specified by the mode parameter.
Characters added to the window after such a call will have mode as their
attribute. The mode parameter is constructed by logically ORing together
attributes that are declared in the cur01.h header file that are
supported by the terminal.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 7
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
The colorout routine overrides the current setting of the window and
works in conjunction with almost all of the routines that cause output to
be placed on the window.
The colorout routine is a macro that invokes xstandout.
The colorout routine always returns the value OK.
cresetty (boolf)
The cresetty routine resets the terminal to the state saved by the last
call to csavetty. Use this routine after the completion of a program
that uses the terminal as a simple terminal. If the boolf parameter is
TRUE, then the data in curscr is redisplayed.
crmode ( )
nocrmode ( )
The crmode routine turns off the canonical processing of input by the
system device driver. When canonical processing is off, data is made
available without waiting for a "'\n'" (new-line character). nocrmode
enables canonical processing by the system device driver.
The wgetch routine, which is used for all Extended Curses input, forces
the equivalent of crmode before requesting input if echoing is active,
and reinstates the original status on exit. If you are using echo, you
should issue a call to either crmode or raw to avoid multiple calls by
wgetch.
The crmode routine differs from raw in that crmode has no effect on
output data processing and does not disable signal processing by the
device driver.
The crmode routine always returns the value OK.
csavetty (boolf)
The csavetty routine saves the current Extended Curses state so that it
can later be reset by cresetty. Use this routine before running a
program that uses the terminal as a simple terminal. If the boolf
parameter is TRUE, then the following status is set before saving the
terminal status: crmode, noecho, meta, nonl, and keypad (TRUE).
delay
See nodelay on page 27
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 8
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
delch ( )
wdelch (win)
mvdelch (line, col)
mvwdelch (win, line, col)
The delch routine deletes the character at the current (line, col)
coordinates. Each character after the deleted character on the line
shifts to the left, and the last characters become blank.
The delch routine always returns the value OK.
deleteln ( )
wdeleteln (win)
The deleteln routine deletes the current line. Every line below the
current line moves up, and the bottom line becomes blank. The current
(line, col) coordinates remain unchanged.
The deleteln routine always returns the value OK.
delwin (win)
The delwin routine deletes the window specified by the win parameter.
All resources used by the deleted window are freed for future use.
If a window has a subwindow allocated inside of it, the deletion of the
window does not affect the subwindow even though the subwindow is
invalidated. Therefore, subwindows must be deleted before the outer
windows are deleted.
The delwin routine always returns the value OK.
dounctrl (boolf)
The dounctrl routine turns the printing of control characters on or off.
If the boolf parameter is TRUE, then the printing is turned on; if FALSE,
printing is turned off. By default, dounctrl processing is initially
turned off. The unctrl routine defined in cur04.h is used to get the
string of printable characters being printed. Control characters become
the printable character represented by the control character plus 0x40,
preceded by a ^ (circumflex).
drawbox (win, line, col, numlines, numcols)
The drawbox routine draws a box with the upper left corner located at the
position specified by the line and col parameters. The numlines
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 9
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
parameter specifies the number of rows to be used by the box, and the
numcols parameter specifies the number of columns to be used by the box.
The characters used to draw the box are either those specified in the
terminfo file, or those defaulted at initialization.
The drawbox routine returns ERR if part or all of the box is outside the
window, or the box addresses the lower right corner of the screen and
scrollok is not on.
#include <cur05.h>
ecactp (pane, boolf)
The ecactp routine specifies the active pane in a panel. The pane
specified by the pane parameter is made the active pane if the boolf
parameter is TRUE. If an active pane has been previously designated,
then the border of that pane is reset to the inactive display mode, and
the border of the pane specified by the pane parameter is set to the
active display mode. If the boolf parameter is FALSE, then the border of
the pane specified by the pane parameter is set to the inactive display
mode.
#include <cur05.h>
ecadpn (pane, win)
The ecadpn routine adds the window specified by the win parameter to the
list of windows that can be presented in the pane specified by the pane
parameter. No visible action occurs as a result of this routine. A call
to ecaspn must be made after ecadpn to change the data associated with
the pane display.
The ecadpn routine returns ERR if the system is unable to allocate the
storage required.
#include <cur05.h>
ecaspn (pane, win)
The ecaspn routine makes the window specified by the win parameter the
current window for display in the pane specified by the pane parameter.
A refresh call for the pane or panel is needed to cause the data to be
presented on the display. The viewport associated with the pane is
positioned with the top left corner of the viewport at the top left
corner of the data for the window.
The ecaspn routine returns ERR if the window specified by the win
parameter was not previously associated with this pane using ecadpn.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 10
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
#include <cur05.h>
WINDOW *ecblks ( )
The ecblks routine returns a pointer to a window that is filled with
blanks. This window is intended to be used as a filler for panes that
have no real content. It requires less storage than normal windows
because all lines will always contain blanks.
Do not modify or delete this window.
#include <cur05.h>
PANEL *ecbpls (numlines, numcols, firstline, firstcol, title, divdim,
border, pane)
short numlines, numcols, firstline, firstcol;
char *title;
char divdim, border;
The ecbpls routine builds a panel structure.
The numlines parameter specifies the panel size in rows.
The numcols parameter specifies the panel size in columns.
The firstline parameter specifies the panel's origin on the display's
upper left corner row coordinate.
The firstcol parameter specifies the panel's origin on the display's
upper left corner column coordinate.
The title parameter points to a title string. The title is shown
centered in the top border. If no title is desired, this parameter
should be NULL.
The divdim parameter specifies the dimension along which this panel is to
be divided: either Pdivtyv (vertical) or Pdivtyh (horizontal).
The border parameter indicates whether or not this panel is to have a
border: either Pbordry (yes) or Pbordrn (no).
The pane parameter points to the first pane that defines the divisions of
this panel.
All parameters should be given as defined here. However, they are not
checked or used until a call is made to ecdvpl. An application may
modify values put into this structure until it calls ecdvpl.
Upon successful completion, a pointer to the new panel is returned.
ecbpls returns ERR if there is not enough storage available.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 11
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
#include <cur05.h>
PANE *ecbpns (numlines, numcols, ln, ld, divdim, ds, du, border, lh, lv)
short numlines, numcols, ds;
PANE *ln, *ld, *lh, *lv;
char divdim, du, border;
The ecbpns routine builds a pane structure.
The numlines parameter specifies the number of rows in the presentation
space for the pane.
The numcols parameter specifies the number of columns in the presentation
space for the pane.
The ln parameter points to a neighboring pane either above or to the
left.
The ld parameter points to the start of a chain for divisions of the
pane.
The divdim parameter specifies the dimension of the pane along which
division is to occur. This parameter is used if and only if the ld
parameter is not NULL. Valid values for this parameter are Pdivpnv
(vertical dimension) and Pdivpnh (horizontal dimension).
The ds and du parameters together specify the size of this pane as part
of the division of a parent pane:
du Vertical or Horizontal Size of the Pane
Pdivszc The size is specified by the ds parameter.
Pdivszp The size is ds / 10000 of the available space. For example,
if ds is 5000, then the row or column size is half of the
available space.
Pdivszf The pane has a floating size. The value of the ds parameter
is not used.
If you specify NULL for the ld parameter or if you are not sure which
value to use for du, specify Pdivszf for the du parameter.
The border parameter specifies whether or not this pane has a border:
either Pbordry (yes) or Pbordrn (no).
The lh parameter points to a pane that is to scroll with this pane when
the pane scrolls horizontally.
The lv parameter points to a pane that is to scroll with this pane when
the pane scrolls vertically.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 12
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
If the ln parameter is not NULL, the divs field of the pane structure
being built receives the value that was in the ln.divs field. The
ln.divs field is modified to point to the new pane structure being built.
If the lh and the lv parameters are not NULL, they are used to link the
new structure to the specified structures and to link the specified
structures to the new structure. The links thus created form a ring that
includes all panes that scroll together.
Upon successful completion, a pointer to the new pane structure is
returned. ecbpns returns ERR if a error is detected during processing.
#include <cur05.h>
ecdfpl (panel, boolf)
The ecdfpl routine creates the Extended Curses WINDOW structures needed
to define the specified panel.
At the time this routine is invoked, all size and location specifications
of the panel and its constituent panes must be properly set. ecdfpl does
not examine any of the division size specifications or the scroll link
specifications.
The fpane pointer in the indicated PANEL structure must point to the
first leaf pane for the panel, and the subsequent nxtpn pointers from
that pane must form a loop back to the first leaf pane. (This is done by
ecdvpl.)
A WINDOW structure is built for the panel specified by the panel
parameter. This WINDOW has a size that corresponds to the size of the
panel. For each of the panes in the subsequent chain, a separate WINDOW
structure is built with a size that corresponds to the specified
presentation space size or the viewport size, whichever is larger.
If borders are specified for any of the panes, those borders are drawn on
the WINDOW for the panel. All corners are checked and, if needed, proper
junction characters are used to draw the corner.
The boolf parameter indicates whether to suppress the creation of
presentation spaces for the panes. If the value is TRUE, presentation
spaces are not created. If FALSE, presentation spaces are created.
The ecdfpl routine returns ERR if sufficient storage is not available for
the WINDOW structures being created.
#include <cur05.h>
ecdppn (pane, oldwin, newwin)
The ecdppn routine adds, drops or replaces a presentation space for a
pane.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 13
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
First, if the oldwin parameter is not NULL, then ecdppn drops oldwin from
the list of windows that are alternatives for the pane specified by the
pane parameter. The previous association should have been established
using edadpn. If the oldwin parameter is NULL, then no window is
dropped.
Next, if the newwin parameter is not NULL, then ecdppn adds newwin as a
valid pane for this window, replacing oldwin, if it was associated with
the pane specified by the pane parameter. (See ecadpn for a better way
to add a pane).
The ecdppn routine always returns the value OK.
#include <cur05.h>
ecdspl (panel)
The ecdspl routine releases all of the data structures associated with
the panel specified by the panel parameter. The released data structures
are returned to the free pool. The released data structures include the
panel structure, all associated pane structures, any window structures
associated with the panes, any auxiliary window structures associated
with the panes, and all private control structures used by Extended
Curses.
#include <cur05.h>
ecdvpl (panel)
The ecdvpl routine assigns a real size and relative position to all the
panes defined for the panel specified by the panel parameter. All of the
panes must be linked to the panel. The structure of a tree is followed
to determine the sizes for each pane.
The direction of the first set of divisions and the size of the first set
of divisions is determined. This information is used to control the
division algorithm. Using the size along the direction of division,
first, the total space for the interior of panes is determined by
counting the panes and their borders. Next, any panes with fixed size
are given the space indicated by the divsz field in the pane structure.
The remaining available space is then assigned to the panes that have
specified a proportional size. Finally, any space that remains is
assigned to those panes that specified a floating size. Once the sizes
are determined, the origin for each pane relative to the panel origin is
determined and entered into the PANE structure. A final pass is made
over the list of panes in the current division, and, for each that is
itself divided, the process is repeated.
If adjacent panes both have a border specified, the border space is
shared between them.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 14
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
If all of the panes have a fixed size and the total is less than the
available space, there will be space that cannot be accessed by the
application in the resulting structure.
If, after allocating space to the proportional panes, there is space
remaining and no floating panes are in the current set, the remaining
free space is allocated to the proportional panes.
The ecdvpl routine returns ERR and the structures are invalid for use by
ecdfpl if one or more of the following occur:
o The total size specified for fixed panes exceeds the space available.
o The total fractions specified for the proportional panes exceed a
total of 1.
o The number of panes exceeds the number of positions available.
#include <cur05.h>
ecflin (pane, firstline, firstcol, numlines, numcols, pat, xc, buf, mask)
NLecflin (pane, firstline, firstcol, numlines, numcols, pat, xc, buf, length,
mask) char *pat, *buf, *mask;
MBecflin (pane, firstline, firstcol, numline, numcols, xc, buf, length,
validcheck, validfunc) int *validfunc;
The ecflin, NLecflin, and MBecflin routines input field data to a pane.
ecflin is retained to preserve traditional functionality. NLceflin,
which supports code set pc850 only, is retained for backward
compatibility, and MBecflin is provided for international character set
support.
NLecflin works like ecflin, but has an additional parameter, length,
which specifies the length of the buffer in which the input data is
stored.
The ecflin routine inputs field data to the pane pointed to by the pane
parameter. The firstline and the firstcol parameters specify the upper
left corner of the field in the current window being shown in the pane.
The numcols parameter specifies the number of columns in the field, and
the numlines parameter specifies the number of rows in the field.
The buf parameter points to a buffer into which input data is stored.
The buffer must be at least numlines * numcols characters long.
The xc parameter specifies the first NLSCHAR to be entered into the
field. If the xc parameter is a null character, it is ignored.
The pat and mask parameters specify the set of characters that are to be
accepted as valid input.
The position in the field may not always correspond to the position in
the input buffer. Input is accepted from the terminal as long as the
cursor remains within the bounds of the field. However, if the input
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 15
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
buffer is filled before the cursor exits the field, input processing
stops and ecflin returns.
Cursor movement that moves the cursor outside the field is allowed and is
reflected on the display. If cursor movement places the cursor in a
position where data input would cause the input buffer to overflow, input
processing stops. Any data keys entered are checked against the
character set specified by the pat parameter. If the data character is
acceptable, then it is echoed. If the character is not acceptable, then
the ecflin routine returns its value.
Insert and delete keys are honored and data is shifted within the field
as needed. If the field spans more than one line and insertions or
deletions are made, then data that is shifted out of one line of the
field is shifted into the end of the next line. Data shifted out of the
field is lost. When characters are deleted, null characters are shifted
into the end of the field.
The pat parameter points to a string that indicates the set of characters
that is acceptable as valid input. These characters include all code
points of the P0 code page (see "display symbols"). The string is formed
of these codes:
U Uppercase letters: "'A'"-"'Z'" plus the accented uppercase letters
from code page P0.
L Lowercase letters: "'a'"-"'z'" plus the accented lowercase letters
from code page P0.
N Numeric characters: "'0'"-"'9'".
A Alphanumeric characters: "'A'"-"'Z'", "'a'"-"'z'", and "'0'"-"'9'"
plus the accented letters from code pages P0, P1, and P2.
B Blank (space character-0x20).
P Printable characters: blank-"'^'" (0x20-0x7E).
G Graphic characters: "'!'"-"'^'" (0x21-0x7E).
X Hexadecimal characters: "'0'"-"'9'", "'A'"-"'F'", and "'a'"-"'f'".
C Control Characters:
o Cursor Up, Cursor Down, Cursor Left, Cursor Right
o Backspace
o Back-tab (to first position of field)
o Insert (enable or disable insert mode)
o Delete (delete current character)
o New-line (to left column and down one line)
D Default characters:
o 0x20-0x7E
o 0x80-0xFF
o Controls, as defined for code "C".
Z Application-specified character set
+ Allows characters indicated by following codes.
- Does not allow characters indicated by following codes.
If the first character of pat is "+" or "-", the set of characters
specified by the rest of the string is added to ("+") or taken from ("-")
the default characters (which can also be specified with "D"). If the
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 16
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
first character in this string is not "+" or "-", then the set of
characters specified by pat replaces the default. After the first
character, the sets indicated are allowed unless preceded by a "-" (minus
sign). For example:
""PC-L"" Allows the printable and control characters, except for
lowercase letters.
""-CBN"" Allows all of the default characters, except for control
characters, blanks, or numeric characters.
If the pat string contains a "Z", then the array pointed to by the mask
parameter specifies a character validity mask. This array must be
exactly 64 bytes long (512 bits), where each bit corresponds to a
character code as returned by wgetch. The bytes in the array correspond
as follows:
Bytes 0-31 P0 characters 0x00-0xFF
Bytes 32-63 Keycodes 0x100-0x1FF
If a given bit is set to 1, then the corresponding character is accepted
(for "+Z") or rejected (for "-Z"). If a bit is set to 0, then the
acceptance status of the corresponding character, as determined by the
rest of pat, is not changed.
Upon successful completion, the code associated with the last input that
terminated input is returned.
The ecflin routine returns ERR if one or more of the following are true:
o There is an error in the parameters.
o The firstline parameter is outside the window.
o The firstcol parameter is outside the window.
o The numcols parameter is too large.
o The numlines parameter is too large.
The MBecflin routine works like the NLecflin routine, except that it also
handles multiple byte and double display width character input. The
definitions of the parameters pane, firstline, firstcol, numline,
numcols, xc, buf, and length are the same as those described for
NLecflin.
When validcheck is TRUE, MBecflin calls the routine validfunc (c) where c
is the input code, and checks the return value from it. If the return
value is TRUE, c is considered valid and processing continues; otherwise,
c is considered invalid and processing terminates.
When validcheck is FALSE, MBecflin performs a default validity check in
which any input data code not defined in the current locale is considered
invalid (that is, _mblen returns a value of -1). c may be data code in
NLSCHAR (mbchar_t, file code), or keypad code defined in cur02.h.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 17
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
The routine validfunc must be defined by the user for the validity check,
and a conversion from file code to wide code might be required in the
routine to achieve code independence.
When an entered character overwrites half of an existing double display
width character, the system replaces the remaining half of that existing
character with a blank. If a character is inserted when the cursor is
positioned at the second column of a double display width character, the
cursor is adjusted to the first column of that character before
insertion. A deletion, on the other hand, always deletes a whole
character regardless of how many columns it occupies.
When a double display width character is entered at the last column of
any line but the last line, the character enters the input buffer. On
the screen, however, it is replaced by two partial-character indicators
(@@), appearing at the last column of the current line, and at the
beginning column of the next line respectively. Note that this is only a
display-time feature. The original character is still kept as is in the
input buffer. For example, during the editing session in the insertion
mode, if there are insertions or deletions before that character, the
character will be displayed normally whenever it is assigned two
consecutive columns.
echo ( )
noecho ( )
The echo routine causes the terminal to echo characters to the display.
If echo is set on, wgetch places all input into the data structure for
the window.
The noecho routine turns echo off. If echo is turned off, characters are
not written to the display.
#include <cur05.h>
ecpnin (pane, boolf, xc)
The ecpnin routine causes the pane to accept keyboard input. The pane
specified by the pane parameter is scrolled, if necessary, to ensure that
the cursor is visible on the display. Keyboard input is then accepted.
If the boolf parameter is TRUE and if the input character is a simple
cursor movement, then the resulting cursor position is reflected on the
display. Further input is then read from the terminal. If the boolf
parameter is FALSE, or if the input character is not a simple cursor
movement, then the value of the input character is returned.
The xc parameter specifies the first NLSCHAR to be assumed from the
display. If xc is a null character, then it is ignored.
This routine tracks the locator cursor if locator tracking is enabled
(see "trackloc" on page 32).
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 18
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
void ecpnmodf (pane)
The ecpnmodf macro marks the panel that contains the pane specified by
the pane parameter as modified. This information is used by ecrfpl to
determine whether a panel needs to be written to the display.
#include <cur05.h>
ecrfpl (panel)
The ecrfpl routine refreshes the panel specified by the panel parameter.
If that panel is partially obscured by other panels, then those panels
are also written to the display. If the panel parameter is NULL, then
all panels that have been marked as modified (with ecpnmodf) are written.
If any panels have been removed (with ecrmpl), then all panels are
written.
#include <cur05.h>
ecrfpn (pane)
The ecrfpn routine refreshes the pane specified by the pane parameter on
the display. If the pane is the active pane, then the window might be
scrolled to ensure that the cursor is visible. If the pane is not
active, then the window is not scrolled.
The ecrfpn routine always returns the value OK.
#include <cur05.h>
ecrlpl (panel)
The ecrlpl routine returns the structures associated with the panel
specified by the panel parameter to the free storage pool. This includes
all window structures associated with the panes of the panel, all
Extended Curses private structures, and any added window structures. The
panel and associated pane structures are not released and can be reused.
The ecrlpl routine always returns the value OK.
#include <cur05.h>
ecrmpl (panel)
The ecrmpl routine removes the panel specified by the panel parameter
from the list of panels that are currently being displayed. If the panel
is not currently in that list, no action is taken and no error is
returned. This routine should be followed by a call to ecrfpl to update
the display.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 19
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
The ecrmpl routine always returns the value OK.
#include <cur05.h>
ecscpn (pane, numlines, numcols)
The ecscpn routine causes the pane specified by the pane parameter to be
scrolled over the underlying window the distance indicated by the numcols
and the numlines parameters. The numcols parameter specifies the
distance to scroll horizontally and the numlines parameter specifies the
distance to scroll vertically. These parameters can be positive or
negative and may imply a movement that positions the viewport partially
or completely off the window. If such a position results from the
scroll, the scroll stops after moving as far in the indicated direction
as possible. Positive values move to the right or down. Negative values
move to the left or up.
If there are other panes linked to the pane specified, those panes will
also scroll an amount necessary to maintain the identical horizontal or
vertical positioning on the respective windows. If the resulting
position requires placing the viewport partially or completely off the
window, the scroll request terminates at the edge of the window.
#include <cur05.h>
ecshpl (panel)
The ecshpl routine shows the panel specified by the panel parameter on
the terminal.
If the specified panel is currently the top panel, no action is taken and
no error is returned. If there is another top panel, the active pane in
that panel is changed to the inactive state. The specified panel is
placed at the top of the panel chain. This routine should be followed by
a call to ecrfpl to update the display.
The ecshpl routine always returns the value OK.
#include <cur05.h>
ectitl (title, line, col)
char *title;
The ectitl routine creates or modifies the title panel. The title panel
is always visible, that is, on top of any other panels. The title
parameter points to a character string that is displayed as the new
title. If title is NULL, then any existing title is removed. The line
and col parameters specify the coordinates for the upper left corner of
the title panel. If firstline is not valid, then it defaults to 1. If
firstcol is not valid, then the title will be centered.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 20
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
endwin ( )
The endwin routine ends window routines before exiting. Ending window
routines before exiting restores the terminal to the state it was before
initscr (or gettmode and setterm) was called. endwin should always be
called before exiting. endwin does not exit.
erase ( )
werase (win)
perase (pane)
The erase routine clears the window and sets it to blanks without setting
the clear flag. Similarly, werase erases the window specified by the win
parameter, and perase erases the pane specified by the pane parameter.
This is analogous to the clear routine, except that it does not cause a
clear-screen sequence to be generated on a refresh.
extended (boolf)
The extended routine turns on and off the combining of input bytes into
multibyte extended characters. If the boolf parameter is TRUE, then this
input processing is turned on; if FALSE, then it is turned off. By
default, extended processing is initially turned on.
flash ( )
The flash routine displays a visual bell on the terminal screen if one is
available. If a visual bell is not available, then flash toggles the
terminal speaker or bell.
The flash routine always returns the value OK.
fullbox (win, vert, hor, topl, topr, botl, botr)
NLSCHAR vert, hor, topl, topr, botl, botr;
The fullbox routine puts box characters on the edges of the window. The
vert parameter specifies the NLSCHAR to use for the vertical sides. The
hor parameter specifies the NLSCHAR to use for the horizontal lines. The
topl and the topr parameters specify the NLSCHARs to use for the top left
and the top right corners. The botl and the botr parameters specify the
NLSCHARs to use for the bottom left and the bottom right corners.
The fullbox routine returns ERR if an attempt is made to scroll when
scrollok is not active.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 21
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
The fullbox routine does not accept double display width characters. If
a double width character is used, the fullbox routine substitutes a
single display character and draws the box. The system returns ERR.
The fullbox routine is a macro that invokes superbox.
#include <cur02.h>
NLSCHAR getch ( )
NLSCHAR wgetch (win)
NLSCHAR mvgetch (line, col)
NLSCHAR mvwgetch (win, line, col)
The getch routine gets a character from the terminal and echoes it on the
window, if necessary. If noecho has been set, then the window does not
change. noecho and either crmode or raw must be set for Extended Curses
to know what is actually on the terminal. If these settings are not
correct, wgetch sets noecho and crmode and resets them to the original
mode when done.
Upon completion, the NLSCHAR for the data key or one of the following
values is returned:
KEY_NOKEY nodelay is active and no data is available.
KEY_xxxx keypad is active and a control key was recognized. See the
cur02.h header file for a complete list of the key codes that
can be returned.
ERR Echoing the character would cause the screen to scroll
illegally.
#include <cur02.h>
NLSCHAR getstr (string)
NLSCHAR wgetstr (win, string)
NLSCHAR mvgetstr (line, col, string)
NLSCHAR mvwgetstr (win, line, col, string)
The getstr routine gets a string through the window and stores it in the
location pointed to by the string parameter. The string may contain
single-shift control codes. The area pointed to must be large enough to
hold the string. getstr calls wgetch to get the characters until a
new-line character or some other control character is encountered.
Upon completion, one of the following values is returned:
OK The input string was terminated with a new-line character.
KEY_NOKEY nodelay is active and no data is available.
KEY_xxxx The input string ended with a control key, and the code for
this key was returned. See the cur02.h header file for a
complete list of the key codes that can be returned.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 22
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
ERR The string caused the screen to scroll illegally.
gettmode ( )
The gettmode routine issues the needed control operation to the display
device driver to save the processing flags in a fixed global area.
gettmode is invoked by initscr and is not normally called directly by
applications.
getyx (win, line, col)
The getyx routine stores the current (line, col) coordinates of window
specified by the win parameter into the variables line and col. Because
getyx is a macro and not a subroutine, the names of line and col are
passed, rather than their addresses.
Upon successful completion, line and col contain the current row and
column coordinates for the cursor in the specified window.
NLSCHAR inch ( )
NLSCHAR winch (win)
NLSCHAR mvinch (line, col)
NLSCHAR mvwinch (win, line, col)
The inch routine returns the NLSCHAR at the current (line, col)
coordinates on the specified window. No changes are made to the window.
Upon successful completion, the code for the character located at the
current cursor location is returned.
WINDOW *initscr ( )
The initscr routine performs screen initialization. initscr must be
called before any of the screen routines are used. It initializes the
terminal-type data, and without it, none of the Extended Curses routines
can operate properly.
If standard input is not a tty, initscr sets the specifications to the
terminal whose name is pointed to by Def_term (initially ""dumb""). If
the value of the bool global variable My_term is TRUE, Def_term is always
used.
If standard input is a terminal, the specifications for the terminal
named in the environment variable TERM are used. These specifications
are obtained from the terminfo description file for that terminal.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 23
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
The initscr routine creates the structures for stdscr and curscr and
saves the pointers to those structures in global variables with the
corresponding names.
Upon successful completion, a pointer to stdscr is returned.
insch (xc)
winsch (win, xc)
mvwinsch (win, line, col, xc)
mvinsch (line, col, xc)
The insch routine inserts the NLSCHAR specified by the xc parameter into
the window at the current (line, col) coordinates. Each character after
the inserted character shifts to the right and the last byte on the line
disappears.
If the current position is at the second column of a double display width
character, the position is moved left to the first byte of that character
before the specified NLSCHAR is inserted.
If a double display width character is inserted at the last column of the
window, nothing is done and ERR is returned; otherwise the insch routine
always returns the value OK.
insertln ( )
winsertln (win)
The insertln routine inserts a line above the current line. Each line
below the current line is shifted down, and the bottom line disappears.
The current line becomes blank and the current (line, col) coordinates
remain unchanged.
The insertln routine always returns the value OK.
keypad (boolf)
The keypad routine turns on and off the mapping of key sequences to
single integers. If the boolf parameter is TRUE, input processing is
turned on. If the boolf parameter is FALSE, input processing is turned
off. By default, input processing is initially turned off.
When turned on, sequences of characters from the terminal are translated
into integers that are defined in the cur02.h header file.
The codes available on a given terminal are determined by the terminfo
terminal description file.
The keypad routine always returns the value OK.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 24
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
leaveok (win, boolf)
The leaveok routine sets a flag, used by the window specified by the win
parameter, which controls where the cursor is placed after the window is
refreshed. If the boolf parameter is TRUE, when the window is refreshed,
the cursor is left at the last point where a change was made on the
terminal, and the current (line, col) coordinates for the window
specified by the win parameter are changed accordingly. If the (line,
col) coordinates are outside the window, the coordinates are forced to
(0, 0). If the boolf parameter is FALSE, when the window is refreshed,
the cursor is moved to the current (line, col) coordinates within the
window. The controlling flag is initially set to FALSE.
The leaveok routine always returns the value OK.
char *longname ( )
The longname routine returns a pointer to a static area that contains the
long (full) name of the terminal as it appears in the terminfo entry for
the terminal.
meta ( )
nometa ( )
The meta routine prevents the stripping of the eighth bit of each keyed
character.
The nometa routine causes the eighth or most-significant bit of each
keyed character to be stripped. Not all terminals support the stripping
of bits.
The meta and nometa routines always return the value OK.
move (line, col)
wmove (win, line, col)
The move routine changes the current (line, col) coordinates of the
window to the coordinates specified by the line and col parameters.
The move routine returns ERR if the destination for the cursor is outside
the window or viewport.
mvcur (line, col, newline, newcol)
int line, col, newline, newcol;
The mvcur routine moves the terminal's cursor from the coordinates
specified by the line and col parameters to the coordinates specified by
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 25
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
the newline and newcol parameters. The line and col parameters must
specify the current coordinates.
It is possible to use this optimization without the benefit of the screen
routines. In fact, mvcur should not be used with the screen routines.
Use move and refresh to move the cursor position and inform the screen
routines of the move.
mvwin (win, line, col)
The mvwin routine moves the position of the viewport or the subwindow
specified by the win parameter from its current starting coordinates to
the coordinates specified by the line and col parameters. The line
parameter specifies the row on the display for the top row of the window.
The col parameter specifies the column on the display for the first
column of the window.
The mvwin routine returns ERR if a part of the window position is outside
the bounds of the window on which the viewport is defined.
WINDOW *newview (win, numlines, numcols)
The newview routine creates a new window that has the number of lines
specified by the numlines parameter and the number of columns specified
by the numcols parameter. The new window is a viewport of the window
specified by the win parameter and starts at the current (line, col)
coordinates of the window specified by the win parameter. The resulting
window's initial position on the display is set to (0, 0).
The viewport window returned by newview is a special subwindow that is
suitable for viewport scrolling. Viewport scrolling here refers to the
type of scrolling that is characteristic of full-screen editors.
Because the returned viewport window is a subwindow, any change made in
either window in the area covered by the viewport window appears in both
windows. Both windows actually share the relevant storage area. A
viewport window cannot be scrolled using scroll.
Other than the exceptions noted above, viewport windows behave like
subwindows.
Upon successful completion, a pointer to the control structure for the
new viewport is returned.
The newview routine returns ERR if the window specified by the win
parameter is a subwindow or a viewport, or if sufficient storage is not
available for the new structures.
WINDOW *newwin (numlines, numcols, firstline, firstcol)
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 26
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
The newwin routine creates a new window that contains the number of lines
specified by the numlines parameter and the number of columns specified
by the numcols parameter. The new window starts at the coordinates
specified by the firstline and the firstcol parameters.
If the numlines parameter is 0, that dimension is set to (LINES -
firstline). If the numcols parameter is 0, that dimension is set to
(COLS - firstcol). Therefore, to get a new window of dimensions (LINES *
COLS), use:
newwin (0, 0, 0, 0)
The size specified for the window can exceed the size of the real
display. In this case, a viewport or subwindow must be used to present
the data from the window on the terminal.
Upon successful completion, a pointer to the new window structure is
returned.
The newwin routine returns ERR if any of the parameters are invalid, or
if there is insufficient storage available for the new structure.
nl ( )
nonl ( )
The nl routine sets the terminal to nl mode. When in nl mode, the system
maps "'\r'" (return characters) to "'\n'" (new-line or line-feed
characters). If the mapping is not done, refresh can do more
optimization. nonl turns nl mode off.
The nl routine and nonl do not affect the way in which waddch processes
new-line characters.
The nl and nonl routines always return the value OK.
nodelay (boolf)
The nodelay routine controls whether read requests wait for input if no
keystroke is available. If the boolf parameter is FALSE, then the read
routines wait for operator input. This is the default setting. If the
boolf parameter is TRUE, then the read routines return immediately if no
keyboard data is available.
If nodelay is set (TRUE) and if no keystroke is available from the
keyboard, then getch returns KEY_NOKEY, which is defined in the cur02.h
header file.
The nodelay routine always returns the value OK.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 27
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
overlay (win1, win2)
The overlay routine overlays the window specified by the win1 parameter
on the window specified by the win2 parameter. The contents of the
window specified by the win1 parameter, insofar as they fit, are placed
on the window specified by the win2 parameter at their starting (line,
col) coordinates. This is done nondestructively; that is, blanks on the
win1 window leave the contents of the space on the win2 window untouched.
The overlay routine moves data only if the data is nonblank or if the
display attribute is different.
The only data that is considered for moving from the win1 window to the
win2 window is data that occupies display positions that are common to
both windows.
The overlay routine is implemented as a macro that invokes overput, which
uses waddch to transfer the data from window to window.
The overlay routine returns ERR if an attempt is made to write to the
lower right corner of the display and scrollok is FALSE.
overwrite (win1, win2)
The overwrite routine copies data from the window specified by the win1
parameter to the window specified by the win2 parameter. The contents of
the win1 window, insofar as they fit, are placed on the win2 window at
their starting (line, col) coordinates. This is done destructively; that
is, blanks on the win1 window become blanks on the win2 window.
Only the data that occupies positions on the display that are common to
the two windows is moved from the win1 window to the win2 window.
The overwrite routine is implemented as a macro that invokes overput
which uses waddch to transfer the data from window to window.
The overwrite routine returns ERR if an attempt is made to write to the
lower right corner and scrollok is FALSE.
printw (fmt [, value,...])
wprintw (win, fmt [, value,...])
char *fmt;
The printw routine performs a printf on the window using the format
control string specified by the fmt parameter and the values specified by
the value parameters. The output to the window starts at the current
(line, col) coordinates. Use the field width options of printf to avoid
leaving things on the window from earlier calls. See "printf, fprintf,
sprintf, NLprintf, NLfprintf, NLsprintf, wsprintf" for details.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 28
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
The printw routine returns ERR if it causes the screen to scroll
illegally.
raw ( )
noraw ( )
The raw routine sets the terminal to raw mode. In raw mode, canonical
processing by the device driver and signal processing are turned off.
The noraw routine turns off raw mode.
The raw and noraw routines always return the value OK.
refresh ( )
wrefresh (win)
The refresh routine synchronizes the terminal screen with the window. If
the window is not a screen, then only the part of the display covered by
it is updated. refresh checks for possible scroll errors at display
time.
The refresh routine returns ERR if the change specified is in the last
position of a window that includes the lower right corner of the display,
or if it would cause the screen to scroll illegally. If it would cause
the screen to scroll illegally, refresh updates whatever can be updated
without causing the scroll.
resetty (boolf)
The resetty routine restores the terminal status flags that were
previously saved by savetty. If the boolf parameter is TRUE, then the
screen is cleared in addition to resetting the terminal. resetty is
performed automatically by endwin and is not normally called directly by
applications.
savetty ( )
The savetty routine saves the current terminal status flags. savetty is
performed automatically by initscr and is not normally called directly by
applications.
scanw (fmt [, pointer,...])
wscanw (win, fmt [, pointer,...])
char *fmt;
The scanw routine performs a scanf through the window using the format
control string specified by the fmt parameter. scanw uses wgetstr to
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 29
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
obtain the string, then invokes the internal routine for scanf to process
the data. See "scanf, fscanf, sscanf, NLscanf, NLfscanf, NLsscanf,
wsscanf" for details.
scroll (win)
The scroll routine moves the data in the window specified by the win
parameter up one line and inserts a new blank line at the bottom.
scrollok (win, boolf)
The scrollok routine sets the scroll flag for the window specified by the
win parameter. If the boolf parameter is TRUE, then scrolling is
allowed. The default setting is FALSE, which prevents scrolling.
sel_attr (set)
int *set;
The sel_attr routine allows you to change the selection and priority of
attributes for the run-time terminal. The set parameter points to a
null-terminated integer array that contains display attribute values from
the cur03.h header file in the order that you want them regardless of
whether or not they are available on the terminal.
Groups of attributes (colors and fonts) cannot be split in the array.
For instance, all foreground colors specified must be in adjacent
locations in the array.
The first element of a group of attributes must be the default color or
font of the terminal. For example, the first foreground color specified
is usually F_WHITE, and the first background color specified is usually
B_BLACK.
It is recommended that sel_attr only be called before initscr. If
sel_attr is called after initscr, then the routine setup_attr should be
called after calling sel_attr. If sel_attr is called after data has been
added to a window, the values in the associated attribute array for that
window may denote different attributes than the original attributes used
when displaying the data (except NORMAL which remains constant). A
subsequent refresh of the window shows the different attributes only if
the data has been modified or if a total refresh has been forced by a
previous call to touchwin.
The sel_attr routine always returns the value OK.
setterm (name)
char *name;
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 30
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
The setterm routine sets the terminal characteristics to be those of the
terminal specified by the name parameter. setterm is called by initscr
so you do not normally have to use it unless you wish to use just the
cursor motion optimizations.
setup_attr ()
The setup_attr routine creates the display attribute masks assigned to
the attribute variables declared in the cur01.h header file. The
priorities of the attributes determine how the masks are created.
This routine is called by initscr and is not normally called by
applications. This routine should only be called following a call to
sel_attr which follows a call to initscr.
standend ( )
wstandend (win)
The standend routine stops displaying characters in standout mode.
standout ( )
wstandout (win)
The standout routine starts displaying characters in standout mode. Any
characters added to the window are put in standout mode on the terminal
if the terminal has that capability. The first available attribute as
determined by sel_attr is used for standout. This is normally the
reverse attribute when the default display attribute priority is used.
The standout routine always returns the value OK.
WINDOW *subwin (win, numlines, numcols, firstline, firstcol)
The subwin routine creates a subwindow in the window pointed to by the
win parameter. The subwindow has the number of lines specified by the
numlines parameter and the number of columns specified by the numcols
parameter. The new subwindow starts at the coordinates specified by the
firstline and the firstcol parameters. Any change made to the window or
the subwindow in the area covered by the subwindow is made to both
windows.
The firstline and firstcol parameters are specified relative to the
overall screen, not to the relative (0, 0) of the window specified by the
win parameter.
If the numlines parameter is 0, then the lines dimension is set to
(LINES - firstline). If the numcols parameter is 0, then the column
dimension is set to (COLS - firstcol).
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 31
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
Upon successful completion, a pointer to the control structure for the
new subwindow is returned.
The subwin routine returns ERR if the window specified by the win
parameter already has a subwindow, or if there is insufficient storage
for the new control structure.
superbox (win, line, col, numlines, numcols, System V, hor, topl, topr,
botl, botr)
NLSCHAR System V, hor, topl, topr, botl, botr;
The superbox routine draws a box on the window specified by the win
parameter. The line and col parameters specify the starting coordinates
for the box. The numlines parameter specifies the depth of the box. The
numcols parameter specifies the width of the box. The System V parameter
specifies the NLSCHAR to use for vertical delimiting. The hor parameter
specifies the NLSCHAR to use for horizontal delimiting. The topl, topr,
botl, and botr parameters specify the NLSCHARs to use for the top left
corner, the top right corner, the bottom left corner, and the bottom
right corner, respectively.
If the window specified by the win parameter is a _SCROLLWIN window and
scrolling is not allowed, then the bottom right corner is not put on the
window.
The superbox routine uses addch to place the characters on the window.
The superbox routine returns ERR if the defined box is outside the
window, or an attempt is made to write to the lower right corner of the
display when scrollok is off.
touchwin (win)
The touchwin routine makes it appear as if every location on the window
specified by the win parameter has been changed. This is useful when
overlapping windows are to be refreshed. A subsequent refresh request
considers all portions of the window as potentially modified. If
touchwin is not used, then only those positions of the window that have
been addressed by an addch are inspected.
trackloc (boolf)
The trackloc routine turns on and off the tracking of the locator cursor
on the screen. If the boolf parameter is TRUE, then locator tracking is
turned on; if FALSE, then it is turned off. By default, locator tracking
is initially turned on.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 32
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
The keycode KEY_LOCESC is returned from getch when a locator report is
input. The locator report is stored in the global char array ESCSTR,
which is 128 bytes long.
Locator tracking is handled by the ecpnin routine.
tstp ( )
The tstp routine saves the current tty state and then put the process to
sleep. When the process is restarted, the tty state is restored and then
wrefresh (curscr) is called to redraw the screen. initscr sets the
signal SIGTSTP to trap tstp.
The tstp routine always returns the value OK.
#include <cur04.h>
char *unctrl (ch)
The unctrl routine returns a string that represents the value of the ch
parameter. Control characters become the lowercase equivalents preceded
by a "^" (circumflex). Other letters are unchanged. This function
supports only the P0 characters 0x00 through 0x7F.
Upon successful completion, a pointer to the string for the parameter
character is returned.
vscroll (win, numlines, numcols)
The vscroll routine scrolls the viewport specified by the win parameter
on the window.
The numlines parameter specifies the direction and amount to scroll up or
down. If the numlines parameter is positive, the viewport scrolls down
the number of lines specified. If the numlines parameter is negative,
the viewport scrolls up the number of lines specified.
The numcols parameter specifies the direction and amount to scroll left
or right. If the numcols parameter is positive, the viewport scrolls to
the right the number of characters specified. If the numcols parameter
is negative, then the viewport scrolls to the left the number of
characters specified.
The vscroll routine always scrolls as much of a requested scroll as
possible. Specifying a parameter with a magnitude larger than that of
the underlying window is not an error.
The vscroll routine calls touchwin if any scrolling is done.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 33
EXTENDED CURSES LIBRARY(3x,L) extended curses library(3x,L)
The vscroll routine returns ERR if the window specified by the win
parameter is not a window created by a call to newview.
FILE
/usr/lib/terminfo/?/* Compiled terminal capability data base.
RELATED INFORMATION
In this book: "curses" and "terminfo."
The discussion of Extended Curses in AIX Programming Tools and Interfaces.
"Introduction to International Character Support" in Managing the AIX Operating
System.
AIX Guide to Multibyte Character Set (MBCS) Support.
Processed Nov. 7, 1990 EXTENDED CURSES LIBRARY(3x,L) 34