.\"***************************************************************************
-.\" Copyright (c) 1998-2017,2018 Free Software Foundation, Inc. *
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2015,2017 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" copy of this software and associated documentation files (the *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_pad.3x,v 1.25 2018/07/28 22:20:54 tom Exp $
+.\" $Id: curs_pad.3x,v 1.59 2024/04/20 21:20:07 tom Exp $
+.TH curs_pad 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
+.ie \n(.g \{\
+.ds `` \(lq
+.ds '' \(rq
+.\}
+.el \{\
+.ie t .ds `` ``
+.el .ds `` ""
+.ie t .ds '' ''
+.el .ds '' ""
+.\}
+.
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
..
-.TH curs_pad 3X ""
-.na
-.hy 0
.SH NAME
-\fBnewpad\fR,
-\fBsubpad\fR,
-\fBprefresh\fR,
-\fBpnoutrefresh\fR,
-\fBpechochar\fR,
-\fBpecho_wchar\fR \- create and display \fBcurses\fR pads
-.ad
-.hy
+\fB\%newpad\fP,
+\fB\%subpad\fP,
+\fB\%prefresh\fP,
+\fB\%pnoutrefresh\fP,
+\fB\%pechochar\fP,
+\fB\%pecho_wchar\fP \-
+create and display \fIcurses\fR pads
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-.sp
-\fBWINDOW *newpad(int \fP\fInlines\fP\fB, int \fP\fIncols\fP\fB);\fR
-.br
-\fBWINDOW *subpad(WINDOW *\fP\fIorig\fP\fB, int \fP\fInlines\fP\fB, int \fP\fIncols\fP\fB,\fR
- \fBint \fP\fIbegin_y\fP\fB, int \fP\fIbegin_x\fP\fB);\fR
-.br
-\fBint prefresh(WINDOW *\fP\fIpad\fP\fB, int \fP\fIpminrow\fP\fB, int \fP\fIpmincol\fP\fB,\fR
- \fBint \fP\fIsminrow\fP\fB, int \fP\fIsmincol\fP\fB, int \fP\fIsmaxrow\fP\fB, int \fP\fIsmaxcol\fP\fB);\fR
-.br
-\fBint pnoutrefresh(WINDOW *\fP\fIpad\fP\fB, int \fP\fIpminrow\fP\fB, int \fP\fIpmincol\fP\fB,\fR
- \fBint \fP\fIsminrow\fP\fB, int \fP\fIsmincol\fP\fB, int \fP\fIsmaxrow\fP\fB, int \fP\fIsmaxcol\fP\fB);\fR
-.br
-\fBint pechochar(WINDOW *\fP\fIpad\fP\fB, chtype \fP\fIch\fP\fB);\fR
-.br
-\fBint pecho_wchar(WINDOW *\fP\fIpad\fP\fB, const cchar_t *\fP\fIwch\fP\fB);\fR
-.SH DESCRIPTION
-.SS newpad
-The \fBnewpad\fR routine creates and returns a pointer to a new pad data
-structure with the given number of lines, \fInlines\fR, and columns,
-\fIncols\fR.
-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
-(e.g., from scrolling or echoing of input) do not occur.
+.nf
+\fB#include <curses.h>
.PP
-It is not
-legal to call \fBwrefresh\fR with a \fIpad\fR as an argument; the routines
-\fBprefresh\fR or \fBpnoutrefresh\fR should be called instead.
-Note that these
-routines 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.
-.SS subpad
+\fBWINDOW *newpad(int \fInlines\fP, int \fIncols\fP);
+\fBWINDOW *subpad(WINDOW *\fIparent\fP, int \fInlines\fP, int \fIncols\fP,
+ \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
.PP
-The \fBsubpad\fR routine creates and returns a pointer to a subwindow within a
-pad with the given number of lines, \fInlines\fR, and columns, \fIncols\fR.
-Unlike \fBsubwin\fR, which uses screen coordinates, the window is at position
-(\fIbegin\fR_\fIx\fR\fB,\fR \fIbegin\fR_\fIy\fR) on the pad.
-The window is
-made in the middle of the window \fIorig\fR, so that changes made to one window
-affect both windows.
-During the use of this routine, it will often be
-necessary to call \fBtouchwin\fR or \fBtouchline\fR on \fIorig\fR before
-calling \fBprefresh\fR.
-.SS prefresh, pnoutrefresh
+\fBint prefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR
+ \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int \fIsmaxcol\fB);\fR
+\fBint pnoutrefresh(WINDOW *\fIpad\fB, int \fIpminrow\fB, int \fIpmincol\fB,\fR
+ \fBint \fIsminrow\fB, int \fIsmincol\fB, int \fIsmaxrow\fB, int \fIsmaxcol\fB);\fR
+.PP
+\fBint pechochar(WINDOW *\fIpad\fB, chtype \fIch\fB);\fR
+\fBint pecho_wchar(WINDOW *\fIpad\fB, const cchar_t *\fIwch\fB);\fR
+.fi
+.SH DESCRIPTION
+A
+.I curses
+.I 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,
+only part of which is to be visible on the screen.
+Pads are not automatically refreshed by scrolling or input-echoing
+operations.
.PP
-The \fBprefresh\fR and \fBpnoutrefresh\fR routines are analogous to
-\fBwrefresh\fR and \fBwnoutrefresh\fR 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.
+Pads cannot be refreshed with \fB\%wrefresh\fP(3X);
+use
+.B \%prefresh
+or
+.B \%pnoutrefresh
+instead.
+.SS newpad
+\fB\%newpad\fP creates and returns a pointer to a new pad data structure
+with the given number of lines,
+.IR nlines ,
+and columns,
+.IR ncols .
+.SS subpad
+.B \%subpad
+creates and returns a pointer to a subwindow within a pad
+with the given number of lines,
+.IR nlines ,
+and columns,
+.IR ncols .
+Unlike \fB\%subwin\fP(3X),
+which uses screen coordinates,
+the new pad is placed at position
+.RI ( begin_y ,
+.IR begin_x )
+relative to its parent.
+Thus,
+changes made to one pad can affect both.
+When operating on a subpad,
+it is often necessary to call \fB\%touchwin\fP(3X) or
+\fB\%touchline\fP(3X) on
+.I parent
+before calling
+.BR \%prefresh .
+.SS "prefresh, pnoutrefresh"
+.B \%prefresh\fP
+and
+.B \%pnoutrefresh
+are analogous to \fB\%wrefresh\fP(3X) and \fB\%wnoutrefresh\fP(3X)
+except that they operate on pads rather than windows.
+They require additional parameters are needed to indicate what portions
+of the pad and screen are involved.
.bP
-The \fIpminrow\fR and \fIpmincol\fR parameters specify the upper
-left-hand corner of the rectangle to be displayed in the pad.
+.I pminrow
+and
+.I pmincol
+specify the upper left-hand corner of a rectanglar view of the pad.
.bP
-The \fIsminrow\fR,
-\fIsmincol\fR, \fIsmaxrow\fR, and \fIsmaxcol\fR
-parameters specify the edges of the
-rectangle to be displayed on the screen.
+.IR sminrow ,
+.IR smincol ,
+.IR smaxrow ,
+and
+.I smaxcol
+specify the vertices of the rectangle to be displayed on the screen.
.PP
-The lower right-hand corner of the
-rectangle to be displayed in the pad is calculated from the screen coordinates,
+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
-\fIpminrow\fR, \fIpmincol\fR, \fIsminrow\fR, or \fIsmincol\fR are treated as if
-they were zero.
+Both rectangles must be entirely contained
+within their respective structures.
+.I curses
+treats
+negative values of any of these parameters as zero.
.SS pechochar
-.PP
-The \fBpechochar\fR routine is functionally equivalent to a call to \fBaddch\fR
-followed by a call to \fBrefresh\fR(3X),
-a call to \fBwaddch\fR followed by a call
-to \fBwrefresh\fR, or a call to \fBwaddch\fR followed by a call to
-\fBprefresh\fR.
-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 \fBpechochar\fR, the last location of the pad on
-the screen is reused for the arguments to \fBprefresh\fR.
+.B \%pechochar
+is functionally equivalent to calling \fB\%waddch\fP(3X) followed by
+.BR \%prefresh .
+It suggests to the
+.I curses
+optimizer that only a single character is being output;
+a considerable performance benefit may be thus enjoyed.
+The location of the character
+.I ch
+written to the pad is used to populate the arguments to
+.BR \%prefresh .
.SS pecho_wchar
-.PP
-The \fBpecho_wchar\fR function is the analogous wide-character
-form of \fBpechochar\fR.
-It outputs one character to a pad and immediately refreshes the pad.
-It does this by a call to \fBwadd_wch\fR followed by a call to \fBprefresh\fR.
+.B \%pecho_wchar\fP
+is functionally equivalent to calling \fB\%wadd_wch\fP(3X) followed by
+.BR \%prefresh .
+It suggests to the
+.I curses
+optimizer that only a single wide character is being output;
+a considerable performance benefit may be thus enjoyed.
+The location of the character
+.I wch
+written to the pad is used to populate the arguments to
+.BR \%prefresh .
.SH RETURN VALUE
-Routines that return an integer return \fBERR\fR upon failure and \fBOK\fR
-(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
-completion.
+Functions that return an integer return \fBERR\fP upon failure and
+\fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
+upon successful completion.
.PP
-Routines that return pointers return \fBNULL\fR on error, and set \fBerrno\fR
-to \fBENOMEM\fR.
+Functions that return pointers return \fBNULL\fP on error,
+and set \fB\%errno\fP to \fB\%ENOMEM\fP.
.PP
-X/Open does not define any error conditions.
+X/Open Curses does not specify any error conditions.
In this implementation
.RS 3
.TP 5
-\fBprefresh\fP and \fBpnoutrefresh\fP
+\fB\%prefresh\fP and \fB\%pnoutrefresh\fP
return an error
if the window pointer is null, or
if the window is not really a pad or
\fBpechochar\fP
returns an error
if the window is not really a pad, and the associated call
-to \fBwechochar\fP returns an error.
+to \fB\%wechochar\fP returns an error.
.TP 5
\fBpecho_wchar\fP
returns an error
if the window is not really a pad, and the associated call
-to \fBwecho_wchar\fP returns an error.
+to \fB\%wecho_wchar\fP returns an error.
.RE
.SH NOTES
-Note that \fBpechochar\fR may be a macro.
+\fB\%pechochar\fP may be a macro.
.SH PORTABILITY
-BSD curses has no \fIpad\fP feature.
+BSD \fIcurses\fP has no \fIpad\fP feature.
.PP
-SVr2 curses (1986) provided the \fBnewpad\fP and related functions,
+SVr2 \fIcurses\fP (1986) provided the \fB\%newpad\fP and related functions,
documenting them in a single line each.
SVr3 (1987) provided more extensive documentation.
.PP
.PP
The two uses may be related.
.PP
-The XSI Curses standard, Issue 4 describes these functions,
+X/Open Curses, Issue 4 describes these functions,
without significant change from the SVr3 documentation.
It describes no error conditions.
-The behavior of \fBsubpad\fP if the parent window is not
+The behavior of \fB\%subpad\fP if the parent window is not
a pad is undocumented,
and is not checked by the vendor Unix implementations:
.bP
-SVr4 curses sets a flag in the \fBWINDOW\fP structure in \fBnewpad\fP
-which tells if the window is a \fIpad\fP.
+SVr4 \fIcurses\fP sets a flag in the \fI\%WINDOW\fP structure in
+\fB\%newpad\fP which tells if the window is a \fIpad\fP.
.IP
However, it uses this information only in
-\fBwaddch\fP (to decide if it should call \fBwrefresh\fP) and
-\fBwscrl\fP (to avoid scrolling a pad),
-and does not check in \fBwrefresh\fP to ensure that the pad
+\fB\%waddch\fP (to decide if it should call \fB\%wrefresh\fP) and
+\fB\%wscrl\fP (to avoid scrolling a pad),
+and does not check in \fB\%wrefresh\fP to ensure that the pad
is refreshed properly.
.bP
-Solaris X/Open Curses checks if a window is a pad in \fBwnoutrefresh\fP,
+Solaris \fI\%xcurses\fP checks whether a window is a pad in
+\fB\%wnoutrefresh\fP,
returning \fBERR\fP in that case.
.IP
-However, it only sets the flag for subwindows if the parent window is a pad.
-Its \fBnewpad\fP function does not set this information.
+However,
+it only sets the flag for subwindows if the parent window is a pad.
+Its \fB\%newpad\fP function does not set this information.
Consequently, the check will never fail.
.IP
-It makes no comparable check in \fBpnoutrefresh\fP,
+It makes no comparable check in \fB\%pnoutrefresh\fP,
though interestingly enough, a comment in the source code
states that the lack of a check was an MKS extension.
.bP
-NetBSD 7 curses
-sets a flag in the \fBWINDOW\fP structure for \fBnewpad\fP and \fBsubpad\fP,
-using this to help with the distinction between \fBwnoutrefresh\fP
-and \fBpnoutrefresh\fP.
+NetBSD 7 \fIcurses\fP
+sets a flag in the \fI\%WINDOW\fP structure
+for \fB\%newpad\fP and \fB\%subpad\fP,
+using this to help with the distinction between \fB\%wnoutrefresh\fP
+and \fB\%pnoutrefresh\fP.
.IP
It does not check for the case where a subwindow is created in
-a pad using \fBsubwin\fP or \fBderwin\fP.
+a pad using \fB\%subwin\fP or \fB\%derwin\fP.
.IP
-The \fBdupwin\fP function returns a regular window when duplicating a pad.
-Likewise, \fBgetwin\fP always returns a window, even if the saved
+The \fB\%dupwin\fP function returns a regular window when duplicating a pad.
+Likewise, \fB\%getwin\fP always returns a window, even if the saved
data was from a pad.
.PP
This implementation
.bP
-sets a flag in the \fBWINDOW\fP structure for \fBnewpad\fP and \fBsubpad\fP,
+sets a flag in the \fI\%WINDOW\fP structure
+for \fB\%newpad\fP and \fB\%subpad\fP,
.bP
-allows a \fBsubwin\fP or \fBderwin\fP call to succeed having a pad parent by
+allows a \fB\%subwin\fP or \fB\%derwin\fP call to succeed having a pad parent by
forcing the subwindow to be a pad,
.bP
-checks in both \fBwnoutrefresh\fP and \fBpnoutrefresh\fP to ensure
+checks in both \fB\%wnoutrefresh\fP and \fB\%pnoutrefresh\fP to ensure
that pads and windows are handled distinctly, and
.bP
-ensures that \fBdupwin\fP and \fBgetwin\fP treat
+ensures that \fB\%dupwin\fP and \fB\%getwin\fP treat
pads versus windows consistently.
.SH SEE ALSO
-\fBcurses\fR(3X),
-\fBcurs_refresh\fR(3X),
-\fBcurs_touch\fR(3X),
-\fBcurs_addch\fR(3X).
+\fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
+\fB\%curs_refresh\fP(3X),
+\fB\%curs_touch\fP(3X)
projects / ncurses.git / blobdiff