X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;ds=sidebyside;f=man%2Fcurs_window.3x;h=d3d55c751444f4374467463a135250ddbee449e3;hb=HEAD;hp=91af66bddbec84c7b41e7a28f55b4891d03ba7ea;hpb=7e062bb2764a87d98073a90ee65a234a2679f9c1;p=ncurses.git

diff --git a/man/curs_window.3x b/man/curs_window.3x
index 91af66bd..88bb4a34 100644
--- a/man/curs_window.3x
+++ b/man/curs_window.3x
@@ -1,5 +1,5 @@
 .\"***************************************************************************
-.\" 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  *
@@ -27,12 +27,8 @@
 .\" 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"
-.de bP
-.ie n  .IP \(bu 4
-.el    .IP \(bu 2
-..
+.\" $Id: curs_window.3x,v 1.52 2024/06/01 22:29:08 tom Exp $
+.TH curs_window 3X 2024-06-01 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls"
 .SH NAME
 \fB\%newwin\fP,
 \fB\%delwin\fP,
@@ -47,35 +43,27 @@
 \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
@@ -135,6 +123,7 @@ 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
@@ -145,7 +134,7 @@ 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.
-.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.
@@ -180,28 +169,36 @@ X/Open defines no error conditions.
 In this implementation
 .TP 5
 \fBdelwin\fP
-returns an error if the window pointer is null, or
+returns
+.B ERR
+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
+returns
+.B ERR
+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.
+returns
+.B ERR
+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
+returns
+.B ERR
 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
+returns
+.B ERR
 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.
@@ -211,11 +208,14 @@ 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
+returns
+.B ERR
 if the window pointer is null.
 .TP 5
 \fBsubwin\fP
-returns an error if the parent window pointer is null, or
+returns
+.B ERR
+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
@@ -228,38 +228,58 @@ 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 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
-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), ncurses 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.
-.br
-PDCurses follows the scheme used in Solaris X/Open curses.
+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),