1curs_window(3X) curs_window(3X)
2
6 newwin, delwin, mvwin, subwin, derwin, mvderwin, dupwin, wsyncup,
7 syncok, wcursyncup, wsyncdown - create curses windows
8
10 #include <curses.h>
11 WINDOW *newwin(int nlines, int ncols, int begin_y,
13 int begin_x);
14 int delwin(WINDOW *win);
15 int mvwin(WINDOW *win, int y, int x);
16 WINDOW *subwin(WINDOW *orig, int nlines, int ncols,
17 int begin_y, int begin_x);
18 WINDOW *derwin(WINDOW *orig, int nlines, int ncols,
19 int begin_y, int begin_x);
20 int mvderwin(WINDOW *win, int par_y, int par_x);
21 WINDOW *dupwin(WINDOW *win);
22 void wsyncup(WINDOW *win);
23 int syncok(WINDOW *win, bool bf);
24 void wcursyncup(WINDOW *win);
25 void wsyncdown(WINDOW *win);
26
28 Calling newwin creates and returns a pointer to a new window with the
29 given number of lines and columns. The upper left-hand corner of the
30 window is at line begin_y, column begin_x. If either nlines or ncols
31 is zero, they default to LINES - begin_y and COLS - begin_x. A new
32 full-screen window is created by calling newwin(0,0,0,0).
33 Calling delwin deletes the named window, freeing all memory associated
35 with it (it does not actually erase the window's screen image). Sub‐
36 windows must be deleted before the main window can be deleted.
37 Calling mvwin moves the window so that the upper left-hand corner is at
39 position (x, y). If the move would cause the window to be off the
40 screen, it is an error and the window is not moved. Moving subwindows
41 is allowed, but should be avoided.
42 Calling subwin creates and returns a pointer to a new window with the
44 given number of lines, nlines, and columns, ncols. The window is at
45 position (begin_y, begin_x) on the screen. (This position is relative
46 to the screen, and not to the window orig.) The window is made in the
47 middle of the window orig, so that changes made to one window will af‐
48 fect both windows. The subwindow shares memory with the window orig.
49 When using this routine, it is necessary to call touchwin or touchline
50 on orig before calling wrefresh on the subwindow.
51 Calling derwin is the same as calling subwin, except that begin_y and
53 begin_x are relative to the origin of the window orig rather than the
54 screen. There is no difference between the subwindows and the derived
55 windows.
56 Calling mvderwin moves a derived window (or subwindow) inside its par‐
58 ent window. The screen-relative parameters of the window are not
59 changed. This routine is used to display different parts of the parent
60 window at the same physical position on the screen.
61 Calling dupwin creates an exact duplicate of the window win.
63 Calling wsyncup touches all locations in ancestors of win that are
65 changed in win. If syncok is called with second argument TRUE then
66 wsyncup is called automatically whenever there is a change in the win‐
67 dow.
68 The wsyncdown routine touches each location in win that has been
70 touched in any of its ancestor windows. This routine is called by wre‐
71 fresh, so it should almost never be necessary to call it manually.
72 The routine wcursyncup updates the current cursor position of all the
74 ancestors of the window to reflect the current cursor position of the
75 window.
76
78 Routines that return an integer return the integer ERR upon failure and
79 OK (SVr4 only specifies "an integer value other than ERR") upon suc‐
80 cessful completion.
81 Routines that return pointers return NULL on error.
83 X/Open defines no error conditions. In this implementation
85 delwin
87 returns an error if the window pointer is null, or if the
88 window is the parent of another window.
89 This implementation also maintains a list of windows, and
91 checks that the pointer passed to delwin is one that it
92 created, returning an error if it was not..
93 mvderwin
95 returns an error if the window pointer is null, or if some
96 part of the window would be placed off-screen.
97 mvwin
99 returns an error if the window pointer is null, or if the
100 window is really a pad, or if some part of the window would
101 be placed off-screen.
102 syncok
104 returns an error if the window pointer is null.
105
107 If many small changes are made to the window, the wsyncup option could
108 degrade performance.
109 Note that syncok may be a macro.
111
113 The subwindow functions (subwin, derwin, mvderwin, wsyncup, wsyncdown,
114 wcursyncup, syncok) are flaky, incompletely implemented, and not well
115 tested.
116 The System V curses documentation is very unclear about what wsyncup
118 and wsyncdown actually do. It seems to imply that they are only sup‐
119 posed to touch exactly those lines that are affected by ancestor
120 changes. The language here, and the behavior of the curses implementa‐
121 tion, is patterned on the XPG4 curses standard. The weaker XPG4 spec
122 may result in slower updates.
123
125 The XSI Curses standard, Issue 4 describes these functions.
126
128 curses(3X), curs_refresh(3X), curs_touch(3X)
129 curs_window(3X)