From b73c2efb2114be81c9bace14b18fc768e475d05f Mon Sep 17 00:00:00 2001 From: William McBrine Date: Mon, 14 Jul 2008 12:22:13 +0000 Subject: [PATCH] Some more documentation cleanup. --- pdcurses/kernel.c | 63 ++++++++++++++++++++---------------------- pdcurses/outopts.c | 12 ++++---- pdcurses/overlay.c | 37 +++++++++++-------------- pdcurses/pad.c | 68 ++++++++++++++++++++-------------------------- pdcurses/scanw.c | 20 ++++---------- 5 files changed, 86 insertions(+), 114 deletions(-) diff --git a/pdcurses/kernel.c b/pdcurses/kernel.c index 3135f67d..e6f53967 100644 --- a/pdcurses/kernel.c +++ b/pdcurses/kernel.c @@ -2,7 +2,7 @@ #include -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) diff --git a/pdcurses/outopts.c b/pdcurses/outopts.c index a8fb8681..0a8fd2d5 100644 --- a/pdcurses/outopts.c +++ b/pdcurses/outopts.c @@ -2,7 +2,7 @@ #include -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. diff --git a/pdcurses/overlay.c b/pdcurses/overlay.c index db2a1e1e..f00458f9 100644 --- a/pdcurses/overlay.c +++ b/pdcurses/overlay.c @@ -2,7 +2,7 @@ #include -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. diff --git a/pdcurses/pad.c b/pdcurses/pad.c index a0376fa4..ccc5db20 100644 --- a/pdcurses/pad.c +++ b/pdcurses/pad.c @@ -2,7 +2,7 @@ #include -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. diff --git a/pdcurses/scanw.c b/pdcurses/scanw.c index 89d3b5d1..af2bcb9e 100644 --- a/pdcurses/scanw.c +++ b/pdcurses/scanw.c @@ -2,7 +2,7 @@ #include -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