.\"***************************************************************************
-.\" Copyright 2020-2022,2023 Thomas E. Dickey *
+.\" Copyright 2020-2023,2024 Thomas E. Dickey *
.\" Copyright 1998-2015,2016 Free Software Foundation, Inc. *
.\" *
.\" Permission is hereby granted, free of charge, to any person obtaining a *
.\" authorization. *
.\"***************************************************************************
.\"
-.\" $Id: curs_window.3x,v 1.39 2023/09/30 23:13:32 tom Exp $
-.TH curs_window 3X 2023-09-30 "ncurses 6.4" "Library calls"
+.\" $Id: curs_window.3x,v 1.48 2024/04/20 21:20:07 tom Exp $
+.TH curs_window 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
.de bP
.ie n .IP \(bu 4
.el .IP \(bu 2
\fB\%wsyncdown\fP \-
create and manipulate \fIcurses\fR windows
.SH SYNOPSIS
-\fB#include <curses.h>\fP
-.sp
-\fBWINDOW *newwin(\fP
+.nf
+\fB#include <curses.h>
+.PP
+\fBWINDOW *newwin(
\fBint \fInlines\fB, int \fIncols\fB,\fR
\fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
-.br
\fBint delwin(WINDOW *\fIwin\fB);\fR
-.br
\fBint mvwin(WINDOW *\fIwin\fB, int \fIy\fB, int \fIx\fB);\fR
-.br
\fBWINDOW *subwin(WINDOW *\fIorig\fB,\fR
\fBint \fInlines\fB, int \fIncols\fB,\fR
\fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
-.br
\fBWINDOW *derwin(WINDOW *\fIorig\fB,\fR
\fBint \fInlines\fB, int \fIncols\fB,\fR
\fBint \fIbegin_y\fB, int \fIbegin_x\fB);\fR
-.br
\fBint mvderwin(WINDOW *\fIwin\fB, int \fIpar_y\fB, int \fIpar_x\fB);\fR
-.br
\fBWINDOW *dupwin(WINDOW *\fIwin\fB);\fR
-.br
\fBvoid wsyncup(WINDOW *\fIwin\fB);\fR
-.br
\fBint syncok(WINDOW *\fIwin\fB, bool \fIbf\fB);\fR
-.br
\fBvoid wcursyncup(WINDOW *\fIwin\fB);\fR
-.br
\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
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
\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.
-.PP
+.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.
degrade performance.
.PP
Note that \fBsyncok\fP may be a macro.
-.SH BUGS
-The subwindow functions (\fBsubwin\fP, \fBderwin\fP, \fBmvderwin\fP,
-\fBwsyncup\fP, \fBwsyncdown\fP, \fBwcursyncup\fP, \fBsyncok\fP) are flaky,
-incompletely implemented, and not well tested.
-.PP
-The System V curses documentation is very unclear about what \fBwsyncup\fP
-and \fBwsyncdown\fP 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\fP implementation,
-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.
+X/Open Curses, Issue 4 describes these functions.
.PP
X/Open Curses states regarding \fBdelwin\fP:
.bP
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), ncurses maintains a list of windows for each screen,
+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 ncurses in 2003.
+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),
projects / ncurses.git / blobdiff