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.53 2024/01/05 21:46:58 tom Exp $
  31 .TH curs_pad 3X 2024-01-05 "ncurses 6.4" "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 *\fIorig\fP, int \fInlines\fP, int \fIncols\fP,
  61       \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
  62 \fBint prefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR
  63       \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int \fIsmaxcol\fB);\fR
  64 \fBint pnoutrefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR
  65       \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int \fIsmaxcol\fB);\fR
  66 \fBint pechochar(WINDOW *\fIpad\fB, chtype \fIch\fB);\fR
  67 \fBint pecho_wchar(WINDOW *\fIpad\fB, const cchar_t *\fIwch\fB);\fR
  68 .fi
  69 .SH DESCRIPTION
  70 .SS newpad
  71 \fB\%newpad\fP creates and returns a pointer to a new pad data structure
  72 with the given number of lines,
  73 \fInlines\fP,
  74 and columns,
  75 \fIncols\fP.
  76 A pad is like a window,
  77 except that it is not restricted by the screen size,
  78 and is not necessarily associated with a particular part of the screen.
  79 Pads can be used when a large window is needed,
  80 and only a part of the window will be on the screen at one time.
  81 Automatic refreshes of pads
  82 (as from scrolling or echoing of input)
  83 do not occur.
  84 .PP
  85 It is not valid to call \fB\%wrefresh\fP with a \fIpad\fP argument;
  86 call \fB\%prefresh\fP or \fB\%pnoutrefresh\fP instead.
  87 They require additional parameters to specify the part of the pad to be
  88 displayed and the location on the screen to be used for the display.
  89 .SS subpad
  90 The \fB\%subpad\fP routine creates and returns a pointer to a subwindow within a
  91 pad with the given number of lines, \fInlines\fP, and columns, \fIncols\fP.
  92 Unlike \fB\%subwin\fP, which uses screen coordinates, the window is at position
  93 (\fIbegin\fR_\fIx\fB,\fR \fIbegin\fR_\fIy\fR) on the pad.
  94 The window is
  95 made in the middle of the window \fIorig\fP, so that changes made to one window
  96 affect both windows.
  97 During the use of this routine, it will often be
  98 necessary to call \fB\%touchwin\fP or \fB\%touchline\fP on \fIorig\fP before
  99 calling \fB\%prefresh\fP.
 100 .SS "prefresh, pnoutrefresh"
 101 The \fB\%prefresh\fP and \fB\%pnoutrefresh\fP routines are analogous to
 102 \fB\%wrefresh\fP and \fB\%wnoutrefresh\fP except that they relate to pads instead
 103 of windows.
 104 The additional parameters are needed to indicate what part of the
 105 pad and screen are involved.
 106 .bP
 107 The \fIpminrow\fP and \fIpmincol\fP parameters specify the upper
 108 left-hand corner of the rectangle to be displayed in the pad.
 109 .bP
 110 The \fIsminrow\fP,
 111 \fIsmincol\fP, \fIsmaxrow\fP, and \fIsmaxcol\fP
 112 parameters specify the edges of the
 113 rectangle to be displayed on the screen.
 114 .PP
 115 The lower right-hand corner of the
 116 rectangle to be displayed in the pad is calculated from the screen coordinates,
 117 since the rectangles must be the same size.
 118 Both rectangles must be entirely
 119 contained within their respective structures.
 120 Negative values of
 121 \fIpminrow\fP, \fIpmincol\fP, \fIsminrow\fP, or \fIsmincol\fP are treated as if
 122 they were zero.
 123 .SS pechochar
 124 The \fB\%pechochar\fP routine is functionally equivalent
 125 to a call to \fB\%addch\fP
 126 followed by a call to \fB\%refresh\fP(3X),
 127 a call to \fB\%waddch\fP followed by a call
 128 to \fB\%wrefresh\fP, or a call to \fB\%waddch\fP followed by a call to
 129 \fB\%prefresh\fP.
 130 The knowledge that only a single character is being output is
 131 taken into consideration and, for non-control characters, a considerable
 132 performance gain might be seen by using these routines instead of their
 133 equivalents.
 134 In the case of \fB\%pechochar\fP, the last location of the pad on
 135 the screen is reused for the arguments to \fB\%prefresh\fP.
 136 .SS pecho_wchar
 137 The \fB\%pecho_wchar\fP function is the analogous wide-character
 138 form of \fB\%pechochar\fP.
 139 It outputs one character to a pad and immediately refreshes the pad.
 140 It does this by a call to \fB\%wadd_wch\fP followed by a call
 141 to \fB\%prefresh\fP.
 142 .SH RETURN VALUE
 143 Functions that return an integer return \fBERR\fP upon failure and
 144 \fBOK\fP
 145 (SVr4 specifies only
 146 \*(``an integer value other than \fBERR\fP\*('')
 147 upon successful completion.
 148 .PP
 149 Functions that return pointers return \fBNULL\fP on error,
 150 and set \fB\%errno\fP to \fB\%ENOMEM\fP.
 151 .PP
 152 X/Open Curses does not define any error conditions.
 153 In this implementation
 154 .RS 3
 155 .TP 5
 156 \fB\%prefresh\fP and \fB\%pnoutrefresh\fP
 157 return an error
 158 if the window pointer is null, or
 159 if the window is not really a pad or
 160 if the area to refresh extends off-screen or
 161 if the minimum coordinates are greater than the maximum.
 162 .TP 5
 163 \fBpechochar\fP
 164 returns an error
 165 if the window is not really a pad, and the associated call
 166 to \fB\%wechochar\fP returns an error.
 167 .TP 5
 168 \fBpecho_wchar\fP
 169 returns an error
 170 if the window is not really a pad, and the associated call
 171 to \fB\%wecho_wchar\fP returns an error.
 172 .RE
 173 .SH NOTES
 174 \fB\%pechochar\fP may be a macro.
 175 .SH PORTABILITY
 176 BSD \fIcurses\fP has no \fIpad\fP feature.
 177 .PP
 178 SVr2 \fIcurses\fP (1986) provided the \fB\%newpad\fP and related functions,
 179 documenting them in a single line each.
 180 SVr3 (1987) provided more extensive documentation.
 181 .PP
 182 The documentation does not explain the term \fIpad\fP.
 183 However, the Apollo \fIAegis\fP workstation operating system
 184 supported a graphical \fIpad\fP feature:
 185 .bP
 186 These graphical pads could be much larger than the computer's display.
 187 .bP
 188 The read-only output from a command could be scrolled back to inspect,
 189 and select text from the pad.
 190 .PP
 191 The two uses may be related.
 192 .PP
 193 The XSI Curses standard, Issue 4 describes these functions,
 194 without significant change from the SVr3 documentation.
 195 It describes no error conditions.
 196 The behavior of \fB\%subpad\fP if the parent window is not
 197 a pad is undocumented,
 198 and is not checked by the vendor Unix implementations:
 199 .bP
 200 SVr4 \fIcurses\fP sets a flag in the \fI\%WINDOW\fP structure in
 201 \fB\%newpad\fP which tells if the window is a \fIpad\fP.
 202 .IP
 203 However, it uses this information only in
 204 \fB\%waddch\fP (to decide if it should call \fB\%wrefresh\fP) and
 205 \fB\%wscrl\fP (to avoid scrolling a pad),
 206 and does not check in \fB\%wrefresh\fP to ensure that the pad
 207 is refreshed properly.
 208 .bP
 209 Solaris \fI\%xcurses\fP checks whether a window is a pad in
 210 \fB\%wnoutrefresh\fP,
 211 returning \fBERR\fP in that case.
 212 .IP
 213 However,
 214 it only sets the flag for subwindows if the parent window is a pad.
 215 Its \fB\%newpad\fP function does not set this information.
 216 Consequently, the check will never fail.
 217 .IP
 218 It makes no comparable check in \fB\%pnoutrefresh\fP,
 219 though interestingly enough, a comment in the source code
 220 states that the lack of a check was an MKS extension.
 221 .bP
 222 NetBSD 7 \fIcurses\fP
 223 sets a flag in the \fI\%WINDOW\fP structure
 224 for \fB\%newpad\fP and \fB\%subpad\fP,
 225 using this to help with the distinction between \fB\%wnoutrefresh\fP
 226 and \fB\%pnoutrefresh\fP.
 227 .IP
 228 It does not check for the case where a subwindow is created in
 229 a pad using \fB\%subwin\fP or \fB\%derwin\fP.
 230 .IP
 231 The \fB\%dupwin\fP function returns a regular window when duplicating a pad.
 232 Likewise, \fB\%getwin\fP always returns a window, even if the saved
 233 data was from a pad.
 234 .PP
 235 This implementation
 236 .bP
 237 sets a flag in the \fI\%WINDOW\fP structure
 238 for \fB\%newpad\fP and \fB\%subpad\fP,
 239 .bP
 240 allows a \fB\%subwin\fP or \fB\%derwin\fP call to succeed having a pad parent by
 241 forcing the subwindow to be a pad,
 242 .bP
 243 checks in both \fB\%wnoutrefresh\fP and \fB\%pnoutrefresh\fP to ensure
 244 that pads and windows are handled distinctly, and
 245 .bP
 246 ensures that \fB\%dupwin\fP and \fB\%getwin\fP treat
 247 pads versus windows consistently.
 248 .SH SEE ALSO
 249 \fB\%curses\fP(3X),
 250 \fB\%curs_addch\fP(3X),
 251 \fB\%curs_refresh\fP(3X),
 252 \fB\%curs_touch\fP(3X)