diff --git a/man/MANUAL.md b/man/MANUAL.md index a93b3e70..b63fc240 100644 --- a/man/MANUAL.md +++ b/man/MANUAL.md @@ -73,85 +73,82 @@ addch ### Description addch() adds the chtype ch to the default window (stdscr) at the - current cursor position, and advances the cursor. Note that - chtypes can convey both text (a single character) and - attributes, including a color pair. add_wch() is the wide- - character version of this function, taking a pointer to a - cchar_t instead of a chtype. + current cursor position, and advances the cursor. Note that chtypes + can convey both text (a single character) and attributes, including a + color pair. add_wch() is the wide-character version of this function, + taking a pointer to a cchar_t instead of a chtype. - waddch() is like addch(), but also lets you specify the window. - (This is in fact the core output routine.) wadd_wch() is the - wide version. + waddch() is like addch(), but also lets you specify the window. (This + is in fact the core output routine.) wadd_wch() is the wide version. - mvaddch() moves the cursor to the specified (y, x) position, and - adds ch to stdscr. mvadd_wch() is the wide version. + mvaddch() moves the cursor to the specified (y, x) position, and adds + ch to stdscr. mvadd_wch() is the wide version. - mvwaddch() moves the cursor to the specified position and adds - ch to the specified window. mvwadd_wch() is the wide version. + mvwaddch() moves the cursor to the specified position and adds ch to + the specified window. mvwadd_wch() is the wide version. - echochar() adds ch to stdscr at the current cursor position and - calls refresh(). echo_wchar() is the wide version. + echochar() adds ch to stdscr at the current cursor position and calls + refresh(). echo_wchar() is the wide version. - wechochar() adds ch to the specified window and calls - wrefresh(). wecho_wchar() is the wide version. + wechochar() adds ch to the specified window and calls wrefresh(). + wecho_wchar() is the wide version. - addrawch(), waddrawch(), mvaddrawch() and mvwaddrawch() are - PDCurses-specific wrappers for addch() etc. that disable the - translation of control characters. + addrawch(), waddrawch(), mvaddrawch() and mvwaddrawch() are PDCurses- + specific wrappers for addch() etc. that disable the translation of + control characters. The following applies to all these functions: - If the cursor moves on to the right margin, an automatic newline - is performed. If scrollok is enabled, and a character is added - to the bottom right corner of the window, the scrolling region - will be scrolled up one line. If scrolling is not allowed, ERR - will be returned. + If the cursor moves on to the right margin, an automatic newline is + performed. If scrollok is enabled, and a character is added to the + bottom right corner of the window, the scrolling region will be + scrolled up one line. If scrolling is not allowed, ERR will be + returned. If ch is a tab, newline, or backspace, the cursor will be moved - appropriately within the window. If ch is a newline, the - clrtoeol routine is called before the cursor is moved to the - beginning of the next line. If newline mapping is off, the - cursor will be moved to the next line, but the x coordinate will - be unchanged. If ch is a tab the cursor is moved to the next - tab position within the window. If ch is another control - character, it will be drawn in the ^X notation. Calling the - inch() routine after adding a control character returns the - representation of the control character, not the control - character. + appropriately within the window. If ch is a newline, the clrtoeol + routine is called before the cursor is moved to the beginning of the + next line. If newline mapping is off, the cursor will be moved to + the next line, but the x coordinate will be unchanged. If ch is a + tab the cursor is moved to the next tab position within the window. + If ch is another control character, it will be drawn in the ^X + notation. Calling the inch() routine after adding a control + character returns the representation of the control character, not + the control character. - Video attributes can be combined with a character by ORing them - into the parameter. Text, including attributes, can be copied - from one place to another by using inch() and addch(). + Video attributes can be combined with a character by ORing them into + the parameter. Text, including attributes, can be copied from one + place to another by using inch() and addch(). - Note that in PDCurses, for now, a cchar_t and a chtype are the - same. The text field is 16 bits wide, and is treated as Unicode - (UCS-2) when PDCurses is built with wide-character support - (define PDC_WIDE). So, in functions that take a chtype, like - addch(), both the wide and narrow versions will handle Unicode. - But for portability, you should use the wide functions. + Note that in PDCurses, for now, a cchar_t and a chtype are the same. + The text field is 16 bits wide, and is treated as Unicode (UCS-2) + when PDCurses is built with wide-character support (define PDC_WIDE). + So, in functions that take a chtype, like addch(), both the wide and + narrow versions will handle Unicode. But for portability, you should + use the wide functions. ### Return Value All functions return OK on success and ERR on error. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD addch Y Y Y waddch Y Y Y mvaddch Y Y Y mvwaddch Y Y Y - echochar Y - 3.0 - wechochar Y - 3.0 + echochar Y Y Y + wechochar Y Y Y + add_wch Y Y Y + wadd_wch Y Y Y + mvadd_wch Y Y Y + mvwadd_wch Y Y Y + echo_wchar Y Y Y + wecho_wchar Y Y Y addrawch - - - waddrawch - - - mvaddrawch - - - mvwaddrawch - - - - add_wch Y - wadd_wch Y - mvadd_wch Y - mvwadd_wch Y - echo_wchar Y - wecho_wchar Y @@ -184,39 +181,38 @@ addchstr ### Description - These routines write a chtype or cchar_t string directly into - the window structure, starting at the current or specified - position. The four routines with n as the last argument copy at - most n elements, but no more than will fit on the line. If n = - -1 then the whole string is copied, up to the maximum number - that will fit on the line. + These routines write a chtype or cchar_t string directly into the + window structure, starting at the current or specified position. The + four routines with n as the last argument copy at most n elements, + but no more than will fit on the line. If n == -1 then the whole + string is copied, up to the maximum number that will fit on the line. - The cursor position is not advanced. These routines do not check - for newline or other special characters, nor does any line - wrapping occur. + The cursor position is not advanced. These routines do not check for + newline or other special characters, nor does any line wrapping + occur. ### Return Value All functions return OK or ERR. ### Portability - X/Open BSD SYS V - addchstr Y - 4.0 - waddchstr Y - 4.0 - mvaddchstr Y - 4.0 - mvwaddchstr Y - 4.0 - addchnstr Y - 4.0 - waddchnstr Y - 4.0 - mvaddchnstr Y - 4.0 - mvwaddchnstr Y - 4.0 - add_wchstr Y - wadd_wchstr Y - mvadd_wchstr Y - mvwadd_wchstr Y - add_wchnstr Y - wadd_wchnstr Y - mvadd_wchnstr Y - mvwadd_wchnstr Y + X/Open ncurses NetBSD + addchstr Y Y Y + waddchstr Y Y Y + mvaddchstr Y Y Y + mvwaddchstr Y Y Y + addchnstr Y Y Y + waddchnstr Y Y Y + mvaddchnstr Y Y Y + mvwaddchnstr Y Y Y + add_wchstr Y Y Y + wadd_wchstr Y Y Y + mvadd_wchstr Y Y Y + mvwadd_wchstr Y Y Y + add_wchnstr Y Y Y + wadd_wchnstr Y Y Y + mvadd_wchnstr Y Y Y + mvwadd_wchnstr Y Y Y @@ -248,38 +244,37 @@ addstr ### Description - These routines write all the characters of the null-terminated - string str or wide-character string wstr to the given window. - The functionality is similar to calling waddch() once for each - character in the string; except that, 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. The routines with n as the last - argument write at most n characters; if n is negative, then the - entire string will be added. + These routines write all the characters of the null-terminated string + str or wide-character string wstr to the given window. The + functionality is similar to calling waddch() once for each character + in the string; except that, 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. + The routines with n as the last argument write at most n characters; + if n is negative, then the entire string will be added. ### Return Value All functions return OK or ERR. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD addstr Y Y Y waddstr Y Y Y mvaddstr Y Y Y mvwaddstr Y Y Y - addnstr Y - 4.0 - waddnstr Y - 4.0 - mvaddnstr Y - 4.0 - mvwaddnstr Y - 4.0 - addwstr Y - waddwstr Y - mvaddwstr Y - mvwaddwstr Y - addnwstr Y - waddnwstr Y - mvaddnwstr Y - mvwaddnwstr Y + addnstr Y Y Y + waddnstr Y Y Y + mvaddnstr Y Y Y + mvwaddnstr Y Y Y + addwstr Y Y Y + waddwstr Y Y Y + mvaddwstr Y Y Y + mvwaddwstr Y Y Y + addnwstr Y Y Y + waddnwstr Y Y Y + mvaddnwstr Y Y Y + mvwaddnwstr Y Y Y @@ -326,6 +321,11 @@ attr chtype getattrs(WINDOW *win); + int underend(void); + int wunderend(WINDOW *win); + int underscore(void); + int wunderscore(WINDOW *win); + ### Description These functions manipulate the current attributes and/or colors of @@ -365,12 +365,15 @@ attr change to the edge of the window. The changes take effect immediately. opts is unused. + wunderscore() turns on the A_UNDERLINE attribute; wunderend() turns + it off. underscore() and underend() are the stdscr versions. + ### Return Value All functions return OK on success and ERR on error. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD attroff Y Y Y wattroff Y Y Y attron Y Y Y @@ -381,21 +384,25 @@ attr wstandend Y Y Y standout Y Y Y wstandout Y Y Y - color_set Y - wcolor_set Y - attr_get Y - wattr_get Y - attr_on Y - wattr_on Y - attr_off Y - wattr_off Y - attr_set Y - wattr_set Y - chgat Y - wchgat Y - mvchgat Y - mvwchgat Y - getattrs - + color_set Y Y Y + wcolor_set Y Y Y + attr_get Y Y Y + wattr_get Y Y Y + attr_on Y Y Y + wattr_on Y Y Y + attr_off Y Y Y + wattr_off Y Y Y + attr_set Y Y Y + wattr_set Y Y Y + chgat Y Y Y + wchgat Y Y Y + mvchgat Y Y Y + mvwchgat Y Y Y + getattrs - Y Y + underend - - Y + wunderend - - Y + underscore - - Y + wunderscore - - Y @@ -412,19 +419,19 @@ beep ### Description - beep() sounds the audible bell on the terminal, if possible; - if not, it calls flash(). + beep() sounds the audible bell on the terminal, if possible; if not, + it calls flash(). flash() "flashes" the screen, by inverting the foreground and - background of every cell, pausing, and then restoring the - original attributes. + background of every cell, pausing, and then restoring the original + attributes. ### Return Value These functions return OK. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD beep Y Y Y flash Y Y Y @@ -477,18 +484,18 @@ bkgd case they return ERR. ### Portability - X/Open BSD SYS V - bkgd Y - 4.0 - bkgdset Y - 4.0 - getbkgd Y - wbkgd Y - 4.0 - wbkgdset Y - 4.0 - bkgrnd Y - bkgrndset Y - getbkgrnd Y - wbkgrnd Y - wbkgrndset Y - wgetbkgrnd Y + X/Open ncurses NetBSD + bkgd Y Y Y + bkgdset Y Y Y + getbkgd Y Y Y + wbkgd Y Y Y + wbkgdset Y Y Y + bkgrnd Y Y Y + bkgrndset Y Y Y + getbkgrnd Y Y Y + wbkgrnd Y Y Y + wbkgrndset Y Y Y + wgetbkgrnd Y Y Y @@ -565,29 +572,29 @@ border These functions return OK on success and ERR on error. ### Portability - X/Open BSD SYS V - border Y - 4.0 - wborder Y - 4.0 + X/Open ncurses NetBSD + border Y Y Y + wborder Y Y Y box Y Y Y - hline Y - 4.0 - vline Y - 4.0 - whline Y - 4.0 - wvline Y - 4.0 - mvhline Y - mvvline Y - mvwhline Y - mvwvline Y - border_set Y - wborder_set Y - box_set Y - hline_set Y - vline_set Y - whline_set Y - wvline_set Y - mvhline_set Y - mvvline_set Y - mvwhline_set Y - mvwvline_set Y + hline Y Y Y + vline Y Y Y + whline Y Y Y + wvline Y Y Y + mvhline Y Y Y + mvvline Y Y Y + mvwhline Y Y Y + mvwvline Y Y Y + border_set Y Y Y + wborder_set Y Y Y + box_set Y Y Y + hline_set Y Y Y + vline_set Y Y Y + whline_set Y Y Y + wvline_set Y Y Y + mvhline_set Y Y Y + mvvline_set Y Y Y + mvwhline_set Y Y Y + mvwvline_set Y Y Y @@ -613,22 +620,22 @@ clear erase() and werase() copy blanks (i.e. the background chtype) to every cell of the window. - clear() and wclear() are similar to erase() and werase(), but - they also call clearok() to ensure that the the window is - cleared on the next wrefresh(). + clear() and wclear() are similar to erase() and werase(), but they + also call clearok() to ensure that the the window is cleared on the + next wrefresh(). - clrtobot() and wclrtobot() clear the window from the current - cursor position to the end of the window. + clrtobot() and wclrtobot() clear the window from the current cursor + position to the end of the window. - clrtoeol() and wclrtoeol() clear the window from the current - cursor position to the end of the current line. + clrtoeol() and wclrtoeol() clear the window from the current cursor + position to the end of the current line. ### Return Value All functions return OK on success and ERR on error. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD clear Y Y Y wclear Y Y Y erase Y Y Y @@ -672,25 +679,23 @@ color has_colors() reports whether the terminal supports color. start_color() initializes eight basic colors (black, red, green, - yellow, blue, magenta, cyan, and white), and two global - variables: COLORS and COLOR_PAIRS (respectively defining the - maximum number of colors and color-pairs the terminal is capable - of displaying). + yellow, blue, magenta, cyan, and white), and two global variables: + COLORS and COLOR_PAIRS (respectively defining the maximum number of + colors and color-pairs the terminal is capable of displaying). - init_pair() changes the definition of a color-pair. It takes - three arguments: the number of the color-pair to be redefined, - and the new values of the foreground and background colors. The - pair number must be between 0 and COLOR_PAIRS - 1, inclusive. - The foreground and background must be between 0 and COLORS - 1, - inclusive. If the color pair was previously initialized, the - screen is refreshed, and all occurrences of that color-pair are - changed to the new definition. + init_pair() changes the definition of a color-pair. It takes three + arguments: the number of the color-pair to be redefined, and the new + values of the foreground and background colors. The pair number must + be between 0 and COLOR_PAIRS - 1, inclusive. The foreground and + background must be between 0 and COLORS - 1, inclusive. If the color + pair was previously initialized, the screen is refreshed, and all + occurrences of that color-pair are changed to the new definition. - pair_content() is used to determine what the colors of a given - color-pair consist of. + pair_content() is used to determine what the colors of a given color- + pair consist of. - can_change_color() indicates if the terminal has the capability - to change the definition of its colors. + can_change_color() indicates if the terminal has the capability to + change the definition of its colors. init_color() is used to redefine a color, if possible. Each of the components -- red, green, and blue -- is specified in a range from 0 @@ -699,21 +704,20 @@ color color_content() reports the current definition of a color in the same format as used by init_color(). - assume_default_colors() and use_default_colors() emulate the - ncurses extensions of the same names. assume_default_colors(f, - b) is essentially the same as init_pair(0, f, b) (which isn't - allowed); it redefines the default colors. use_default_colors() - allows the use of -1 as a foreground or background color with - init_pair(), and calls assume_default_colors(-1, -1); -1 - represents the foreground or background color that the terminal - had at startup. If the environment variable PDC_ORIGINAL_COLORS - is set at the time start_color() is called, that's equivalent to - calling use_default_colors(). + assume_default_colors() and use_default_colors() emulate the ncurses + extensions of the same names. assume_default_colors(f, b) is + essentially the same as init_pair(0, f, b) (which isn't allowed); it + redefines the default colors. use_default_colors() allows the use of + -1 as a foreground or background color with init_pair(), and calls + assume_default_colors(-1, -1); -1 represents the foreground or + background color that the terminal had at startup. If the environment + variable PDC_ORIGINAL_COLORS is set at the time start_color() is + called, that's equivalent to calling use_default_colors(). PDC_set_line_color() is used to set the color, globally, for the - color of the lines drawn for the attributes: A_UNDERLINE, A_LEFT - and A_RIGHT. A value of -1 (the default) indicates that the - current foreground color should be used. + color of the lines drawn for the attributes: A_UNDERLINE, A_LEFT and + A_RIGHT. A value of -1 (the default) indicates that the current + foreground color should be used. NOTE: COLOR_PAIR() and PAIR_NUMBER() are implemented as macros. @@ -723,16 +727,16 @@ color has_colors() and can_change_colors(), which return TRUE or FALSE. ### Portability - X/Open BSD SYS V - has_colors Y - 3.2 - start_color Y - 3.2 - init_pair Y - 3.2 - pair_content Y - 3.2 - can_change_color Y - 3.2 - init_color Y - 3.2 - color_content Y - 3.2 - assume_default_colors - - - - use_default_colors - - - + X/Open ncurses NetBSD + has_colors Y Y Y + start_color Y Y Y + init_pair Y Y Y + pair_content Y Y Y + can_change_color Y Y Y + init_color Y Y Y + color_content Y Y Y + assume_default_colors - Y Y + use_default_colors - Y Y PDC_set_line_color - - - @@ -755,16 +759,15 @@ debug information to the file "trace". Although not standard, similar functions are in some other curses implementations. - PDC_debug() is the function that writes to the file, based on - whether traceon() has been called. It's used from the PDC_LOG() - macro. + PDC_debug() is the function that writes to the file, based on whether + traceon() has been called. It's used from the PDC_LOG() macro. - The environment variable PDC_TRACE_FLUSH controls whether the - trace file contents are fflushed after each write. The default - is not. Set it to enable this (may affect performance). + The environment variable PDC_TRACE_FLUSH controls whether the trace + file contents are fflushed after each write. The default is not. Set + it to enable this (may affect performance). ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD traceon - - - traceoff - - - PDC_debug - - - @@ -786,18 +789,18 @@ delch ### Description - The character under the cursor in the window is deleted. All - characters to the right on the same line are moved to the left - one position and the last character on the line is filled with - a blank. The cursor position does not change (after moving to - y, x if coordinates are specified). + The character under the cursor in the window is deleted. All + characters to the right on the same line are moved to the left one + position and the last character on the line is filled with a blank. + The cursor position does not change (after moving to y, x if + coordinates are specified). ### Return Value All functions return OK on success and ERR on error. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD delch Y Y Y wdelch Y Y Y mvdelch Y Y Y @@ -827,29 +830,29 @@ deleteln ### Description - With the deleteln() and wdeleteln() functions, the line under - the cursor in the window is deleted. All lines below the - current line are moved up one line. The bottom line of the - window is cleared. The cursor position does not change. + With the deleteln() and wdeleteln() functions, the line under the + cursor in the window is deleted. All lines below the current line are + moved up one line. The bottom line of the window is cleared. The + cursor position does not change. With the insertln() and winsertn() functions, a blank line is inserted above the current line and the bottom line is lost. - mvdeleteln(), mvwdeleteln(), mvinsertln() and mvwinsertln() - allow moving the cursor and inserting/deleting in one call. + mvdeleteln(), mvwdeleteln(), mvinsertln() and mvwinsertln() allow + moving the cursor and inserting/deleting in one call. ### Return Value All functions return OK on success and ERR on error. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD deleteln Y Y Y wdeleteln Y Y Y mvdeleteln - - - mvwdeleteln - - - - insdelln Y - 4.0 - winsdelln Y - 4.0 + insdelln Y Y Y + winsdelln Y Y Y insertln Y Y Y winsertln Y Y Y mvinsertln - - - @@ -884,28 +887,28 @@ getch ### Description - With the getch(), wgetch(), mvgetch(), and mvwgetch() functions, - a character is read from the terminal associated with the window. - In nodelay mode, if there is no input waiting, the value ERR is + With the getch(), wgetch(), mvgetch(), and mvwgetch() functions, a + character is read from the terminal associated with the window. In + nodelay mode, if there is no input waiting, the value ERR is returned. In delay mode, the program will hang until the system passes text through to the program. Depending on the setting of cbreak(), this will be after one character or after the first - newline. Unless noecho() has been set, the character will also - be echoed into the designated window. + newline. Unless noecho() has been set, the character will also be + echoed into the designated window. If keypad() is TRUE, and a function key is pressed, the token for that function key will be returned instead of the raw characters. Possible function keys are defined in with integers beginning with 0401, whose names begin with KEY_. - If nodelay(win, TRUE) has been called on the window and no input - is waiting, the value ERR is returned. + If nodelay(win, TRUE) has been called on the window and no input is + waiting, the value ERR is returned. - ungetch() 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(). - flushinp() 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. wget_wch() is the wide-character version of wgetch(), available when PDCurses is built with the PDC_WIDE option. It takes a pointer to a @@ -920,9 +923,9 @@ getch control, alt, numlock) effective at the time of the last getch() call, if PDC_save_key_modifiers(TRUE) has been called before the getch(). Use the macros PDC_KEY_MODIFIER_* to determine which - modifier(s) were set. PDC_return_key_modifiers() tells getch() - to return modifier keys pressed alone as keystrokes (KEY_ALT_L, - etc.). These may not work on all platforms. + modifier(s) were set. PDC_return_key_modifiers() tells getch() to + return modifier keys pressed alone as keystrokes (KEY_ALT_L, etc.). + These may not work on all platforms. NOTE: getch() and ungetch() are implemented as macros, to avoid conflict with many DOS compiler's runtime libraries. @@ -933,18 +936,18 @@ getch character or function key token. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD getch Y Y Y wgetch Y Y Y mvgetch Y Y Y mvwgetch Y Y Y ungetch Y Y Y flushinp Y Y Y - get_wch Y - wget_wch Y - mvget_wch Y - mvwget_wch Y - unget_wch Y + get_wch Y Y Y + wget_wch Y Y Y + mvget_wch Y Y Y + mvwget_wch Y Y Y + unget_wch Y Y Y PDC_get_key_modifiers - - - @@ -978,40 +981,39 @@ getstr ### Description 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. + 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. 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 - These functions return ERR on failure or any other value on - success. + These functions return ERR on failure or any other value on success. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD getstr Y Y Y wgetstr Y Y Y mvgetstr Y Y Y mvwgetstr Y Y Y - getnstr Y - 4.0 - wgetnstr Y - 4.0 - mvgetnstr Y - - - mvwgetnstr Y - - - get_wstr Y - wget_wstr Y - mvget_wstr Y - mvwget_wstr Y - getn_wstr Y - wgetn_wstr Y - mvgetn_wstr Y - mvwgetn_wstr Y + getnstr Y Y Y + wgetnstr Y Y Y + mvgetnstr Y Y Y + mvwgetnstr Y Y Y + get_wstr Y Y Y + wget_wstr Y Y Y + mvget_wstr Y Y Y + mvwget_wstr Y Y Y + getn_wstr Y Y Y + wgetn_wstr Y Y Y + mvgetn_wstr Y Y Y + mvwgetn_wstr Y Y Y @@ -1042,47 +1044,47 @@ getyx ### Description - The getyx() macro (defined in curses.h -- the prototypes here - are merely illustrative) puts the current cursor position of the - specified window into y and x. getbegyx() and getmaxyx() return - the starting coordinates and size of the specified window, - respectively. getparyx() returns the starting coordinates of the - parent's window, if the specified window is a subwindow; - otherwise it sets y and x to -1. These are all macros. + The getyx() macro (defined in curses.h -- the prototypes here are + merely illustrative) puts the current cursor position of the + specified window into y and x. getbegyx() and getmaxyx() return the + starting coordinates and size of the specified window, respectively. + getparyx() returns the starting coordinates of the parent's window, + if the specified window is a subwindow; otherwise it sets y and x to + -1. These are all macros. 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(). + 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(). - setsyx() sets the virtual screen cursor to the y, x coordinates. - If either y or x is -1, leaveok() is set TRUE, else it's set FALSE. + setsyx() sets the virtual screen cursor to the y, x coordinates. If + either y or x is -1, leaveok() is set TRUE, else it's set FALSE. - 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 getsyx() is defined only as a macro. + 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 getsyx() is defined only as a macro. - getbegy(), getbegx(), getcurx(), getcury(), getmaxy(), - getmaxx(), getpary(), and getparx() return the appropriate - coordinate or size values, or ERR in the case of a NULL window. + getbegy(), getbegx(), getcurx(), getcury(), getmaxy(), getmaxx(), + getpary(), and getparx() return the appropriate coordinate or size + values, or ERR in the case of a NULL window. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD getyx Y Y Y - getparyx - - 4.0 - getbegyx - - 3.0 - getmaxyx - - 3.0 - getsyx - - 3.0 - setsyx - - 3.0 - getbegy - - - - getbegx - - - - getcury - - - - getcurx - - - - getpary - - - - getparx - - - - getmaxy - - - - getmaxx - - - + getparyx Y Y Y + getbegyx Y Y Y + getmaxyx Y Y Y + getsyx - Y Y + setsyx - Y Y + getbegy - Y Y + getbegx - Y Y + getcury - Y Y + getcurx - Y Y + getpary - Y Y + getparx - Y Y + getmaxy - Y Y + getmaxx - Y Y @@ -1106,26 +1108,25 @@ inch ### Description - The inch() functions retrieve the character and attribute from - the current or specified window position, in the form of a - chtype. If a NULL window is specified, (chtype)ERR is returned. + The inch() functions retrieve the character and attribute from the + current or specified window position, in the form of a chtype. If a + NULL window is specified, (chtype)ERR is returned. - The in_wch() functions are the wide-character versions; instead - of returning a chtype, they store a cchar_t at the address - specified by wcval, and return OK or ERR. (No value is stored - when ERR is returned.) Note that in PDCurses, chtype and cchar_t - are the same. + The in_wch() functions are the wide-character versions; instead of + returning a chtype, they store a cchar_t at the address specified by + wcval, and return OK or ERR. (No value is stored when ERR is + returned.) Note that in PDCurses, chtype and cchar_t are the same. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD inch Y Y Y winch Y Y Y mvinch Y Y Y mvwinch Y Y Y - in_wch Y - win_wch Y - mvin_wch Y - mvwin_wch Y + in_wch Y Y Y + win_wch Y Y Y + mvin_wch Y Y Y + mvwin_wch Y Y Y @@ -1163,27 +1164,26 @@ inchstr ### Return Value - All functions return the number of elements read, or ERR on - error. + All functions return the number of elements read, or ERR on error. ### Portability - X/Open BSD SYS V - inchstr Y - 4.0 - winchstr Y - 4.0 - mvinchstr Y - 4.0 - mvwinchstr Y - 4.0 - inchnstr Y - 4.0 - winchnstr Y - 4.0 - mvinchnstr Y - 4.0 - mvwinchnstr Y - 4.0 - in_wchstr Y - win_wchstr Y - mvin_wchstr Y - mvwin_wchstr Y - in_wchnstr Y - win_wchnstr Y - mvin_wchnstr Y - mvwin_wchnstr Y + X/Open ncurses NetBSD + inchstr Y Y Y + winchstr Y Y Y + mvinchstr Y Y Y + mvwinchstr Y Y Y + inchnstr Y Y Y + winchnstr Y Y Y + mvinchnstr Y Y Y + mvwinchnstr Y Y Y + in_wchstr Y Y Y + win_wchstr Y Y Y + mvin_wchstr Y Y Y + mvwin_wchstr Y Y Y + in_wchnstr Y Y Y + win_wchnstr Y Y Y + mvin_wchnstr Y Y Y + mvwin_wchnstr Y Y Y @@ -1208,19 +1208,20 @@ initscr const char *curses_version(void); void PDC_get_version(PDC_VERSION *ver); + int set_tabsize(int tabsize); + ### Description - 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. + 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 - the proper non-visual mode. To resume curses after a temporary - escape, call refresh() or doupdate(). + 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 the proper + non-visual mode. To resume curses after a temporary escape, call + refresh() or doupdate(). isendwin() returns TRUE if endwin() has been called without a subsequent refresh, unless SP is NULL. @@ -1229,55 +1230,56 @@ initscr multiple terminals. Here, it's just an alternative interface for initscr(). It always returns SP, or NULL. - delscreen() frees the memory allocated by newterm() or - initscr(), since it's not freed by endwin(). This function is - usually not needed. In PDCurses, the parameter must be the - value of SP, and delscreen() sets SP to NULL. + delscreen() frees the memory allocated by newterm() or initscr(), + since it's not freed by endwin(). This function is usually not + needed. In PDCurses, the parameter must be the value of SP, and + delscreen() sets SP to NULL. - set_term() does nothing meaningful in PDCurses, but is included - for compatibility with other curses implementations. + set_term() does nothing meaningful in PDCurses, but is included for + compatibility with other curses implementations. - resize_term() is effectively two functions: When called with - nonzero values for nlines and ncols, it attempts to resize the - screen to the given size. When called with (0, 0), it merely - adjusts the internal structures to match the current size after - the screen is resized by the user. On the currently supported - platforms, SDL, Windows console, and X11 allow user resizing, while - DOS, OS/2, SDL and Windows console allow programmatic resizing. If - you want to support user resizing, you should check for getch() - returning KEY_RESIZE, and/or call is_termresized() at appropriate - times; if either condition occurs, call resize_term(0, 0). Then, with - either user or programmatic resizing, you'll have to resize any - windows you've created, as appropriate; resize_term() only - handles stdscr and curscr. + resize_term() is effectively two functions: When called with nonzero + values for nlines and ncols, it attempts to resize the screen to the + given size. When called with (0, 0), it merely adjusts the internal + structures to match the current size after the screen is resized by + the user. On the currently supported platforms, SDL, Windows console, + and X11 allow user resizing, while DOS, OS/2, SDL and Windows console + allow programmatic resizing. If you want to support user resizing, + you should check for getch() returning KEY_RESIZE, and/or call + is_termresized() at appropriate times; if either condition occurs, + call resize_term(0, 0). Then, with either user or programmatic + resizing, you'll have to resize any windows you've created, as + appropriate; resize_term() only handles stdscr and curscr. - is_termresized() returns TRUE if the curses screen has been - resized by the user, and a call to resize_term() is needed. - Checking for KEY_RESIZE is generally preferable, unless you're - not handling the keyboard. + is_termresized() returns TRUE if the curses screen has been resized + by the user, and a call to resize_term() is needed. Checking for + KEY_RESIZE is generally preferable, unless you're not handling the + keyboard. - curses_version() returns a string describing the version of - PDCurses. + curses_version() returns a string describing the version of PDCurses. PDC_get_version() fills a PDC_VERSION structure provided by the user with more detailed version info (see curses.h). + set_tabsize() sets the tab interval, stored in TABSIZE. + ### Return Value All functions return NULL on error, except endwin(), which always returns OK, and resize_term(), which returns either OK or ERR. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD initscr Y Y Y endwin Y Y Y - isendwin Y - 3.0 - newterm Y - Y - set_term Y - Y - delscreen Y - 4.0 - resize_term - - - + isendwin Y Y Y + newterm Y Y Y + set_term Y Y Y + delscreen Y Y Y + resize_term - Y Y + set_tabsize - Y Y + curses_version - Y - is_termresized - - - - curses_version - - - @@ -1312,88 +1314,92 @@ inopts int crmode(void); int nocrmode(void); + bool is_keypad(const WINDOW *win); + ### Description 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. + 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. - Subsequent calls to echo() and noecho() do not flush type-ahead. + echo() and noecho() control whether typed characters are echoed by + the input routine. Initially, input characters are echoed. Subsequent + calls to echo() and noecho() do not flush type-ahead. - halfdelay() is similar to cbreak(), but allows for a time limit - to be specified, in tenths of a second. This causes getch() to - block for that period before returning ERR if no key has been - received. tenths must be between 1 and 255. + halfdelay() is similar to cbreak(), but allows for a time limit to be + specified, in tenths of a second. This causes getch() to block for + that period before returning ERR if no key has been received. tenths + must be between 1 and 255. - 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. + 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. - 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. + 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. - nl() enables the translation of a carriage return into a newline - on input. nonl() disables this. 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. 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 + 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. - 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. + 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 - other curses implementations. + intrflush(), notimeout(), noqiflush(), qiflush() and typeahead() do + nothing in PDCurses, but are included for compatibility with other + curses implementations. crmode() and nocrmode() are archaic equivalents to cbreak() and nocbreak(), respectively. + is_keypad() reports whether the specified window is in keypad mode. + ### Return Value - All functions return OK on success and ERR on error. + All functions except is_keypad() and the void functions return OK on + success and ERR on error. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD cbreak Y Y Y nocbreak Y Y Y echo Y Y Y noecho Y Y Y - halfdelay Y - Y - intrflush Y - Y - keypad Y - Y - meta Y - Y + halfdelay Y Y Y + intrflush Y Y Y + keypad Y Y Y + meta Y Y Y nl Y Y Y nonl Y Y Y - nodelay Y - Y - notimeout Y - Y + nodelay Y Y Y + notimeout Y Y Y raw Y Y Y noraw Y Y Y - noqiflush Y - Y - qiflush Y - Y - timeout Y - Y - wtimeout Y - Y - typeahead Y - Y - crmode - - nocrmode - + noqiflush Y Y Y + qiflush Y Y Y + timeout Y Y Y + wtimeout Y Y Y + typeahead Y Y Y + crmode Y Y Y + nocrmode Y Y Y + is_keypad - Y Y @@ -1422,38 +1428,37 @@ insch ### Description - The insch() functions insert a chtype into the window at the - current or specified cursor position. The cursor is NOT - advanced. A newline is equivalent to clrtoeol(); tabs are - expanded; other control characters are converted as with - unctrl(). + The insch() functions insert a chtype into the window at the current + or specified cursor position. The cursor is NOT advanced. A newline + is equivalent to clrtoeol(); tabs are expanded; other control + characters are converted as with unctrl(). - The ins_wch() functions are the wide-character - equivalents, taking cchar_t pointers rather than chtypes. + The ins_wch() functions are the wide-character equivalents, taking + cchar_t pointers rather than chtypes. - Video attributes can be combined with a character by ORing - them into the parameter. Text, including attributes, can be - copied from one place to another using inch() and insch(). + Video attributes can be combined with a character by ORing them into + the parameter. Text, including attributes, can be copied from one + place to another using inch() and insch(). - insrawch() etc. are PDCurses-specific wrappers for insch() etc. - that disable the translation of control characters. + insrawch() etc. are PDCurses-specific wrappers for insch() etc. that + disable the translation of control characters. ### Return Value All functions return OK on success and ERR on error. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD insch Y Y Y winsch Y Y Y mvinsch Y Y Y mvwinsch Y Y Y + ins_wch Y Y Y + wins_wch Y Y Y + mvins_wch Y Y Y + mvwins_wch Y Y Y insrawch - - - winsrawch - - - - ins_wch Y - wins_wch Y - mvins_wch Y - mvwins_wch Y @@ -1485,40 +1490,39 @@ insstr ### Description - 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. + 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. ### Portability - X/Open BSD SYS V - insstr Y - 4.0 - winsstr Y - 4.0 - mvinsstr Y - 4.0 - mvwinsstr Y - 4.0 - insnstr Y - 4.0 - winsnstr Y - 4.0 - mvinsnstr Y - 4.0 - mvwinsnstr Y - 4.0 - ins_wstr Y - wins_wstr Y - mvins_wstr Y - mvwins_wstr Y - ins_nwstr Y - wins_nwstr Y - mvins_nwstr Y - mvwins_nwstr Y + X/Open ncurses NetBSD + insstr Y Y Y + winsstr Y Y Y + mvinsstr Y Y Y + mvwinsstr Y Y Y + insnstr Y Y Y + winsnstr Y Y Y + mvinsnstr Y Y Y + mvwinsnstr Y Y Y + ins_wstr Y Y Y + wins_wstr Y Y Y + mvins_wstr Y Y Y + mvwins_wstr Y Y Y + ins_nwstr Y Y Y + wins_nwstr Y Y Y + mvins_nwstr Y Y Y + mvwins_nwstr Y Y Y @@ -1550,37 +1554,36 @@ instr ### Description - These functions take characters (or wide characters) from the - current or specified position in the window, and return them as - a string in str (or wstr). Attributes are ignored. The functions - with n as the last argument return a string at most n characters - long. + These functions take characters (or wide characters) from the current + or specified position in the window, and return them as a string in + str (or wstr). Attributes are ignored. The functions with n as the + last argument return a string at most n characters long. ### Return Value - Upon successful completion, innstr(), mvinnstr(), mvwinnstr() - and winnstr() return the number of characters actually read into - the string; instr(), mvinstr(), mvwinstr() and winstr() return - OK. Otherwise, all these functions return ERR. + Upon successful completion, innstr(), mvinnstr(), mvwinnstr() and + winnstr() return the number of characters actually read into the + string; instr(), mvinstr(), mvwinstr() and winstr() return OK. + Otherwise, all these functions return ERR. ### Portability - X/Open BSD SYS V - instr Y - 4.0 - winstr Y - 4.0 - mvinstr Y - 4.0 - mvwinstr Y - 4.0 - innstr Y - 4.0 - winnstr Y - 4.0 - mvinnstr Y - 4.0 - mvwinnstr Y - 4.0 - inwstr Y - winwstr Y - mvinwstr Y - mvwinwstr Y - innwstr Y - winnwstr Y - mvinnwstr Y - mvwinnwstr Y + X/Open ncurses NetBSD + instr Y Y Y + winstr Y Y Y + mvinstr Y Y Y + mvwinstr Y Y Y + innstr Y Y Y + winnstr Y Y Y + mvinnstr Y Y Y + mvwinnstr Y Y Y + inwstr Y Y Y + winwstr Y Y Y + mvinwstr Y Y Y + mvwinwstr Y Y Y + innwstr Y Y Y + winnwstr Y Y Y + mvinnwstr Y Y Y + mvwinnwstr Y Y Y @@ -1609,41 +1612,38 @@ kernel ### Description - def_prog_mode() and def_shell_mode() save the current terminal - modes as the "program" (in curses) or "shell" (not in curses) - state for use by the reset_prog_mode() and reset_shell_mode() - functions. This is done automatically by initscr(). + def_prog_mode() and def_shell_mode() save the current terminal modes + as the "program" (in curses) or "shell" (not in curses) state for use + by the reset_prog_mode() and reset_shell_mode() functions. This is + done automatically by initscr(). reset_prog_mode() and reset_shell_mode() restore the terminal to - "program" (in curses) or "shell" (not in curses) state. These - are done automatically by endwin() and doupdate() after an - endwin(), so they would normally not be called before these - functions. + "program" (in curses) or "shell" (not in curses) state. These are + done automatically by endwin() and doupdate() after an endwin(), so + they would normally not be called before these functions. - savetty() and resetty() save and restore the state of the - terminal modes. savetty() saves the current state in a buffer, - and resetty() restores the state to what it was at the last call - to savetty(). + savetty() and resetty() save and restore the state of the terminal + modes. savetty() saves the current state in a buffer, and resetty() + restores the state to what it was at the last call to savetty(). - 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). + 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). - 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. + 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. 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(), + resetterm(), fixterm() and saveterm() are archaic equivalents for + reset_shell_mode(), reset_prog_mode() and def_prog_mode(), respectively. ### Return Value @@ -1652,20 +1652,20 @@ kernel curs_set(), which returns the previous visibility. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD def_prog_mode Y Y Y def_shell_mode Y Y Y reset_prog_mode Y Y Y reset_shell_mode Y Y Y resetty Y Y Y savetty Y Y Y - ripoffline Y - 3.0 - curs_set Y - 3.0 + ripoffline Y Y Y + curs_set Y Y Y napms Y Y Y - draino - - resetterm - - fixterm - - saveterm - + fixterm - Y - + resetterm - Y - + saveterm - Y - + draino - - - @@ -1685,20 +1685,20 @@ keyname ### Description - keyname() returns a string corresponding to the argument key. - key may be any key returned by wgetch(). + keyname() returns a string corresponding to the argument key. key may + be any key returned by wgetch(). key_name() is the wide-character version. It takes a wchar_t parameter, but still returns a char *. - has_key() returns TRUE for recognized keys, FALSE otherwise. - This function is an ncurses extension. + has_key() returns TRUE for recognized keys, FALSE otherwise. This + function is an ncurses extension. ### Portability - X/Open BSD SYS V - keyname Y - 3.0 - key_name Y - has_key - - - + X/Open ncurses NetBSD + keyname Y Y Y + key_name Y Y Y + has_key - Y Y @@ -1724,16 +1724,17 @@ mouse mmask_t mousemask(mmask_t mask, mmask_t *oldmask); int nc_getmouse(MEVENT *event); int ungetmouse(MEVENT *event); + bool has_mouse(void); ### Description As of PDCurses 3.0, there are two separate mouse interfaces: the - classic interface, which is based on the undocumented Sys V - mouse functions; and an ncurses-compatible interface. Both are - active at all times, and you can mix and match functions from - each, though it's not recommended. The ncurses interface is - essentially an emulation layer built on top of the classic - interface; it's here to allow easier porting of ncurses apps. + classic interface, which is based on the undocumented Sys V mouse + functions; and an ncurses-compatible interface. Both are active at + all times, and you can mix and match functions from each, though it's + not recommended. The ncurses interface is essentially an emulation + layer built on top of the classic interface; it's here to allow + easier porting of ncurses apps. The classic interface: mouse_set(), mouse_on(), mouse_off(), request_mouse_pos(), wmouse_position(), and getmouse(). An @@ -1742,99 +1743,99 @@ mouse would check for a KEY_MOUSE return from getch(). If found, it would call request_mouse_pos() to get the current mouse status. - mouse_set(), mouse_on() and mouse_off() are analagous to - attrset(), attron() and attroff(). These functions set the - mouse button events to trap. The button masks used in these - functions are defined in curses.h and can be or'ed together. - They are the group of masks starting with BUTTON1_RELEASED. + mouse_set(), mouse_on() and mouse_off() are analagous to attrset(), + attron() and attroff(). These functions set the mouse button events + to trap. The button masks used in these functions are defined in + curses.h and can be or'ed together. They are the group of masks + starting with BUTTON1_RELEASED. request_mouse_pos() requests curses to fill in the Mouse_status structure with the current state of the mouse. - wmouse_position() determines if the current mouse position is - within the window passed as an argument. If the mouse is - outside the current window, -1 is returned in the y and x - arguments; otherwise the y and x coordinates of the mouse - (relative to the top left corner of the window) are returned in - y and x. + wmouse_position() determines if the current mouse position is within + the window passed as an argument. If the mouse is outside the current + window, -1 is returned in the y and x arguments; otherwise the y and + x coordinates of the mouse (relative to the top left corner of the + window) are returned in y and x. - getmouse() returns the current status of the trapped mouse - buttons as set by mouse_set() or mouse_on(). + getmouse() returns the current status of the trapped mouse buttons as + set by mouse_set() or mouse_on(). - The ncurses interface: mouseinterval(), wenclose(), - wmouse_trafo(), mouse_trafo(), mousemask(), nc_getmouse(), and - ungetmouse(). A typical application using this interface would - start by calling mousemask() with a non-zero value, often - ALL_MOUSE_EVENTS. Then it would check for a KEY_MOUSE return - from getch(). If found, it would call nc_getmouse() to get the - current mouse status. + The ncurses interface: mouseinterval(), wenclose(), wmouse_trafo(), + mouse_trafo(), mousemask(), nc_getmouse(), ungetmouse() and + has_mouse(). A typical application using this interface would start + by calling mousemask() with a non-zero value, often ALL_MOUSE_EVENTS. + Then it would check for a KEY_MOUSE return from getch(). If found, it + would call nc_getmouse() to get the current mouse status. - mouseinterval() sets the timeout for a mouse click. On all - current platforms, PDCurses receives mouse button press and - release events, but must synthesize click events. It does this - by checking whether a release event is queued up after a press - event. If it gets a press event, and there are no more events - waiting, it will wait for the timeout interval, then check again - for a release. A press followed by a release is reported as - BUTTON_CLICKED; otherwise it's passed through as BUTTON_PRESSED. - The default timeout is 150ms; valid values are 0 (no clicks - reported) through 1000ms. In x11, the timeout can also be set - via the clickPeriod resource. The return value from - mouseinterval() is the old timeout. To check the old value - without setting a new one, call it with a parameter of -1. Note - that although there's no classic equivalent for this function - (apart from the clickPeriod resource), the value set applies in - both interfaces. + mouseinterval() sets the timeout for a mouse click. On all current + platforms, PDCurses receives mouse button press and release events, + but must synthesize click events. It does this by checking whether a + release event is queued up after a press event. If it gets a press + event, and there are no more events waiting, it will wait for the + timeout interval, then check again for a release. A press followed by + a release is reported as BUTTON_CLICKED; otherwise it's passed + through as BUTTON_PRESSED. The default timeout is 150ms; valid values + are 0 (no clicks reported) through 1000ms. In x11, the timeout can + also be set via the clickPeriod resource. The return value from + mouseinterval() is the old timeout. To check the old value without + setting a new one, call it with a parameter of -1. Note that although + there's no classic equivalent for this function (apart from the + clickPeriod resource), the value set applies in both interfaces. - wenclose() reports whether the given screen-relative y, x - coordinates fall within the given window. + wenclose() reports whether the given screen-relative y, x coordinates + fall within the given window. - wmouse_trafo() converts between screen-relative and window- - relative coordinates. A to_screen parameter of TRUE means to - convert from window to screen; otherwise the reverse. The - function returns FALSE if the coordinates aren't within the - window, or if any of the parameters are NULL. The coordinates - have been converted when the function returns TRUE. + wmouse_trafo() converts between screen-relative and window-relative + coordinates. A to_screen parameter of TRUE means to convert from + window to screen; otherwise the reverse. The function returns FALSE + if the coordinates aren't within the window, or if any of the + parameters are NULL. The coordinates have been converted when the + function returns TRUE. mouse_trafo() is the stdscr version of wmouse_trafo(). mousemask() is nearly equivalent to mouse_set(), but instead of OK/ERR, it returns the value of the mask after setting it. (This - isn't necessarily the same value passed in, since the mask could - be altered on some platforms.) And if the second parameter is a - non-null pointer, mousemask() stores the previous mask value - there. Also, since the ncurses interface doesn't work with - PDCurses' BUTTON_MOVED events, mousemask() filters them out. + isn't necessarily the same value passed in, since the mask could be + altered on some platforms.) And if the second parameter is a non-null + pointer, mousemask() stores the previous mask value there. Also, + since the ncurses interface doesn't work with PDCurses' BUTTON_MOVED + events, mousemask() filters them out. - nc_getmouse() returns the current mouse status in an MEVENT - struct. This is equivalent to ncurses' getmouse(), renamed to - avoid conflict with PDCurses' getmouse(). But if you define - PDC_NCMOUSE before including curses.h, it defines getmouse() to - nc_getmouse(), along with a few other redefintions needed for - compatibility with ncurses code. nc_getmouse() calls - request_mouse_pos(), which (not getmouse()) is the classic - equivalent. + nc_getmouse() returns the current mouse status in an MEVENT struct. + This is equivalent to ncurses' getmouse(), renamed to avoid conflict + with PDCurses' getmouse(). But if you define PDC_NCMOUSE before + including curses.h, it defines getmouse() to nc_getmouse(), along + with a few other redefintions needed for compatibility with ncurses + code. nc_getmouse() calls request_mouse_pos(), which (not getmouse()) + is the classic equivalent. - ungetmouse() is the mouse equivalent of ungetch(). However, - PDCurses doesn't maintain a queue of mouse events; only one can - be pushed back, and it can overwrite or be overwritten by real - mouse events. + ungetmouse() is the mouse equivalent of ungetch(). However, PDCurses + doesn't maintain a queue of mouse events; only one can be pushed + back, and it can overwrite or be overwritten by real mouse events. + + has_mouse() reports whether the mouse is available at all on the + current platform. ### Portability - X/Open BSD SYS V - mouse_set - - 4.0 - mouse_on - - 4.0 - mouse_off - - 4.0 - request_mouse_pos - - 4.0 - wmouse_position - - 4.0 - getmouse - - 4.0 - mouseinterval - - - - wenclose - - - - wmouse_trafo - - - - mouse_trafo - - - - mousemask - - - - nc_getmouse - - - - ungetmouse - - - + X/Open ncurses NetBSD + mouse_set - - - + mouse_on - - - + mouse_off - - - + request_mouse_pos - - - + wmouse_position - - - + getmouse - * - + mouseinterval - Y - + wenclose - Y - + wmouse_trafo - Y - + mouse_trafo - Y - + mousemask - Y - + nc_getmouse - * - + ungetmouse - Y - + has_mouse - Y - + + * See above, under Description @@ -1852,20 +1853,20 @@ move ### Description - move() and wmove() move the cursor associated with the window to - the given location. This does not move the physical cursor of the - terminal until refresh() is called. The position specified is + move() and wmove() move the cursor associated with the window to the + given location. This does not move the physical cursor of the + terminal until refresh() is called. The position specified is relative to the upper left corner of the window, which is (0,0). - mvcur() moves the physical cursor without updating any window - cursor positions. + mvcur() moves the physical cursor without updating any window cursor + positions. ### Return Value All functions return OK on success and ERR on error. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD move Y Y Y mvcur Y Y Y wmove Y Y Y @@ -1891,50 +1892,53 @@ outopts int raw_output(bool bf); + bool is_leaveok(const WINDOW *win); + ### Description - With clearok(), if bf is TRUE, the next call to wrefresh() with - this window will clear the screen completely and redraw the - entire screen. + With clearok(), if bf is TRUE, the next call to wrefresh() with this + window will clear the screen completely and redraw the entire screen. - immedok(), called with a second argument of TRUE, causes an - automatic wrefresh() every time a change is made to the - specified window. + 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 - 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. + 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'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 - 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. + 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. - raw_output() enables the output of raw characters using the - standard *add* and *ins* curses functions (that is, it disables - translation of control characters). + raw_output() enables the output of raw characters using the standard + *add* and *ins* curses functions (that is, it disables translation of + control characters). + + is_leaveok() reports whether the specified window is in leaveok mode. ### Return Value - All functions return OK on success and ERR on error. + All functions except is_leaveok() return OK on success and ERR on + error. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD clearok Y Y Y idlok Y Y Y - idcok Y - 4.0 - immedok Y - 4.0 + idcok Y Y Y + immedok Y Y Y leaveok Y Y Y setscrreg Y Y Y wsetscrreg Y Y Y scrollok Y Y Y + is_leaveok - Y Y raw_output - - - @@ -1955,32 +1959,32 @@ overlay ### Description - 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). + 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, 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. + 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. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD overlay Y Y Y overwrite Y Y Y - copywin Y - 3.0 + copywin Y Y Y @@ -2002,53 +2006,57 @@ pad int pechochar(WINDOW *pad, chtype ch); int pecho_wchar(WINDOW *pad, const cchar_t *wch); + bool is_pad(const WINDOW *pad); + ### Description - 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. + 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. newpad() creates a new pad data structure. 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(). + 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(). pnoutrefresh() copies the specified pad to the virtual screen. 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. + 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. + 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. + + is_pad() reports whether the specified window is a pad. ### Return Value - All functions return OK on success and ERR on error. + All functions except is_pad() return OK on success and ERR on error. ### Portability - X/Open BSD SYS V - newpad Y - Y - subpad Y - Y - prefresh Y - Y - pnoutrefresh Y - Y - pechochar Y - 3.0 - pecho_wchar Y + X/Open ncurses NetBSD + newpad Y Y Y + subpad Y Y Y + prefresh Y Y Y + pnoutrefresh Y Y Y + pechochar Y Y Y + pecho_wchar Y Y Y + is_pad - Y Y @@ -2147,22 +2155,22 @@ panel if it executes successfully and ERR if it does not. ### Portability - X/Open BSD SYS V - bottom_panel - - Y - del_panel - - Y - hide_panel - - Y - move_panel - - Y - new_panel - - Y - panel_above - - Y - panel_below - - Y - panel_hidden - - Y - panel_userptr - - Y - panel_window - - Y - replace_panel - - Y - set_panel_userptr - - Y - show_panel - - Y - top_panel - - Y - update_panels - - Y + X/Open ncurses NetBSD + bottom_panel - Y Y + del_panel - Y Y + hide_panel - Y Y + move_panel - Y Y + new_panel - Y Y + panel_above - Y Y + panel_below - Y Y + panel_hidden - Y Y + panel_userptr - Y Y + panel_window - Y Y + replace_panel - Y Y + set_panel_userptr - Y Y + show_panel - Y Y + top_panel - Y Y + update_panels - Y Y Credits: Original Author - Warren Tucker @@ -2186,27 +2194,27 @@ printw ### Description - The printw() functions add a formatted string to the window at - the current or specified cursor position. The format strings are - the same as used in the standard C library's printf(). (printw() - can be used as a drop-in replacement for printf().) + The printw() functions add a formatted string to the window at the + current or specified cursor position. The format strings are the same + as used in the standard C library's printf(). (printw() can be used + as a drop-in replacement for printf().) The duplication between vwprintw() and vw_printw() is for historic reasons. In PDCurses, they're the same. ### Return Value - All functions return the number of characters printed, or - ERR on error. + All functions return the number of characters printed, or ERR on + error. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD printw Y Y Y wprintw Y Y Y mvprintw Y Y Y mvwprintw Y Y Y - vwprintw Y - 4.0 - vw_printw Y + vwprintw Y Y Y + vw_printw Y Y Y @@ -2227,42 +2235,40 @@ refresh ### Description - wrefresh() copies the named window to the physical terminal - screen, taking into account what is already there in order to - optimize cursor movement. refresh() does the same, using stdscr. - These routines must be called to get any output on the terminal, - as other routines only manipulate data structures. Unless - leaveok() has been enabled, the physical cursor of the terminal - is left at the location of the window's cursor. + wrefresh() copies the named window to the physical terminal screen, + taking into account what is already there in order to optimize cursor + movement. refresh() does the same, using stdscr. These routines must + be called to get any output on the terminal, as other routines only + manipulate data structures. Unless leaveok() has been enabled, the + physical cursor of the terminal is left at the location of the + window's cursor. wnoutrefresh() and doupdate() allow multiple updates with more - efficiency than wrefresh() alone. wrefresh() works by first - calling wnoutrefresh(), which copies the named window to the - virtual screen. It then calls doupdate(), which compares the - virtual screen to the physical screen and does the actual - update. A series of calls to wrefresh() will result in - alternating calls to wnoutrefresh() and doupdate(), causing - several bursts of output to the screen. By first calling - wnoutrefresh() for each window, it is then possible to call + efficiency than wrefresh() alone. wrefresh() works by first calling + wnoutrefresh(), which copies the named window to the virtual screen. + It then calls doupdate(), which compares the virtual screen to the + physical screen and does the actual update. A series of calls to + wrefresh() will result in alternating calls to wnoutrefresh() and + doupdate(), causing several bursts of output to the screen. By first + calling wnoutrefresh() for each window, it is then possible to call doupdate() only once. - In PDCurses, redrawwin() is equivalent to touchwin(), and - wredrawln() is the same as touchline(). In some other curses - implementations, there's a subtle distinction, but it has no - meaning in PDCurses. + In PDCurses, redrawwin() is equivalent to touchwin(), and wredrawln() + is the same as touchline(). In some other curses implementations, + there's a subtle distinction, but it has no meaning in PDCurses. ### Return Value All functions return OK on success and ERR on error. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD refresh Y Y Y wrefresh Y Y Y wnoutrefresh Y Y Y doupdate Y Y Y - redrawwin Y - 4.0 - wredrawln Y - 4.0 + redrawwin Y Y Y + wredrawln Y Y Y @@ -2283,26 +2289,26 @@ scanw ### Description - 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. + 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. The duplication between vwscanw() and vw_scanw() is for historic reasons. In PDCurses, they're the same. ### Return Value - On successful completion, these functions return the number of - items successfully matched. 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 + X/Open ncurses NetBSD scanw Y Y Y wscanw Y Y Y mvscanw Y Y Y mvwscanw Y Y Y - vwscanw Y - 4.0 - vw_scanw Y + vwscanw Y Y Y + vw_scanw Y Y Y @@ -2323,43 +2329,42 @@ scr_dump ### Description - getwin() reads window-related data previously stored in a file - by putwin(). It then creates and initialises a new window using - that data. + getwin() reads window-related data previously stored in a file by + putwin(). It then creates and initialises a new window using that + data. - putwin() writes all data associated with a window into a file, - using an unspecified format. This information can be retrieved - later using getwin(). + putwin() writes all data associated with a window into a file, using + an unspecified format. This information can be retrieved later using + getwin(). - scr_dump() writes the current contents of the virtual screen to - the file named by filename in an unspecified format. + scr_dump() writes the current contents of the virtual screen to the + file named by filename in an unspecified format. - scr_restore() function sets the virtual screen to the contents - of the file named by filename, which must have been written - using scr_dump(). The next refresh operation restores the screen - to the way it looked in the dump file. + scr_restore() function sets the virtual screen to the contents of the + file named by filename, which must have been written using + scr_dump(). The next refresh operation restores the screen to the way + it looked in the dump file. - In PDCurses, scr_init() does nothing, and scr_set() is a synonym - for scr_restore(). Also, scr_dump() and scr_restore() save and - load from curscr. This differs from some other implementations, - where scr_init() works with curscr, and scr_restore() works with - newscr; but the effect should be the same. (PDCurses has no - newscr.) + In PDCurses, scr_init() does nothing, and scr_set() is a synonym for + scr_restore(). Also, scr_dump() and scr_restore() save and load from + curscr. This differs from some other implementations, where + scr_init() works with curscr, and scr_restore() works with newscr; + but the effect should be the same. (PDCurses has no newscr.) ### Return Value - On successful completion, getwin() returns a pointer to the - window it created. Otherwise, it returns a null pointer. Other - functions return OK or ERR. + On successful completion, getwin() returns a pointer to the window it + created. Otherwise, it returns a null pointer. Other functions return + OK or ERR. ### Portability - X/Open BSD SYS V - putwin Y - getwin Y - scr_dump Y - scr_init Y - scr_restore Y - scr_set Y + X/Open ncurses NetBSD + putwin Y Y Y + getwin Y Y Y + scr_dump Y Y - + scr_init Y Y - + scr_restore Y Y - + scr_set Y Y - @@ -2377,26 +2382,26 @@ scroll ### Description - scroll() causes the window to scroll up one line. This involves + scroll() causes the window to scroll up one line. This involves moving the lines in the window data strcture. - With a positive n, scrl() and wscrl() scroll the window up n - lines (line i + n becomes i); otherwise they scroll the window - down n lines. + With a positive n, scrl() and wscrl() scroll the window up n lines + (line i + n becomes i); otherwise they scroll the window down n + lines. For these functions to work, scrolling must be enabled via - scrollok(). Note also that scrolling is not allowed if the - supplied window is a pad. + scrollok(). Note also that scrolling is not allowed if the supplied + window is a pad. ### Return Value All functions return OK on success and ERR on error. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD scroll Y Y Y - scrl Y - 4.0 - wscrl Y - 4.0 + scrl Y Y Y + wscrl Y Y Y @@ -2435,15 +2440,15 @@ slk ### Description These functions manipulate a window that contain Soft Label Keys - (SLK). To use the SLK functions, a call to slk_init() must be - made BEFORE initscr() or newterm(). slk_init() removes 1 or 2 - lines from the useable screen, depending on the format selected. + (SLK). To use the SLK functions, a call to slk_init() must be made + BEFORE initscr() or newterm(). slk_init() removes 1 or 2 lines from + the useable screen, depending on the format selected. - The line(s) removed from the screen are used as a separate - window, in which SLKs are displayed. + The line(s) removed from the screen are used as a separate window, in + which SLKs are displayed. - slk_init() requires a single parameter which describes the - format of the SLKs as follows: + slk_init() requires a single parameter which describes the format of + the SLKs as follows: 0 3-2-3 format 1 4-4 format @@ -2452,30 +2457,30 @@ slk 2 lines used 55 5-5 format (pdcurses format) - slk_refresh(), slk_noutrefresh() and slk_touch() are analogous - to refresh(), noutrefresh() and touch(). + 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. ### Portability - X/Open BSD SYS V - slk_init Y - Y - slk_set Y - Y - slk_refresh Y - Y - slk_noutrefresh Y - Y - slk_label Y - Y - slk_clear Y - Y - slk_restore Y - Y - slk_touch Y - Y - slk_attron Y - Y - slk_attrset Y - Y - slk_attroff Y - Y - slk_attr_on Y - slk_attr_set Y - slk_attr_off Y - slk_wset Y + X/Open ncurses NetBSD + slk_init Y Y Y + slk_set Y Y Y + slk_refresh Y Y Y + slk_noutrefresh Y Y Y + slk_label Y Y Y + slk_clear Y Y Y + slk_restore Y Y Y + slk_touch Y Y Y + slk_attron Y Y Y + slk_attrset Y Y Y + slk_attroff Y Y Y + slk_attr_on Y Y Y + slk_attr_set Y Y Y + slk_attr_off Y Y Y + slk_wset Y Y Y PDC_mouse_in_slk - - - PDC_slk_free - - - PDC_slk_initialize - - - @@ -2508,35 +2513,35 @@ termattr ### Description - baudrate() is supposed to return the output speed of the - terminal. In PDCurses, it simply returns INT_MAX. + baudrate() is supposed to return the output speed of the terminal. In + PDCurses, it simply returns INT_MAX. - has_ic and has_il() return TRUE. These functions have meaning in - some other implementations of curses. + has_ic and has_il() return TRUE. These functions have meaning in some + other implementations of curses. erasechar() and killchar() return ^H and ^U, respectively -- the - ERASE and KILL characters. In other curses implementations, - these may vary by terminal type. erasewchar() and killwchar() - are the wide-character versions; they take a pointer to a - location in which to store the character, and return OK or ERR. + ERASE and KILL characters. In other curses implementations, these may + vary by terminal type. erasewchar() and killwchar() are the wide- + character versions; they take a pointer to a location in which to + store the character, and return OK or ERR. - longname() returns a pointer to a static area containing a - verbose description of the current terminal. The maximum length - of the string is 128 characters. It is defined only after the - call to initscr() or newterm(). + longname() returns a pointer to a static area containing a verbose + description of the current terminal. The maximum length of the string + is 128 characters. It is defined only after the call to initscr() or + newterm(). - termname() returns a pointer to a static area containing a - short description of the current terminal (14 characters). + termname() returns a pointer to a static area containing a short + description of the current terminal (14 characters). - termattrs() returns a logical OR of all video attributes - supported by the terminal. + termattrs() returns a logical OR of all video attributes supported by + the terminal. wordchar() is a PDCurses extension of the concept behind the - functions erasechar() and killchar(), returning the "delete - word" character, ^W. + functions erasechar() and killchar(), returning the "delete word" + character, ^W. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD baudrate Y Y Y erasechar Y Y Y has_ic Y Y Y @@ -2545,9 +2550,9 @@ termattr longname Y Y Y termattrs Y Y Y termname Y Y Y - erasewchar Y - killwchar Y - term_attrs Y + erasewchar Y Y Y + killwchar Y Y Y + term_attrs Y Y Y wordchar - - - @@ -2567,29 +2572,32 @@ touch bool is_linetouched(WINDOW *win, int line); bool is_wintouched(WINDOW *win); + int touchoverlap(const WINDOW *win1, WINDOW *win2); + ### Description - touchwin() and touchline() throw away all information about - which parts of the window have been touched, pretending that the - entire window has been drawn on. This is sometimes necessary - when using overlapping windows, since a change to one window - will affect the other window, but the records of which lines - have been changed in the other window will not reflect the - change. + touchwin() and touchline() throw away all information about which + parts of the window have been touched, pretending that the entire + window has been drawn on. This is sometimes necessary when using + overlapping windows, since a change to one window will affect the + other window, but the records of which lines have been changed in the + other window will not reflect the change. - untouchwin() marks all lines in the window as unchanged since - the last call to wrefresh(). + untouchwin() marks all lines in the window as unchanged since the + last call to wrefresh(). - wtouchln() makes n lines in the window, starting at line y, look - as if they have (changed == 1) or have not (changed == 0) been - changed since the last call to wrefresh(). + wtouchln() makes n lines in the window, starting at line y, look as + if they have (changed == 1) or have not (changed == 0) been changed + since the last call to wrefresh(). - is_linetouched() returns TRUE if the specified line in the - specified window has been changed since the last call to - wrefresh(). + is_linetouched() returns TRUE if the specified line in the specified + window has been changed since the last call to wrefresh(). - is_wintouched() returns TRUE if the specified window - has been changed since the last call to wrefresh(). + is_wintouched() returns TRUE if the specified window has been changed + since the last call to wrefresh(). + + touchoverlap(win1, win2) marks the portion of win2 which overlaps + with win1 as modified. ### Return Value @@ -2597,13 +2605,14 @@ touch is_wintouched() and is_linetouched(). ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD touchwin Y Y Y - touchline Y - 3.0 - untouchwin Y - 4.0 + touchline Y Y Y + untouchwin Y Y Y wtouchln Y Y Y - is_linetouched Y - 4.0 - is_wintouched Y - 4.0 + is_linetouched Y Y Y + is_wintouched Y Y Y + touchoverlap - - Y @@ -2632,51 +2641,50 @@ util ### Description - unctrl() expands the text portion of the chtype c into a - printable string. Control characters are changed to the "^X" - notation; others are passed through. wunctrl() is the wide- - character version of the function. + unctrl() expands the text portion of the chtype c into a printable + string. Control characters are changed to the "^X" notation; others + are passed through. wunctrl() is the wide- character version of the + function. filter() and use_env() are no-ops in PDCurses. delay_output() inserts an ms millisecond pause in output. - getcchar() works in two modes: When wch is not NULL, it reads - the cchar_t pointed to by wcval and stores the attributes in - attrs, the color pair in color_pair, and the text in the - wide-character string wch. When wch is NULL, getcchar() merely - returns the number of wide characters in wcval. In either mode, - the opts argument is unused. + getcchar() works in two modes: When wch is not NULL, it reads the + cchar_t pointed to by wcval and stores the attributes in attrs, the + color pair in color_pair, and the text in the wide-character string + wch. When wch is NULL, getcchar() merely returns the number of wide + characters in wcval. In either mode, the opts argument is unused. - setcchar constructs a cchar_t at wcval from the wide-character - text at wch, the attributes in attr and the color pair in - color_pair. The opts argument is unused. + setcchar constructs a cchar_t at wcval from the wide-character text + at wch, the attributes in attr and the color pair in color_pair. The + opts argument is unused. Currently, the length returned by getcchar() is always 1 or 0. - Similarly, setcchar() will only take the first wide character - from wch, and ignore any others that it "should" take (i.e., - combining characters). Nor will it correctly handle any - character outside the basic multilingual plane (UCS-2). + Similarly, setcchar() will only take the first wide character from + wch, and ignore any others that it "should" take (i.e., combining + characters). Nor will it correctly handle any character outside the + basic multilingual plane (UCS-2). ### Return Value - unctrl() and wunctrl() return NULL on failure. delay_output() - always returns OK. + unctrl() and wunctrl() return NULL on failure. delay_output() always + returns OK. - getcchar() returns the number of wide characters wcval points to - when wch is NULL; when it's not, getcchar() returns OK or ERR. + getcchar() returns the number of wide characters wcval points to when + wch is NULL; when it's not, getcchar() returns OK or ERR. setcchar() returns OK or ERR. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD unctrl Y Y Y - filter Y - 3.0 - use_env Y - 4.0 + filter Y Y Y + use_env Y Y Y delay_output Y Y Y - getcchar Y - setcchar Y - wunctrl Y + getcchar Y Y Y + setcchar Y Y Y + wunctrl Y Y Y PDC_mbtowc - - - PDC_mbstowcs - - - PDC_wcstombs - - - @@ -2713,103 +2721,100 @@ window ### Description - newwin() creates a new window with the given number of lines, - nlines and columns, ncols. The upper left corner of the window - is at line begy, column begx. If nlines is zero, it defaults to - LINES - begy; ncols to COLS - begx. Create a new full-screen - window by calling newwin(0, 0, 0, 0). + newwin() creates a new window with the given number of lines, nlines + and columns, ncols. The upper left corner of the window is at line + begy, column begx. If nlines is zero, it defaults to LINES - begy; + ncols to COLS - begx. Create a new full-screen window by calling + newwin(0, 0, 0, 0). - delwin() deletes the named window, freeing all associated - memory. In the case of overlapping windows, subwindows should be - deleted before the main window. + delwin() deletes the named window, freeing all associated memory. In + the case of overlapping windows, subwindows should be deleted before + the main window. - mvwin() moves the window so that the upper left-hand corner is - at position (y,x). If the move would cause the window to be off - the screen, it is an error and the window is not moved. Moving - subwindows is allowed. + mvwin() moves the window so that the upper left-hand corner is at + position (y,x). If the move would cause the window to be off the + screen, it is an error and the window is not moved. Moving subwindows + is allowed. - subwin() creates a new subwindow within a window. The - dimensions of the subwindow are nlines lines and ncols columns. - The subwindow is at position (begy, begx) on the screen. This - position is relative to the screen, and not to the window orig. - Changes made to either window will affect both. When using this - routine, you will often need to call touchwin() before calling - wrefresh(). + subwin() creates a new subwindow within a window. The dimensions of + the subwindow are nlines lines and ncols columns. The subwindow is at + position (begy, begx) on the screen. This position is relative to the + screen, and not to the window orig. Changes made to either window + will affect both. When using this routine, you will often need to + call touchwin() before calling wrefresh(). derwin() is the same as subwin(), except that begy and begx are - relative to the origin of the window orig rather than the - screen. There is no difference between subwindows and derived - windows. + relative to the origin of the window orig rather than the screen. + There is no difference between subwindows and derived windows. - mvderwin() moves a derived window (or subwindow) inside its - parent window. The screen-relative parameters of the window are - not changed. This routine is used to display different parts of - the parent window at the same physical position on the screen. + mvderwin() moves a derived window (or subwindow) inside its parent + window. The screen-relative parameters of the window are not changed. + This routine is used to display different parts of the parent window + at the same physical position on the screen. dupwin() creates an exact duplicate of the window win. wsyncup() causes a touchwin() of all of the window's parents. - If wsyncok() is called with a second argument of TRUE, this - causes a wsyncup() to be called every time the window is - changed. + If wsyncok() is called with a second argument of TRUE, this causes a + wsyncup() to be called every time the window is changed. - wcursyncup() causes the current cursor position of all of a - window's ancestors to reflect the current cursor position of the - current window. + wcursyncup() causes the current cursor position of all of a window's + ancestors to reflect the current cursor position of the current + window. - wsyncdown() causes a touchwin() of the current window if any of - its parent's windows have been touched. + wsyncdown() causes a touchwin() of the current window if any of its + parent's windows have been touched. resize_window() allows the user to resize an existing window. It returns the pointer to the new window, or NULL on failure. - wresize() is an ncurses-compatible wrapper for resize_window(). - Note that, unlike ncurses, it will NOT process any subwindows of - the window. (However, you still can call it _on_ subwindows.) It - returns OK or ERR. + wresize() is an ncurses-compatible wrapper for resize_window(). Note + that, unlike ncurses, it will NOT process any subwindows of the + window. (However, you still can call it _on_ subwindows.) It returns + OK or ERR. - PDC_makenew() allocates all data for a new WINDOW * except the - actual lines themselves. If it's unable to allocate memory for - the window structure, it will free all allocated memory and - return a NULL pointer. + PDC_makenew() allocates all data for a new WINDOW * except the actual + lines themselves. If it's unable to allocate memory for the window + structure, it will free all allocated memory and return a NULL + pointer. PDC_makelines() allocates the memory for the lines. - PDC_sync() handles wrefresh() and wsyncup() calls when a window - is changed. + PDC_sync() handles wrefresh() and wsyncup() calls when a window is + changed. ### Return Value - newwin(), subwin(), derwin() and dupwin() return a pointer - to the new window, or NULL on failure. delwin(), mvwin(), - mvderwin() and syncok() return OK or ERR. wsyncup(), - wcursyncup() and wsyncdown() return nothing. + newwin(), subwin(), derwin() and dupwin() return a pointer to the new + window, or NULL on failure. delwin(), mvwin(), mvderwin() and + syncok() return OK or ERR. wsyncup(), wcursyncup() and wsyncdown() + return nothing. ### Errors It is an error to call resize_window() before calling initscr(). - Also, an error will be generated if we fail to create a newly - sized replacement window for curscr, or stdscr. This could - happen when increasing the window size. NOTE: If this happens, - the previously successfully allocated windows are left alone; - i.e., the resize is NOT cancelled for those windows. + Also, an error will be generated if we fail to create a newly sized + replacement window for curscr, or stdscr. This could happen when + increasing the window size. NOTE: If this happens, the previously + successfully allocated windows are left alone; i.e., the resize is + NOT cancelled for those windows. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD newwin Y Y Y delwin Y Y Y mvwin Y Y Y subwin Y Y Y - derwin Y - Y - mvderwin Y - Y - dupwin Y - 4.0 - wsyncup Y - 4.0 - syncok Y - 4.0 - wcursyncup Y - 4.0 - wsyncdown Y - 4.0 + derwin Y Y Y + mvderwin Y Y Y + dupwin Y Y Y + wsyncup Y Y Y + syncok Y Y Y + wcursyncup Y Y Y + wsyncdown Y Y Y + wresize - Y Y resize_window - - - - wresize - - - PDC_makelines - - - PDC_makenew - - - PDC_sync - - - @@ -2832,11 +2837,10 @@ clipboard ### Description PDC_getclipboard() gets the textual contents of the system's - clipboard. This function returns the contents of the clipboard - in the contents argument. It is the responsibilitiy of the - caller to free the memory returned, via PDC_freeclipboard(). - The length of the clipboard contents is returned in the length - argument. + clipboard. This function returns the contents of the clipboard in the + contents argument. It is the responsibilitiy of the caller to free + the memory returned, via PDC_freeclipboard(). The length of the + clipboard contents is returned in the length argument. PDC_setclipboard copies the supplied text into the system's clipboard, emptying the clipboard prior to the copy. @@ -2853,7 +2857,7 @@ clipboard PDC_CLIP_ACCESS_ERROR no clipboard support ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD PDC_getclipboard - - - PDC_setclipboard - - - PDC_freeclipboard - - - @@ -2873,11 +2877,11 @@ pdckbd ### Description - PDC_get_input_fd() returns the file descriptor that PDCurses - reads its input from. It can be used for select(). + PDC_get_input_fd() returns the file descriptor that PDCurses reads + its input from. It can be used for select(). ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD PDC_get_input_fd - - - @@ -2896,11 +2900,11 @@ pdcsetsc ### Description - PDC_set_blink() toggles whether the A_BLINK attribute sets an - actual blink mode (TRUE), or sets the background color to high - intensity (FALSE). The default is platform-dependent (FALSE in - most cases). It returns OK if it could set the state to match - the given parameter, ERR otherwise. + PDC_set_blink() toggles whether the A_BLINK attribute sets an actual + blink mode (TRUE), or sets the background color to high intensity + (FALSE). The default is platform-dependent (FALSE in most cases). It + returns OK if it could set the state to match the given parameter, + ERR otherwise. PDC_set_bold() toggles whether the A_BOLD attribute selects an actual bold font (TRUE), or sets the foreground color to high intensity @@ -2912,7 +2916,7 @@ pdcsetsc platforms. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD PDC_set_blink - - - PDC_set_title - - - @@ -2942,7 +2946,7 @@ sb All functions return OK on success and ERR on error. ### Portability - X/Open BSD SYS V + X/Open ncurses NetBSD sb_init - - - sb_set_horz - - - sb_set_vert - - -