diff options
Diffstat (limited to 'upstream/fedora-rawhide/man3/curs_window.3x')
| -rw-r--r-- | upstream/fedora-rawhide/man3/curs_window.3x | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/upstream/fedora-rawhide/man3/curs_window.3x b/upstream/fedora-rawhide/man3/curs_window.3x new file mode 100644 index 00000000..e1f84207 --- /dev/null +++ b/upstream/fedora-rawhide/man3/curs_window.3x @@ -0,0 +1,272 @@ +.\"*************************************************************************** +.\" Copyright 2020-2022,2023 Thomas E. Dickey * +.\" Copyright 1998-2015,2016 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 * +.\" "Software"), to deal in the Software without restriction, including * +.\" without limitation the rights to use, copy, modify, merge, publish, * +.\" distribute, distribute with modifications, sublicense, and/or sell * +.\" copies of the Software, and to permit persons to whom the Software is * +.\" furnished to do so, subject to the following conditions: * +.\" * +.\" The above copyright notice and this permission notice shall be included * +.\" in all copies or substantial portions of the Software. * +.\" * +.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * +.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * +.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * +.\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * +.\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * +.\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * +.\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * +.\" * +.\" Except as contained in this notice, the name(s) of the above copyright * +.\" holders shall not be used in advertising or otherwise to promote the * +.\" sale, use or other dealings in this Software without prior written * +.\" authorization. * +.\"*************************************************************************** +.\" +.\" $Id: curs_window.3x,v 1.44 2023/12/16 20:32:22 tom Exp $ +.TH curs_window 3X 2023-12-16 "ncurses 6.4" "Library calls" +.de bP +.ie n .IP \(bu 4 +.el .IP \(bu 2 +.. +.SH NAME +\fB\%newwin\fP, +\fB\%delwin\fP, +\fB\%mvwin\fP, +\fB\%subwin\fP, +\fB\%derwin\fP, +\fB\%mvderwin\fP, +\fB\%dupwin\fP, +\fB\%wsyncup\fP, +\fB\%syncok\fP, +\fB\%wcursyncup\fP, +\fB\%wsyncdown\fP \- +create and manipulate \fIcurses\fR windows +.SH SYNOPSIS +.nf +\fB#include <curses.h> +.PP +\fBWINDOW *newwin( + \fBint \fInlines\fB, int \fIncols\fB,\fR + \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR +\fBint delwin(WINDOW *\fIwin\fB);\fR +\fBint mvwin(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR +\fBWINDOW *subwin(WINDOW *\fIorig\fB,\fR + \fBint \fInlines\fB, int \fIncols\fB,\fR + \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR +\fBWINDOW *derwin(WINDOW *\fIorig\fB,\fR + \fBint \fInlines\fB, int \fIncols\fB,\fR + \fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR +\fBint mvderwin(WINDOW *\fIwin\fB, int \fIpar_y\fB, int \fIpar_x\fB);\fR +\fBWINDOW *dupwin(WINDOW *\fIwin\fB);\fR +\fBvoid wsyncup(WINDOW *\fIwin\fB);\fR +\fBint syncok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR +\fBvoid wcursyncup(WINDOW *\fIwin\fB);\fR +\fBvoid wsyncdown(WINDOW *\fIwin\fB);\fR +.fi +.SH DESCRIPTION +.SS newwin +Calling \fBnewwin\fP creates and returns a pointer to a new window with the +given number of lines and columns. +The upper left-hand corner of the window is +at +.RS +line \fIbegin\fR_\fIy\fP, +.br +column \fIbegin\fR_\fIx\fP +.RE +.PP +If either +\fInlines\fP or \fIncols\fP is zero, they default to +.RS +\fBLINES \-\fP \fIbegin\fR_\fIy\fP and +.br +\fBCOLS \-\fP \fIbegin\fR_\fIx\fP. +.RE +.PP +A new full-screen window is created by calling \fBnewwin(0,0,0,0)\fP. +.PP +Regardless of the function used for creating a new window +(e.g., \fBnewwin\fP, \fBsubwin\fP, \fBderwin\fP, \fBnewpad\fP), +rather than a duplicate (with \fBdupwin\fP), +all of the window modes are initialized to the default values. +These functions set window modes after a window is created: +.RS +.PP +\fB\%idcok\fP +\fB\%idlok\fP +\fB\%immedok\fP +\fB\%keypad\fP +\fB\%leaveok\fP +\fB\%nodelay\fP +\fB\%scrollok\fP +\fB\%setscrreg\fP +\fB\%syncok\fP +\fB\%wbkgdset\fP +\fB\%wbkgrndset\fP and +\fB\%wtimeout\fP. +.RE +.SS delwin +Calling \fBdelwin\fP deletes the named window, freeing all memory +associated with it (it does not actually erase the window's screen +image). +Subwindows must be deleted before the main window can be deleted. +.SS mvwin +Calling \fBmvwin\fP moves the window so that the upper left-hand +corner is at position (\fIx\fP, \fIy\fP). +If the move would cause the window to be off the screen, +it is an error and the window is not moved. +Moving subwindows is allowed, but should be avoided. +.SS subwin +Calling \fBsubwin\fP creates and returns a pointer to a new window +with the given number of lines, \fInlines\fP, and columns, \fIncols\fP. +The window is at position (\fIbegin\fR_\fIy\fP, +\fIbegin\fR_\fIx\fP) on the screen. +The subwindow shares memory with the window \fIorig\fP, +its \fIancestor\fP, +so that changes made to one window +will affect both windows. +When using this routine, it is necessary to call +\fBtouchwin\fP or \fBtouchline\fP on \fIorig\fP before calling +\fBwrefresh\fP on the subwindow. +.SS derwin +Calling \fBderwin\fP is the same as calling \fBsubwin,\fP except that +\fIbegin\fR_\fIy\fP and \fIbegin\fR_\fIx\fP are relative to the origin +of the window \fIorig\fP rather than the screen. +There is no difference between the subwindows and the derived windows. +.SS mvderwin +Calling \fBmvderwin\fP moves a derived window (or subwindow) +inside its parent window. +The screen-relative parameters of the window are not changed. +This routine is used to display different +parts of the parent window at the same physical position on the +screen. +.SS dupwin +Calling \fBdupwin\fP creates an exact duplicate of the window \fIwin\fP. +.SS wsyncup +Calling \fBwsyncup\fP touches all locations in ancestors of \fIwin\fP that are +changed in \fIwin\fP. +If \fBsyncok\fP is called with second argument +\fBTRUE\fP then \fBwsyncup\fP is called automatically whenever there is a +change in the window. +.SS wsyncdown +The \fBwsyncdown\fP routine touches each location in \fIwin\fP that has been +touched in any of its ancestor windows. +This routine is called by +\fBwrefresh\fP, so it should almost never be necessary to call it manually. +.SS wcursyncup +The routine \fBwcursyncup\fP updates the current cursor position of all the +ancestors of the window to reflect the current cursor position of the +window. +.SH RETURN VALUE +Routines that return an integer return the integer \fBERR\fP upon failure and +\fBOK\fP (SVr4 only specifies "an integer value other than \fBERR\fP") upon +successful completion. +.PP +Routines that return pointers return \fBNULL\fP on error. +.PP +X/Open defines no error conditions. +In this implementation +.TP 5 +\fBdelwin\fP +returns an error if the window pointer is null, or +if the window is the parent of another window. +.TP 5 +\fBderwin\fP +returns an error if the parent window pointer is null, or +if any of its ordinates or dimensions is negative, or +if the resulting window does not fit inside the parent window. +.TP 5 +\fBdupwin\fP +returns an error if the window pointer is null. +.IP +This implementation also maintains a list of windows, +and checks that the pointer passed to \fBdelwin\fP is one that +it created, returning an error if it was not.. +.TP 5 +\fBmvderwin\fP +returns an error +if the window pointer is null, or +if some part of the window would be placed off-screen. +.TP 5 +\fBmvwin\fP +returns an error +if the window pointer is null, or +if the window is really a pad, or +if some part of the window would be placed off-screen. +.TP 5 +\fBnewwin\fP +will fail if either of its beginning ordinates is negative, or +if either the number of lines or columns is negative. +.TP 5 +\fBsyncok\fP +returns an error +if the window pointer is null. +.TP 5 +\fBsubwin\fP +returns an error if the parent window pointer is null, or +if any of its ordinates or dimensions is negative, or +if the resulting window does not fit inside the parent window. +.PP +The functions which return a window pointer +may also fail if there is insufficient memory for its data structures. +Any of these functions will fail if the screen has not been initialized, +i.e., with \fBinitscr\fP or \fBnewterm\fP. +.SH NOTES +If many small changes are made to the window, the \fBwsyncup\fP option could +degrade performance. +.PP +Note that \fBsyncok\fP may be a macro. +.SH PORTABILITY +The XSI Curses standard, Issue 4 describes these functions. +.PP +X/Open Curses states regarding \fBdelwin\fP: +.bP +It must delete subwindows before deleting their parent. +.bP +If \fBdelwin\fP is asked to delete a parent window, +it can only succeed if the curses library keeps a list of the subwindows. +SVr4 curses kept a count of the number of subwindows rather than a list. +It simply returned \fBERR\fP when asked to delete a subwindow. +Solaris X/Open curses does not even make that check, +and will delete a parent window which still has subwindows. +.bP +Since release 4.0 (1996), +\fI\%ncurses\fP maintains a list of windows for each screen, +to ensure that a window has no subwindows before allowing deletion. +.bP +NetBSD copied this feature of \fI\%ncurses\fP in 2003. +.br +PDCurses follows the scheme used in Solaris X/Open curses. +.SH BUGS +The subwindow functions +\fB\%subwin\fP, +\fB\%derwin\fP, +\fB\%mvderwin\fP, +\fB\%wsyncup\fP, +\fB\%wsyncdown\fP, +\fB\%wcursyncup\fP, +and +\fB\%syncok\fP +are flaky, +incompletely implemented, +and not well tested. +.PP +System\ V's \fIcurses\fP documentation is unclear about what +\fB\%wsyncup\fP and \fB\%wsyncdown\fP actually do. +It seems to imply that they are supposed to touch only those lines that +are affected by changes to a window's ancestors. +The language here, +and behavior of \fI\%ncurses\fP, +is patterned on the X/Open Curses standard; +this approach may result in slower updates. +.SH SEE ALSO +\fB\%curses\fP(3X), +\fB\%curs_initscr\fP(3X), +\fB\%curs_refresh\fP(3X), +\fB\%curs_touch\fP(3X), +\fB\%curs_variables\fP(3X) |