X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_pad.3x;h=64cf0081f9c5a81ee138e85f6e2b2e2573175e68;hp=52fe51cf35f11ff34be15ea7679880dee0062828;hb=97cb42f22c43eb31a4bf11475bd73ab0e0b10923;hpb=6a530b46563470c2ca73579d1994a0c8e275dd98

diff --git a/man/curs_pad.3x b/man/curs_pad.3x
index 52fe51cf..64cf0081 100644
--- a/man/curs_pad.3x
+++ b/man/curs_pad.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" Copyright (c) 1998-2010,2015 Free Software Foundation, Inc.              *
+.\" Copyright (c) 1998-2017,2018 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            *
@@ -26,7 +26,11 @@
 .\" authorization.                                                           *
 .\"***************************************************************************
 .\"
-.\" $Id: curs_pad.3x,v 1.18 2015/07/21 08:58:44 tom Exp $
+.\" $Id: curs_pad.3x,v 1.25 2018/07/28 22:20:54 tom Exp $
+.de bP
+.ie n  .IP \(bu 4
+.el    .IP \(bu 2
+..
 .TH curs_pad 3X ""
 .na
 .hy 0
@@ -68,6 +72,7 @@ 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.
+.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.
@@ -93,12 +98,15 @@ The \fBprefresh\fR and \fBpnoutrefresh\fR routines are analogous to
 of windows.
 The additional parameters are needed to indicate what part 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.
+.bP
 The \fIsminrow\fR,
 \fIsmincol\fR, \fIsmaxrow\fR, and \fIsmaxcol\fR
 parameters specify the edges 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,
 since the rectangles must be the same size.
@@ -110,7 +118,8 @@ they were zero.
 .SS pechochar
 .PP
 The \fBpechochar\fR routine is functionally equivalent to a call to \fBaddch\fR
-followed by a call to \fBrefresh\fR, a call to \fBwaddch\fR followed by a call
+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
@@ -157,6 +166,76 @@ to \fBwecho_wchar\fP returns an error.
 .SH NOTES
 Note that \fBpechochar\fR may be a macro.
 .SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions.
+BSD curses has no \fIpad\fP feature.
+.PP
+SVr2 curses (1986) provided the \fBnewpad\fP and related functions,
+documenting them in a single line each.
+SVr3 (1987) provided more extensive documentation.
+.PP
+The documentation does not explain the term \fIpad\fP.
+However, the Apollo \fIAegis\fP workstation operating system
+supported a graphical \fIpad\fP feature:
+.bP
+These graphical pads could be much larger than the computer's display.
+.bP
+The read-only output from a command could be scrolled back to inspect,
+and select text from the pad.
+.PP
+The two uses may be related.
+.PP
+The XSI Curses standard, 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
+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.
+.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
+is refreshed properly.
+.bP
+Solaris X/Open Curses checks if a window is a pad in \fBwnoutrefresh\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.
+Consequently, the check will never fail.
+.IP
+It makes no comparable check in \fBpnoutrefresh\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.
+.IP
+It does not check for the case where a subwindow is created in
+a pad using \fBsubwin\fP or \fBderwin\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
+data was from a pad.
+.PP
+This implementation
+.bP
+sets a flag in the \fBWINDOW\fP structure for \fBnewpad\fP and \fBsubpad\fP,
+.bP
+allows a \fBsubwin\fP or \fBderwin\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
+that pads and windows are handled distinctly, and
+.bP
+ensures that \fBdupwin\fP and \fBgetwin\fP treat
+pads versus windows consistently.
 .SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_refresh\fR(3X), \fBcurs_touch\fR(3X), \fBcurs_addch\fR(3X).
+\fBcurses\fR(3X),
+\fBcurs_refresh\fR(3X),
+\fBcurs_touch\fR(3X),
+\fBcurs_addch\fR(3X).