# curs_pad 3x 2024-01-05 ncurses 6.4 Library calls

    curs_pad(3x)                     Library calls                    curs_pad(3x)

## NAME

           newpad, subpad, prefresh, pnoutrefresh, pechochar, pecho_wchar - create
           and display curses pads

## SYNOPSIS

           #include <curses.h>

           WINDOW *newpad(int nlines, int ncols);
           WINDOW *subpad(WINDOW *orig, int nlines, int ncols,
                 int begin_y, int begin_x);
           int prefresh(WINDOW *pad, int pminrow, int pmincol,
                 int sminrow, int smincol, int smaxrow, int smaxcol);
           int pnoutrefresh(WINDOW *pad, int pminrow, int pmincol,
                 int sminrow, int smincol, int smaxrow, int smaxcol);
           int pechochar(WINDOW *pad, chtype ch);
           int pecho_wchar(WINDOW *pad, const cchar_t *wch);

## DESCRIPTION

### newpad

           newpad creates and returns a pointer to a new pad data  structure  with
           the given number of lines, nlines, and columns, ncols.  A pad is like a
           window, except that it is not restricted by the screen size, and is not
           necessarily  associated with a particular part of the screen.  Pads can
           be used when a large window is needed, and only a part  of  the  window
           will  be  on  the  screen at one time.  Automatic refreshes of pads (as
           from scrolling or echoing of input) do not occur.

           It is not valid to call wrefresh with a pad argument; call prefresh  or
           pnoutrefresh  instead.   They  require additional parameters to specify
           the part of the pad to be displayed and the location on the  screen  to
           be used for the display.

### subpad

           The  subpad routine creates and returns a pointer to a subwindow within
           a pad with the given number  of  lines,  nlines,  and  columns,  ncols.
           Unlike subwin, which uses screen coordinates, the window is at position
           (begin_x, begin_y) on the pad.  The window is made in the middle of the
           window  orig,  so  that changes made to one window affect both windows.
           During the use of this routine, it will  often  be  necessary  to  call
           touchwin or touchline on orig before calling prefresh.

### prefresh, pnoutrefresh

           The  prefresh  and  pnoutrefresh routines are analogous to wrefresh and
           wnoutrefresh except that they relate to pads instead of  windows.   The
           additional  parameters  are needed to indicate what part of the pad and
           screen are involved.

           o   The pminrow and pmincol  parameters  specify  the  upper  left-hand
               corner of the rectangle to be displayed in the pad.

           o   The  sminrow,  smincol, smaxrow, and smaxcol parameters specify the
               edges of the rectangle to be displayed on the screen.

           The lower right-hand corner of the rectangle to be displayed in the pad
           is calculated from the screen coordinates, since the rectangles must be
           the same size.  Both rectangles must be entirely contained within their
           respective  structures.   Negative values of pminrow, pmincol, sminrow,
           or smincol are treated as if they were zero.

### pechochar

           The pechochar routine is functionally equivalent to  a  call  to  addch
           followed  by a call to refresh(3x), a call to waddch followed by a call
           to wrefresh, or a call to waddch followed by a call to  prefresh.   The
           knowledge  that  only  a single character is being output is taken into
           consideration  and,  for   non-control   characters,   a   considerable
           performance gain might be seen by using these routines instead of their
           equivalents.  In the case of pechochar, the last location of the pad on
           the screen is reused for the arguments to prefresh.

### pecho_wchar

           The  pecho_wchar  function  is  the  analogous  wide-character  form of
           pechochar.  It outputs one character to a pad and immediately refreshes
           the  pad.   It  does  this  by a call to wadd_wch followed by a call to
           prefresh.

## RETURN VALUE

           Functions that return an integer return ERR upon failure and  OK  (SVr4
           specifies  only  "an  integer  value  other  than ERR") upon successful
           completion.

           Functions that return pointers return NULL on error, and set  errno  to
           ENOMEM.

           X/Open   Curses   does  not  define  any  error  conditions.   In  this
           implementation

              prefresh and pnoutrefresh
                   return an error if the window pointer is null, or if the window
                   is  not  really  a  pad  or if the area to refresh extends off-
                   screen or if the  minimum  coordinates  are  greater  than  the
                   maximum.

              pechochar
                   returns  an  error  if  the window is not really a pad, and the
                   associated call to wechochar returns an error.

              pecho_wchar
                   returns an error if the window is not really  a  pad,  and  the
                   associated call to wecho_wchar returns an error.

## NOTES

           pechochar may be a macro.

## PORTABILITY

           BSD curses has no pad feature.

           SVr2   curses   (1986)  provided  the  newpad  and  related  functions,
           documenting them in a single line  each.   SVr3  (1987)  provided  more
           extensive documentation.

           The  documentation  does not explain the term pad.  However, the Apollo
           Aegis workstation operating system supported a graphical pad feature:

           o   These graphical pads could  be  much  larger  than  the  computer's
               display.

           o   The  read-only  output  from  a  command  could be scrolled back to
               inspect, and select text from the pad.

           The two uses may be related.

           The XSI Curses standard, Issue 4  describes  these  functions,  without
           significant  change from the SVr3 documentation.  It describes no error
           conditions.  The behavior of subpad if the parent window is not  a  pad
           is undocumented, and is not checked by the vendor Unix implementations:

           o   SVr4  curses  sets  a  flag in the WINDOW structure in newpad which
               tells if the window is a pad.

               However, it uses this information only in waddch (to decide  if  it
               should  call  wrefresh)  and  wscrl (to avoid scrolling a pad), and
               does not check in wrefresh to ensure  that  the  pad  is  refreshed
               properly.

           o   Solaris  xcurses  checks whether a window is a pad in wnoutrefresh,
               returning ERR in that case.

               However, it only sets the flag for subwindows if the parent  window
               is  a  pad.   Its  newpad  function  does not set this information.
               Consequently, the check will never fail.

               It makes no comparable check in pnoutrefresh, though  interestingly
               enough,  a  comment  in  the  source code states that the lack of a
               check was an MKS extension.

           o   NetBSD 7 curses sets a flag in the WINDOW structure for newpad  and
               subpad,   using   this   to   help  with  the  distinction  between
               wnoutrefresh and pnoutrefresh.

               It does not check for the case where a subwindow is  created  in  a
               pad using subwin or derwin.

               The  dupwin  function  returns  a regular window when duplicating a
               pad.  Likewise, getwin always returns a window, even if  the  saved
               data was from a pad.

           This implementation

           o   sets a flag in the WINDOW structure for newpad and subpad,

           o   allows  a  subwin  or derwin call to succeed having a pad parent by
               forcing the subwindow to be a pad,

           o   checks in both wnoutrefresh and pnoutrefresh to  ensure  that  pads
               and windows are handled distinctly, and

           o   ensures   that   dupwin   and  getwin  treat  pads  versus  windows
               consistently.

## SEE ALSO

           curses(3x), curs_addch(3x), curs_refresh(3x), curs_touch(3x)

    ncurses 6.4                       2024-01-05                      curs_pad(3x)