1.\" $NetBSD: curses_touch.3,v 1.10 2018/02/08 09:05:16 dholland Exp $ 2.\" 3.\" Copyright (c) 2002 4.\" Brett Lymn (blymn@NetBSD.org, brett_lymn@yahoo.com.au) 5.\" 6.\" This code is donated to the NetBSD Foundation by the Author. 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 3. The name of the Author may not be used to endorse or promote 17.\" products derived from this software without specific prior written 18.\" permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" 33.Dd January 2, 2017 34.Dt CURSES_TOUCH 3 35.Os 36.Sh NAME 37.Nm curses_touch , 38.Nm touchline , 39.Nm touchoverlap , 40.Nm touchwin , 41.Nm untouchwin , 42.Nm wtouchln , 43.Nm is_linetouched , 44.Nm is_wintouched , 45.Nm redrawwin , 46.Nm wredrawln , 47.Nm syncok , 48.Nm wsyncup , 49.Nm wsyncdown 50.Nd curses window modification routines 51.Sh LIBRARY 52.Lb libcurses 53.Sh SYNOPSIS 54.In curses.h 55.Ft int 56.Fn touchline "WINDOW *win" "int start" "int count" 57.Ft int 58.Fn touchoverlap "WINDOW *win1" "WINDOW *win2" 59.Ft int 60.Fn touchwin "WINDOW *win" 61.Ft int 62.Fn untouchwin "WINDOW *win" 63.Ft int 64.Fn wtouchln "WINDOW *win" "int line" "int n" "boolf changed" 65.Ft bool 66.Fn is_linetouched "WINDOW *win" "int line" 67.Ft bool 68.Fn is_wintouched "WINDOW *win" 69.Ft int 70.Fn redrawwin "WINDOW *win" 71.Ft int 72.Fn wredrawln "WINDOW *win" "int line" "int n" 73.Ft int 74.Fn syncok "WINDOW *win" 75.Ft void 76.Fn wsyncup "WINDOW *win" 77.Ft void 78.Fn wsyncdown "WINDOW *win" 79.Sh DESCRIPTION 80These functions mark lines and windows as modified and check the modification 81status of lines and windows. 82.Pp 83The 84.Fn touchline 85function marks 86.Fa count 87lines starting from 88.Fa start 89in window 90.Fa win 91as having been modified. 92These characters will be synced to the terminal on the next call to 93.Fn wrefresh . 94.Pp 95The 96.Fn touchoverlap 97function marks the portion of 98.Fa win2 99that overlaps 100.Fa win1 101as being modified. 102.Pp 103The 104.Fn touchwin 105function marks the entire window 106.Fa win 107as having been modified. 108Conversely, 109the 110.Fn untouchwin 111function marks the window 112.Fa win 113as being unmodified, so that any changes made to that window will 114not be synced to the terminal during a 115.Fn wrefresh . 116.Pp 117The 118.Fn wtouchln 119function performs one of two operations on 120.Fa n 121lines starting at 122.Fa line 123in the given window. 124If 125.Fa changed 126is 1 then the given line range is marked as being modified, if 127.Fa changed 128is 0 then the given line range is set to being unmodified. 129.Pp 130The 131.Fn is_linetouched 132function returns 133.Dv TRUE 134if 135.Fa line 136in window 137.Fa win 138has been modified since the last refresh was done, otherwise 139.Dv FALSE 140is returned. 141.Pp 142.Fn is_wintouched 143returns 144.Dv TRUE 145if the window 146.Fa win 147has been modified since the last refresh, otherwise 148.Dv FALSE 149is returned. 150.Pp 151The 152.Fn redrawwin 153function marks the entire window 154.Fa win 155as having been corrupted. 156Is is equivalent to the 157.Fn touchwin 158function. 159.Pp 160The 161.Fn wredrawln 162function marks 163.Fa n 164lines starting at 165.Fa line 166in the given window as corrupted. 167It is equivalent to 168.Fn wtouchln win line n 1 . 169.Pp 170The 171.Fn syncok 172function determines whether all the ancestors of the specified window are 173implicitly touched whenever there is a change in the window. 174The initial state is 175.Dv FALSE . 176.Pp 177The 178.Fn wsyncup 179function touches all ancestors of 180.Fa win . 181.Pp 182The 183.Fn wsyncdown 184function touches 185.Fa win 186if any of its ancestors is touched. 187.Sh RETURN VALUES 188Functions returning pointers will return 189.Dv NULL 190if an error is detected. 191The functions that return an int will return one of the following 192values: 193.Pp 194.Bl -tag -width ERR -compact 195.It Er OK 196The function completed successfully. 197.It Er ERR 198An error occurred in the function. 199.El 200.Sh SEE ALSO 201.Xr curses_refresh 3 202.Sh STANDARDS 203The 204.Nx 205Curses library complies with the X/Open Curses specification, part of the 206Single Unix Specification. 207.Sh HISTORY 208The Curses package appeared in 209.Bx 4.0 . 210