X-Git-Url: http://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=man%2Fcurs_touch.3x;h=22391fd66e3f2ac221f1e6d5a6e71f92a35831ef;hp=5b67d3f8bf8df30ff56e4e10d4926a56428176a8;hb=HEAD;hpb=3a9b6a3bf0269231bef7de74757a910dedd04e0c diff --git a/man/curs_touch.3x b/man/curs_touch.3x index 5b67d3f8..613b6958 100644 --- a/man/curs_touch.3x +++ b/man/curs_touch.3x @@ -1,64 +1,124 @@ -.TH curs_touch 3X "" +.\"*************************************************************************** +.\" Copyright 2018-2023,2024 Thomas E. Dickey * +.\" Copyright 1998-2015,2017 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_touch.3x,v 1.47 2024/04/20 21:20:07 tom Exp $ +.TH curs_touch 3X 2024-04-20 "ncurses @NCURSES_MAJOR@.@NCURSES_MINOR@" "Library calls" .SH NAME -\fBtouchwin\fR, \fBtouchline\fR, \fBuntouchwin\fR, -\fBwtouchln\fR, \fBis_linetouched\fR, \fBis_wintouched\fR - -\fBcurses\fR refresh control routines +\fB\%touchwin\fP, +\fB\%touchline\fP, +\fB\%untouchwin\fP, +\fB\%wtouchln\fP, +\fB\%is_linetouched\fP, +\fB\%is_wintouched\fP \- +control terminal output refresh in a \fIcurses\fR window .SH SYNOPSIS -\fB#include \fR -.br -\fBint touchwin(WINDOW *win);\fR -.br -\fBint touchline(WINDOW *win, int start, int count);\fR -.br -\fBint untouchwin(WINDOW *win);\fR -.br -\fBint wtouchln(WINDOW *win, int y, int n, int changed);\fR -.br -\fBint is_linetouched(WINDOW *win, int line);\fR -.br -\fBint is_wintouched(WINDOW *win);\fR -.br +.nf +\fB#include +.PP +\fBint touchline(WINDOW *\fIwin\fP, int \fIstart\fP, int \fIcount\fP); +.PP +\fBint touchwin(WINDOW *\fIwin\fP); +\fBint wtouchln(WINDOW *\fIwin\fP, int \fIy\fP, int \fIn\fP, int \fIchanged\fP); +.PP +\fBint untouchwin(WINDOW *\fIwin\fP); +.PP +\fBbool is_linetouched(WINDOW *\fIwin\fP, int \fIline\fP); +\fBbool is_wintouched(WINDOW *\fIwin\fP); +.fi .SH DESCRIPTION -The \fBtouchwin\fR and \fBtouchline\fR routines throw away all +The \fB\%touchwin\fP and \fB\%touchline\fP routines throw away all optimization information about which parts of the window have been -touched, by pretending that the entire window has been drawn on. This +touched, by pretending that the entire window has been drawn on. +This is sometimes necessary when using overlapping windows, since a change to one window affects the other window, but the records of which lines -have been changed in the other window do not reflect the change. The -routine \fBtouchline\fR only pretends that \fIcount\fR lines have been -changed, beginning with line \fIstart\fR. - -The \fBuntouchwin\fR routine marks all lines in the window as unchanged since -the last call to \fBwrefresh\fR. - -The \fBwtouchln\fR routine makes \fIn\fR lines in the window, starting -at line \fIy\fR, look as if they have (\fIchanged\fR\fB=1\fR) or have -not (\fIchanged\fR\fB=0\fR) been changed since the last call to -\fBwrefresh\fR. - -The \fBis_linetouched\fR and \fBis_wintouched\fR routines return -\fBTRUE\fR if the specified line/window was modified since the last -call to \fBwrefresh\fR; otherwise they return \fBFALSE\fR. In -addition, \fBis_linetouched\fR returns \fBERR\fR if \fIline\fR is not +have been changed in the other window do not reflect the change. +The +routine \fB\%touchline\fP only pretends that \fIcount\fP lines have been +changed, beginning with line \fIstart\fP. +.PP +The \fB\%untouchwin\fP routine marks all lines in the window as unchanged since +the last call to \fB\%wrefresh\fP. +.PP +The \fB\%wtouchln\fP routine makes \fIn\fP lines in the window, starting +at line \fIy\fR, look as if they have (\fIchanged\fB=1\fR) or have +not (\fIchanged\fB=0\fR) been changed since the last call to +\fB\%wrefresh\fP. +.PP +The \fB\%is_linetouched\fP and \fB\%is_wintouched\fP routines return +\fBTRUE\fP if the specified line/window was modified since the last +call to \fB\%wrefresh\fP; otherwise they return \fBFALSE\fP. In +addition, \fB\%is_linetouched\fP returns \fBERR\fP if \fIline\fP is not valid for the given window. .SH RETURN VALUE -All routines return the integer \fBERR\fR upon failure and an integer value -other than \fBERR\fR upon successful completion, unless otherwise noted in the +All routines return the integer \fBERR\fP upon failure and an integer value +other than \fBERR\fP upon successful completion, unless otherwise noted in the preceding routine descriptions. -.SH PORTABILITY -The XSI Curses standard, Issue 4 describes these functions. - -Some historic curses implementations had, as an undocumented feature, the -ability to do the equivalent of \fBclearok(..., 1)\fR by saying -\fBtouchwin(stdscr)\fR or \fBclear(stdscr)\fR. This will not work under -ncurses. +.PP +X/Open Curses does not specify any error conditions. +In this implementation +.RS 3 +.TP 5 +\fBis_linetouched\fP +returns an error +if the window pointer is null, or +if the line number is outside the window boundaries. +.IP +The constant \fBERR\fP is distinct from \fBTRUE\fP and \fBFALSE\fP, +which are the normal return values of this function. +Because the function returns a \fBbool\fP, +returning \fBERR\fP (which is neither \fBTRUE\fP nor \fBFALSE\fP) +may not be supported by the compiler. +.IP +To provide error-checking and also match the X/Open function prototype, +the \fBERR\fP is provided by a macro named \fB\%is_linetouched\fP. +The actual function returns \fBFALSE\fP when it detects an error. +.TP 5 +\fBwtouchln\fP +returns an error +if the window pointer is null, or +if the line number is outside the window boundaries. +.RE .SH NOTES -Note that all routines except \fBwtouchln\fR may be macros. +All of these routines except \fB\%wtouchln\fP may be macros. +.SH PORTABILITY +These functions were introduced by SVr4. +The Solaris \fIcurses\fP header file, +for instance, defines both an actual function and macro for each. +The macros give the same result as the actual functions. +SVr4 \fIcurses\fP does not check the window parameter \fIwin\fP to ensure +that it is not \fBNULL\fP; +otherwise this implementation behaves the same as SVr4. +.PP +X/Open Curses, Issue 4 describes these functions, +but defines no error conditions. .SH SEE ALSO -\fBcurses\fR(3X), \fBcurs_refresh\fR(3X). -.\"# -.\"# The following sets edit modes for GNU EMACS -.\"# Local Variables: -.\"# mode:nroff -.\"# fill-column:79 -.\"# End: +\fB\%curses\fP(3X), +\fB\%curs_refresh\fP(3X), +\fB\%curs_variables\fP(3X)