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.63 2024/05/25 20:10:58 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-05-25 ncurses 6.5 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-05-25 ncurses 6.5 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            rectangular 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  <STRONG>ERR</STRONG>  if the window pointer is null, or if the window is
 144                not really a pad or if the area to refresh  extends  off-screen
 145                or if the minimum coordinates are greater than the maximum.
 146
 147           <STRONG>pechochar</STRONG>
 148                returns  <STRONG>ERR</STRONG>  if  the  window  is  not  really  a  pad, and the
 149                associated call to <STRONG>wechochar</STRONG> returns <STRONG>ERR</STRONG>.
 150
 151           <STRONG>pecho_wchar</STRONG>
 152                returns <STRONG>ERR</STRONG> if  the  window  is  not  really  a  pad,  and  the
 153                associated call to <STRONG>wecho_wchar</STRONG> returns <STRONG>ERR</STRONG>.
 154
 155
 156 </PRE><H2><a name="h2-NOTES">NOTES</a></H2><PRE>
 157        <STRONG>pechochar</STRONG> may be a macro.
 158
 159
 160 </PRE><H2><a name="h2-PORTABILITY">PORTABILITY</a></H2><PRE>
 161        BSD <EM>curses</EM> has no <EM>pad</EM> feature.
 162
 163        SVr2   <EM>curses</EM>   (1986)  provided  the  <STRONG>newpad</STRONG>  and  related  functions,
 164        documenting them in a single line  each.   SVr3  (1987)  provided  more
 165        extensive documentation.
 166
 167        The  documentation  does not explain the term <EM>pad</EM>.  However, the Apollo
 168        <EM>Aegis</EM> workstation operating system supported a graphical <EM>pad</EM> feature:
 169
 170        <STRONG>o</STRONG>   These graphical pads could  be  much  larger  than  the  computer's
 171            display.
 172
 173        <STRONG>o</STRONG>   The  read-only  output  from  a  command  could be scrolled back to
 174            inspect, and select text from the pad.
 175
 176        The two uses may be related.
 177
 178        X/Open Curses, Issue 4 describes these functions,  without  significant
 179        change  from the SVr3 documentation.  It describes no error conditions.
 180        The  behavior  of  <STRONG>subpad</STRONG>  if  the  parent  window  is  not  a  pad  is
 181        undocumented, and is not checked by the vendor Unix implementations:
 182
 183        <STRONG>o</STRONG>   SVr4  <EM>curses</EM>  sets  a  flag in the <EM>WINDOW</EM> structure in <STRONG>newpad</STRONG> which
 184            tells if the window is a <EM>pad</EM>.
 185
 186            However, it uses this information only in <STRONG>waddch</STRONG> (to decide  if  it
 187            should  call  <STRONG>wrefresh</STRONG>)  and  <STRONG>wscrl</STRONG> (to avoid scrolling a pad), and
 188            does not check in <STRONG>wrefresh</STRONG> to ensure  that  the  pad  is  refreshed
 189            properly.
 190
 191        <STRONG>o</STRONG>   Solaris  <EM>xcurses</EM>  checks whether a window is a pad in <STRONG>wnoutrefresh</STRONG>,
 192            returning <STRONG>ERR</STRONG> in that case.
 193
 194            However, it only sets the flag for subwindows if the parent  window
 195            is  a  pad.   Its  <STRONG>newpad</STRONG>  function  does not set this information.
 196            Consequently, the check will never fail.
 197
 198            It makes no comparable check in <STRONG>pnoutrefresh</STRONG>, though  interestingly
 199            enough,  a  comment  in  the  source code states that the lack of a
 200            check was an MKS extension.
 201
 202        <STRONG>o</STRONG>   NetBSD 7 <EM>curses</EM> sets a flag in the <EM>WINDOW</EM> structure for <STRONG>newpad</STRONG>  and
 203            <STRONG>subpad</STRONG>,   using   this   to   help  with  the  distinction  between
 204            <STRONG>wnoutrefresh</STRONG> and <STRONG>pnoutrefresh</STRONG>.
 205
 206            It does not check for the case where a subwindow is  created  in  a
 207            pad using <STRONG>subwin</STRONG> or <STRONG>derwin</STRONG>.
 208
 209            The  <STRONG>dupwin</STRONG>  function  returns  a regular window when duplicating a
 210            pad.  Likewise, <STRONG>getwin</STRONG> always returns a window, even if  the  saved
 211            data was from a pad.
 212
 213        This implementation
 214
 215        <STRONG>o</STRONG>   sets a flag in the <EM>WINDOW</EM> structure for <STRONG>newpad</STRONG> and <STRONG>subpad</STRONG>,
 216
 217        <STRONG>o</STRONG>   allows  a  <STRONG>subwin</STRONG>  or <STRONG>derwin</STRONG> call to succeed having a pad parent by
 218            forcing the subwindow to be a pad,
 219
 220        <STRONG>o</STRONG>   checks in both <STRONG>wnoutrefresh</STRONG> and <STRONG>pnoutrefresh</STRONG> to  ensure  that  pads
 221            and windows are handled distinctly, and
 222
 223        <STRONG>o</STRONG>   ensures   that   <STRONG>dupwin</STRONG>   and  <STRONG>getwin</STRONG>  treat  pads  versus  windows
 224            consistently.
 225
 226
 227 </PRE><H2><a name="h2-SEE-ALSO">SEE ALSO</a></H2><PRE>
 228        <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>
 229
 230
 231
 232 ncurses 6.5                       2024-05-25                      <STRONG><A HREF="curs_pad.3x.html">curs_pad(3x)</A></STRONG>
 233 </PRE>
 234 <div class="nav">
 235 <ul>
 236 <li><a href="#h2-NAME">NAME</a></li>
 237 <li><a href="#h2-SYNOPSIS">SYNOPSIS</a></li>
 238 <li><a href="#h2-DESCRIPTION">DESCRIPTION</a>
 239 <ul>
 240 <li><a href="#h3-newpad">newpad</a></li>
 241 <li><a href="#h3-subpad">subpad</a></li>
 242 <li><a href="#h3-prefresh_pnoutrefresh">prefresh, pnoutrefresh</a></li>
 243 <li><a href="#h3-pechochar">pechochar</a></li>
 244 <li><a href="#h3-pecho_wchar">pecho_wchar</a></li>
 245 </ul>
 246 </li>
 247 <li><a href="#h2-RETURN-VALUE">RETURN VALUE</a></li>
 248 <li><a href="#h2-NOTES">NOTES</a></li>
 249 <li><a href="#h2-PORTABILITY">PORTABILITY</a></li>
 250 <li><a href="#h2-SEE-ALSO">SEE ALSO</a></li>
 251 </ul>
 252 </div>
 253 </BODY>
 254 </HTML>