VARCem/PDCurses
1
0
Fork 0
mirror of https://github.com/VARCem/PDCurses.git synced 2026-09-24 15:55:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Some more documentation cleanup.

Browse Source
This commit is contained in:
William McBrine
2008-07-14 12:22:13 +00:00
parent 2bd1949a76
commit b73c2efb21
5 changed files with 86 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
pdcurses/kernel.c
View File

@@ -2,7 +2,7 @@
#include <curspriv.h>
RCSID("$Id: kernel.c,v 1.76 2008/07/13 16:08:18 wmcbrine Exp $")
RCSID("$Id: kernel.c,v 1.77 2008/07/14 12:22:13 wmcbrine Exp $")
/*man-start**************************************************************
@@ -43,42 +43,35 @@ RCSID("$Id: kernel.c,v 1.76 2008/07/13 16:08:18 wmcbrine Exp $")
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.
getsyx() gets the coordinates of the virtual screen cursor, and
stores them in y and x. If leaveok() is TRUE, it returns -1, -1.
If lines have been removed with ripoffline(), then getsyx()
includes these lines in its count; so, the returned y and x
values should only be used with setsyx().
Note that getsyx() and setsyx() are defined as macros only.
setsyx() sets the virtual screen cursor to the y, x coordinates.
If y, x are -1, -1, leaveok() is set TRUE.
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).
getsyx() and setsyx() are meant to be used by a library routine
that manipulates curses windows without altering the position of
the cursor. Note that they're defined only as macros.
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.
curs_set() alters the appearance of the cursor. A visibility of
0 makes it disappear; 1 makes it appear "normal" (usually an
underline) and 2 makes it "highly visible" (usually a block).
The napms() function suspends the program for the specified
number of milliseconds. draino() is an archaic equivalent.
ripoffline() reduces the size of stdscr by one line. If the
"line" parameter is positive, the line is removed from the top
of the screen; if negative, from the bottom. Up to 5 lines can
be ripped off stdscr by calling ripoffline() repeatedly. The
function argument, init, is called from within initscr() or
newterm(), so ripoffline() must be called before either of these
functions. The init function receives a pointer to a one-line
WINDOW, and the width of the window. Calling ripoffline() with a
NULL init function pointer is an error.
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.
napms() suspends the program for the specified number of
milliseconds. draino() is an archaic equivalent.
resetterm(), fixterm() and saveterm() are archaic equivalents
for reset_shell_mode(), reset_prog_mode() and def_prog_mode(),
@@ -240,13 +233,15 @@ int ripoffline(int line, int (*init)(WINDOW *, int))
{
PDC_LOG(("ripoffline() - called: line=%d\n", line));
if (linesrippedoff < 5 && line)
if (linesrippedoff < 5 && line && init)
{
linesripped[(int)linesrippedoff].line = line;
linesripped[(int)linesrippedoff++].init = init;
return OK;
}
return OK;
return ERR;
}
int draino(int ms)

12
pdcurses/outopts.c
View File

@@ -2,7 +2,7 @@
#include <curspriv.h>
RCSID("$Id: outopts.c,v 1.38 2008/07/13 16:08:18 wmcbrine Exp $")
RCSID("$Id: outopts.c,v 1.39 2008/07/14 12:22:13 wmcbrine Exp $")
/*man-start**************************************************************
@@ -31,13 +31,13 @@ RCSID("$Id: outopts.c,v 1.38 2008/07/13 16:08:18 wmcbrine Exp $")
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
left wherever the update happens to leave it. It's 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.
wsetscrreg() sets a scrolling region in a window; 'top' and
'bot' are the line numbers for the top and bottom margins. If
wsetscrreg() sets a scrolling region in a window; "top" and
"bot" are the line numbers for the top and bottom margins. If
this option and scrollok() are enabled, any attempt to move off
the bottom margin will cause all lines in the scrolling region
to scroll up one line. setscrreg() is the stdscr version.
@@ -46,8 +46,8 @@ RCSID("$Id: outopts.c,v 1.38 2008/07/13 16:08:18 wmcbrine Exp $")
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).
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.

37
pdcurses/overlay.c
View File

@@ -2,7 +2,7 @@
#include <curspriv.h>
RCSID("$Id: overlay.c,v 1.34 2008/07/13 16:08:18 wmcbrine Exp $")
RCSID("$Id: overlay.c,v 1.35 2008/07/14 12:22:13 wmcbrine Exp $")
/*man-start**************************************************************
@@ -16,27 +16,22 @@ RCSID("$Id: overlay.c,v 1.34 2008/07/13 16:08:18 wmcbrine Exp $")
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).
overlay() and overwrite() copy all the text from src_w into
dst_w. The windows need not be the same size. Those characters
in the source window that intersect with the destination window
are copied, 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.
copywin() is similar, but doesn't require that the two windows
overlap. The arguments src_tc and src_tr specify the top left
corner of the region to be copied. dst_tc, dst_tr, dst_br, and
dst_bc specify the region within the destination window to copy
to. 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, blanks are copied.
Return Value:
All functions return OK on success and ERR on error.

68
pdcurses/pad.c
View File

@@ -2,7 +2,7 @@
#include <curspriv.h>
RCSID("$Id: pad.c,v 1.49 2008/07/13 16:08:18 wmcbrine Exp $")
RCSID("$Id: pad.c,v 1.50 2008/07/14 12:22:13 wmcbrine Exp $")
/*man-start**************************************************************
@@ -20,48 +20,38 @@ RCSID("$Id: pad.c,v 1.49 2008/07/13 16:08:18 wmcbrine Exp $")
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.
A pad is a special kind of window, which is not restricted by
the screen size, and is not necessarily associated with a
particular part of the screen. You can use a pad when you need
a large window, and only a part of the window will be on the
screen at one time. Pads are not refreshed automatically (e.g.,
from scrolling or echoing of input). You can't call wrefresh()
with a pad as an argument; use prefresh() or pnoutrefresh()
instead. Note that these routines require additional parameters
to specify the part of the pad to be displayed, and the location
to use on the screen.
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().
newpad() creates a new pad data structure.
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.
subpad() creates a new sub-pad within a pad, at position (begy,
begx), with dimensions of nlines lines and ncols columns. This
position is relative to the pad, and not to the screen as with
subwin. Changes to either the parent pad or sub-pad will affect
both. When using sub-pads, you may need to call touchwin()
before calling prefresh().
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.
pnoutrefresh() copies the specified pad to the virtual screen.
pechochar() is functionally equivalent to addch() followed by
a call to prefresh().
prefresh() calls pnoutrefresh(), followed by doupdate().
These routines are analogous to wnoutrefresh() and wrefresh().
(py, px) specifies the upper left corner of the part of the pad
to be displayed; (sy1, sx1) and (sy2, sx2) describe the screen
rectangle that will contain the selected part of the pad.
pechochar() is functionally equivalent to addch() followed by
a call to prefresh(), with the last-used coordinates and
dimensions. pecho_wchar() is the wide-character version.
Return Value:
All functions return OK on success and ERR on error.

20
pdcurses/scanw.c
View File

@@ -2,7 +2,7 @@
#include <curspriv.h>
RCSID("$Id: scanw.c,v 1.41 2008/07/13 16:08:18 wmcbrine Exp $")
RCSID("$Id: scanw.c,v 1.42 2008/07/14 12:22:13 wmcbrine Exp $")
/*man-start**************************************************************
@@ -17,21 +17,13 @@ RCSID("$Id: scanw.c,v 1.41 2008/07/13 16:08:18 wmcbrine Exp $")
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.
These routines correspond to the standard C library's scanf()
family. Each gets a string from the window via wgetnstr(), and
uses the resulting line as input for the scan.
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.
On successful completion, these functions return the number of
items successfully matched. Otherwise they return ERR.
Portability X/Open BSD SYS V
scanw Y Y Y