ncurses 4.1
[ncurses.git] / man / curs_window.3x
1 .TH curs_window 3X ""
2 .SH NAME
3 \fBnewwin\fR, \fBdelwin\fR, \fBmvwin\fR,
4 \fBsubwin\fR, \fBderwin\fR, \fBmvderwin\fR, \fBdupwin\fR,
5 \fBwsyncup\fR, \fBsyncok\fR, \fBwcursyncup\fR, \fBwsyncdown\fR -
6 create \fBcurses\fR windows
7 .SH SYNOPSIS
8 \fB#include <curses.h>\fR
9
10 \fBWINDOW *newwin(int nlines, int ncols, int begin_y,\fR
11       \fBintbegin_x);\fR
12 .br
13 \fBint delwin(WINDOW *win);\fR
14 .br
15 \fBint mvwin(WINDOW *win, int y, int x);\fR
16 .br
17 \fBWINDOW *subwin(WINDOW *orig, int nlines, int ncols,
18       int begin_y, int begin_x);\fR
19 .br
20 \fBWINDOW *derwin(WINDOW *orig, int nlines, int ncols,
21       int begin_y, int begin_x);\fR
22 .br
23 \fBint mvderwin(WINDOW *win, int par_y, int par_x);\fR
24 .br
25 \fBWINDOW *dupwin(WINDOW *win);\fR
26 .br
27 \fBvoid wsyncup(WINDOW *win);\fR
28 .br
29 \fBint syncok(WINDOW *win, bool bf);\fR
30 .br
31 \fBvoid wcursyncup(WINDOW *win);\fR
32 .br
33 \fBvoid wsyncdown(WINDOW *win);\fR
34 .br
35 .SH DESCRIPTION
36 Calling \fBnewwin\fR creates and returns a pointer to a new window with the
37 given number of lines and columns.  The upper left-hand corner of the window is
38 at line \fIbegin\fR_\fIy\fR, column \fIbegin\fR_\fIx\fR.  If either
39 \fInlines\fR or \fIncols\fR is zero, they default to \fBLINES -\fR
40 \fIbegin\fR_\fIy\fR and \fBCOLS -\fR \fIbegin\fR_\fIx\fR.  A new full-screen
41 window is created by calling \fBnewwin(0,0,0,0)\fR.
42
43 Calling \fBdelwin\fR deletes the named window, freeing all memory
44 associated with it (it does not actually erase the window's screen
45 image).  Subwindows must be deleted before the main window can be
46 deleted.
47
48 Calling \fBmvwin\fR moves the window so that the upper left-hand
49 corner is at position (\fIx\fR, \fIy\fR).  If the move would cause the
50 window to be off the screen, it is an error and the window is not
51 moved.  Moving subwindows is allowed, but should be avoided.
52
53 Calling \fBsubwin\fR creates and returns a pointer to a new window
54 with the given number of lines, \fInlines\fR, and columns,
55 \fIncols\fR.  The window is at position (\fIbegin\fR_\fIy\fR,
56 \fIbegin\fR_\fIx\fR) on the screen.  (This position is relative to the
57 screen, and not to the window \fIorig\fR.)  The window is made in the
58 middle of the window \fIorig\fR, so that changes made to one window
59 will affect both windows.  The subwindow shares memory with the window
60 \fIorig\fR.  When using this routine, it is necessary to call
61 \fBtouchwin\fR or \fBtouchline\fR on \fIorig\fR before calling
62 \fBwrefresh\fR on the subwindow.
63
64 Calling \fBderwin\fR is the same as calling \fBsubwin,\fR except that
65 \fIbegin\fR_\fIy\fR and \fIbegin\fR_\fIx\fR are relative to the origin
66 of the window \fIorig\fR rather than the screen.  There is no
67 difference between the subwindows and the derived windows.
68
69 Calling \fBmvderwin\fR moves a derived window (or subwindow)
70 inside its parent window.  The screen-relative parameters of the
71 window are not changed.  This routine is used to display different
72 parts of the parent window at the same physical position on the
73 screen.
74
75 Calling \fBdupwin\fR creates an exact duplicate of the window \fIwin\fR.
76
77 Calling \fBwsyncup\fR touches all locations in ancestors of \fIwin\fR that are
78 changed in \fIwin\fR.  If \fBsyncok\fR is called with second argument
79 \fBTRUE\fR then \fBwsyncup\fR is called automatically whenever there is a
80 change in the window.
81
82 The \fBwsyncdown\fR routine touches each location in \fIwin\fR that has been
83 touched in any of its ancestor windows.  This routine is called by
84 \fBwrefresh\fR, so it should almost never be necessary to call it manually.
85
86 The routine \fBwcursyncup\fR updates the current cursor position of all the
87 ancestors of the window to reflect the current cursor position of the
88 window.
89 .SH RETURN VALUE
90 Routines that return an integer return the integer \fBERR\fR upon failure and
91 \fBOK\fR (SVr4 only specifies "an integer value other than \fBERR\fR") upon
92 successful completion.
93
94 \fBdelwin\fR returns the integer \fBERR\fR upon failure and \fBOK\fR
95 upon successful completion.
96
97 Routines that return pointers return \fBNULL\fR on error.
98 .SH NOTES
99 If many small changes are made to the window, the \fBwsyncup\fR option could
100 degrade performance.
101
102 Note that \fBsyncok\fR may be a macro.
103 .SH BUGS
104 The subwindow functions (\fIsubwin\fR, \fIderwin\fR, \fImvderwin\fR,
105 \fBwsyncup\fR, \fBwsyncdown\fR, \fBwcursyncup\fR, \fBsyncok\fR) are flaky,
106 incompletely implemented, and not well tested.
107
108 The System V curses documentation is very unclear about what \fBwsyncup\fR
109 and \fBwsyncdown\fR actually do.  It seems to imply that they are only 
110 supposed to touch exactly those lines that are affected by ancestor changes.
111 The language here, and the behavior of the \fBcurses\fR implementation,
112 is patterned on the XPG4 curses standard.  The weaker XPG4 spec may result
113 in slower updates.
114 .SH PORTABILITY
115 The XSI Curses standard, Issue 4 describes these functions.
116 .SH SEE ALSO
117 \fBcurses\fR(3X), \fBcurs_refresh\fR(3X), \fBcurs_touch\fR(3X)
118 .\"#
119 .\"# The following sets edit modes for GNU EMACS
120 .\"# Local Variables:
121 .\"# mode:nroff
122 .\"# fill-column:79
123 .\"# End: