X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fhtml%2Fman%2Fcurs_window.3x.html;h=660ed566fd72c60357778012cd8a8069effebfe5;hb=205ea499dbbceba5201d997fbd8b6b1f7f29bd50;hp=a28edd6c3bf2767c1685ac87530af30df0c39656;hpb=b0b1980be11bba618d84beb8b30ac94e2c820602;p=ncurses.git diff --git a/doc/html/man/curs_window.3x.html b/doc/html/man/curs_window.3x.html index a28edd6c..660ed566 100644 --- a/doc/html/man/curs_window.3x.html +++ b/doc/html/man/curs_window.3x.html @@ -1,7 +1,7 @@ - - +
+ +- -curs_window(3x) curs_window(3x) +curs_window(3x) curs_window(3x) --
- newwin, delwin, mvwin, subwin, derwin, mvderwin, dupwin, - wsyncup, syncok, wcursyncup, wsyncdown - create curses - windows +
+ newwin, delwin, mvwin, subwin, derwin, mvderwin, dupwin, wsyncup, + syncok, wcursyncup, wsyncdown - create curses windows --
+
#include <curses.h> WINDOW *newwin( - int nlines, int ncols, - int begin_y, int begin_x); - int delwin(WINDOW *win); - int mvwin(WINDOW *win, int y, int x); - WINDOW *subwin(WINDOW *orig, - int nlines, int ncols, - int begin_y, int begin_x); - WINDOW *derwin(WINDOW *orig, - int nlines, int ncols, - int begin_y, int begin_x); - int mvderwin(WINDOW *win, int par_y, int par_x); - WINDOW *dupwin(WINDOW *win); - void wsyncup(WINDOW *win); - int syncok(WINDOW *win, bool bf); - void wcursyncup(WINDOW *win); - void wsyncdown(WINDOW *win); - - --
- Calling newwin creates and returns a pointer to a new win- - dow with the given number of lines and columns. The upper - left-hand corner of the window is at + int nlines, int ncols, + int begin_y, int begin_x); + int delwin(WINDOW *win); + int mvwin(WINDOW *win, int y, int x); + WINDOW *subwin(WINDOW *orig, + int nlines, int ncols, + int begin_y, int begin_x); + WINDOW *derwin(WINDOW *orig, + int nlines, int ncols, + int begin_y, int begin_x); + int mvderwin(WINDOW *win, int par_y, int par_x); + WINDOW *dupwin(WINDOW *win); + void wsyncup(WINDOW *win); + int syncok(WINDOW *win, bool bf); + void wcursyncup(WINDOW *win); + void wsyncdown(WINDOW *win); + + +
+ +
+ Calling newwin creates and returns a pointer to a new window with the + given number of lines and columns. The upper left-hand corner of the + window is at line begin_y, column begin_x @@ -87,154 +86,199 @@ LINES - begin_y and COLS - begin_x. - A new full-screen window is created by calling - newwin(0,0,0,0). - - Calling delwin deletes the named window, freeing all memo- - ry associated with it (it does not actually erase the win- - dow's screen image). Subwindows must be deleted before - the main window can be deleted. - - Calling mvwin moves the window so that the upper left-hand - corner is at position (x, y). 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, but should be - avoided. - - Calling subwin creates and returns a pointer to a new win- - dow with the given number of lines, nlines, and columns, - ncols. The window is at position (begin_y, begin_x) on - the screen. The subwindow shares memory with the window - orig, so that changes made to one window will affect both - windows. When using this routine, it is necessary to call - touchwin or touchline on orig before calling wrefresh on - the subwindow. - - Calling derwin is the same as calling subwin, except that - begin_y and begin_x are relative to the origin of the win- - dow orig rather than the screen. There is no difference - between the subwindows and the derived windows. - - Calling mvderwin moves a derived window (or subwindow) in- - side its parent window. The screen-relative parameters of - the window are not changed. This routine is used to dis- - play different parts of the parent window at the same - physical position on the screen. - - Calling dupwin creates an exact duplicate of the window - win. - - Calling wsyncup touches all locations in ancestors of win - that are changed in win. If syncok is called with second - argument TRUE then wsyncup is called automatically whenev- - er there is a change in the window. - - The wsyncdown routine touches each location in win that - has been touched in any of its ancestor windows. This - routine is called by wrefresh, so it should almost never - be necessary to call it manually. - - The routine wcursyncup updates the current cursor position - of all the ancestors of the window to reflect the current - cursor position of the window. + A new full-screen window is created by calling newwin(0,0,0,0). + Regardless of the function used for creating a new window (e.g., + newwin, subwin, derwin, newpad), rather than a duplicate (with dupwin), + all of the window modes are initialized to the default values. These + functions set window modes after a window is created: + + idcok, idlok, immedok, keypad, leaveok, nodelay, scrollok, + setscrreg, syncok, wbkgdset, wbkgrndset, and wtimeout + + +
+ Calling delwin deletes the named window, freeing all memory associated + with it (it does not actually erase the window's screen image). Sub- + windows must be deleted before the main window can be deleted. + + +
+ Calling mvwin moves the window so that the upper left-hand corner is at + position (x, y). 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, but should be avoided. + + +
+ Calling subwin creates and returns a pointer to a new window with the + given number of lines, nlines, and columns, ncols. The window is at + position (begin_y, begin_x) on the screen. The subwindow shares memory + with the window orig, so that changes made to one window will affect + both windows. When using this routine, it is necessary to call touch- + win or touchline on orig before calling wrefresh on the subwindow. + + +
+ Calling derwin is the same as calling subwin, except that begin_y and + begin_x are relative to the origin of the window orig rather than the + screen. There is no difference between the subwindows and the derived + windows. + + Calling mvderwin moves a derived window (or subwindow) inside its par- + ent 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. --
- Routines that return an integer return the integer ERR up- - on failure and OK (SVr4 only specifies "an integer value - other than ERR") upon successful completion. + +
+ Calling dupwin creates an exact duplicate of the window win. + + +
+ Calling wsyncup touches all locations in ancestors of win that are + changed in win. If syncok is called with second argument TRUE then + wsyncup is called automatically whenever there is a change in the win- + dow. + + +
+ The wsyncdown routine touches each location in win that has been + touched in any of its ancestor windows. This routine is called by wre- + fresh, so it should almost never be necessary to call it manually. + + +
+ The routine wcursyncup updates the current cursor position of all the + ancestors of the window to reflect the current cursor position of the + window. + + +
+ Routines that return an integer return the integer ERR upon failure and + OK (SVr4 only specifies "an integer value other than ERR") upon suc- + cessful completion. Routines that return pointers return NULL on error. - X/Open defines no error conditions. In this implementa- - tion + X/Open defines no error conditions. In this implementation delwin - returns an error if the window pointer is null, or if - the window is the parent of another window. + returns an error if the window pointer is null, or if the window + is the parent of another window. derwin - returns an error if the parent window pointer is - null, or if any of its ordinates or dimensions is - negative, or if the resulting window does not fit in- - side the parent window. + returns an error if the parent window pointer is null, or if any + of its ordinates or dimensions is negative, or if the resulting + window does not fit inside the parent window. dupwin returns an error if the window pointer is null. - This implementation also maintains a list of windows, - and checks that the pointer passed to delwin is one - that it created, returning an error if it was not.. + This implementation also maintains a list of windows, and checks + that the pointer passed to delwin is one that it created, return- + ing an error if it was not.. mvderwin - returns an error if the window pointer is null, or if - some part of the window would be placed off-screen. + returns an error if the window pointer is null, or if some part of + the window would be placed off-screen. mvwin - returns an error if the window pointer is null, or if - the window is really a pad, or if some part of the - window would be placed off-screen. + returns an error if the window pointer is null, or if the window + is really a pad, or if some part of the window would be placed + off-screen. newwin - will fail if either of its beginning ordinates is - negative, or if either the number of lines or columns - is negative. + will fail if either of its beginning ordinates is negative, or if + either the number of lines or columns is negative. syncok returns an error if the window pointer is null. subwin - returns an error if the parent window pointer is - null, or if any of its ordinates or dimensions is - negative, or if the resulting window does not fit in- - side the parent window. + returns an error if the parent window pointer is null, or if any + of its ordinates or dimensions is negative, or if the resulting + window does not fit inside the parent window. - The functions which return a window pointer may also fail - if there is insufficient memory for its data structures. - Any of these functions will fail if the screen has not - been initialized, i.e., with initscr or newterm. + The functions which return a window pointer may also fail if there is + insufficient memory for its data structures. Any of these functions + will fail if the screen has not been initialized, i.e., with initscr or + newterm. --
- If many small changes are made to the window, the wsyncup - option could degrade performance. +
+ If many small changes are made to the window, the wsyncup option could + degrade performance. Note that syncok may be a macro. --
- The subwindow functions (subwin, derwin, mvderwin, wsyn- - cup, wsyncdown, wcursyncup, syncok) are flaky, incomplete- - ly implemented, and not well tested. - - The System V curses documentation is very unclear about - what wsyncup and wsyncdown actually do. It seems to imply - that they are only supposed to touch exactly those lines - that are affected by ancestor changes. The language here, - and the behavior of the curses implementation, is pat- - terned on the XPG4 curses standard. The weaker XPG4 spec +
+ The subwindow functions (subwin, derwin, mvderwin, wsyncup, wsyncdown, + wcursyncup, syncok) are flaky, incompletely implemented, and not well + tested. + + The System V curses documentation is very unclear about what wsyncup + and wsyncdown actually do. It seems to imply that they are only sup- + posed to touch exactly those lines that are affected by ancestor + changes. The language here, and the behavior of the curses implementa- + tion, is patterned on the XPG4 curses standard. The weaker XPG4 spec may result in slower updates. --
- The XSI Curses standard, Issue 4 describes these func- - tions. +
+ The XSI Curses standard, Issue 4 describes these functions. + X/Open Curses states regarding delwin: --
- curses(3x), curs_refresh(3x), curs_touch(3x), curs_vari- - ables(3x) + o It must delete subwindows before deleting their parent. + + o If delwin is asked to delete a parent window, it can only succeed + if the curses library keeps a list of the subwindows. SVr4 curses + kept a count of the number of subwindows rather than a list. It + simply returned ERR when asked to delete a subwindow. Solaris + X/Open curses does not even make that check, and will delete a par- + ent window which still has subwindows. + + o Since release 4.0 (1996), ncurses maintains a list of windows for + each screen, to ensure that a window has no subwindows before al- + lowing deletion. + + o NetBSD copied this feature of ncurses in 2003. + PDCurses follows the scheme used in Solaris X/Open curses. + + +
+ curses(3x), curs_initscr(3x), curs_refresh(3x), curs_touch(3x), + curs_variables(3x) - curs_window(3x) + curs_window(3x)-