lib/libcurses/curses_touch.3

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