2 ****************************************************************************
3 * Copyright 2018,2020 Thomas E. Dickey *
4 * Copyright 1998-2015,2017 Free Software Foundation, Inc. *
6 * Permission is hereby granted, free of charge, to any person obtaining a *
7 * copy of this software and associated documentation files (the *
8 * "Software"), to deal in the Software without restriction, including *
9 * without limitation the rights to use, copy, modify, merge, publish, *
10 * distribute, distribute with modifications, sublicense, and/or sell *
11 * copies of the Software, and to permit persons to whom the Software is *
12 * furnished to do so, subject to the following conditions: *
14 * The above copyright notice and this permission notice shall be included *
15 * in all copies or substantial portions of the Software. *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
18 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
19 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
20 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
21 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
22 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
23 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
25 * Except as contained in this notice, the name(s) of the above copyright *
26 * holders shall not be used in advertising or otherwise to promote the *
27 * sale, use or other dealings in this Software without prior written *
29 ****************************************************************************
30 * @Id: curs_pad.3x,v 1.26 2020/02/02 23:34:34 tom Exp @
32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
35 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
36 <meta name="generator" content="Manpage converted by man2html - see https://invisible-island.net/scripts/readme.html#others_scripts">
37 <TITLE>curs_pad 3x</TITLE>
38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
39 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
42 <H1 class="no-header">curs_pad 3x</H1>
44 <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG> <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
49 </PRE><H2><a name="h2-NAME">NAME</a></H2><PRE>
50 <STRONG>newpad</STRONG>, <STRONG>subpad</STRONG>, <STRONG>prefresh</STRONG>, <STRONG>pnoutrefresh</STRONG>, <STRONG>pechochar</STRONG>, <STRONG>pecho_wchar</STRONG> - create
51 and display <STRONG>curses</STRONG> pads
54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
55 <STRONG>#include</STRONG> <STRONG><curses.h></STRONG>
57 <STRONG>WINDOW</STRONG> <STRONG>*newpad(int</STRONG> <EM>nlines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>);</STRONG>
58 <STRONG>WINDOW</STRONG> <STRONG>*subpad(WINDOW</STRONG> <STRONG>*</STRONG><EM>orig</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>nlines</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>ncols</EM><STRONG>,</STRONG>
59 <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>y</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>begin</EM><STRONG>_</STRONG><EM>x</EM><STRONG>);</STRONG>
60 <STRONG>int</STRONG> <STRONG>prefresh(WINDOW</STRONG> <STRONG>*</STRONG><EM>pad</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pminrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pmincol</EM><STRONG>,</STRONG>
61 <STRONG>int</STRONG> <EM>sminrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smincol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smaxrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smaxcol</EM><STRONG>);</STRONG>
62 <STRONG>int</STRONG> <STRONG>pnoutrefresh(WINDOW</STRONG> <STRONG>*</STRONG><EM>pad</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pminrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>pmincol</EM><STRONG>,</STRONG>
63 <STRONG>int</STRONG> <EM>sminrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smincol</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smaxrow</EM><STRONG>,</STRONG> <STRONG>int</STRONG> <EM>smaxcol</EM><STRONG>);</STRONG>
64 <STRONG>int</STRONG> <STRONG>pechochar(WINDOW</STRONG> <STRONG>*</STRONG><EM>pad</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
65 <STRONG>int</STRONG> <STRONG>pecho_wchar(WINDOW</STRONG> <STRONG>*</STRONG><EM>pad</EM><STRONG>,</STRONG> <STRONG>const</STRONG> <STRONG>cchar_t</STRONG> <STRONG>*</STRONG><EM>wch</EM><STRONG>);</STRONG>
68 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
70 </PRE><H3><a name="h3-newpad">newpad</a></H3><PRE>
71 The <STRONG>newpad</STRONG> routine creates and returns a pointer to a new pad data
72 structure with the given number of lines, <EM>nlines</EM>, and columns, <EM>ncols</EM>.
73 A pad is like a window, except that it is not restricted by the screen
74 size, and is not necessarily associated with a particular part of the
75 screen. Pads can be used when a large window is needed, and only a
76 part of the window will be on the screen at one time. Automatic re-
77 freshes of pads (e.g., from scrolling or echoing of input) do not oc-
80 It is not legal to call <STRONG>wrefresh</STRONG> with a <EM>pad</EM> as an argument; the rou-
81 tines <STRONG>prefresh</STRONG> or <STRONG>pnoutrefresh</STRONG> should be called instead. Note that
82 these routines require additional parameters to specify the part of the
83 pad to be displayed and the location on the screen to be used for the
87 </PRE><H3><a name="h3-subpad">subpad</a></H3><PRE>
88 The <STRONG>subpad</STRONG> routine creates and returns a pointer to a subwindow within
89 a pad with the given number of lines, <EM>nlines</EM>, and columns, <EM>ncols</EM>. Un-
90 like <STRONG>subwin</STRONG>, which uses screen coordinates, the window is at position
91 (<EM>begin</EM>_<EM>x</EM><STRONG>,</STRONG> <EM>begin</EM>_<EM>y</EM>) on the pad. The window is made in the middle of the
92 window <EM>orig</EM>, so that changes made to one window affect both windows.
93 During the use of this routine, it will often be necessary to call
94 <STRONG>touchwin</STRONG> or <STRONG>touchline</STRONG> on <EM>orig</EM> before calling <STRONG>prefresh</STRONG>.
97 </PRE><H3><a name="h3-prefresh_-pnoutrefresh">prefresh, pnoutrefresh</a></H3><PRE>
98 The <STRONG>prefresh</STRONG> and <STRONG>pnoutrefresh</STRONG> routines are analogous to <STRONG>wrefresh</STRONG> and
99 <STRONG>wnoutrefresh</STRONG> except that they relate to pads instead of windows. The
100 additional parameters are needed to indicate what part of the pad and
103 <STRONG>o</STRONG> The <EM>pminrow</EM> and <EM>pmincol</EM> parameters specify the upper left-hand cor-
104 ner of the rectangle to be displayed in the pad.
106 <STRONG>o</STRONG> The <EM>sminrow</EM>, <EM>smincol</EM>, <EM>smaxrow</EM>, and <EM>smaxcol</EM> parameters specify the
107 edges of the rectangle to be displayed on the screen.
109 The lower right-hand corner of the rectangle to be displayed in the pad
110 is calculated from the screen coordinates, since the rectangles must be
111 the same size. Both rectangles must be entirely contained within their
112 respective structures. Negative values of <EM>pminrow</EM>, <EM>pmincol</EM>, <EM>sminrow</EM>,
113 or <EM>smincol</EM> are treated as if they were zero.
116 </PRE><H3><a name="h3-pechochar">pechochar</a></H3><PRE>
117 The <STRONG>pechochar</STRONG> routine is functionally equivalent to a call to <STRONG>addch</STRONG>
118 followed by a call to <STRONG><A HREF="curs_refresh.3x.html">refresh(3x)</A></STRONG>, a call to <STRONG>waddch</STRONG> followed by a call
119 to <STRONG>wrefresh</STRONG>, or a call to <STRONG>waddch</STRONG> followed by a call to <STRONG>prefresh</STRONG>. The
120 knowledge that only a single character is being output is taken into
121 consideration and, for non-control characters, a considerable perfor-
122 mance gain might be seen by using these routines instead of their
123 equivalents. In the case of <STRONG>pechochar</STRONG>, the last location of the pad on
124 the screen is reused for the arguments to <STRONG>prefresh</STRONG>.
127 </PRE><H3><a name="h3-pecho_wchar">pecho_wchar</a></H3><PRE>
128 The <STRONG>pecho_wchar</STRONG> function is the analogous wide-character form of <STRONG>pe-</STRONG>
129 <STRONG>chochar</STRONG>. It outputs one character to a pad and immediately refreshes
130 the pad. It does this by a call to <STRONG>wadd_wch</STRONG> followed by a call to <STRONG>pre-</STRONG>
131 <STRONG>fresh</STRONG>.
134 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
135 Routines that return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4
136 only specifies "an integer value other than <STRONG>ERR</STRONG>") upon successful com-
139 Routines that return pointers return <STRONG>NULL</STRONG> on error, and set <STRONG>errno</STRONG> to
140 <STRONG>ENOMEM</STRONG>.
142 X/Open does not define any error conditions. In this implementation
144 <STRONG>prefresh</STRONG> and <STRONG>pnoutrefresh</STRONG>
145 return an error if the window pointer is null, or if the window
146 is not really a pad or if the area to refresh extends off-
147 screen or if the minimum coordinates are greater than the maxi-
150 <STRONG>pechochar</STRONG>
151 returns an error if the window is not really a pad, and the as-
152 sociated call to <STRONG>wechochar</STRONG> returns an error.
154 <STRONG>pecho_wchar</STRONG>
155 returns an error if the window is not really a pad, and the as-
156 sociated call to <STRONG>wecho_wchar</STRONG> returns an error.
159 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
160 Note that <STRONG>pechochar</STRONG> may be a macro.
163 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
164 BSD curses has no <EM>pad</EM> feature.
166 SVr2 curses (1986) provided the <STRONG>newpad</STRONG> and related functions, document-
167 ing them in a single line each. SVr3 (1987) provided more extensive
170 The documentation does not explain the term <EM>pad</EM>. However, the Apollo
171 <EM>Aegis</EM> workstation operating system supported a graphical <EM>pad</EM> feature:
173 <STRONG>o</STRONG> These graphical pads could be much larger than the computer's dis-
176 <STRONG>o</STRONG> The read-only output from a command could be scrolled back to in-
177 spect, and select text from the pad.
179 The two uses may be related.
181 The XSI Curses standard, Issue 4 describes these functions, without
182 significant change from the SVr3 documentation. It describes no error
183 conditions. The behavior of <STRONG>subpad</STRONG> if the parent window is not a pad
184 is undocumented, and is not checked by the vendor Unix implementations:
186 <STRONG>o</STRONG> SVr4 curses sets a flag in the <STRONG>WINDOW</STRONG> structure in <STRONG>newpad</STRONG> which
187 tells if the window is a <EM>pad</EM>.
189 However, it uses this information only in <STRONG>waddch</STRONG> (to decide if it
190 should call <STRONG>wrefresh</STRONG>) and <STRONG>wscrl</STRONG> (to avoid scrolling a pad), and
191 does not check in <STRONG>wrefresh</STRONG> to ensure that the pad is refreshed
194 <STRONG>o</STRONG> Solaris X/Open Curses checks if a window is a pad in <STRONG>wnoutrefresh</STRONG>,
195 returning <STRONG>ERR</STRONG> in that case.
197 However, it only sets the flag for subwindows if the parent window
198 is a pad. Its <STRONG>newpad</STRONG> function does not set this information. Con-
199 sequently, the check will never fail.
201 It makes no comparable check in <STRONG>pnoutrefresh</STRONG>, though interestingly
202 enough, a comment in the source code states that the lack of a
203 check was an MKS extension.
205 <STRONG>o</STRONG> NetBSD 7 curses sets a flag in the <STRONG>WINDOW</STRONG> structure for <STRONG>newpad</STRONG> and
206 <STRONG>subpad</STRONG>, using this to help with the distinction between <STRONG>wnoutre-</STRONG>
207 <STRONG>fresh</STRONG> and <STRONG>pnoutrefresh</STRONG>.
209 It does not check for the case where a subwindow is created in a
210 pad using <STRONG>subwin</STRONG> or <STRONG>derwin</STRONG>.
212 The <STRONG>dupwin</STRONG> function returns a regular window when duplicating a
213 pad. Likewise, <STRONG>getwin</STRONG> always returns a window, even if the saved
218 <STRONG>o</STRONG> sets a flag in the <STRONG>WINDOW</STRONG> structure for <STRONG>newpad</STRONG> and <STRONG>subpad</STRONG>,
220 <STRONG>o</STRONG> allows a <STRONG>subwin</STRONG> or <STRONG>derwin</STRONG> call to succeed having a pad parent by
221 forcing the subwindow to be a pad,
223 <STRONG>o</STRONG> checks in both <STRONG>wnoutrefresh</STRONG> and <STRONG>pnoutrefresh</STRONG> to ensure that pads
224 and windows are handled distinctly, and
226 <STRONG>o</STRONG> ensures that <STRONG>dupwin</STRONG> and <STRONG>getwin</STRONG> treat pads versus windows consis-
230 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
231 <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_refresh.3x.html">curs_refresh(3x)</A></STRONG>, <STRONG><A HREF="curs_touch.3x.html">curs_touch(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(3x)</A></STRONG>.
235 <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
239 <li><a href="#h2-NAME">NAME</a></li>
240 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
241 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
243 <li><a href="#h3-newpad">newpad</a></li>
244 <li><a href="#h3-subpad">subpad</a></li>
245 <li><a href="#h3-prefresh_-pnoutrefresh">prefresh, pnoutrefresh</a></li>
246 <li><a href="#h3-pechochar">pechochar</a></li>
247 <li><a href="#h3-pecho_wchar">pecho_wchar</a></li>
250 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
251 <li><a href="#h2-NOTES">NOTES</a></li>
252 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
253 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>