8370a72faa
old 1M, 3X and 3S section numbers) and make some minor formatting changes to silence manck.
124 lines
5.0 KiB
Groff
124 lines
5.0 KiB
Groff
.TH curs_window 3 ""
|
|
.SH NAME
|
|
\fBnewwin\fR, \fBdelwin\fR, \fBmvwin\fR,
|
|
\fBsubwin\fR, \fBderwin\fR, \fBmvderwin\fR, \fBdupwin\fR,
|
|
\fBwsyncup\fR, \fBsyncok\fR, \fBwcursyncup\fR,
|
|
\fBwsyncdown\fR - create \fBncurses\fR windows
|
|
.SH SYNOPSIS
|
|
\fB#include <ncurses.h>\fR
|
|
|
|
\fBWINDOW *newwin(int nlines, int ncols, int begin_y,\fR
|
|
\fBintbegin_x);\fR
|
|
|
|
\fBint delwin(WINDOW *win);\fR
|
|
.br
|
|
\fBint mvwin(WINDOW *win, int y, int x);\fR
|
|
.br
|
|
\fBWINDOW *subwin(WINDOW *orig, int nlines, int ncols,
|
|
int begin_y, int begin_x);\fR
|
|
\fBWINDOW *derwin(WINDOW *orig, int nlines, int ncols,
|
|
int begin_y, int begin_x);\fR
|
|
\fBint mvderwin(WINDOW *win, int par_y, int par_x);\fR
|
|
.br
|
|
\fBWINDOW *dupwin(WINDOW *win);\fR
|
|
.br
|
|
\fBvoid wsyncup(WINDOW *win);\fR
|
|
.br
|
|
\fBint syncok(WINDOW *win, bool bf);\fR
|
|
.br
|
|
\fBvoid wcursyncup(WINDOW *win);\fR
|
|
.br
|
|
\fBvoid wsyncdown(WINDOW *win);\fR
|
|
.br
|
|
.SH DESCRIPTION
|
|
The \fBnewwin\fR routine 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 line \fIbegin\fR_\fIy\fR, column \fIbegin\fR_\fIx\fR. If either
|
|
\fInlines\fR or \fIncols\fR is zero, they default to \fBLINES -\fR
|
|
\fIbegin\fR_\fIy\fR and \fBCOLS -\fR \fIbegin\fR_\fIx\fR. A new full-screen
|
|
window is created by calling \fBnewwin(0,0,0,0)\fR.
|
|
|
|
The \fBdelwin\fR routine 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.
|
|
|
|
The \fBmvwin\fR routine moves the window so that the upper left-hand
|
|
corner is at position (\fIx\fR, \fIy\fR). 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.
|
|
|
|
The \fBsubwin\fR routine creates and returns a pointer to a new window
|
|
with the given number of lines, \fInlines\fR, and columns,
|
|
\fIncols\fR. The window is at position (\fIbegin\fR_\fIy\fR,
|
|
\fIbegin\fR_\fIx\fR) on the screen. (This position is relative to the
|
|
screen, and not to the window \fIorig\fR.) The window is made in the
|
|
middle of the window \fIorig\fR, so that changes made to one window
|
|
will affect both windows. The subwindow shares memory with the window
|
|
\fIorig\fR. When using this routine, it is necessary to call
|
|
\fBtouchwin\fR or \fBtouchline\fR on \fIorig\fR before calling
|
|
\fBwrefresh\fR on the subwindow.
|
|
|
|
The \fBderwin\fR routine is the same as \fBsubwin,\fR except that
|
|
\fIbegin\fR_\fIy\fR and \fIbegin\fR_\fIx\fR are relative to the origin
|
|
of the window \fIorig\fR rather than the screen. There is no
|
|
difference between the subwindows and the derived windows.
|
|
|
|
The \fBmvderwin\fR routine 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.
|
|
|
|
The \fBdupwin\fR routine creates an exact duplicate of the window \fIwin\fR.
|
|
|
|
Each \fBncurses\fR window maintains two data structures: the character
|
|
image structure and the status structure. The character image
|
|
structure is shared among all windows in the window hierarchy
|
|
(\fIi\fR.\fIe\fR., the window with all subwindows). The status
|
|
structure, which contains information about individual line changes in
|
|
the window, is private to each window. The routine \fBwrefresh\fR
|
|
uses the status data structure when performing screen updating. Since
|
|
status structures are not shared, changes made to one window in the
|
|
hierarchy may not be properly reflected on the screen.
|
|
|
|
The routine \fBwsyncup\fR causes the changes in the status structure
|
|
of a window to be reflected in the status structures of its ancestors.
|
|
If \fBsyncok\fR is called with second argument \fBTRUE\fR then
|
|
\fBwsyncup\fR is called automatically whenever there is a change in
|
|
the window.
|
|
|
|
The routine \fBwcursyncup\fR updates the current cursor position of all the
|
|
ancestors of the window to reflect the current cursor position of the
|
|
window.
|
|
|
|
The routine \fBwsyncdown\fR updates the status structure of the window
|
|
to reflect the changes in the status structures of its ancestors.
|
|
Applications seldom call this routine because it is called
|
|
automatically by \fBwrefresh\fR.
|
|
.SH RETURN VALUE
|
|
Routines that return an integer return the integer \fBERR\fR upon failure and
|
|
an integer value other than \fBERR\fR upon successful completion.
|
|
|
|
\fBdelwin\fR returns the integer \fBERR\fR upon failure and \fBOK\fR
|
|
upon successful completion.
|
|
|
|
Routines that return pointers return \fBNULL\fR on error.
|
|
.SH NOTES
|
|
If many small changes are made to the window, the \fBwsyncup\fR option could
|
|
degrade performance.
|
|
|
|
Note that \fBsyncok\fR may be a macro.
|
|
.SH BUGS
|
|
The subwindow functions (\fIsubwin\fR, \fIderwin\fR, etc.) are flaky,
|
|
incompletely implemented, and not well tested, especially in their
|
|
interaction with scrolling.
|
|
.SH SEE ALSO
|
|
\fBncurses\fR(3), \fBcurs_refresh\fR(3), \fBcurs_touch\fR(3)
|
|
.\"#
|
|
.\"# The following sets edit modes for GNU EMACS
|
|
.\"# Local Variables:
|
|
.\"# mode:nroff
|
|
.\"# fill-column:79
|
|
.\"# End:
|