home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / files / gnu / crssrc16 / intro.1 < prev    next >
Text File  |  1993-07-29  |  6KB  |  256 lines
  1. .\" Copyright 1980 Kenneth C. R. C. Arnold and The Regents of the
  2. .\" University of California.  Permission is granted to freely
  3. .\" distribute curses and its documentation provided that this
  4. .\" notice is left intact.
  5. .\"
  6. .\"    @(#)intro.1    6.1 (Berkeley) 4/23/86
  7. .\"
  8. .bp
  9. .sh 1 Overview
  10. .pp
  11. In making available the generalized terminal descriptions in \*(tc,
  12. much information was made available to the programmer,
  13. but little work was taken out of one's hands.
  14. The purpose of this package is to allow the C programmer
  15. to do the most common type of terminal dependent functions,
  16. those of movement optimization and optimal screen updating,
  17. without doing any of the dirty work,
  18. and (hopefully) with nearly as much ease as is necessary to simply print
  19. or read things.
  20. .pp
  21. The package is split into three parts:
  22. (1) Screen updating;
  23. (2) Screen updating with user input;
  24. and
  25. (3) Cursor motion optimization.
  26. .pp
  27. It is possible to use the motion optimization
  28. without using either of the other two,
  29. and screen updating and input can be done
  30. without any programmer knowledge of the motion optimization,
  31. or indeed the \*(et \*(db itself.
  32. .sh 2 "Terminology (or, Words You Can Say to Sound Brilliant)"
  33. .pp
  34. In this document,
  35. the following terminology is kept to with reasonable consistency:
  36. .de Ip
  37. .sp
  38. .in 5n
  39. .ti 0n
  40. .bi "\\$1" :
  41. ..
  42. .Ip window
  43. An internal representation
  44. containing an image of what a section of the terminal screen may look like
  45. at some point in time.
  46. This subsection can either encompass the entire terminal screen,
  47. or any smaller portion down to a single character within that screen.
  48. .Ip "terminal"
  49. Sometimes called
  50. .bi terminal
  51. .bi screen .
  52. The package's idea of what the terminal's screen currently looks like,
  53. .i i.e. ,
  54. what the user sees now.
  55. This is a special
  56. .i screen :
  57. .Ip screen
  58. This is a subset of windows which are as large as the terminal screen,
  59. .i i.e. ,
  60. they start at the upper left hand corner
  61. and encompass the lower right hand corner.
  62. One of these,
  63. .Vn stdscr ,
  64. is automatically provided for the programmer.
  65. .rm Ip
  66. .sh 2 "Compiling Things"
  67. .pp
  68. In order to use the library,
  69. it is necessary to have certain types and variables defined.
  70. Therefore, the programmer must have a line:
  71. .(l
  72. .b "#include <curses.h>"
  73. .)l
  74. at the top of the program source.
  75. The header file
  76. .b <curses.h>
  77. needs to include
  78. .b <sgtty.h> ,
  79. so the one should not do so oneself\**.
  80. .(f
  81. \**
  82. The screen package also uses the Standard I/O library,
  83. so
  84. .b <curses.h>
  85. includes
  86. .b <stdio.h> .
  87. It is redundant
  88. (but harmless)
  89. for the programmer to do it, too.
  90. .)f
  91. Also,
  92. compilations should have the following form:
  93. .(l
  94. .ie t \fBcc\fR [ \fIflags\fR ] file ... \fB\-lcurses \-ltermcap\fR
  95. .el \fIcc\fR [ flags ] file ... \fI\-lcurses \-ltermcap\fR
  96. .)l
  97. .sh 2 "Screen Updating"
  98. .pp
  99. In order to update the screen optimally,
  100. it is necessary for the routines to know what the screen currently looks like
  101. and what the programmer wants it to look like next.
  102. For this purpose,
  103. a data type
  104. (structure)
  105. named
  106. .Vn WINDOW
  107. is defined
  108. which describes a window image to the routines,
  109. including its starting position on the screen
  110. (the \*y of the upper left hand corner)
  111. and its size.
  112. One of these
  113. (called
  114. .Vn curscr
  115. for
  116. .i "current screen" )
  117. is a screen image of what the terminal currently looks like.
  118. Another screen
  119. (called
  120. .Vn stdscr ,
  121. for
  122. .i "standard screen" )
  123. is provided
  124. by default
  125. to make changes on.
  126. .pp
  127. A window is a purely internal representation.
  128. It is used to build and store
  129. a potential image of a portion of the terminal.
  130. It doesn't bear any necessary relation
  131. to what is really on the terminal screen.
  132. It is more like an array of characters on which to make changes.
  133. .pp
  134. When one has a window which describes
  135. what some part the terminal should look like,
  136. the routine
  137. .Fn refresh
  138. (or
  139. .Fn wrefresh
  140. if the window is not
  141. .Vn stdscr )
  142. is called.
  143. .Fn refresh
  144. makes the terminal,
  145. in the area covered by the window,
  146. look like that window.
  147. Note, therefore, that changing something on a window
  148. .i does
  149. .bi not
  150. .i "change the terminal" .
  151. Actual updates to the terminal screen
  152. are made only by calling
  153. .Fn refresh
  154. or
  155. .Fn wrefresh .
  156. This allows the programmer to maintain several different ideas
  157. of what a portion of the terminal screen should look like.
  158. Also, changes can be made to windows in any order,
  159. without regard to motion efficiency.
  160. Then, at will,
  161. the programmer can effectively say
  162. .q "make it look like this" ,
  163. and let the package worry about the best way to do this.
  164. .sh 2 "Naming Conventions"
  165. .pp
  166. As hinted above,
  167. the routines can use several windows,
  168. but two are automatically given:
  169. .Vn curscr ,
  170. which knows what the terminal looks like,
  171. and
  172. .Vn stdscr ,
  173. which is what the programmer wants the terminal to look like next.
  174. The user should never really access
  175. .Vn curscr
  176. directly.
  177. Changes should be made to
  178. the appropriate screen,
  179. and then the routine
  180. .Fn refresh
  181. (or
  182. .Fn wrefresh )
  183. should be called.
  184. .pp
  185. Many functions are set up to deal with
  186. .Vn stdscr
  187. as a default screen.
  188. For example, to add a character to
  189. .Vn stdscr ,
  190. one calls
  191. .Fn addch
  192. with the desired character.
  193. If a different window is to be used,
  194. the routine
  195. .Fn waddch
  196. (for
  197. .b w indow-specific
  198. .Fn addch )
  199. is provided\**.
  200. .(f
  201. \**
  202. Actually,
  203. .Fn addch
  204. is really a
  205. .q #define
  206. macro with arguments,
  207. as are most of the "functions" which deal with
  208. .Vn stdscr
  209. as a default.
  210. .)f
  211. This convention of prepending function names with a
  212. .Bq w
  213. when they are to be applied to specific windows
  214. is consistent.
  215. The only routines which do
  216. .i not
  217. do this are those
  218. to which a window must always be specified.
  219. .pp
  220. In order to move the current \*y from one point to another,
  221. the routines
  222. .Fn move
  223. and
  224. .Fn wmove
  225. are provided.
  226. However,
  227. it is often desirable to first move and then perform some I/O operation.
  228. In order to avoid clumsyness,
  229. most I/O routines can be preceded by the prefix
  230. .Bq mv
  231. and the desired \*y then can be added to the arguments to the function.
  232. For example,
  233. the calls
  234. .(l
  235. move(y\*,x);
  236. addch(ch);
  237. .)l
  238. can be replaced by
  239. .(l
  240. mvaddch(y\*,x\*,ch);
  241. .)l
  242. and
  243. .(l
  244. wmove(win\*,y\*,x);
  245. waddch(win\*,ch);
  246. .)l
  247. can be replaced by
  248. .(l
  249. mvwaddch(win\*,y\*,x\*,ch);
  250. .)l
  251. Note that the window description pointer
  252. .Vn win ) (
  253. comes before the added \*y.
  254. If such pointers are need,
  255. they are always the first parameters passed.
  256.