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.57 2024/04/13 22:13:17 tom Exp $
  31 .TH curs_pad 3X 2024-04-13 "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 \fB\%newpad\fP creates and returns a pointer to a new pad data structure
  91 with the given number of lines,
  92 .IR nlines ,
  93 and columns,
  94 .IR ncols .
  95 .SS subpad
  96 .B \%subpad
  97 creates and returns a pointer to a subwindow within a pad
  98 with the given number of lines,
  99 .IR nlines ,
 100 and columns,
 101 .IR ncols .
 102 Unlike \fB\%subwin\fP(3X),
 103 which uses screen coordinates,
 104 the new pad is placed at position
 105 .RI ( begin_y ,
 106 .IR begin_x )
 107 relative to its parent.
 108 Thus,
 109 changes made to one pad can affect both.
 110 When operating on a subpad,
 111 it is often necessary to call \fB\%touchwin\fP(3X) or
 112 \fB\%touchline\fP(3X) on
 113 .I parent
 114 before calling
 115 .BR \%prefresh .
 116 .SS "prefresh, pnoutrefresh"
 117 .B \%prefresh\fP
 118 and
 119 .B \%pnoutrefresh
 120 are analogous to \fB\%wrefresh\fP(3X) and \fB\%wnoutrefresh\fP(3X)
 121 except that they operate on pads rather than windows.
 122 They require additional parameters are needed to indicate what portions
 123 of the pad and screen are involved.
 124 .bP
 125 .I pminrow
 126 and
 127 .I pmincol
 128 specify the upper left-hand corner of a rectanglar view of the pad.
 129 .bP
 130 .IR sminrow ,
 131 .IR smincol ,
 132 .IR smaxrow ,
 133 and
 134 .I smaxcol
 135 specify the vertices of the rectangle to be displayed on the screen.
 136 .PP
 137 The lower right-hand corner
 138 of the rectangle to be displayed in the pad
 139 is calculated from the screen coordinates,
 140 since the rectangles must be the same size.
 141 Both rectangles must be entirely contained
 142 within their respective structures.
 143 .I curses
 144 treats
 145 negative values of any of these parameters as zero.
 146 .SS pechochar
 147 .B \%pechochar
 148 is functionally equivalent to calling \fB\%waddch\fP(3X) followed by
 149 .BR \%prefresh .
 150 It suggests to the
 151 .I curses
 152 optimizer that only a single character is being output;
 153 a considerable performance benefit may be thus enjoyed.
 154 The location of the character
 155 .I ch
 156 written to the pad is used to populate the arguments to
 157 .BR \%prefresh .
 158 .SS pecho_wchar
 159 .B \%pecho_wchar\fP
 160 is functionally equivalent to calling \fB\%wadd_wch\fP(3X) followed by
 161 .BR \%prefresh .
 162 It suggests to the
 163 .I curses
 164 optimizer that only a single wide character is being output;
 165 a considerable performance benefit may be thus enjoyed.
 166 The location of the character
 167 .I wch
 168 written to the pad is used to populate the arguments to
 169 .BR \%prefresh .
 170 .SH RETURN VALUE
 171 Functions that return an integer return \fBERR\fP upon failure and
 172 \fBOK\fP
 173 (SVr4 specifies only
 174 \*(``an integer value other than \fBERR\fP\*('')
 175 upon successful completion.
 176 .PP
 177 Functions that return pointers return \fBNULL\fP on error,
 178 and set \fB\%errno\fP to \fB\%ENOMEM\fP.
 179 .PP
 180 X/Open Curses does not specify any error conditions.
 181 In this implementation
 182 .RS 3
 183 .TP 5
 184 \fB\%prefresh\fP and \fB\%pnoutrefresh\fP
 185 return an error
 186 if the window pointer is null, or
 187 if the window is not really a pad or
 188 if the area to refresh extends off-screen or
 189 if the minimum coordinates are greater than the maximum.
 190 .TP 5
 191 \fBpechochar\fP
 192 returns an error
 193 if the window is not really a pad, and the associated call
 194 to \fB\%wechochar\fP returns an error.
 195 .TP 5
 196 \fBpecho_wchar\fP
 197 returns an error
 198 if the window is not really a pad, and the associated call
 199 to \fB\%wecho_wchar\fP returns an error.
 200 .RE
 201 .SH NOTES
 202 \fB\%pechochar\fP may be a macro.
 203 .SH PORTABILITY
 204 BSD \fIcurses\fP has no \fIpad\fP feature.
 205 .PP
 206 SVr2 \fIcurses\fP (1986) provided the \fB\%newpad\fP and related functions,
 207 documenting them in a single line each.
 208 SVr3 (1987) provided more extensive documentation.
 209 .PP
 210 The documentation does not explain the term \fIpad\fP.
 211 However, the Apollo \fIAegis\fP workstation operating system
 212 supported a graphical \fIpad\fP feature:
 213 .bP
 214 These graphical pads could be much larger than the computer's display.
 215 .bP
 216 The read-only output from a command could be scrolled back to inspect,
 217 and select text from the pad.
 218 .PP
 219 The two uses may be related.
 220 .PP
 221 The XSI Curses standard, Issue 4 describes these functions,
 222 without significant change from the SVr3 documentation.
 223 It describes no error conditions.
 224 The behavior of \fB\%subpad\fP if the parent window is not
 225 a pad is undocumented,
 226 and is not checked by the vendor Unix implementations:
 227 .bP
 228 SVr4 \fIcurses\fP sets a flag in the \fI\%WINDOW\fP structure in
 229 \fB\%newpad\fP which tells if the window is a \fIpad\fP.
 230 .IP
 231 However, it uses this information only in
 232 \fB\%waddch\fP (to decide if it should call \fB\%wrefresh\fP) and
 233 \fB\%wscrl\fP (to avoid scrolling a pad),
 234 and does not check in \fB\%wrefresh\fP to ensure that the pad
 235 is refreshed properly.
 236 .bP
 237 Solaris \fI\%xcurses\fP checks whether a window is a pad in
 238 \fB\%wnoutrefresh\fP,
 239 returning \fBERR\fP in that case.
 240 .IP
 241 However,
 242 it only sets the flag for subwindows if the parent window is a pad.
 243 Its \fB\%newpad\fP function does not set this information.
 244 Consequently, the check will never fail.
 245 .IP
 246 It makes no comparable check in \fB\%pnoutrefresh\fP,
 247 though interestingly enough, a comment in the source code
 248 states that the lack of a check was an MKS extension.
 249 .bP
 250 NetBSD 7 \fIcurses\fP
 251 sets a flag in the \fI\%WINDOW\fP structure
 252 for \fB\%newpad\fP and \fB\%subpad\fP,
 253 using this to help with the distinction between \fB\%wnoutrefresh\fP
 254 and \fB\%pnoutrefresh\fP.
 255 .IP
 256 It does not check for the case where a subwindow is created in
 257 a pad using \fB\%subwin\fP or \fB\%derwin\fP.
 258 .IP
 259 The \fB\%dupwin\fP function returns a regular window when duplicating a pad.
 260 Likewise, \fB\%getwin\fP always returns a window, even if the saved
 261 data was from a pad.
 262 .PP
 263 This implementation
 264 .bP
 265 sets a flag in the \fI\%WINDOW\fP structure
 266 for \fB\%newpad\fP and \fB\%subpad\fP,
 267 .bP
 268 allows a \fB\%subwin\fP or \fB\%derwin\fP call to succeed having a pad parent by
 269 forcing the subwindow to be a pad,
 270 .bP
 271 checks in both \fB\%wnoutrefresh\fP and \fB\%pnoutrefresh\fP to ensure
 272 that pads and windows are handled distinctly, and
 273 .bP
 274 ensures that \fB\%dupwin\fP and \fB\%getwin\fP treat
 275 pads versus windows consistently.
 276 .SH SEE ALSO
 277 \fB\%curses\fP(3X),
 278 \fB\%curs_addch\fP(3X),
 279 \fB\%curs_refresh\fP(3X),
 280 \fB\%curs_touch\fP(3X)