1.\" $NetBSD: curses_touch.3,v 1.8 2010/02/24 13:02:13 drochner 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 February 23, 2010 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 wsyncup , 48.Nm wsyncdown 49.Nd curses window modification routines 50.Sh LIBRARY 51.Lb libcurses 52.Sh SYNOPSIS 53.In curses.h 54.Ft int 55.Fn touchline "WINDOW *win" "int start" "int count" 56.Ft int 57.Fn touchoverlap "WINDOW *win1" "WINDOW *win2" 58.Ft int 59.Fn touchwin "WINDOW *win" 60.Ft int 61.Fn untouchwin "WINDOW *win" 62.Ft int 63.Fn wtouchln "WINDOW *win" "int line" "int n" "boolf changed" 64.Ft bool 65.Fn is_linetouched "WINDOW *win" "int line" 66.Ft bool 67.Fn is_wintouched "WINDOW *win" 68.Ft int 69.Fn redrawwin "WINDOW *win" 70.Ft int 71.Fn wredrawln "WINDOW *win" "int line" "int n" 72.Ft void 73.Fn wsyncup "WINDOW *win" 74.Ft void 75.Fn wsyncdown "WINDOW *win" 76.Sh DESCRIPTION 77These functions mark lines and windows as modified and check the modification 78status of lines and windows. 79.Pp 80The 81.Fn touchline 82function marks 83.Fa count 84lines starting from 85.Fa start 86in window 87.Fa win 88as having been modified. 89These characters will be synced to the terminal on the next call to 90.Fn wrefresh . 91.Pp 92The 93.Fn touchoverlap 94function marks the portion of 95.Fa win2 96that overlaps 97.Fa win1 98as being modified. 99.Pp 100The 101.Fn touchwin 102function marks the entire window 103.Fa win 104as having been modified. 105Conversely, 106the 107.Fn untouchwin 108function marks the window 109.Fa win 110as being unmodified, so that any changes made to that window will 111not be synced to the terminal during a 112.Fn wrefresh . 113.Pp 114The 115.Fn wtouchln 116function performs one of two operations on 117.Fa n 118lines starting at 119.Fa line 120in the given window. 121If 122.Fa changed 123is 1 then the given line range is marked as being modified, if 124.Fa changed 125is 0 then the given line range is set to being unmodified. 126.Pp 127The 128.Fn is_linetouched 129function returns 130.Dv TRUE 131if 132.Fa line 133in window 134.Fa win 135has been modified since the last refresh was done, otherwise 136.Dv FALSE 137is returned. 138.Pp 139.Fn is_wintouched 140returns 141.Dv TRUE 142if the window 143.Fa win 144has been modified since the last refresh, otherwise 145.Dv FALSE 146is returned. 147.Pp 148The 149.Fn redrawwin 150function marks the entire window 151.Fa win 152as having been corrupted. 153Is is equivalent to the 154.Fn touchwin 155function. 156.Pp 157The 158.Fn wredrawln 159function marks 160.Fa n 161lines starting at 162.Fa line 163in the given window as corrupted. 164It is equivalent to 165.Fn wtouchln win line n 1 . 166.Pp 167The 168.Fn wsyncup 169function touches all ancestors of 170.Fa win . 171.Pp 172The 173.Fn wsyncdown 174function touches 175.Fa win 176if any of its ancestors is touched. 177.Sh RETURN VALUES 178Functions returning pointers will return 179.Dv NULL 180if an error is detected. 181The functions that return an int will return one of the following 182values: 183.Pp 184.Bl -tag -width ERR -compact 185.It Er OK 186The function completed successfully. 187.It Er ERR 188An error occurred in the function. 189.El 190.Sh SEE ALSO 191.Xr curses_refresh 3 192.Sh STANDARDS 193The 194.Nx 195Curses library complies with the X/Open Curses specification, part of the 196Single Unix Specification. 197.Sh HISTORY 198The Curses package appeared in 199.Bx 4.0 . 200