diff options
Diffstat (limited to 'upstream/archlinux/man3/curs_pad.3x')
| -rw-r--r-- | upstream/archlinux/man3/curs_pad.3x | 288 |
1 files changed, 163 insertions, 125 deletions
diff --git a/upstream/archlinux/man3/curs_pad.3x b/upstream/archlinux/man3/curs_pad.3x index da25f3b7..f23b2df4 100644 --- a/upstream/archlinux/man3/curs_pad.3x +++ b/upstream/archlinux/man3/curs_pad.3x @@ -1,5 +1,5 @@ .\"*************************************************************************** -.\" Copyright 2018-2021,2022 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 * @@ -27,127 +27,161 @@ .\" authorization. * .\"*************************************************************************** .\" -.\" $Id: curs_pad.3x,v 1.29 2022/02/12 20:05:11 tom Exp $ +.\" $Id: curs_pad.3x,v 1.61 2024/04/27 17:55:43 tom Exp $ +.TH curs_pad 3X 2024-04-27 "ncurses 6.5" "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\fP, -\fBsubpad\fP, -\fBprefresh\fP, -\fBpnoutrefresh\fP, -\fBpechochar\fP, -\fBpecho_wchar\fP \- create and display \fBcurses\fP 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>\fP -.sp -\fBWINDOW *newpad(int \fInlines\fB, int \fIncols\fB);\fR -.br -\fBWINDOW *subpad(WINDOW *\fIorig\fB, int \fInlines\fB, int \fIncols\fB,\fR +.nf +\fB#include <curses.h> +.PP +\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 -.br +.PP \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 -.br \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 -.br +.PP \fBint pechochar(WINDOW *\fIpad\fB, chtype \fIch\fB);\fR -.br \fBint pecho_wchar(WINDOW *\fIpad\fB, const cchar_t *\fIwch\fB);\fR +.fi .SH DESCRIPTION -.SS newpad -The \fBnewpad\fP routine 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. -Automatic refreshes of pads -(e.g., from scrolling or echoing of input) do not occur. +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 -It is not -legal to call \fBwrefresh\fP with a \fIpad\fP as an argument; the routines -\fBprefresh\fP or \fBpnoutrefresh\fP 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. +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 -.PP -The \fBsubpad\fP routine creates and returns a pointer to a subwindow within a -pad with the given number of lines, \fInlines\fP, and columns, \fIncols\fP. -Unlike \fBsubwin\fP, which uses screen coordinates, the window is at position -(\fIbegin\fR_\fIx\fB,\fR \fIbegin\fR_\fIy\fR) on the pad. -The window is -made in the middle of the window \fIorig\fP, so that changes made to one window -affect both windows. -During the use of this routine, it will often be -necessary to call \fBtouchwin\fP or \fBtouchline\fP on \fIorig\fP before -calling \fBprefresh\fP. -.SS prefresh, pnoutrefresh -.PP -The \fBprefresh\fP and \fBpnoutrefresh\fP routines are analogous to -\fBwrefresh\fP and \fBwnoutrefresh\fP 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. +.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\fP and \fIpmincol\fP 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 rectangular view of the pad. .bP -The \fIsminrow\fP, -\fIsmincol\fP, \fIsmaxrow\fP, and \fIsmaxcol\fP -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\fP, \fIpmincol\fP, \fIsminrow\fP, or \fIsmincol\fP 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\fP routine is functionally equivalent to a call to \fBaddch\fP -followed by a call to \fBrefresh\fP(3X), -a call to \fBwaddch\fP followed by a call -to \fBwrefresh\fP, or a call to \fBwaddch\fP followed by a call to -\fBprefresh\fP. -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\fP, the last location of the pad on -the screen is reused for the arguments to \fBprefresh\fP. +.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\fP function is the analogous wide-character -form of \fBpechochar\fP. -It outputs one character to a pad and immediately refreshes the pad. -It does this by a call to \fBwadd_wch\fP followed by a call to \fBprefresh\fP. +.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\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 \fBerrno\fP -to \fBENOMEM\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 -\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 @@ -157,19 +191,19 @@ if the minimum coordinates are greater than the maximum. \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\fP 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 @@ -184,59 +218,63 @@ and select text from the pad. .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\fP(3X), -\fBcurs_refresh\fP(3X), -\fBcurs_touch\fP(3X), -\fBcurs_addch\fP(3X). +\fB\%curses\fP(3X), +\fB\%curs_addch\fP(3X), +\fB\%curs_refresh\fP(3X), +\fB\%curs_touch\fP(3X) |