vasilito
ff4ff35918
Red Bear OS is a full fork. All sources must be available from git clone with zero network access. Removed gitignore rules that excluded fetched source trees under recipes/*/source/, local/recipes/kde/*/source/, local/recipes/qt/*/source/, and vendor source trees. Build artifacts (target/, build/, source.tar, *.o, *.so) remain excluded. 127291 files added — kernel, relibc, base, bootloader, pkgar, all KDE/Qt frameworks, mesa, wayland, DRM drivers, and every other recipe source.
349 lines
10 KiB
Plaintext
349 lines
10 KiB
Plaintext
.\"***************************************************************************
|
|
.\" Copyright 2020-2024,2025 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.71 2025/08/23 22:50:00 tom Exp $
|
|
.TH curs_window 3X 2025-08-23 "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
|
|
..
|
|
.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(\fR
|
|
\fBint \fInlines\fP, int \fIncols\fP,
|
|
\fBint \fIbegin_y\fP, int \fIbegin_x\fP);
|
|
\fBint delwin(WINDOW * \fIwin\fP);
|
|
\fBint mvwin(WINDOW * \fIwin\fP, int \fIy\fP, int \fIx\fP);
|
|
\fBWINDOW * subwin(WINDOW * \fIorig\fP,
|
|
\fBint \fInlines\fP, int \fIncols\fP,
|
|
\fBint \fIbegin_y\fP, int \fIbegin_x\fP);
|
|
\fBWINDOW * derwin(WINDOW * \fIorig\fP,
|
|
\fBint \fInlines\fP, int \fIncols\fP,
|
|
\fBint \fIbegin_y\fP, int \fIbegin_x\fP);
|
|
\fBint mvderwin(WINDOW * \fIwin\fP, int \fIpar_y\fP, int \fIpar_x\fP);
|
|
\fBWINDOW * dupwin(WINDOW * \fIwin\fP);
|
|
\fBvoid wsyncup(WINDOW * \fIwin\fP);
|
|
\fBint syncok(WINDOW * \fIwin\fP, bool \fIbf\fP);
|
|
\fBvoid wcursyncup(WINDOW * \fIwin\fP);
|
|
\fBvoid wsyncdown(WINDOW * \fIwin\fP);
|
|
.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.
|
|
The following functions set a window's modes after it is created:
|
|
.RS
|
|
.PP
|
|
.BR \%idcok ","
|
|
.BR \%idlok ","
|
|
.BR \%immedok ","
|
|
.BR \%keypad ","
|
|
.BR \%leaveok ","
|
|
.BR \%nodelay ","
|
|
.BR \%notimeout ","
|
|
.BR \%scrollok ","
|
|
.BR \%setscrreg ","
|
|
.BR \%syncok ","
|
|
.BR \%wbkgdset ","
|
|
.BR \%wbkgrndset ","
|
|
and
|
|
.BR \%wtimeout "."
|
|
.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
|
|
Functions that return integers return
|
|
.B ERR
|
|
upon failure and
|
|
.B OK
|
|
upon success.
|
|
.PP
|
|
Functions that return pointers return a null pointer on failure.
|
|
.PP
|
|
.I \%ncurses
|
|
defines several error conditions.
|
|
.bP
|
|
.B \%delwin
|
|
returns
|
|
.B ERR
|
|
if
|
|
.I win
|
|
is a null pointer,
|
|
or if it is the parent of another window.
|
|
.IP
|
|
.I \%ncurses
|
|
maintains a list of windows,
|
|
and checks that the pointer passed to
|
|
.B \%delwin
|
|
is one that it created,
|
|
returning
|
|
.B ERR
|
|
if it was not.
|
|
.bP
|
|
.B \%derwin
|
|
returns
|
|
.B ERR
|
|
if
|
|
.I orig
|
|
is a null pointer,
|
|
or if any of the ordinate or dimension arguments is negative,
|
|
or if the resulting window does not fit inside the parent window.
|
|
.bP
|
|
.B \%dupwin
|
|
returns
|
|
.B ERR
|
|
if
|
|
.I win
|
|
is a null pointer.
|
|
.bP
|
|
.B \%mvderwin
|
|
returns
|
|
.B ERR
|
|
if
|
|
.I win
|
|
is a null pointer,
|
|
or if any part of the window would be placed off-screen.
|
|
.bP
|
|
.B \%mvwin
|
|
returns
|
|
.B ERR
|
|
if
|
|
.I win
|
|
is a null pointer,
|
|
if
|
|
.I win
|
|
is a pad,
|
|
or if any part of the window would be placed off-screen.
|
|
.bP
|
|
.B \%newwin
|
|
returns
|
|
.B ERR
|
|
if any of its arguments is negative.
|
|
.bP
|
|
.B \%subwin
|
|
returns
|
|
.B ERR
|
|
if
|
|
.I orig
|
|
is a null pointer,
|
|
or if any of the ordinate or dimension arguments is negative,
|
|
or if the resulting window does not fit inside the parent window.
|
|
.bP
|
|
.B \%syncok
|
|
returns
|
|
.B ERR
|
|
if
|
|
.I win
|
|
is a null pointer.
|
|
.PP
|
|
Functions that return a window pointer fail if memory allocation
|
|
for their data structures fails.
|
|
.PP
|
|
All of these functions fail if the screen has not been initialized;
|
|
see \fBinitscr\fP(3X) or \fBnewterm\fP(3X).
|
|
.SH NOTES
|
|
.B \%syncok
|
|
may be implemented as a macro.
|
|
.PP
|
|
Calling
|
|
.B \%syncup
|
|
on a window and making many small changes to it
|
|
could degrade performance.
|
|
.SH PORTABILITY
|
|
X/Open Curses Issue\ 4 describes these functions.
|
|
It specifies no error conditions for
|
|
.IR \%delwin ","
|
|
.IR \%derwin ","
|
|
.IR \%dupwin ","
|
|
.IR \%newwin ","
|
|
.IR \%mvderwin ","
|
|
or
|
|
.IR \%syncok "."
|
|
.PP
|
|
For functions returning integers
|
|
(except
|
|
.IR \%delwin "),"
|
|
SVr4 describes a successful return value only as
|
|
\*(``an integer value other than
|
|
.IR ERR \*(''. \" Courier roman in source; SVID 4, vol. 3, p. 544
|
|
.PP
|
|
Regarding
|
|
.IR \%delwin ","
|
|
X/Open Curses states that
|
|
.RS
|
|
.PP
|
|
[t]he application must delete subwindows before deleting the main
|
|
window.
|
|
.RE
|
|
.PP
|
|
If
|
|
.I \%delwin
|
|
is asked to delete a parent window,
|
|
it can succeed only if the
|
|
.I curses
|
|
library keeps a list of its subwindows.
|
|
SVr4
|
|
.I curses
|
|
kept a count of the number of subwindows rather than a list.
|
|
It simply returned
|
|
.B ERR
|
|
when asked to delete a subwindow.
|
|
Solaris X/Open
|
|
.I curses
|
|
.RI \%( xcurses )
|
|
does not make even that check,
|
|
and will delete a parent window that still has subwindows.
|
|
.I \%PDCurses
|
|
also behaves this way.
|
|
.PP
|
|
.I \%ncurses
|
|
4.0 (1996) and later maintains a list of windows for each screen
|
|
to ensure that a window has no subwindows before allowing its deletion.
|
|
NetBSD
|
|
.I curses
|
|
has followed suit since 2003.
|
|
.PP
|
|
SVr4
|
|
.I curses
|
|
documentation is unclear about what
|
|
.I \%wsyncup
|
|
and
|
|
.I \%wsyncdown
|
|
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 description and behavior of these functions in
|
|
.I \%ncurses
|
|
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)
|