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(
13 int nlines, int ncols,
14 int begin_y, int begin_x);
15 int delwin(WINDOW *win);
16 int mvwin(WINDOW *win, int y, int x);
17 WINDOW *subwin(WINDOW *orig,
18 int nlines, int ncols,
19 int begin_y, int begin_x);
20 WINDOW *derwin(WINDOW *orig,
21 int nlines, int ncols,
22 int begin_y, int begin_x);
23 int mvderwin(WINDOW *win, int par_y, int par_x);
24 WINDOW *dupwin(WINDOW *win);
25 void wsyncup(WINDOW *win);
26 int syncok(WINDOW *win, bool bf);
27 void wcursyncup(WINDOW *win);
28 void wsyncdown(WINDOW *win);
29
31 newwin
32 Calling newwin creates and returns a pointer to a new window with the
33 given number of lines and columns. The upper left-hand corner of the
34 window is at
35 line begin_y,
36 column begin_x
37 If either nlines or ncols is zero, they default to
39 LINES - begin_y and
40 COLS - begin_x.
41 A new full-screen window is created by calling newwin(0,0,0,0).
43 delwin
45 Calling delwin deletes the named window, freeing all memory associated
46 with it (it does not actually erase the window's screen image). Sub‐
47 windows must be deleted before the main window can be deleted.
48 mvwin
50 Calling mvwin moves the window so that the upper left-hand corner is at
51 position (x, y). If the move would cause the window to be off the
52 screen, it is an error and the window is not moved. Moving subwindows
53 is allowed, but should be avoided.
54 subwin
56 Calling subwin creates and returns a pointer to a new window with the
57 given number of lines, nlines, and columns, ncols. The window is at
58 position (begin_y, begin_x) on the screen. The subwindow shares memory
59 with the window orig, so that changes made to one window will affect
60 both windows. When using this routine, it is necessary to call touch‐
61 win or touchline on orig before calling wrefresh on the subwindow.
62 derwin
64 Calling derwin is the same as calling subwin, except that begin_y and
65 begin_x are relative to the origin of the window orig rather than the
66 screen. There is no difference between the subwindows and the derived
67 windows.
68 Calling mvderwin moves a derived window (or subwindow) inside its par‐
70 ent window. The screen-relative parameters of the window are not
71 changed. This routine is used to display different parts of the parent
72 window at the same physical position on the screen.
73 dupwin
75 Calling dupwin creates an exact duplicate of the window win.
76 wsyncup
78 Calling wsyncup touches all locations in ancestors of win that are
79 changed in win. If syncok is called with second argument TRUE then
80 wsyncup is called automatically whenever there is a change in the win‐
81 dow.
82 wsyncdown
84 The wsyncdown routine touches each location in win that has been
85 touched in any of its ancestor windows. This routine is called by wre‐
86 fresh, so it should almost never be necessary to call it manually.
87 wcursyncup
89 The routine wcursyncup updates the current cursor position of all the
90 ancestors of the window to reflect the current cursor position of the
91 window.
92
94 Routines that return an integer return the integer ERR upon failure and
95 OK (SVr4 only specifies "an integer value other than ERR") upon suc‐
96 cessful completion.
97 Routines that return pointers return NULL on error.
99 X/Open defines no error conditions. In this implementation
101 delwin
103 returns an error if the window pointer is null, or if the window
104 is the parent of another window.
105 derwin
107 returns an error if the parent window pointer is null, or if any
108 of its ordinates or dimensions is negative, or if the resulting
109 window does not fit inside the parent window.
110 dupwin
112 returns an error if the window pointer is null.
113 This implementation also maintains a list of windows, and checks
115 that the pointer passed to delwin is one that it created, return‐
116 ing an error if it was not..
117 mvderwin
119 returns an error if the window pointer is null, or if some part of
120 the window would be placed off-screen.
121 mvwin
123 returns an error if the window pointer is null, or if the window
124 is really a pad, or if some part of the window would be placed
125 off-screen.
126 newwin
128 will fail if either of its beginning ordinates is negative, or if
129 either the number of lines or columns is negative.
130 syncok
132 returns an error if the window pointer is null.
133 subwin
135 returns an error if the parent window pointer is null, or if any
136 of its ordinates or dimensions is negative, or if the resulting
137 window does not fit inside the parent window.
138 The functions which return a window pointer may also fail if there is
140 insufficient memory for its data structures. Any of these functions
141 will fail if the screen has not been initialized, i.e., with initscr or
142 newterm.
143
145 If many small changes are made to the window, the wsyncup option could
146 degrade performance.
147 Note that syncok may be a macro.
149
151 The subwindow functions (subwin, derwin, mvderwin, wsyncup, wsyncdown,
152 wcursyncup, syncok) are flaky, incompletely implemented, and not well
153 tested.
154 The System V curses documentation is very unclear about what wsyncup
156 and wsyncdown actually do. It seems to imply that they are only sup‐
157 posed to touch exactly those lines that are affected by ancestor
158 changes. The language here, and the behavior of the curses implementa‐
159 tion, is patterned on the XPG4 curses standard. The weaker XPG4 spec
160 may result in slower updates.
161
163 The XSI Curses standard, Issue 4 describes these functions.
164
166 curses(3X), curs_refresh(3X), curs_touch(3X), curs_variables(3X)
167 curs_window(3X)