.\"***************************************************************************
-.\" Copyright (c) 1998-2006,2010 Free Software Foundation, Inc. *
+.\" Copyright (c) 1998-2014,2015 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 *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_window.3x,v 1.17 2010/12/04 18:38:55 tom Exp $
+.\" $Id: curs_window.3x,v 1.19 2015/07/21 08:25:23 tom Exp $
.TH curs_window 3X ""
.na
.hy 0
.SH SYNOPSIS
\fB#include <curses.h>\fR
.sp
-\fBWINDOW *newwin(int nlines, int ncols, int begin_y,\fR
- \fBint begin_x);\fR
+\fBWINDOW *newwin(\fR
+ \fBint \fP\fInlines\fP\fB, int \fP\fIncols\fP\fB,\fR
+ \fBint \fP\fIbegin_y\fP\fB, int \fP\fIbegin_x\fP\fB);\fR
.br
-\fBint delwin(WINDOW *win);\fR
+\fBint delwin(WINDOW *\fP\fIwin\fP\fB);\fR
.br
-\fBint mvwin(WINDOW *win, int y, int x);\fR
+\fBint mvwin(WINDOW *\fP\fIwin\fP\fB, int \fP\fIy\fP\fB, int \fP\fIx\fP\fB);\fR
.br
-\fBWINDOW *subwin(WINDOW *orig, int nlines, int ncols,\fR
- \fBint begin_y, int begin_x);\fR
+\fBWINDOW *subwin(WINDOW *\fP\fIorig\fP\fB,\fR
+ \fBint \fP\fInlines\fP\fB, int \fP\fIncols\fP\fB,\fR
+ \fBint \fP\fIbegin_y\fP\fB, int \fP\fIbegin_x\fP\fB);\fR
.br
-\fBWINDOW *derwin(WINDOW *orig, int nlines, int ncols,\fR
- \fBint begin_y, int begin_x);\fR
+\fBWINDOW *derwin(WINDOW *\fP\fIorig\fP\fB,\fR
+ \fBint \fP\fInlines\fP\fB, int \fP\fIncols\fP\fB,\fR
+ \fBint \fP\fIbegin_y\fP\fB, int \fP\fIbegin_x\fP\fB);\fR
.br
-\fBint mvderwin(WINDOW *win, int par_y, int par_x);\fR
+\fBint mvderwin(WINDOW *\fP\fIwin\fP\fB, int \fP\fIpar_y\fP\fB, int \fP\fIpar_x\fP\fB);\fR
.br
-\fBWINDOW *dupwin(WINDOW *win);\fR
+\fBWINDOW *dupwin(WINDOW *\fP\fIwin\fP\fB);\fR
.br
-\fBvoid wsyncup(WINDOW *win);\fR
+\fBvoid wsyncup(WINDOW *\fP\fIwin\fP\fB);\fR
.br
-\fBint syncok(WINDOW *win, bool bf);\fR
+\fBint syncok(WINDOW *\fP\fIwin\fP\fB, bool \fP\fIbf\fP\fB);\fR
.br
-\fBvoid wcursyncup(WINDOW *win);\fR
+\fBvoid wcursyncup(WINDOW *\fP\fIwin\fP\fB);\fR
.br
-\fBvoid wsyncdown(WINDOW *win);\fR
+\fBvoid wsyncdown(WINDOW *\fP\fIwin\fP\fB);\fR
.br
.SH DESCRIPTION
+.SS newwin
Calling \fBnewwin\fR 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.
+given number of lines and columns.
+The upper left-hand corner of the window is
+at
+.RS
+line \fIbegin\fR_\fIy\fR,
+.br
+column \fIbegin\fR_\fIx\fR
+.RE
+.PP
+If either
+\fInlines\fR or \fIncols\fR is zero, they default to
+.RS
+\fBLINES \-\fR \fIbegin\fR_\fIy\fR and
+.br
+\fBCOLS \-\fR \fIbegin\fR_\fIx\fR.
+.RE
+.PP
+A new full-screen window is created by calling \fBnewwin(0,0,0,0)\fR.
+.SS delwin
.PP
Calling \fBdelwin\fR 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.
+image).
+Subwindows must be deleted before the main window can be deleted.
+.SS mvwin
.PP
Calling \fBmvwin\fR 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.
+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.
+.SS subwin
.PP
Calling \fBsubwin\fR 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
+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.
+The subwindow shares memory with the window \fIorig\fR,
+so that changes made to one window
+will affect both windows.
+When using this routine, it is necessary to call
\fBtouchwin\fR or \fBtouchline\fR on \fIorig\fR before calling
\fBwrefresh\fR on the subwindow.
+.SS derwin
.PP
Calling \fBderwin\fR is the same as calling \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.
+of the window \fIorig\fR rather than the screen.
+There is no difference between the subwindows and the derived windows.
.PP
Calling \fBmvderwin\fR 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
+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
.PP
Calling \fBdupwin\fR creates an exact duplicate of the window \fIwin\fR.
+.SS wsyncup
.PP
Calling \fBwsyncup\fR touches all locations in ancestors of \fIwin\fR that are
-changed in \fIwin\fR. If \fBsyncok\fR is called with second argument
+changed in \fIwin\fR.
+If \fBsyncok\fR is called with second argument
\fBTRUE\fR then \fBwsyncup\fR is called automatically whenever there is a
change in the window.
+.SS wsyncdown
.PP
The \fBwsyncdown\fR routine touches each location in \fIwin\fR that has been
-touched in any of its ancestor windows. This routine is called by
+touched in any of its ancestor windows.
+This routine is called by
\fBwrefresh\fR, so it should almost never be necessary to call it manually.
+.SS wcursyncup
.PP
The routine \fBwcursyncup\fR updates the current cursor position of all the
ancestors of the window to reflect the current cursor position of the
.PP
X/Open defines no error conditions.
In this implementation
-.RS
.TP 5
\fBdelwin\fR
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
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.
-.RE
+.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\fR option could
degrade performance.
incompletely implemented, and not well tested.
.PP
The System V curses documentation is very unclear about what \fBwsyncup\fR
-and \fBwsyncdown\fR actually do. It seems to imply that they are only
+and \fBwsyncdown\fR actually do.
+It seems to imply that they are only
supposed to touch exactly those lines that are affected by ancestor changes.
The language here, and the behavior of the \fBcurses\fR implementation,
-is patterned on the XPG4 curses standard. The weaker XPG4 spec may result
-in slower updates.
+is patterned on the XPG4 curses standard.
+The weaker XPG4 spec may result in slower updates.
.SH PORTABILITY
The XSI Curses standard, Issue 4 describes these functions.
.SH SEE ALSO
projects / ncurses.git / blobdiff