.\"***************************************************************************
-.\" Copyright 2018-2022,2023 Thomas E. Dickey *
+.\" 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_pad.3x,v 1.43 2023/09/23 22:49:51 tom Exp $
-.TH curs_pad 3X 2023-09-23 "ncurses 6.4" "Library calls"
+.\" $Id: curs_pad.3x,v 1.55 2024/03/16 15:49:29 tom Exp $
+.TH curs_pad 3X 2024-03-16 "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
create and display \fIcurses\fR pads
.SH SYNOPSIS
.nf
-\fB#include <curses.h>\fP
+\fB#include <curses.h>
.PP
-\fBWINDOW *newpad(int \fInlines\fB, int \fIncols\fB);\fR
-\fBWINDOW *subpad(WINDOW *\fIorig\fB, int \fInlines\fB, int \fIncols\fB,\fR
+\fBWINDOW *newpad(int \fInlines\fP, int \fIncols\fP);
+\fBWINDOW *subpad(WINDOW *\fIorig\fP, int \fInlines\fP, int \fIncols\fP,
\fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
\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
.fi
.SH DESCRIPTION
.SS newpad
-The \fB\%newpad\fP routine creates and returns a pointer to a new pad data
-structure with the given number of lines, \fInlines\fP, and columns,
+\fB\%newpad\fP creates and returns a pointer to a new pad data structure
+with the given number of lines,
+\fInlines\fP,
+and columns,
\fIncols\fP.
-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.
+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.
+(as from scrolling or echoing of input)
+do not occur.
.PP
-It is not
-legal to call \fB\%wrefresh\fP with a \fIpad\fP as an argument; the routines
-\fB\%prefresh\fP or \fB\%pnoutrefresh\fP should be called instead.
-Note that these
-routines require additional parameters to specify the part of the pad to be
+It is not valid to call \fB\%wrefresh\fP with a \fIpad\fP argument;
+call \fB\%prefresh\fP or \fB\%pnoutrefresh\fP 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.
.SS subpad
The \fB\%subpad\fP routine creates and returns a pointer to a subwindow within a
During the use of this routine, it will often be
necessary to call \fB\%touchwin\fP or \fB\%touchline\fP on \fIorig\fP before
calling \fB\%prefresh\fP.
-.SS prefresh, pnoutrefresh
+.SS "prefresh, pnoutrefresh"
The \fB\%prefresh\fP and \fB\%pnoutrefresh\fP routines are analogous to
\fB\%wrefresh\fP and \fB\%wnoutrefresh\fP except that they relate to pads instead
of windows.
\fIpminrow\fP, \fIpmincol\fP, \fIsminrow\fP, or \fIsmincol\fP are treated as if
they were zero.
.SS pechochar
-The \fB\%pechochar\fP routine is functionally equivalent to a call to \fB\%addch\fP
+The \fB\%pechochar\fP routine is functionally equivalent
+to a call to \fB\%addch\fP
followed by a call to \fB\%refresh\fP(3X),
a call to \fB\%waddch\fP followed by a call
to \fB\%wrefresh\fP, or a call to \fB\%waddch\fP followed by a call to
The \fB\%pecho_wchar\fP function is the analogous wide-character
form of \fB\%pechochar\fP.
It outputs one character to a pad and immediately refreshes the pad.
-It does this by a call to \fB\%wadd_wch\fP followed by a call to \fB\%prefresh\fP.
+It does this by a call to \fB\%wadd_wch\fP followed by a call
+to \fB\%prefresh\fP.
.SH RETURN VALUE
-Routines that return an integer return \fBERR\fP upon failure and \fBOK\fP
-(SVr4 only specifies "an integer value other than \fBERR\fP") 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\fP on error, and set \fB\%errno\fP
-to \fB\%ENOMEM\fP.
+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
to \fB\%wecho_wchar\fP returns an error.
.RE
.SH NOTES
-Note that \fB\%pechochar\fP may be a macro.
+\fB\%pechochar\fP may be a macro.
.SH PORTABILITY
BSD \fIcurses\fP has no \fIpad\fP feature.
.PP
a pad is undocumented,
and is not checked by the vendor Unix implementations:
.bP
-SVr4 \fIcurses\fP sets a flag in the \fB\%WINDOW\fP structure in \fB\%newpad\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
\fB\%waddch\fP (to decide if it should call \fB\%wrefresh\fP) and
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 \fB\%wnoutrefresh\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.
+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
states that the lack of a check was an MKS extension.
.bP
NetBSD 7 \fIcurses\fP
-sets a flag in the \fB\%WINDOW\fP structure for \fB\%newpad\fP and \fB\%subpad\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
.PP
This implementation
.bP
-sets a flag in the \fB\%WINDOW\fP structure for \fB\%newpad\fP and \fB\%subpad\fP,
+sets a flag in the \fI\%WINDOW\fP structure
+for \fB\%newpad\fP and \fB\%subpad\fP,
.bP
allows a \fB\%subwin\fP or \fB\%derwin\fP call to succeed having a pad parent by
forcing the subwindow to be a pad,
pads versus windows consistently.
.SH SEE ALSO
\fB\%curses\fP(3X),
+\fB\%curs_addch\fP(3X),
\fB\%curs_refresh\fP(3X),
-\fB\%curs_touch\fP(3X),
-\fB\%curs_addch\fP(3X)
+\fB\%curs_touch\fP(3X)
projects / ncurses.git / blobdiff