man/curs_pad.3x

   1 .\"***************************************************************************
   2 .\" Copyright 2018-2023,2024 Thomas E. Dickey                                *
   3 .\" Copyright 1998-2015,2017 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_pad.3x,v 1.65 2024/06/22 22:20:03 tom Exp $
  31 .TH curs_pad 3X 2024-06-22 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
  32 .ie \n(.g \{\
  33 .ds `` \(lq
  34 .ds '' \(rq
  35 .\}
  36 .el \{\
  37 .ie t .ds `` ``
  38 .el   .ds `` ""
  39 .ie t .ds '' ''
  40 .el   .ds '' ""
  41 .\}
  42 .
  43 .de bP
  44 .ie n  .IP \(bu 4
  45 .el    .IP \(bu 2
  46 ..
  47 .SH NAME
  48 \fB\%newpad\fP,
  49 \fB\%subpad\fP,
  50 \fB\%prefresh\fP,
  51 \fB\%pnoutrefresh\fP,
  52 \fB\%pechochar\fP,
  53 \fB\%pecho_wchar\fP \-
  54 create and display \fIcurses\fR pads
  55 .SH SYNOPSIS
  56 .nf
  57 \fB#include <curses.h>
  58 .PP
  59 \fBWINDOW *newpad(int \fInlines\fP, int \fIncols\fP);
  60 \fBWINDOW *subpad(WINDOW *\fIparent\fP, int \fInlines\fP, int \fIncols\fP,
  61       \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
  62 .PP
  63 \fBint prefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR
  64       \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int \fIsmaxcol\fB);\fR
  65 \fBint pnoutrefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR
  66       \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int \fIsmaxcol\fB);\fR
  67 .PP
  68 \fBint pechochar(WINDOW *\fIpad\fB, chtype \fIch\fB);\fR
  69 \fBint pecho_wchar(WINDOW *\fIpad\fB, const cchar_t *\fIwch\fB);\fR
  70 .fi
  71 .SH DESCRIPTION
  72 A
  73 .I curses
  74 .I pad
  75 is like a window,
  76 except that it is not restricted by the screen size,
  77 and is not necessarily associated with a particular part of the screen.
  78 Pads can be used when a large window is needed,
  79 only part of which is to be visible on the screen.
  80 Pads are not automatically refreshed by scrolling or input-echoing
  81 operations.
  82 .PP
  83 Pads cannot be refreshed with \fB\%wrefresh\fP(3X);
  84 use
  85 .B \%prefresh
  86 or
  87 .B \%pnoutrefresh
  88 instead.
  89 .SS newpad
  90 .B \%newpad
  91 creates and returns a pointer to a new pad data structure
  92 with the given number of lines,
  93 .IR nlines ,
  94 and columns,
  95 .IR ncols .
  96 .SS subpad
  97 .B \%subpad
  98 creates and returns a pointer to a subwindow within a pad
  99 with the given number of lines,
 100 .IR nlines ,
 101 and columns,
 102 .IR ncols .
 103 Unlike \fB\%subwin\fP(3X),
 104 which uses screen coordinates,
 105 the new pad is placed at position
 106 .RI ( begin_y ,
 107 .IR begin_x )
 108 relative to its parent.
 109 Thus,
 110 changes made to one pad can affect both.
 111 When operating on a subpad,
 112 it is often necessary to call \fB\%touchwin\fP(3X) or
 113 \fB\%touchline\fP(3X) on
 114 .I parent
 115 before calling
 116 .BR \%prefresh .
 117 .SS "prefresh, pnoutrefresh"
 118 .B \%prefresh
 119 and
 120 .B \%pnoutrefresh
 121 are analogous to \fB\%wrefresh\fP(3X) and \fB\%wnoutrefresh\fP(3X)
 122 except that they operate on pads rather than windows.
 123 They require additional parameters are needed to indicate what portions
 124 of the pad and screen are involved.
 125 .bP
 126 .I pminrow
 127 and
 128 .I pmincol
 129 specify the upper left-hand corner of a rectangular view of the pad.
 130 .bP
 131 .IR sminrow ,
 132 .IR smincol ,
 133 .IR smaxrow ,
 134 and
 135 .I smaxcol
 136 specify the vertices of the rectangle to be displayed on the screen.
 137 .PP
 138 The lower right-hand corner
 139 of the rectangle to be displayed in the pad
 140 is calculated from the screen coordinates,
 141 since the rectangles must be the same size.
 142 Both rectangles must be entirely contained
 143 within their respective structures.
 144 .I curses
 145 treats
 146 negative values of any of these parameters as zero.
 147 .SS pechochar
 148 .B \%pechochar
 149 is functionally equivalent to calling \fB\%waddch\fP(3X) followed by
 150 .BR \%prefresh .
 151 It suggests to the
 152 .I curses
 153 optimizer that only a single character is being output;
 154 a considerable performance benefit may be thus enjoyed.
 155 The location of the character
 156 .I ch
 157 written to the pad is used to populate the arguments to
 158 .BR \%prefresh .
 159 .SS pecho_wchar
 160 .B \%pecho_wchar
 161 is functionally equivalent to calling \fB\%wadd_wch\fP(3X) followed by
 162 .BR \%prefresh .
 163 It suggests to the
 164 .I curses
 165 optimizer that only a single wide character is being output;
 166 a considerable performance benefit may be thus enjoyed.
 167 The location of the character
 168 .I wch
 169 written to the pad is used to populate the arguments to
 170 .BR \%prefresh .
 171 .SH RETURN VALUE
 172 Functions that return an integer return
 173 .B ERR
 174 upon failure and
 175 .B OK
 176 (SVr4 specifies only
 177 \*(``an integer value other than
 178 .BR ERR \*('')
 179 upon successful completion.
 180 .PP
 181 Functions that return pointers return
 182 .B NULL
 183 on error,
 184 and set
 185 .I \%errno
 186 to
 187 .BR \%ENOMEM "."
 188 .PP
 189 X/Open Curses does not specify any error conditions.
 190 In this implementation
 191 .RS 3
 192 .TP 5
 193 .BR prefresh\  and\  pnoutrefresh
 194 return
 195 .B ERR
 196 if the window pointer is null, or
 197 if the window is not really a pad or
 198 if the area to refresh extends off-screen or
 199 if the minimum coordinates are greater than the maximum.
 200 .TP 5
 201 .B pechochar
 202 returns
 203 .B ERR
 204 if the window is not really a pad,
 205 and the associated call to
 206 .B \%wechochar
 207 returns
 208 .BR ERR "."
 209 .TP 5
 210 .B pecho_wchar
 211 returns
 212 .B ERR
 213 if the window is not really a pad,
 214 and the associated call to
 215 .B \%wecho_wchar
 216 returns
 217 .BR ERR "."
 218 .RE
 219 .SH NOTES
 220 .B \%pechochar
 221 may be a macro.
 222 .SH PORTABILITY
 223 BSD
 224 .I curses
 225 has no
 226 .I pad
 227 feature.
 228 .PP
 229 SVr2 \fIcurses\fP (1986) provided the \fB\%newpad\fP and related functions,
 230 documenting them in a single line each.
 231 SVr3 (1987) provided more extensive documentation.
 232 .PP
 233 The documentation does not explain the term \fIpad\fP.
 234 However, the Apollo \fIAegis\fP workstation operating system
 235 supported a graphical \fIpad\fP feature:
 236 .bP
 237 These graphical pads could be much larger than the computer's display.
 238 .bP
 239 The read-only output from a command could be scrolled back to inspect,
 240 and select text from the pad.
 241 .PP
 242 The two uses may be related.
 243 .PP
 244 X/Open Curses, Issue 4 describes these functions,
 245 without significant change from the SVr3 documentation.
 246 It describes no error conditions.
 247 The behavior of \fB\%subpad\fP if the parent window is not
 248 a pad is undocumented,
 249 and is not checked by the vendor Unix implementations:
 250 .bP
 251 SVr4 \fIcurses\fP sets a flag in the \fI\%WINDOW\fP structure in
 252 \fB\%newpad\fP which tells if the window is a \fIpad\fP.
 253 .IP
 254 However, it uses this information only in
 255 \fB\%waddch\fP (to decide if it should call \fB\%wrefresh\fP) and
 256 \fB\%wscrl\fP (to avoid scrolling a pad),
 257 and does not check in \fB\%wrefresh\fP to ensure that the pad
 258 is refreshed properly.
 259 .bP
 260 Solaris \fI\%xcurses\fP checks whether a window is a pad in
 261 \fB\%wnoutrefresh\fP,
 262 returning \fBERR\fP in that case.
 263 .IP
 264 However,
 265 it only sets the flag for subwindows if the parent window is a pad.
 266 Its \fB\%newpad\fP function does not set this information.
 267 Consequently, the check will never fail.
 268 .IP
 269 It makes no comparable check in \fB\%pnoutrefresh\fP,
 270 though interestingly enough, a comment in the source code
 271 states that the lack of a check was an MKS extension.
 272 .bP
 273 NetBSD 7 \fIcurses\fP
 274 sets a flag in the \fI\%WINDOW\fP structure
 275 for \fB\%newpad\fP and \fB\%subpad\fP,
 276 using this to help with the distinction between \fB\%wnoutrefresh\fP
 277 and \fB\%pnoutrefresh\fP.
 278 .IP
 279 It does not check for the case where a subwindow is created in
 280 a pad using \fB\%subwin\fP or \fB\%derwin\fP.
 281 .IP
 282 The \fB\%dupwin\fP function returns a regular window when duplicating a pad.
 283 Likewise, \fB\%getwin\fP always returns a window, even if the saved
 284 data was from a pad.
 285 .PP
 286 This implementation
 287 .bP
 288 sets a flag in the \fI\%WINDOW\fP structure
 289 for \fB\%newpad\fP and \fB\%subpad\fP,
 290 .bP
 291 allows a \fB\%subwin\fP or \fB\%derwin\fP call to succeed having a pad parent by
 292 forcing the subwindow to be a pad,
 293 .bP
 294 checks in both \fB\%wnoutrefresh\fP and \fB\%pnoutrefresh\fP to ensure
 295 that pads and windows are handled distinctly, and
 296 .bP
 297 ensures that \fB\%dupwin\fP and \fB\%getwin\fP treat
 298 pads versus windows consistently.
 299 .SH SEE ALSO
 300 \fB\%curses\fP(3X),
 301 \fB\%curs_addch\fP(3X),
 302 \fB\%curs_refresh\fP(3X),
 303 \fB\%curs_touch\fP(3X)