man/curs_window.3x

   1 .\"***************************************************************************
   2 .\" Copyright 2020-2022,2023 Thomas E. Dickey                                *
   3 .\" Copyright 1998-2015,2016 Free Software Foundation, Inc.                  *
   4 .\"                                                                          *
   5 .\" Permission is hereby granted, free of charge, to any person obtaining a  *
   6 .\" copy of this software and associated documentation files (the            *
   7 .\" "Software"), to deal in the Software without restriction, including      *
   8 .\" without limitation the rights to use, copy, modify, merge, publish,      *
   9 .\" distribute, distribute with modifications, sublicense, and/or sell       *
  10 .\" copies of the Software, and to permit persons to whom the Software is    *
  11 .\" furnished to do so, subject to the following conditions:                 *
  12 .\"                                                                          *
  13 .\" The above copyright notice and this permission notice shall be included  *
  14 .\" in all copies or substantial portions of the Software.                   *
  15 .\"                                                                          *
  16 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS  *
  17 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF               *
  18 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.   *
  19 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,   *
  20 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR    *
  21 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR    *
  22 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE.                               *
  23 .\"                                                                          *
  24 .\" Except as contained in this notice, the name(s) of the above copyright   *
  25 .\" holders shall not be used in advertising or otherwise to promote the     *
  26 .\" sale, use or other dealings in this Software without prior written       *
  27 .\" authorization.                                                           *
  28 .\"***************************************************************************
  29 .\"
  30 .\" $Id: curs_window.3x,v 1.32 2023/07/01 15:46:10 tom Exp $
  31 .TH curs_window 3X 2023-07-01 "ncurses 6.4" "Library calls"
  32 .de bP
  33 .ie n  .IP \(bu 4
  34 .el    .IP \(bu 2
  35 ..
  36 .na
  37 .hy 0
  38 .SH NAME
  39 \fBnewwin\fP,
  40 \fBdelwin\fP,
  41 \fBmvwin\fP,
  42 \fBsubwin\fP,
  43 \fBderwin\fP,
  44 \fBmvderwin\fP,
  45 \fBdupwin\fP,
  46 \fBwsyncup\fP,
  47 \fBsyncok\fP,
  48 \fBwcursyncup\fP,
  49 \fBwsyncdown\fP \- create \fBcurses\fP windows
  50 .ad
  51 .hy
  52 .SH SYNOPSIS
  53 \fB#include <curses.h>\fP
  54 .sp
  55 \fBWINDOW *newwin(\fP
  56       \fBint \fInlines\fB, int \fIncols\fB,\fR
  57       \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
  58 .br
  59 \fBint delwin(WINDOW *\fIwin\fB);\fR
  60 .br
  61 \fBint mvwin(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR
  62 .br
  63 \fBWINDOW *subwin(WINDOW *\fIorig\fB,\fR
  64       \fBint \fInlines\fB, int \fIncols\fB,\fR
  65       \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
  66 .br
  67 \fBWINDOW *derwin(WINDOW *\fIorig\fB,\fR
  68       \fBint \fInlines\fB, int \fIncols\fB,\fR
  69       \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
  70 .br
  71 \fBint mvderwin(WINDOW *\fIwin\fB, int \fIpar_y\fB, int \fIpar_x\fB);\fR
  72 .br
  73 \fBWINDOW *dupwin(WINDOW *\fIwin\fB);\fR
  74 .br
  75 \fBvoid wsyncup(WINDOW *\fIwin\fB);\fR
  76 .br
  77 \fBint syncok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR
  78 .br
  79 \fBvoid wcursyncup(WINDOW *\fIwin\fB);\fR
  80 .br
  81 \fBvoid wsyncdown(WINDOW *\fIwin\fB);\fR
  82 .SH DESCRIPTION
  83 .SS newwin
  84 Calling \fBnewwin\fP creates and returns a pointer to a new window with the
  85 given number of lines and columns.
  86 The upper left-hand corner of the window is
  87 at
  88 .RS
  89 line \fIbegin\fR_\fIy\fP,
  90 .br
  91 column \fIbegin\fR_\fIx\fP
  92 .RE
  93 .PP
  94 If either
  95 \fInlines\fP or \fIncols\fP is zero, they default to
  96 .RS
  97 \fBLINES \-\fP \fIbegin\fR_\fIy\fP and
  98 .br
  99 \fBCOLS \-\fP \fIbegin\fR_\fIx\fP.
 100 .RE
 101 .PP
 102 A new full-screen window is created by calling \fBnewwin(0,0,0,0)\fP.
 103 .PP
 104 Regardless of the function used for creating a new window
 105 (e.g., \fBnewwin\fP, \fBsubwin\fP, \fBderwin\fP, \fBnewpad\fP),
 106 rather than a duplicate (with \fBdupwin\fP),
 107 all of the window modes are initialized to the default values.
 108 These functions set window modes after a window is created:
 109 .RS
 110 .na
 111 .PP
 112 idcok,
 113 idlok,
 114 immedok,
 115 keypad,
 116 leaveok,
 117 nodelay,
 118 scrollok,
 119 setscrreg,
 120 syncok,
 121 wbkgdset,
 122 wbkgrndset, and
 123 wtimeout
 124 .RE
 125 .ad
 126 .SS delwin
 127 Calling \fBdelwin\fP deletes the named window, freeing all memory
 128 associated with it (it does not actually erase the window's screen
 129 image).
 130 Subwindows must be deleted before the main window can be deleted.
 131 .SS mvwin
 132 Calling \fBmvwin\fP moves the window so that the upper left-hand
 133 corner is at position (\fIx\fP, \fIy\fP).
 134 If the move would cause the window to be off the screen,
 135 it is an error and the window is not moved.
 136 Moving subwindows is allowed, but should be avoided.
 137 .SS subwin
 138 Calling \fBsubwin\fP creates and returns a pointer to a new window
 139 with the given number of lines, \fInlines\fP, and columns, \fIncols\fP.
 140 The window is at position (\fIbegin\fR_\fIy\fP,
 141 \fIbegin\fR_\fIx\fP) on the screen.
 142 The subwindow shares memory with the window \fIorig\fP,
 143 so that changes made to one window
 144 will affect both windows.
 145 When using this routine, it is necessary to call
 146 \fBtouchwin\fP or \fBtouchline\fP on \fIorig\fP before calling
 147 \fBwrefresh\fP on the subwindow.
 148 .SS derwin
 149 Calling \fBderwin\fP is the same as calling \fBsubwin,\fP except that
 150 \fIbegin\fR_\fIy\fP and \fIbegin\fR_\fIx\fP are relative to the origin
 151 of the window \fIorig\fP rather than the screen.
 152 There is no difference between the subwindows and the derived windows.
 153 .PP
 154 Calling \fBmvderwin\fP moves a derived window (or subwindow)
 155 inside its parent window.
 156 The screen-relative parameters of the window are not changed.
 157 This routine is used to display different
 158 parts of the parent window at the same physical position on the
 159 screen.
 160 .SS dupwin
 161 Calling \fBdupwin\fP creates an exact duplicate of the window \fIwin\fP.
 162 .SS wsyncup
 163 Calling \fBwsyncup\fP touches all locations in ancestors of \fIwin\fP that are
 164 changed in \fIwin\fP.
 165 If \fBsyncok\fP is called with second argument
 166 \fBTRUE\fP then \fBwsyncup\fP is called automatically whenever there is a
 167 change in the window.
 168 .SS wsyncdown
 169 The \fBwsyncdown\fP routine touches each location in \fIwin\fP that has been
 170 touched in any of its ancestor windows.
 171 This routine is called by
 172 \fBwrefresh\fP, so it should almost never be necessary to call it manually.
 173 .SS wcursyncup
 174 The routine \fBwcursyncup\fP updates the current cursor position of all the
 175 ancestors of the window to reflect the current cursor position of the
 176 window.
 177 .SH RETURN VALUE
 178 Routines that return an integer return the integer \fBERR\fP upon failure and
 179 \fBOK\fP (SVr4 only specifies "an integer value other than \fBERR\fP") upon
 180 successful completion.
 181 .PP
 182 Routines that return pointers return \fBNULL\fP on error.
 183 .PP
 184 X/Open defines no error conditions.
 185 In this implementation
 186 .TP 5
 187 \fBdelwin\fP
 188 returns an error if the window pointer is null, or
 189 if the window is the parent of another window.
 190 .TP 5
 191 \fBderwin\fP
 192 returns an error if the parent window pointer is null, or
 193 if any of its ordinates or dimensions is negative, or
 194 if the resulting window does not fit inside the parent window.
 195 .TP 5
 196 \fBdupwin\fP
 197 returns an error if the window pointer is null.
 198 .IP
 199 This implementation also maintains a list of windows,
 200 and checks that the pointer passed to \fBdelwin\fP is one that
 201 it created, returning an error if it was not..
 202 .TP 5
 203 \fBmvderwin\fP
 204 returns an error
 205 if the window pointer is null, or
 206 if some part of the window would be placed off-screen.
 207 .TP 5
 208 \fBmvwin\fP
 209 returns an error
 210 if the window pointer is null, or
 211 if the window is really a pad, or
 212 if some part of the window would be placed off-screen.
 213 .TP 5
 214 \fBnewwin\fP
 215 will fail if either of its beginning ordinates is negative, or
 216 if either the number of lines or columns is negative.
 217 .TP 5
 218 \fBsyncok\fP
 219 returns an error
 220 if the window pointer is null.
 221 .TP 5
 222 \fBsubwin\fP
 223 returns an error if the parent window pointer is null, or
 224 if any of its ordinates or dimensions is negative, or
 225 if the resulting window does not fit inside the parent window.
 226 .PP
 227 The functions which return a window pointer
 228 may also fail if there is insufficient memory for its data structures.
 229 Any of these functions will fail if the screen has not been initialized,
 230 i.e., with \fBinitscr\fP or \fBnewterm\fP.
 231 .SH NOTES
 232 If many small changes are made to the window, the \fBwsyncup\fP option could
 233 degrade performance.
 234 .PP
 235 Note that \fBsyncok\fP may be a macro.
 236 .SH BUGS
 237 The subwindow functions (\fBsubwin\fP, \fBderwin\fP, \fBmvderwin\fP,
 238 \fBwsyncup\fP, \fBwsyncdown\fP, \fBwcursyncup\fP, \fBsyncok\fP) are flaky,
 239 incompletely implemented, and not well tested.
 240 .PP
 241 The System V curses documentation is very unclear about what \fBwsyncup\fP
 242 and \fBwsyncdown\fP actually do.
 243 It seems to imply that they are only
 244 supposed to touch exactly those lines that are affected by ancestor changes.
 245 The language here, and the behavior of the \fBcurses\fP implementation,
 246 is patterned on the XPG4 curses standard.
 247 The weaker XPG4 spec may result in slower updates.
 248 .SH PORTABILITY
 249 The XSI Curses standard, Issue 4 describes these functions.
 250 .PP
 251 X/Open Curses states regarding \fBdelwin\fP:
 252 .bP
 253 It must delete subwindows before deleting their parent.
 254 .bP
 255 If \fBdelwin\fP is asked to delete a parent window,
 256 it can only succeed if the curses library keeps a list of the subwindows.
 257 SVr4 curses kept a count of the number of subwindows rather than a list.
 258 It simply returned \fBERR\fP when asked to delete a subwindow.
 259 Solaris X/Open curses does not even make that check,
 260 and will delete a parent window which still has subwindows.
 261 .bP
 262 Since release 4.0 (1996), ncurses maintains a list of windows for each screen,
 263 to ensure that a window has no subwindows before allowing deletion.
 264 .bP
 265 NetBSD copied this feature of ncurses in 2003.
 266 .br
 267 PDCurses follows the scheme used in Solaris X/Open curses.
 268 .SH SEE ALSO
 269 \fBcurses\fP(3X),
 270 \fBcurs_initscr\fP(3X),
 271 \fBcurs_refresh\fP(3X),
 272 \fBcurs_touch\fP(3X),
 273 \fBcurs_variables\fP(3X)