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

   1 <!--
   2   ****************************************************************************
   3   * Copyright 2018-2023,2024 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.59 2024/04/20 21:20:07 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 2024-04-20 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 2024-04-20 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>parent</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
  61        <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>
  62              <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>
  63        <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>
  64              <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>
  65
  66        <STRONG>int</STRONG> <STRONG>pechochar(WINDOW</STRONG> <STRONG>*</STRONG><EM>pad</EM><STRONG>,</STRONG> <STRONG>chtype</STRONG> <EM>ch</EM><STRONG>);</STRONG>
  67        <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
  69
  70 </PRE><H2><a name="h2-DESCRIPTION">DESCRIPTION</a></H2><PRE>
  71        A <EM>curses</EM> <EM>pad</EM> is like a window, except that it is not restricted by  the
  72        screen  size,  and is not necessarily associated with a particular part
  73        of the screen.  Pads can be used when a large window  is  needed,  only
  74        part  of  which  is  to  be  visible  on  the  screen.   Pads  are  not
  75        automatically refreshed by scrolling or input-echoing operations.
  76
  77        Pads  cannot  be  refreshed  with   <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>;   use   <STRONG>prefresh</STRONG>   or
  78        <STRONG>pnoutrefresh</STRONG> instead.
  79
  80
  81 </PRE><H3><a name="h3-newpad">newpad</a></H3><PRE>
  82        <STRONG>newpad</STRONG>  creates  and returns a pointer to a new pad data structure with
  83        the given number of lines, <EM>nlines</EM>, and columns, <EM>ncols</EM>.
  84
  85
  86 </PRE><H3><a name="h3-subpad">subpad</a></H3><PRE>
  87        <STRONG>subpad</STRONG> creates and returns a pointer to a subwindow within a  pad  with
  88        the  given  number  of  lines,  <EM>nlines</EM>,  and  columns,  <EM>ncols</EM>.   Unlike
  89        <STRONG><A HREF="subwin.3x.html">subwin(3x)</A></STRONG>, which uses screen coordinates, the new  pad  is  placed  at
  90        position (<EM>begin</EM><STRONG>_</STRONG><EM>y</EM>, <EM>begin</EM><STRONG>_</STRONG><EM>x</EM>) relative to its parent.  Thus, changes made
  91        to one pad can affect both.  When operating on a subpad,  it  is  often
  92        necessary  to  call  <STRONG><A HREF="curs_touch.3x.html">touchwin(3x)</A></STRONG>  or  <STRONG><A HREF="curs_touch.3x.html">touchline(3x)</A></STRONG>  on  <EM>parent</EM> before
  93        calling <STRONG>prefresh</STRONG>.
  94
  95
  96 </PRE><H3><a name="h3-prefresh_pnoutrefresh">prefresh, pnoutrefresh</a></H3><PRE>
  97        <STRONG>prefresh</STRONG>  and  <STRONG>pnoutrefresh</STRONG>   are   analogous   to   <STRONG><A HREF="curs_refresh.3x.html">wrefresh(3x)</A></STRONG>   and
  98        <STRONG><A HREF="curs_refresh.3x.html">wnoutrefresh(3x)</A></STRONG>  except that they operate on pads rather than windows.
  99        They require additional parameters are needed to indicate what portions
 100        of the pad and screen are involved.
 101
 102        <STRONG>o</STRONG>   <EM>pminrow</EM>  and  <EM>pmincol</EM>  specify  the  upper  left-hand  corner  of a
 103            rectanglar view of the pad.
 104
 105        <STRONG>o</STRONG>   <EM>sminrow</EM>, <EM>smincol</EM>, <EM>smaxrow</EM>, and <EM>smaxcol</EM> specify the vertices of  the
 106            rectangle to be displayed on the screen.
 107
 108        The lower right-hand corner of the rectangle to be displayed in the pad
 109        is calculated from the screen coordinates, since the rectangles must be
 110        the same size.  Both rectangles must be entirely contained within their
 111        respective structures.  <EM>curses</EM> treats negative values of any  of  these
 112        parameters as zero.
 113
 114
 115 </PRE><H3><a name="h3-pechochar">pechochar</a></H3><PRE>
 116        <STRONG>pechochar</STRONG>  is functionally equivalent to calling <STRONG><A HREF="curs_addch.3x.html">waddch(3x)</A></STRONG> followed by
 117        <STRONG>prefresh</STRONG>.  It suggests to the  <EM>curses</EM>  optimizer  that  only  a  single
 118        character  is  being  output; a considerable performance benefit may be
 119        thus enjoyed.  The location of the character <EM>ch</EM> written to the  pad  is
 120        used to populate the arguments to <STRONG>prefresh</STRONG>.
 121
 122
 123 </PRE><H3><a name="h3-pecho_wchar">pecho_wchar</a></H3><PRE>
 124        <STRONG>pecho_wchar</STRONG> is functionally equivalent to calling <STRONG><A HREF="curs_add_wch.3x.html">wadd_wch(3x)</A></STRONG> followed
 125        by <STRONG>prefresh</STRONG>.  It suggests to the <EM>curses</EM> optimizer that  only  a  single
 126        wide  character is being output; a considerable performance benefit may
 127        be thus enjoyed.  The location of the character <EM>wch</EM> written to the  pad
 128        is used to populate the arguments to <STRONG>prefresh</STRONG>.
 129
 130
 131 </PRE><H2><a name="h2-RETURN-VALUE">RETURN VALUE</a></H2><PRE>
 132        Functions  that  return an integer return <STRONG>ERR</STRONG> upon failure and <STRONG>OK</STRONG> (SVr4
 133        specifies only "an integer  value  other  than  <STRONG>ERR</STRONG>")  upon  successful
 134        completion.
 135
 136        Functions  that  return pointers return <STRONG>NULL</STRONG> on error, and set <STRONG>errno</STRONG> to
 137        <STRONG>ENOMEM</STRONG>.
 138
 139        X/Open  Curses  does  not  specify  any  error  conditions.   In   this
 140        implementation
 141
 142           <STRONG>prefresh</STRONG> and <STRONG>pnoutrefresh</STRONG>
 143                return an error if the window pointer is null, or if the window
 144                is not really a pad or if the  area  to  refresh  extends  off-
 145                screen  or  if  the  minimum  coordinates  are greater than the
 146                maximum.
 147
 148           <STRONG>pechochar</STRONG>
 149                returns an error if the window is not really  a  pad,  and  the
 150                associated call to <STRONG>wechochar</STRONG> returns an error.
 151
 152           <STRONG>pecho_wchar</STRONG>
 153                returns  an  error  if  the window is not really a pad, and the
 154                associated call to <STRONG>wecho_wchar</STRONG> returns an error.
 155
 156
 157 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 158        <STRONG>pechochar</STRONG> may be a macro.
 159
 160
 161 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 162        BSD <EM>curses</EM> has no <EM>pad</EM> feature.
 163
 164        SVr2  <EM>curses</EM>  (1986)  provided  the  <STRONG>newpad</STRONG>  and   related   functions,
 165        documenting  them  in  a  single  line each.  SVr3 (1987) provided more
 166        extensive documentation.
 167
 168        The documentation does not explain the term <EM>pad</EM>.  However,  the  Apollo
 169        <EM>Aegis</EM> workstation operating system supported a graphical <EM>pad</EM> feature:
 170
 171        <STRONG>o</STRONG>   These  graphical  pads  could  be  much  larger than the computer's
 172            display.
 173
 174        <STRONG>o</STRONG>   The read-only output from a  command  could  be  scrolled  back  to
 175            inspect, and select text from the pad.
 176
 177        The two uses may be related.
 178
 179        X/Open  Curses,  Issue 4 describes these functions, without significant
 180        change from the SVr3 documentation.  It describes no error  conditions.
 181        The  behavior  of  <STRONG>subpad</STRONG>  if  the  parent  window  is  not  a  pad  is
 182        undocumented, and is not checked by the vendor Unix implementations:
 183
 184        <STRONG>o</STRONG>   SVr4 <EM>curses</EM> sets a flag in the <EM>WINDOW</EM>  structure  in  <STRONG>newpad</STRONG>  which
 185            tells if the window is a <EM>pad</EM>.
 186
 187            However,  it  uses this information only in <STRONG>waddch</STRONG> (to decide if it
 188            should call <STRONG>wrefresh</STRONG>) and <STRONG>wscrl</STRONG> (to avoid  scrolling  a  pad),  and
 189            does  not  check  in  <STRONG>wrefresh</STRONG>  to ensure that the pad is refreshed
 190            properly.
 191
 192        <STRONG>o</STRONG>   Solaris <EM>xcurses</EM> checks whether a window is a pad  in  <STRONG>wnoutrefresh</STRONG>,
 193            returning <STRONG>ERR</STRONG> in that case.
 194
 195            However,  it only sets the flag for subwindows if the parent window
 196            is a pad.  Its <STRONG>newpad</STRONG>  function  does  not  set  this  information.
 197            Consequently, the check will never fail.
 198
 199            It  makes no comparable check in <STRONG>pnoutrefresh</STRONG>, though interestingly
 200            enough, a comment in the source code states  that  the  lack  of  a
 201            check was an MKS extension.
 202
 203        <STRONG>o</STRONG>   NetBSD  7 <EM>curses</EM> sets a flag in the <EM>WINDOW</EM> structure for <STRONG>newpad</STRONG> and
 204            <STRONG>subpad</STRONG>,  using  this  to  help   with   the   distinction   between
 205            <STRONG>wnoutrefresh</STRONG> and <STRONG>pnoutrefresh</STRONG>.
 206
 207            It  does  not  check for the case where a subwindow is created in a
 208            pad using <STRONG>subwin</STRONG> or <STRONG>derwin</STRONG>.
 209
 210            The <STRONG>dupwin</STRONG> function returns a regular  window  when  duplicating  a
 211            pad.   Likewise,  <STRONG>getwin</STRONG> always returns a window, even if the saved
 212            data was from a pad.
 213
 214        This implementation
 215
 216        <STRONG>o</STRONG>   sets a flag in the <EM>WINDOW</EM> structure for <STRONG>newpad</STRONG> and <STRONG>subpad</STRONG>,
 217
 218        <STRONG>o</STRONG>   allows a <STRONG>subwin</STRONG> or <STRONG>derwin</STRONG> call to succeed having a  pad  parent  by
 219            forcing the subwindow to be a pad,
 220
 221        <STRONG>o</STRONG>   checks  in  both  <STRONG>wnoutrefresh</STRONG> and <STRONG>pnoutrefresh</STRONG> to ensure that pads
 222            and windows are handled distinctly, and
 223
 224        <STRONG>o</STRONG>   ensures  that  <STRONG>dupwin</STRONG>  and  <STRONG>getwin</STRONG>  treat   pads   versus   windows
 225            consistently.
 226
 227
 228 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 229        <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>
 230
 231
 232
 233 ncurses 6.4                       2024-04-20                      <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
 234 </PRE>
 235 <div class="nav">
 236 <ul>
 237 <li><a href="#h2-NAME">NAME</a></li>
 238 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 239 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 240 <ul>
 241 <li><a href="#h3-newpad">newpad</a></li>
 242 <li><a href="#h3-subpad">subpad</a></li>
 243 <li><a href="#h3-prefresh_pnoutrefresh">prefresh, pnoutrefresh</a></li>
 244 <li><a href="#h3-pechochar">pechochar</a></li>
 245 <li><a href="#h3-pecho_wchar">pecho_wchar</a></li>
 246 </ul>
 247 </li>
 248 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 249 <li><a href="#h2-NOTES">NOTES</a></li>
 250 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 251 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 252 </ul>
 253 </div>
 254 </BODY>
 255 </HTML>