lib/libcurses/PSD.doc/appen.B

   1 .\"     $NetBSD: appen.B,v 1.5 2003/08/07 16:44:26 agc Exp $
   2 .\"
   3 .\" Copyright (c) 1980, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)appen.B     8.1 (Berkeley) 6/8/93
  31 .\"
  32 .ie t .oh '\*(Ln Appendix B''PS1:19-%'
  33 .eh 'PS1:19-%''\*(Ln Appendix B'
  34 .el .he ''\fIAppendix B\fR''
  35 .bp
  36 .(x
  37 .ti 0
  38 .b "Appendix B"
  39 .)x
  40 .nr $1 0
  41 .sh 1 "The WINDOW structure"
  42 .pp
  43 The WINDOW structure is defined as follows:
  44 .(l I
  45 .so win_st.gr
  46 .)l
  47 .pp
  48 .Vn \*_cury \\*
  49 .(f
  50 \**
  51 All variables not normally accessed directly by the user
  52 are named with an initial
  53 .Bq \*_
  54 to avoid conflicts with the user's variables.
  55 .)f
  56 and
  57 .Vn \*_curx
  58 are the current \*y for the window.
  59 New characters added to the screen
  60 are added at this point.
  61 .Vn \*_maxy
  62 and
  63 .Vn \*_maxx
  64 are the maximum values allowed for
  65 .Vn \*_cury\*,\*_curx ). (
  66 .Vn \*_begy
  67 and
  68 .Vn \*_begx
  69 are the starting \*y on the terminal for the window,
  70 .i i.e. ,
  71 the window's home.
  72 .Vn \*_cury ,
  73 .Vn \*_curx ,
  74 .Vn \*_maxy ,
  75 and
  76 .Vn \*_maxx
  77 are measured relative to
  78 .Vn \*_begy\*,\*_begx ), (
  79 not the terminal's home.
  80 .pp
  81 .Vn \*_clear
  82 tells if a clear-screen sequence is to be generated
  83 on the next
  84 .Fn refresh
  85 call.
  86 This is only meaningful for screens.
  87 The initial clear-screen for the first
  88 .Fn refresh
  89 call is generated by initially setting clear to be TRUE for
  90 .Vn curscr ,
  91 which always generates a clear-screen if set,
  92 irrelevant of the dimensions of the window involved.
  93 .Vn \*_leave
  94 is TRUE if the current \*y and the cursor
  95 are to be left after the last character changed on the terminal,
  96 or not moved if there is no change.
  97 .Vn \*_scroll
  98 is TRUE
  99 if scrolling is allowed.
 100 .pp
 101 .Vn \*_y
 102 is a pointer to an array of lines which describe the terminal.
 103 Thus:
 104 .(l
 105 \*_y[i]
 106 .)l
 107 .lp
 108 is a pointer to the
 109 .Vn i th
 110 line, and
 111 .(l
 112 \*_y[i][j]
 113 .)l
 114 .lp
 115 is the
 116 .Vn j th
 117 character on the
 118 .Vn i th
 119 line.
 120 .Vn \*_flags
 121 can have one or more values
 122 or'd into it.
 123 .pp
 124 For windows that are not subwindows,
 125 .Vn \*_orig
 126 is
 127 NULL .
 128 For subwindows,
 129 it points to the main window
 130 to which the window is subsidiary.
 131 .Vn \*_nextp
 132 is a pointer in a circularly linked list
 133 of all the windows which are subwindows of the same main window,
 134 plus the main window itself.
 135 .pp
 136 .Vn \*_firstch
 137 and
 138 .Vn \*_lastch
 139 are
 140 .Fn malloc ed
 141 arrays which contain the index of the
 142 first and last changed characters
 143 on the line.
 144 .Vn \*_ch\*_off
 145 is the x offset for the window
 146 in the
 147 .Vn \*_firstch
 148 and
 149 .Vn \*_lastch
 150 arrays for this window.
 151 For main windows,
 152 this is always 0;
 153 for subwindows
 154 it is the difference between the starting point of the main window
 155 and that of the subindow,
 156 so that change markers can be set relative to the main window.
 157 This makes these markers global in scope.
 158 .pp
 159 All subwindows share the appropriate portions of
 160 .Vn _y ,
 161 .Vn _firstch ,
 162 .Vn _lastch ,
 163 and
 164 .Vn _insdel
 165 with their main window.
 166 .pp
 167 .b \*_ENDLINE
 168 says that the end of the line for this window
 169 is also the end of a screen.
 170 .b \*_FULLWIN
 171 says that this window is a screen.
 172 .b \*_SCROLLWIN
 173 indicates that the last character of this screen
 174 is at the lower right-hand corner of the terminal;
 175 .i i.e. ,
 176 if a character was put there,
 177 the terminal would scroll.
 178 .b \*_FULLLINE
 179 says that the width of a line is the same as the width of the terminal.
 180 If
 181 .b \*_FLUSH
 182 is set,
 183 it says that
 184 .Fn fflush "" "" stdout
 185 should be called at the end of each
 186 .Fn refresh
 187 .b \*_STANDOUT
 188 says that all characters added to the screen
 189 are in standout mode.
 190 .b \*_INSDEL
 191 is reserved for future use,
 192 and is set by
 193 .Fn idlok .
 194 .Vn \*_firstch
 195 is set to
 196 .b \*_NOCHANGE
 197 for lines on which there has been no change
 198 since the last
 199 .Fn refresh .