From 13fc5538718bbd3c718a96277b7ef3aedd8f7433 Mon Sep 17 00:00:00 2001 From: William McBrine Date: Wed, 5 Dec 2007 19:30:34 +0000 Subject: [PATCH] More documentation updates. --- pdcurses/getch.c | 10 +++---- pdcurses/getstr.c | 24 +++++++---------- pdcurses/initscr.c | 14 +++++----- pdcurses/inopts.c | 66 +++++++++++++++++++++------------------------- pdcurses/insstr.c | 21 ++++++++------- pdcurses/outopts.c | 23 +++++++--------- pdcurses/slk.c | 6 ++--- 7 files changed, 76 insertions(+), 88 deletions(-) diff --git a/pdcurses/getch.c b/pdcurses/getch.c index 91701b76..cd5cd289 100644 --- a/pdcurses/getch.c +++ b/pdcurses/getch.c @@ -13,7 +13,7 @@ #include -RCSID("$Id: getch.c,v 1.69 2007/12/03 02:27:04 wmcbrine Exp $") +RCSID("$Id: getch.c,v 1.70 2007/12/05 19:30:34 wmcbrine Exp $") /*man-start************************************************************** @@ -55,11 +55,11 @@ RCSID("$Id: getch.c,v 1.69 2007/12/03 02:27:04 wmcbrine Exp $") If nodelay(win, TRUE) has been called on the window and no input is waiting, the value ERR is returned. - The ungetch() function places ch back onto the input queue to be - returned by the next call to wgetch(). + ungetch() places ch back onto the input queue to be returned by + the next call to wgetch(). - The flushinp() routine throws away any type-ahead that has been - typed by the user and has not yet been read by the program. + flushinp() throws away any type-ahead that has been typed by the + user and has not yet been read by the program. PDC_get_key_modifiers() returns the keyboard modifiers (shift, control, alt, numlock) effective at the time of the last getch() diff --git a/pdcurses/getstr.c b/pdcurses/getstr.c index 3ee7847c..c79f11b6 100644 --- a/pdcurses/getstr.c +++ b/pdcurses/getstr.c @@ -13,7 +13,7 @@ #include -RCSID("$Id: getstr.c,v 1.47 2007/06/14 13:50:27 wmcbrine Exp $") +RCSID("$Id: getstr.c,v 1.48 2007/12/05 19:30:34 wmcbrine Exp $") /*man-start************************************************************** @@ -39,20 +39,16 @@ RCSID("$Id: getstr.c,v 1.47 2007/06/14 13:50:27 wmcbrine Exp $") int mvwgetn_wstr(WINDOW *win, int y, int x, wint_t *wstr, int n); Description: - The effect of getstr() is as though a series of calls to getch() - were made, until a newline or carriage return is received. The - resulting value is placed in the area pointed to by *str. The - erase and kill characters are interpreted, as well as any - special keys, such as function keys. + These routines call wgetch() repeatedly to build a string, + interpreting erase and kill characters along the way, until a + newline or carriage return is received. When PDCurses is built + with wide-character support enabled, the narrow-character + functions convert the wgetch()'d values into a multibyte string + in the current locale before returning it. The resulting string + is placed in the area pointed to by *str. The routines with n as + the last argument read at most n characters. - With wgetnstr(), a series of characters are read until a newline - or carriage return is received. The resulting value is placed - in the area pointed to by the character pointer str. The erase - and kill characters are interpreted. This differs from - wgetstr() in that the number of characters read is limited by a - passed argument. - - WARNING: There is no way to know how long the buffer passed to + Note that there's no way to know how long the buffer passed to wgetstr() is, so use wgetnstr() to avoid buffer overflows. Return Value: diff --git a/pdcurses/initscr.c b/pdcurses/initscr.c index 09b99eaa..a59c5627 100644 --- a/pdcurses/initscr.c +++ b/pdcurses/initscr.c @@ -13,7 +13,7 @@ #include -RCSID("$Id: initscr.c,v 1.111 2007/11/07 23:33:06 wmcbrine Exp $") +RCSID("$Id: initscr.c,v 1.112 2007/12/05 19:30:34 wmcbrine Exp $") /*man-start************************************************************** @@ -33,12 +33,12 @@ RCSID("$Id: initscr.c,v 1.111 2007/11/07 23:33:06 wmcbrine Exp $") const char *curses_version(void); Description: - initscr() should be the first curses routine called. This will - determine the terminal type and initialize all curses data - structures. initscr() also arranges that the first call to - refresh() will clear the screen. If errors occur, initscr() - will write a message to standard error and end the program. - + initscr() should be the first curses routine called. It will + initialize all curses data structures, and arrange that the + first call to refresh() will clear the screen. In case of + error, initscr() will write a message to standard error and end + the program. + endwin() should be called before exiting or escaping from curses mode temporarily. It will restore tty modes, move the cursor to the lower left corner of the screen and reset the terminal into diff --git a/pdcurses/inopts.c b/pdcurses/inopts.c index bf812a02..4f29d6c7 100644 --- a/pdcurses/inopts.c +++ b/pdcurses/inopts.c @@ -13,7 +13,7 @@ #include -RCSID("$Id: inopts.c,v 1.40 2007/06/14 13:50:27 wmcbrine Exp $") +RCSID("$Id: inopts.c,v 1.41 2007/12/05 19:30:34 wmcbrine Exp $") /*man-start************************************************************** @@ -44,14 +44,12 @@ RCSID("$Id: inopts.c,v 1.40 2007/06/14 13:50:27 wmcbrine Exp $") int nocrmode(void); Description: - cbreak() and nocbreak() put the terminal into and out of cbreak - mode. In cbreak mode, characters typed by the user are - immediately available to the program and erase/kill character - processing is not performed. When out of cbreak mode, the - terminal driver will buffer characters typed until a newline or - carriage return is typed. Interrupt and flow control characters - are unaffected by this mode. Initially the terminal may or may - not need be in cbreak mode. + cbreak() and nocbreak() toggle cbreak mode. In cbreak mode, + characters typed by the user are made available immediately, and + erase/kill character processing is not performed. In nocbreak + mode, typed characters are buffered until a newline or carriage + return. Interrupt and flow control characters are unaffected by + this mode. PDCurses always starts in cbreak mode. echo() and noecho() control whether typed characters are echoed by the input routine. Initially, input characters are echoed. @@ -62,39 +60,35 @@ RCSID("$Id: inopts.c,v 1.40 2007/06/14 13:50:27 wmcbrine Exp $") block for that period before returning ERR if no key has been received. tenths must be between 1 and 255. - The keypad() function changes the keypad option of the user's - terminal. If enabled (bf is TRUE), the user can press a function - key (such as the left arrow key) and getch() will return a - single value that represents the KEY_LEFT function key. - If disabled, nothing will be returned. + keypad() controls whether getch() returns function/special keys + as single key codes (e.g., the left arrow key as KEY_LEFT). Per + X/Open, the default for keypad mode is OFF. You'll probably want + it on. With keypad mode off, if a special key is pressed, + getch() does nothing or returns ERR. - The nodelay() function controls whether wgetch() is a - non-blocking call. If the option is enabled, and no input is - ready, wgetch() will return ERR. If disabled, wgetch() will hang - until input is ready. + nodelay() controls whether wgetch() is a non-blocking call. If + the option is enabled, and no input is ready, wgetch() will + return ERR. If disabled, wgetch() will hang until input is + ready. - The nl() function enables the translation of a carriage return - into a newline on input. The nonl() function disables it. - Initially, the translation does occur. + nl() enables the translation of a carriage return into a newline + on input. nonl() disables this. Initially, the translation does + occur. - With raw() and noraw(), the terminal in placed into or out of - raw mode. Raw mode is similar to cbreak mode, in that - characters typed are immediately passed through to the user - program. The differences are that in raw mode, the INTR, QUIT, - SUSP, and STOP characters are passed through without being - interpreted, and without generating a signal. The behaviour of - the BREAK key depends on other parameters of the terminal drive - that are not set by curses. + raw() and noraw() toggle raw mode. Raw mode is similar to cbreak + mode, in that characters typed are immediately passed through to + the user program. The difference is that in raw mode, the INTR, + QUIT, SUSP, and STOP characters are passed through without being + interpreted, and without generating a signal. In PDCurses, the meta() function sets raw mode on or off. - The timeout() and wtimeout() functions set blocking or - non-blocking reads for the specified window. The delay is - measured in milliseconds. If it's negative, a blocking read is - used; if zero, then non-blocking reads are done -- if no input - is waiting, ERR is returned immediately. If the delay is - positive, the read blocks for the delay period; if the period - expires, ERR is returned. + timeout() and wtimeout() set blocking or non-blocking reads for + the specified window. The delay is measured in milliseconds. If + it's negative, a blocking read is used; if zero, then non- + blocking reads are done -- if no input is waiting, ERR is + returned immediately. If the delay is positive, the read blocks + for the delay period; if the period expires, ERR is returned. intrflush(), notimeout(), noqiflush(), qiflush() and typeahead() do nothing in PDCurses, but are included for compatibility with diff --git a/pdcurses/insstr.c b/pdcurses/insstr.c index d09d42ea..3b86983f 100644 --- a/pdcurses/insstr.c +++ b/pdcurses/insstr.c @@ -13,7 +13,7 @@ #include -RCSID("$Id: insstr.c,v 1.43 2007/06/14 14:11:30 wmcbrine Exp $") +RCSID("$Id: insstr.c,v 1.44 2007/12/05 19:30:34 wmcbrine Exp $") /*man-start************************************************************** @@ -39,14 +39,17 @@ RCSID("$Id: insstr.c,v 1.43 2007/06/14 14:11:30 wmcbrine Exp $") int mvwins_nwstr(WINDOW *win, int y, int x, const wchar_t *wstr, int n); Description: - With these routines, a character string (as many characters as - will fit on the line) is inserted before the character under - the cursor. All characters to the right of the cursor are moved - to the right, with the possibility of the rightmost characters - on the line being lost. The cursor position does not change - (after moving to y, x, if specified). The routines with n as - the last argument insert at most n characters; if n is - negative, then the entire string is inserted. + The insstr() functions insert a character string into a window + at the current cursor position, by repeatedly calling winsch(). + When PDCurses is built with wide-character support enabled, the + narrow-character functions treat the string as a multibyte + string in the current locale, and convert it first. All + characters to the right of the cursor are moved to the right, + with the possibility of the rightmost characters on the line + being lost. The cursor position does not change (after moving + to y, x, if specified). The routines with n as the last + argument insert at most n characters; if n is negative, then the + entire string is inserted. Return Value: All functions return OK on success and ERR on error. diff --git a/pdcurses/outopts.c b/pdcurses/outopts.c index 99c288f8..d9544313 100644 --- a/pdcurses/outopts.c +++ b/pdcurses/outopts.c @@ -13,7 +13,7 @@ #include -RCSID("$Id: outopts.c,v 1.35 2007/06/14 13:50:27 wmcbrine Exp $") +RCSID("$Id: outopts.c,v 1.36 2007/12/05 19:30:34 wmcbrine Exp $") /*man-start************************************************************** @@ -36,11 +36,9 @@ RCSID("$Id: outopts.c,v 1.35 2007/06/14 13:50:27 wmcbrine Exp $") this window will clear the screen completely and redraw the entire screen. - The immedok() routine, called with a second argument of TRUE, - causes an automatic wrefrsh() to be called on the window every - time a change is made to that window, due to calls like; - waddch(), wclrtoeol(), etc... Not surprisingly, this causes a - severe performance overhead. + immedok(), called with a second argument of TRUE, causes an + automatic wrefresh() every time a change is made to the + specified window. Normally, the hardware cursor is left at the location of the window being refreshed. leaveok() allows the cursor to be @@ -49,14 +47,11 @@ RCSID("$Id: outopts.c,v 1.35 2007/06/14 13:50:27 wmcbrine Exp $") the need for cursor motions. If possible, the cursor is made invisible when this option is enabled. - The setscrreg() and wsetscrreg() functions allow the user to set - a software scrolling region in a window. The parameters 'top' - and 'bot' are the line numbers of the top and bottom margin of - the scrolling region. (Line 0 is the top line of the window.) - If this option and scrollok() are enabled, an attempt to move - off the bottom margin will cause all lines in the scrolling - region to scroll up one line. Only the text of the window is - scrolled. + 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. idlok() and idcok() do nothing in PDCurses, but are provided for compatibility with other curses implementations. diff --git a/pdcurses/slk.c b/pdcurses/slk.c index a0faed0a..4503bfe7 100644 --- a/pdcurses/slk.c +++ b/pdcurses/slk.c @@ -13,7 +13,7 @@ #include -RCSID("$Id: slk.c,v 1.57 2007/06/22 10:01:10 wmcbrine Exp $") +RCSID("$Id: slk.c,v 1.58 2007/12/05 19:30:34 wmcbrine Exp $") /*man-start************************************************************** @@ -63,8 +63,8 @@ RCSID("$Id: slk.c,v 1.57 2007/06/22 10:01:10 wmcbrine Exp $") 2 lines used 55 5-5 format (pdcurses format) - The functions slk_refresh(), slk_noutrefresh() and slk_touch() - are analagous to refresh(), noutrefresh() and touch() functions. + slk_refresh(), slk_noutrefresh() and slk_touch() are analogous + to refresh(), noutrefresh() and touch(). Return Value: All functions return OK on success and ERR on error.