-.TH curs_refresh 3X ""
+.\"***************************************************************************
+.\" Copyright 2018-2023,2024 Thomas E. Dickey *
+.\" Copyright 1998-2010,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_refresh.3x,v 1.46 2024/04/20 21:20:07 tom Exp $
+.TH curs_refresh 3X 2024-04-20 "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
-\fBrefresh\fR, \fBwrefresh\fR, \fBwnoutrefresh\fR,
-\fBdoupdate\fR, \fBredrawwin\fR, \fBwredrawln\fR - refresh
-\fBcurses\fR windows and lines
+\fB\%doupdate\fP,
+\fB\%redrawwin\fP,
+\fB\%refresh\fP,
+\fB\%wnoutrefresh\fP,
+\fB\%wredrawln\fP,
+\fB\%wrefresh\fP \-
+refresh \fIcurses\fR windows or lines thereupon
.SH SYNOPSIS
-\fB#include <curses.h>\fR
-
-\fBint refresh(void);\fR
-.br
-\fBint wrefresh(WINDOW *win);\fR
-.br
-\fBint wnoutrefresh(WINDOW *win);\fR
-.br
-\fBint doupdate(void);\fR
-.br
-\fBint redrawwin(WINDOW *win);\fR
-.br
-\fBint wredrawln(WINDOW *win, int beg_line, int num_lines);\fR
-.br
+.nf
+\fB#include <curses.h>
+.PP
+\fBint refresh(void);
+\fBint wrefresh(WINDOW *\fIwin\fP);
+\fBint wnoutrefresh(WINDOW *\fIwin\fP);
+\fBint doupdate(void);
+.PP
+\fBint redrawwin(WINDOW *\fIwin\fP);
+\fBint wredrawln(WINDOW *\fIwin\fP, int \fIbeg_line\fP, int \fInum_lines\fP);
+.fi
.SH DESCRIPTION
-The \fBrefresh\fR and \fBwrefresh\fR routines (or \fBwnoutrefresh\fR and
-\fBdoupdate\fR) must be called to get actual output to the terminal, as other
-routines merely manipulate data structures. The routine \fBwrefresh\fR copies
-the named window to the physical terminal screen, taking into account what is
-already there in order to do optimizations. The \fBrefresh\fR routine is the
-same, using \fBstdscr\fR as the default window. Unless \fBleaveok\fR has been
+.SS "refresh, wrefresh"
+The \fBrefresh\fP and \fBwrefresh\fP routines (or \fBwnoutrefresh\fP and
+\fBdoupdate\fP) must be called to get actual output to the terminal,
+as other routines merely manipulate data structures.
+The routine \fBwrefresh\fP copies
+the named window to the \fIphysical screen\fP,
+taking into account what is already there to do optimizations.
+The \fBrefresh\fP routine is the
+same, using \fBstdscr\fP as the default window.
+Unless \fBleaveok\fP(3X) has been
enabled, the physical cursor of the terminal is left at the location of the
cursor for that window.
-
-The \fBwnoutrefresh\fR and \fBdoupdate\fR routines allow multiple updates with
-more efficiency than \fBwrefresh\fR alone. In addition to all the window
-structures, \fBcurses\fR keeps two data structures representing the terminal
-screen: a physical screen, describing what is actually on the screen, and a
-virtual screen, describing what the programmer wants to have on the screen.
-
-The routine \fBwrefresh\fR works by first calling \fBwnoutrefresh\fR, which
-copies the named window to the virtual screen, and then calling \fBdoupdate\fR,
-which compares the virtual screen to the physical screen and does the actual
-update. If the programmer wishes to output several windows at once, a series
-of calls to \fBwrefresh\fR results in alternating calls to \fBwnoutrefresh\fR
-and \fBdoupdate\fR, causing several bursts of output to the screen. By first
-calling \fBwnoutrefresh\fR for each window, it is then possible to call
-\fBdoupdate\fR once, resulting in only one burst of output, with fewer total
-characters transmitted and less CPU time used. If the \fIwin\fR argument to
-\fBwrefresh\fR is the global variable \fBcurscr\fR, the screen is immediately
-cleared and repainted from scratch.
-
-The phrase "copies the named window to the virtual screen" above is ambiguous.
-What actually happens is that all \fItouched\fR (changed) lines in the window
-are copied to the virtual screen. This affects programs that use overlapping
+.SS "wnoutrefresh, doupdate"
+The \fBwnoutrefresh\fP and \fBdoupdate\fP routines allow multiple updates with
+more efficiency than \fBwrefresh\fP alone.
+In addition to all the window
+structures, \fBcurses\fP keeps two data structures representing the terminal
+screen:
+.bP
+a \fIphysical screen\fP,
+describing what is actually on the screen, and
+.bP
+a \fIvirtual screen\fP,
+describing what the programmer wants to have on the screen.
+.PP
+The routine \fBwrefresh\fP works by
+.bP
+first calling \fBwnoutrefresh\fP,
+which copies the named window to the \fIvirtual screen\fP, and
+.bP
+then calling \fBdoupdate\fP, which compares
+the \fIvirtual screen\fP to the \fIphysical screen\fP
+and does the actual update.
+.PP
+If the programmer wishes to output several windows at once, a series
+of calls to \fBwrefresh\fP results in alternating calls to \fBwnoutrefresh\fP
+and \fBdoupdate\fP, causing several bursts of output to the screen.
+By first
+calling \fBwnoutrefresh\fP for each window, it is then possible to call
+\fBdoupdate\fP once, resulting in only one burst of output, with fewer total
+characters transmitted and less CPU time used.
+.PP
+If the \fIwin\fP argument to
+\fBwrefresh\fP is the \fIphysical screen\fP
+(i.e., the global variable \fBcurscr\fP),
+the screen is immediately cleared and repainted from scratch.
+.PP
+The phrase \*(``copies the named window
+to the virtual screen\*('' above is ambiguous.
+What actually happens is that all \fItouched\fP (changed) lines in the window
+are copied to the virtual screen.
+This affects programs that use overlapping
windows; it means that if two windows overlap, you can refresh them in either
order and the overlap region will be modified only when it is explicitly
-changed. (But see the section on \fBPORTABILITY\fR below for a warning about
+changed.
+(But see the section on \fBPORTABILITY\fP below for a warning about
exploiting this behavior.)
-
-The \fBwredrawln\fR routine indicates to \fBcurses\fR that some screen lines
-are corrupted and should be thrown away before anything is written over them
-it touches the indicated lines (marking them changed) then does a refresh
-of the window. The routine \fBredrawwin\fR() touches the entire window and then
-refreshes it.
+.SS "wredrawln, redrawwin"
+The \fBwredrawln\fP routine indicates to \fBcurses\fP that some screen lines
+are corrupted and should be thrown away before anything is written over them.
+It touches the indicated lines (marking them changed).
+The routine \fBredrawwin\fP touches the entire window.
.SH RETURN VALUE
-Routines that return an integer return \fBERR\fR upon failure, and \fBOK\fR
-(SVr4 only specifies "an integer value other than \fBERR\fR") upon successful
-completion.
+These routines return the integer \fBERR\fP upon failure and \fBOK\fP
+(SVr4 specifies only
+\*(``an integer value other than \fBERR\fP\*('')
+upon successful completion.
+.PP
+X/Open Curses does not specify any error conditions.
+In this implementation
+.RS 3
+.TP 5
+\fBwnoutrefresh\fP
+returns an error
+if the window pointer is null, or
+if the window is really a pad.
+.TP 5
+\fBwredrawln\fP
+returns an error
+if the associated call to \fBtouchln\fP returns an error.
+.RE
.SH NOTES
-Note that \fBrefresh\fR and \fBredrawwin\fR may be macros.
+Note that \fBrefresh\fP and \fBredrawwin\fP may be macros.
.SH PORTABILITY
-The XSI Curses standard, Issue 4 describes these functions.
-
-Whether \fBwnoutrefresh()\fR copies to the virtual screen the entire contents
+X/Open Curses, Issue 4 describes these functions.
+.PP
+Whether \fBwnoutrefresh\fP copies to the virtual screen the entire contents
of a window or just its changed portions has never been well-documented in
-historic curses versions (including SVr4). It might be unwise to rely on
+historic curses versions (including SVr4).
+It might be unwise to rely on
either behavior in programs that might have to be linked with other curses
-implementations. Instead, you can do an explicit \fBtouchwin()\fR before the
-\fBwnoutrefresh()\fR call to guarantee an entire-contents copy anywhere.
+implementations.
+Instead, you can do an explicit \fBtouchwin\fP before the
+\fBwnoutrefresh\fP call to guarantee an entire-contents copy anywhere.
.SH SEE ALSO
-\fBcurses\fR(3X), \fBcurs_outopts\fR(3X)
-.\"#
-.\"# The following sets edit modes for GNU EMACS
-.\"# Local Variables:
-.\"# mode:nroff
-.\"# fill-column:79
-.\"# End:
+\fB\%curses\fP(3X),
+\fB\%curs_outopts\fP(3X)
+\fB\%curs_variables\fP(3X)
projects / ncurses.git / blobdiff