home *** CD-ROM | disk | FTP | other *** search
/ Serving the Web / ServingTheWeb1995.disc1of1.iso / linux / slacksrce / d / libc / libc-4.6 / libc-4 / libc-linux / curses-bsd4.4 / PSD.doc / intro.1 < prev    next >
Encoding:
Text File  |  1994-06-01  |  7.0 KB  |  250 lines
  1. .\" Copyright (c) 1980, 1993
  2. .\"    The Regents of the University of California.  All rights reserved.
  3. .\"
  4. .\" Redistribution and use in source and binary forms, with or without
  5. .\" modification, are permitted provided that the following conditions
  6. .\" are met:
  7. .\" 1. Redistributions of source code must retain the above copyright
  8. .\"    notice, this list of conditions and the following disclaimer.
  9. .\" 2. Redistributions in binary form must reproduce the above copyright
  10. .\"    notice, this list of conditions and the following disclaimer in the
  11. .\"    documentation and/or other materials provided with the distribution.
  12. .\" 3. All advertising materials mentioning features or use of this software
  13. .\"    must display the following acknowledgement:
  14. .\"    This product includes software developed by the University of
  15. .\"    California, Berkeley and its contributors.
  16. .\" 4. Neither the name of the University nor the names of its contributors
  17. .\"    may be used to endorse or promote products derived from this software
  18. .\"    without specific prior written permission.
  19. .\"
  20. .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``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 REGENTS OR CONTRIBUTORS 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. .\"    @(#)intro.1    8.1 (Berkeley) 6/4/93
  33. .\"
  34. .bp
  35. .sh 1 Overview
  36. .pp
  37. In making available the generalized terminal descriptions in \*(tc,
  38. much information was made available to the programmer,
  39. but little work was taken out of one's hands.
  40. The purpose of this package is to allow the C programmer
  41. to do the most common type of terminal dependent functions,
  42. those of movement optimization and optimal screen updating,
  43. without doing any of the dirty work,
  44. and with nearly as much ease as is necessary to simply print
  45. or read things.
  46. .sh 2 "Terminology"
  47. .pp
  48. In this document, the following terminology is used:
  49. .de Ip
  50. .sp
  51. .in 5n
  52. .ti 0n
  53. .b "\\$1" :
  54. ..
  55. .Ip window
  56. An internal representation
  57. containing an image of what a section of the terminal screen may look like
  58. at some point in time.
  59. This subsection can either encompass the entire terminal screen,
  60. or any smaller portion down to a single character within that screen.
  61. .Ip terminal
  62. Sometimes called
  63. .b terminal
  64. .b screen .
  65. The package's idea of what the terminal's screen currently looks like,
  66. .i i.e. ,
  67. what the user sees now.
  68. This is a special
  69. .i screen :
  70. .Ip screen
  71. This is a subset of windows which are as large as the terminal screen,
  72. .i i.e. ,
  73. they start at the upper left hand corner
  74. and encompass the lower right hand corner.
  75. One of these,
  76. .Vn stdscr ,
  77. is automatically provided for the programmer.
  78. .rm Ip
  79. .sh 2 "Compiling Applications"
  80. .pp
  81. In order to use the library,
  82. it is necessary to have certain types and variables defined.
  83. Therefore, the programmer must have a line:
  84. .(l
  85. .b "#include <curses.h>"
  86. .)l
  87. at the top of the program source.
  88. Compilations should have the following form:
  89. .(l
  90. .ie t \fBcc\fR [ \fIflags\fR ] file ... \fB\-lcurses \-ltermcap\fR
  91. .el \fIcc\fR [ flags ] file ... \fI\-lcurses \-ltermcap\fR
  92. .)l
  93. .sh 2 "Screen Updating"
  94. .pp
  95. In order to update the screen optimally,
  96. it is necessary for the routines to know what the screen currently looks like
  97. and what the programmer wants it to look like next.
  98. For this purpose,
  99. a data type
  100. (structure)
  101. named
  102. .Vn WINDOW
  103. is defined
  104. which describes a window image to the routines,
  105. including its starting position on the screen
  106. (the \*y of the upper left hand corner)
  107. and its size.
  108. One of these
  109. (called
  110. .Vn curscr
  111. for
  112. .i "current screen" )
  113. is a screen image of what the terminal currently looks like.
  114. Another screen
  115. (called
  116. .Vn stdscr ,
  117. for
  118. .i "standard screen" )
  119. is provided
  120. by default
  121. to make changes on.
  122. .pp
  123. A window is a purely internal representation.
  124. It is used to build and store
  125. a potential image of a portion of the terminal.
  126. It doesn't bear any necessary relation
  127. to what is really on the terminal screen.
  128. It is more like an array of characters on which to make changes.
  129. .pp
  130. When one has a window which describes
  131. what some part the terminal should look like,
  132. the routine
  133. .Fn refresh
  134. (or
  135. .Fn wrefresh
  136. if the window is not
  137. .Vn stdscr )
  138. is called.
  139. .Fn Refresh
  140. makes the terminal,
  141. in the area covered by the window,
  142. look like that window.
  143. Note, therefore, that changing something on a window
  144. .i does
  145. .bi not
  146. .i "change the terminal" .
  147. Actual updates to the terminal screen
  148. are made only by calling
  149. .Fn refresh
  150. or
  151. .Fn wrefresh .
  152. This allows the programmer to maintain several different ideas
  153. of what a portion of the terminal screen should look like.
  154. Also, changes can be made to windows in any order,
  155. without regard to motion efficiency.
  156. Then, at will,
  157. the programmer can effectively say
  158. .q "make it look like this" ,
  159. and the package will execute the changes in an optimal way.
  160. .sh 2 "Naming Conventions"
  161. .pp
  162. As hinted above,
  163. the routines can use several windows,
  164. but two are always available:
  165. .Vn curscr ,
  166. which is the image of what the terminal looks like at present, 
  167. and
  168. .Vn stdscr ,
  169. which is the image of what the programmer wants the terminal to look like next.
  170. The user should not access
  171. .Vn curscr
  172. directly.
  173. Changes should be made to
  174. the appropriate screen,
  175. and then the routine
  176. .Fn refresh
  177. (or
  178. .Fn wrefresh )
  179. should be called.
  180. .pp
  181. Many functions are set up to deal with
  182. .Vn stdscr
  183. as a default screen.
  184. For example, to add a character to
  185. .Vn stdscr ,
  186. one calls
  187. .Fn addch
  188. with the desired character.
  189. If a different window is to be used,
  190. the routine
  191. .Fn waddch
  192. (for
  193. .b w indow-specific
  194. .Fn addch )
  195. is provided\**.
  196. .(f
  197. \**
  198. Actually,
  199. .Fn addch
  200. is really a
  201. .q #define
  202. macro with arguments,
  203. as are most of the "functions" which act upon
  204. .Vn stdscr .
  205. .)f
  206. This convention of prepending function names with a
  207. .Bq w
  208. when they are to be applied to specific windows
  209. is consistent.
  210. The only routines which do
  211. .i not
  212. do this are those
  213. to which a window must always be specified.
  214. .pp
  215. In order to move the current \*y from one point to another,
  216. the routines
  217. .Fn move
  218. and
  219. .Fn wmove
  220. are provided.
  221. However,
  222. it is often desirable to first move and then perform some I/O operation.
  223. In order to avoid clumsiness,
  224. most I/O routines can be preceded by the prefix
  225. .Bq mv
  226. and the desired \*y can then be added to the arguments to the function.
  227. For example,
  228. the calls
  229. .(l
  230. move(y\*,x);
  231. addch(ch);
  232. .)l
  233. can be replaced by
  234. .(l
  235. mvaddch(y\*,x\*,ch);
  236. .)l
  237. and
  238. .(l
  239. wmove(win\*,y\*,x);
  240. waddch(win\*,ch);
  241. .)l
  242. can be replaced by
  243. .(l
  244. mvwaddch(win\*,y\*,x\*,ch);
  245. .)l
  246. Note that the window description pointer
  247. .Vn win ) (
  248. comes before the added \*y.
  249. If a window pointer is needed, it is always the first parameter passed.
  250.