lib/libcurses/PSD.doc/intro.3

   1 .\"     $NetBSD: intro.3,v 1.9 2003/11/02 11:16:03 wiz 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 .\"     @(#)intro.3     8.1 (Berkeley) 6/4/93
  31 .\"
  32 .sh 1 Usage
  33 .pp
  34 This is a description of how to actually use the screen package.
  35 For simplicity, we assume all updating, reading, etc.
  36 is applied to
  37 .Vn stdscr ,
  38 although a different window can of course be specified.
  39 .sh 2 "Initialization"
  40 .pp
  41 In order to use the screen package,
  42 the routines must know about terminal characteristics,
  43 and the space for
  44 .Vn curscr
  45 and
  46 .Vn stdscr
  47 must be allocated.
  48 These functions are performed by
  49 .Fn initscr .
  50 Since it must allocate space for the windows,
  51 it can overflow core when attempting to do so.
  52 On this rather rare occasion,
  53 .Fn initscr
  54 returns ERR.
  55 .Fn initscr
  56 must
  57 .bi always
  58 be called before any of the routines which affect windows are used.
  59 If it is not,
  60 the program will core dump as soon as either
  61 .Vn curscr
  62 or
  63 .Vn stdscr
  64 are referenced.
  65 However, it is usually best to wait to call it
  66 until after you are sure you will need it,
  67 like after checking for startup errors.
  68 Terminal status changing routines
  69 like
  70 .Fn nl
  71 and
  72 .Fn cbreak
  73 should be called after
  74 .Fn initscr .
  75 .pp
  76 After the initial window allocation done by
  77 .Fn initscr ,
  78 specific window characteristics can be set.
  79 Scrolling can be enabled by calling
  80 .Fn scrollok .
  81 If you want the cursor to be left after the last change, use
  82 .Fn leaveok .
  83 If this isn't done,
  84 .Fn refresh
  85 will move the cursor to the window's current \*y after updating it.
  86 Additional windows can be created by using the functions
  87 .Fn newwin
  88 and
  89 .Fn subwin .
  90 .Fn delwin
  91 allows you to delete an existing window.
  92 The variables
  93 .Vn LINES
  94 and
  95 .Vn COLS
  96 control the size of the terminal.
  97 They are initially implicitly set by
  98 .Fn initscr ,
  99 but can be altered explicitly by the user followed by a call to
 100 .Fn initscr .
 101 Note that any call to
 102 .Fn initscr ,
 103 will always delete any existing
 104 .Vn stdscr
 105 and/or
 106 .Vn curscr
 107 before creating new ones so this change is best done before the initial call to
 108 .Fn initscr .
 109 .pp
 110 .sh 2 "Output"
 111 .pp
 112 The basic functions
 113 used to change what will go on a window are
 114 .Fn addch
 115 and
 116 .Fn move .
 117 .Fn addch
 118 adds a character at the current \*y,
 119 returning ERR if it would cause the window to illegally scroll,
 120 .i i.e. ,
 121 printing a character in the lower right-hand corner
 122 of a terminal which automatically scrolls
 123 if scrolling is not allowed.
 124 .Fn move
 125 changes the current \*y to whatever you want them to be.
 126 It returns ERR if you try to move off the window.
 127 As mentioned above, you can combine the two into
 128 .Fn mvaddch
 129 to do both things in one call.
 130 .pp
 131 The other output functions
 132 (such as
 133 .Fn addstr
 134 and
 135 .Fn printw )
 136 all call
 137 .Fn addch
 138 to add characters to the window.
 139 .pp
 140 After a change has been made to the window,
 141 you must call
 142 .Fn refresh .
 143 when you want the portion of the terminal covered by the window
 144 to reflect the change.
 145 In order to optimize finding changes,
 146 .Fn refresh
 147 assumes that any part of the window not changed
 148 since the last
 149 .Fn refresh
 150 of that window has not been changed on the terminal,
 151 .i i.e. ,
 152 that you have not refreshed a portion of the terminal
 153 with an overlapping window.
 154 If this is not the case,
 155 the routines
 156 .Fn touchwin ,
 157 .Fn touchline ,
 158 and
 159 .Fn touchoverlap
 160 are provided to make it look like a desired part of window has been changed,
 161 thus forcing
 162 .Fn refresh
 163 to check that whole subsection of the terminal for changes.
 164 .pp
 165 If you call
 166 .Fn wrefresh
 167 with
 168 .Vn curscr ,
 169 it will make the screen look like the image of
 170 .Vn curscr .
 171 This is useful for implementing a command
 172 which would redraw the screen in case it got messed up.
 173 .sh 2 Input
 174 .pp
 175 Input is essentially a mirror image of output.
 176 The complementary function to
 177 .Fn addch
 178 is
 179 .Fn getch
 180 which,
 181 if echo is set,
 182 will call
 183 .Fn addch
 184 to echo the character.
 185 Since the screen package needs to know what is on the terminal at all times,
 186 if characters are to be echoed,
 187 the tty must be in raw or cbreak mode.
 188 If it is not,
 189 .Fn getch
 190 sets it to be cbreak,
 191 and then reads in the character.
 192 .sh 2 "Termination"
 193 .pp
 194 In order to perform certain optimizations,
 195 and,
 196 on some terminals,
 197 to work at all,
 198 some things must be done
 199 before the screen routines start up.
 200 These functions are performed in
 201 .Fn getttmode
 202 and
 203 .Fn setterm ,
 204 which are called by
 205 .Fn initscr .
 206 In order to clean up after the routines,
 207 the routine
 208 .Fn endwin
 209 is provided.
 210 It restores tty modes to what they were
 211 when
 212 .Fn initscr
 213 was first called.
 214 The terminal state module uses the variable
 215 .Vn curses_termios
 216 to save the original terminal state which is then restored upon a call to
 217 .Fn endwin .
 218 Thus,
 219 anytime after the call to initscr,
 220 .Fn endwin
 221 should be called before exiting.
 222 Note however, that
 223 .Fn endwin
 224 should always be called
 225 .b before
 226 the final calls to
 227 .Fn delwin ,
 228 which free the storage of the windows.