doc/html/man/curs_pad.3x.html

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2022,2023 Thomas E. Dickey                                *
   4   * Copyright 1998-2015,2017 Free Software Foundation, Inc.                  *
   5   *                                                                          *
   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:                 *
  13   *                                                                          *
  14   * The above copyright notice and this permission notice shall be included  *
  15   * in all copies or substantial portions of the Software.                   *
  16   *                                                                          *
  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.                               *
  24   *                                                                          *
  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       *
  28   * authorization.                                                           *
  29   ****************************************************************************
  30   * @Id: curs_pad.3x,v 1.50 2023/12/16 21:18:02 tom Exp @
  31 -->
  32 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
  33 <HTML>
  34 <HEAD>
  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 2023-12-16 ncurses 6.4 Library calls</TITLE>
  38 <link rel="author" href="mailto:bug-ncurses@gnu.org">
  39
  40 </HEAD>
  41 <BODY>
  42 <H1 class="no-header">curs_pad 3x 2023-12-16 ncurses 6.4 Library calls</H1>
  43 <PRE>
  44 <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>                     Library calls                    <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
  45
  46
  47
  48
  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 <EM>curses</EM> pads
  52
  53
  54 </PRE><H2><a name="h2-SYNOPSIS">SYNOPSIS</a></H2><PRE>
  55        <STRONG>#include</STRONG> <STRONG>&lt;curses.h&gt;</STRONG>
  56
  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>
  66
  67
  68 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  69
  70 </PRE><H3><a name="h3-newpad">newpad</a></H3><PRE>
  71        <STRONG>newpad</STRONG> creates and returns a pointer to a new pad data  structure  with
  72        the given number of lines, <EM>nlines</EM>, and columns, <EM>ncols</EM>.  A pad is like a
  73        window, except that it is not restricted by the screen size, and is not
  74        necessarily  associated with a particular part of the screen.  Pads can
  75        be used when a large window is needed, and only a part  of  the  window
  76        will  be  on  the  screen at one time.  Automatic refreshes of pads (as
  77        from scrolling or echoing of input) do not occur.
  78
  79        It is not valid to call <STRONG>wrefresh</STRONG> with a <EM>pad</EM> argument; call <STRONG>prefresh</STRONG>  or
  80        <STRONG>pnoutrefresh</STRONG>  instead.   They  require additional parameters to specify
  81        the part of the pad to be displayed and the location on the  screen  to
  82        be used for the display.
  83
  84
  85 </PRE><H3><a name="h3-subpad">subpad</a></H3><PRE>
  86        The  <STRONG>subpad</STRONG> routine creates and returns a pointer to a subwindow within
  87        a pad with the given number  of  lines,  <EM>nlines</EM>,  and  columns,  <EM>ncols</EM>.
  88        Unlike <STRONG>subwin</STRONG>, which uses screen coordinates, the window is at position
  89        (<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
  90        window  <EM>orig</EM>,  so  that changes made to one window affect both windows.
  91        During the use of this routine, it will  often  be  necessary  to  call
  92        <STRONG>touchwin</STRONG> or <STRONG>touchline</STRONG> on <EM>orig</EM> before calling <STRONG>prefresh</STRONG>.
  93
  94
  95 </PRE><H3><a name="h3-prefresh_-pnoutrefresh">prefresh, pnoutrefresh</a></H3><PRE>
  96        The  <STRONG>prefresh</STRONG>  and  <STRONG>pnoutrefresh</STRONG> routines are analogous to <STRONG>wrefresh</STRONG> and
  97        <STRONG>wnoutrefresh</STRONG> except that they relate to pads instead of  windows.   The
  98        additional  parameters  are needed to indicate what part of the pad and
  99        screen are involved.
 100
 101        <STRONG>o</STRONG>   The <EM>pminrow</EM> and <EM>pmincol</EM>  parameters  specify  the  upper  left-hand
 102            corner of the rectangle to be displayed in the pad.
 103
 104        <STRONG>o</STRONG>   The  <EM>sminrow</EM>,  <EM>smincol</EM>, <EM>smaxrow</EM>, and <EM>smaxcol</EM> parameters specify the
 105            edges of the rectangle to be displayed on the screen.
 106
 107        The lower right-hand corner of the rectangle to be displayed in the pad
 108        is calculated from the screen coordinates, since the rectangles must be
 109        the same size.  Both rectangles must be entirely contained within their
 110        respective  structures.   Negative values of <EM>pminrow</EM>, <EM>pmincol</EM>, <EM>sminrow</EM>,
 111        or <EM>smincol</EM> are treated as if they were zero.
 112
 113
 114 </PRE><H3><a name="h3-pechochar">pechochar</a></H3><PRE>
 115        The <STRONG>pechochar</STRONG> routine is functionally equivalent to  a  call  to  <STRONG>addch</STRONG>
 116        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
 117        to <STRONG>wrefresh</STRONG>, or a call to <STRONG>waddch</STRONG> followed by a call to  <STRONG>prefresh</STRONG>.   The
 118        knowledge  that  only  a single character is being output is taken into
 119        consideration  and,  for   non-control   characters,   a   considerable
 120        performance gain might be seen by using these routines instead of their
 121        equivalents.  In the case of <STRONG>pechochar</STRONG>, the last location of the pad on
 122        the screen is reused for the arguments to <STRONG>prefresh</STRONG>.
 123
 124
 125 </PRE><H3><a name="h3-pecho_wchar">pecho_wchar</a></H3><PRE>
 126        The  <STRONG>pecho_wchar</STRONG>  function  is  the  analogous  wide-character  form of
 127        <STRONG>pechochar</STRONG>.  It outputs one character to a pad and immediately refreshes
 128        the  pad.   It  does  this  by a call to <STRONG>wadd_wch</STRONG> followed by a call to
 129        <STRONG>prefresh</STRONG>.
 130
 131
 132 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 133        Functions that return an integer return <STRONG>ERR</STRONG> upon failure and  <STRONG>OK</STRONG>  (SVr4
 134        specifies  only  "an  integer  value  other  than <STRONG>ERR</STRONG>") upon successful
 135        completion.
 136
 137        Functions that return pointers return <STRONG>NULL</STRONG> on error, and set  <STRONG>errno</STRONG>  to
 138        <STRONG>ENOMEM</STRONG>.
 139
 140        X/Open   Curses   does  not  define  any  error  conditions.   In  this
 141        implementation
 142
 143           <STRONG>prefresh</STRONG> and <STRONG>pnoutrefresh</STRONG>
 144                return an error if the window pointer is null, or if the window
 145                is  not  really  a  pad  or if the area to refresh extends off-
 146                screen or if the  minimum  coordinates  are  greater  than  the
 147                maximum.
 148
 149           <STRONG>pechochar</STRONG>
 150                returns  an  error  if  the window is not really a pad, and the
 151                associated call to <STRONG>wechochar</STRONG> returns an error.
 152
 153           <STRONG>pecho_wchar</STRONG>
 154                returns an error if the window is not really  a  pad,  and  the
 155                associated call to <STRONG>wecho_wchar</STRONG> returns an error.
 156
 157
 158 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 159        <STRONG>pechochar</STRONG> may be a macro.
 160
 161
 162 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 163        BSD <EM>curses</EM> has no <EM>pad</EM> feature.
 164
 165        SVr2   <EM>curses</EM>   (1986)  provided  the  <STRONG>newpad</STRONG>  and  related  functions,
 166        documenting them in a single line  each.   SVr3  (1987)  provided  more
 167        extensive documentation.
 168
 169        The  documentation  does not explain the term <EM>pad</EM>.  However, the Apollo
 170        <EM>Aegis</EM> workstation operating system supported a graphical <EM>pad</EM> feature:
 171
 172        <STRONG>o</STRONG>   These graphical pads could  be  much  larger  than  the  computer's
 173            display.
 174
 175        <STRONG>o</STRONG>   The  read-only  output  from  a  command  could be scrolled back to
 176            inspect, and select text from the pad.
 177
 178        The two uses may be related.
 179
 180        The XSI Curses standard, Issue 4  describes  these  functions,  without
 181        significant  change from the SVr3 documentation.  It describes no error
 182        conditions.  The behavior of <STRONG>subpad</STRONG> if the parent window is not  a  pad
 183        is undocumented, and is not checked by the vendor Unix implementations:
 184
 185        <STRONG>o</STRONG>   SVr4  <EM>curses</EM>  sets  a  flag in the <EM>WINDOW</EM> structure in <STRONG>newpad</STRONG> which
 186            tells if the window is a <EM>pad</EM>.
 187
 188            However, it uses this information only in <STRONG>waddch</STRONG> (to decide  if  it
 189            should  call  <STRONG>wrefresh</STRONG>)  and  <STRONG>wscrl</STRONG> (to avoid scrolling a pad), and
 190            does not check in <STRONG>wrefresh</STRONG> to ensure  that  the  pad  is  refreshed
 191            properly.
 192
 193        <STRONG>o</STRONG>   Solaris  <EM>xcurses</EM>  checks whether a window is a pad in <STRONG>wnoutrefresh</STRONG>,
 194            returning <STRONG>ERR</STRONG> in that case.
 195
 196            However, it only sets the flag for subwindows if the parent  window
 197            is  a  pad.   Its  <STRONG>newpad</STRONG>  function  does not set this information.
 198            Consequently, the check will never fail.
 199
 200            It makes no comparable check in <STRONG>pnoutrefresh</STRONG>, though  interestingly
 201            enough,  a  comment  in  the  source code states that the lack of a
 202            check was an MKS extension.
 203
 204        <STRONG>o</STRONG>   NetBSD 7 <EM>curses</EM> sets a flag in the <EM>WINDOW</EM> structure for <STRONG>newpad</STRONG>  and
 205            <STRONG>subpad</STRONG>,   using   this   to   help  with  the  distinction  between
 206            <STRONG>wnoutrefresh</STRONG> and <STRONG>pnoutrefresh</STRONG>.
 207
 208            It does not check for the case where a subwindow is  created  in  a
 209            pad using <STRONG>subwin</STRONG> or <STRONG>derwin</STRONG>.
 210
 211            The  <STRONG>dupwin</STRONG>  function  returns  a regular window when duplicating a
 212            pad.  Likewise, <STRONG>getwin</STRONG> always returns a window, even if  the  saved
 213            data was from a pad.
 214
 215        This implementation
 216
 217        <STRONG>o</STRONG>   sets a flag in the <EM>WINDOW</EM> structure for <STRONG>newpad</STRONG> and <STRONG>subpad</STRONG>,
 218
 219        <STRONG>o</STRONG>   allows  a  <STRONG>subwin</STRONG>  or <STRONG>derwin</STRONG> call to succeed having a pad parent by
 220            forcing the subwindow to be a pad,
 221
 222        <STRONG>o</STRONG>   checks in both <STRONG>wnoutrefresh</STRONG> and <STRONG>pnoutrefresh</STRONG> to  ensure  that  pads
 223            and windows are handled distinctly, and
 224
 225        <STRONG>o</STRONG>   ensures   that   <STRONG>dupwin</STRONG>   and  <STRONG>getwin</STRONG>  treat  pads  versus  windows
 226            consistently.
 227
 228
 229 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 230        <STRONG><A HREF="ncurses.3x.html">curses(3x)</A></STRONG>, <STRONG><A HREF="curs_addch.3x.html">curs_addch(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>
 231
 232
 233
 234 ncurses 6.4                       2023-12-16                      <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
 235 </PRE>
 236 <div class="nav">
 237 <ul>
 238 <li><a href="#h2-NAME">NAME</a></li>
 239 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 240 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 241 <ul>
 242 <li><a href="#h3-newpad">newpad</a></li>
 243 <li><a href="#h3-subpad">subpad</a></li>
 244 <li><a href="#h3-prefresh_-pnoutrefresh">prefresh, pnoutrefresh</a></li>
 245 <li><a href="#h3-pechochar">pechochar</a></li>
 246 <li><a href="#h3-pecho_wchar">pecho_wchar</a></li>
 247 </ul>
 248 </li>
 249 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 250 <li><a href="#h2-NOTES">NOTES</a></li>
 251 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 252 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 253 </ul>
 254 </div>
 255 </BODY>
 256 </HTML>