X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=man%2Fcurs_refresh.3x;h=6052825785db91d72f9245c2cd75f059d0e7d533;hb=e6725415d8e5cbb514b8d6056e0700152c540fa0;hp=77bae2eeb90ccc6ecab903054ee5b7dee78ccffc;hpb=3a9b6a3bf0269231bef7de74757a910dedd04e0c;p=ncurses.git diff --git a/man/curs_refresh.3x b/man/curs_refresh.3x index 77bae2ee..60528257 100644 --- a/man/curs_refresh.3x +++ b/man/curs_refresh.3x @@ -1,84 +1,165 @@ -.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.42 2024/01/05 21:46:58 tom Exp $ +.TH curs_refresh 3X 2024-01-05 "ncurses 6.4" "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 \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 +.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 does not define 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 +.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)