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