lib/libcurses/curses_touch.3

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