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 / doc.III < prev    next >
Encoding:
Text File  |  1994-06-01  |  8.1 KB  |  344 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. .\"    @(#)doc.III    8.1 (Berkeley) 6/4/93
  33. .\"
  34. .Ds
  35. .Fd baudrate "" \*m
  36. .De
  37. Returns the output baud rate of the terminal.
  38. This is a system dependent constant
  39. (defined in
  40. .b <sys/tty.h>
  41. on BSD systems,
  42. which is included by
  43. .b <curses.h> ).
  44. .Ds
  45. .Fd delwin win
  46. WINDOW    *win;
  47. .De
  48. Deletes the window from existence.
  49. All resources are freed for future use by
  50. .b calloc (3).
  51. If a window has a
  52. .Fn subwin
  53. allocated window inside of it,
  54. deleting the outer window
  55. the subwindow is not affected,
  56. even though this does invalidate it.
  57. Therefore,
  58. subwindows should be deleted before their
  59. outer windows are.
  60. .Ds
  61. .Fd endwin
  62. .De
  63. Finish up window routines before exit.
  64. This restores the terminal to the state it was before
  65. .Fn initscr
  66. (or
  67. .Fn gettmode
  68. and
  69. .Fn setterm )
  70. was called.
  71. It should always be called before exiting.
  72. It does not exit.
  73. This is especially useful for resetting tty stats
  74. when trapping rubouts via
  75. .b signal (2).
  76. .Ds
  77. .Fd erasechar "" \*m
  78. .De
  79. Returns the erase character
  80. for the terminal,
  81. .i i.e. ,
  82. the character used by the user to erase a single character from the input.
  83. .Ds
  84. .Fd getcap str "" "char *"
  85. char    *str;
  86. .De
  87. Return a pointer to the
  88. .b termcap
  89. capability described by
  90. .Vn str
  91. (see
  92. .b termcap (5)
  93. for details).
  94. .Ds
  95. .Fd getyx win\*,y\*,x \*m
  96. WINDOW    *win;
  97. int    y\*,x;
  98. .De
  99. Puts the current \*y of
  100. .Vn win
  101. in the variables
  102. .Vn y
  103. and
  104. .Vn x .
  105. Since it is a macro,
  106. not a function,
  107. you do not pass the address
  108. of
  109. .Vn y
  110. and
  111. .Vn x .
  112. .Ds
  113. .Fd inch "" \*m
  114. .Fd winch win \*m
  115. WINDOW    *win;
  116. .De
  117. Returns the character at the current \*(y
  118. on the given window.
  119. This does not make any changes to the window.
  120. .Ds
  121. .Fd initscr
  122. .De
  123. Initialize the screen routines.
  124. This must be called before any of the screen routines are used.
  125. It initializes the terminal-type data and such,
  126. and without it none of the routines can operate.
  127. If standard input is not a tty,
  128. it sets the specifications to the terminal
  129. whose name is pointed to by
  130. .Vn Def\*_term
  131. (initialy "dumb").
  132. If the boolean
  133. .Vn My\*_term
  134. is true,
  135. .Vn Def\*_term
  136. is always used.
  137. If the system supports the
  138. .b TIOCGWINSZ
  139. .Fn ioctl "" "" 2
  140. call,
  141. it is used to get the number of lines and columns for the terminal,
  142. otherwise it is taken from the
  143. .b termcap
  144. description.
  145. .Ds
  146. .Fd killchar "" \*m
  147. .De
  148. Returns the line kill character
  149. for the terminal,
  150. .i i.e. ,
  151. the character used by the user to erase an entire line from the input.
  152. .Ds
  153. .Fd leaveok win\*,boolf \*m
  154. WINDOW    *win;
  155. bool    boolf;
  156. .De
  157. Sets the boolean flag for leaving the cursor after the last change.
  158. If
  159. .Vn boolf
  160. is TRUE,
  161. the cursor will be left after the last update on the terminal,
  162. and the current \*y for
  163. .Vn win
  164. will be changed accordingly.
  165. If it is FALSE,
  166. it will be moved to the current \*y.
  167. This flag
  168. (initialy FALSE)
  169. retains its value until changed by the user.
  170. .Ds
  171. .Fd longname termbuf\*,name
  172. char    *termbuf\*,*name;
  173. .Fd fullname termbuf\*,name
  174. char    *termbuf\*,*name;
  175. .De
  176. .Fn longname
  177. fills in
  178. .Vn name
  179. with the long name of the terminal described by the
  180. .b termcap
  181. entry in
  182. .Vn termbuf .
  183. It is generally of little use,
  184. but is nice for telling the user in a readable format what terminal
  185. we think he has.
  186. This is available in the global variable
  187. .Vn ttytype .
  188. .Vn termbuf
  189. is usually set via the termlib routine
  190. .Fn tgetent .
  191. .Fn fullname
  192. is the same as
  193. .Fn longname ,
  194. except that it gives the fullest name given in the entry,
  195. which can be quite verbose.
  196. .Ds
  197. .Fd mvwin win\*,y\*,x
  198. WINDOW    *win;
  199. int    y, x;
  200. .De
  201. Move the home position of the window
  202. .Vn win
  203. from its current starting coordinates
  204. to
  205. .Vn y\*,x ). (
  206. If that would put part or all of the window
  207. off the edge of the terminal screen,
  208. .Fn mvwin
  209. returns ERR and does not change anything.
  210. For subwindows,
  211. .Fn mvwin
  212. also returns ERR if you attempt to move it off its main window.
  213. If you move a main window,
  214. all subwindows are moved along with it.
  215. .Ds
  216. .Fd newwin lines\*,cols\*,begin\*_y\*,begin\*_x "" "WINDOW *"
  217. int    lines\*,cols\*,begin\*_y\*,begin\*_x;
  218. .De
  219. Create a new window with
  220. .Vn lines
  221. lines and
  222. .Vn cols
  223. columns starting at position
  224. .Vn begin\*_y\*,begin\*_x ). (
  225. If either
  226. .Vn lines
  227. or
  228. .Vn cols
  229. is 0 (zero),
  230. that dimension will be set to
  231. .Vn "LINES \- begin\*_y" ) (
  232. or
  233. .Vn "COLS \- begin\*_x" ) (
  234. respectively.
  235. Thus, to get a new window of dimensions
  236. .Vn LINES
  237. \(mu
  238. .Vn COLS ,
  239. use
  240. .Fn newwin . "" 0\*,0\*,0\*,0
  241. .Ds
  242. .Fd nl "" \*m
  243. .Fd nonl "" \*m
  244. .De
  245. Set or unset the terminal to/from nl mode,
  246. .i i.e. ,
  247. start/stop the system from mapping
  248. .b <RETURN>
  249. to
  250. .b <LINE-FEED> .
  251. If the mapping is not done,
  252. .Fn refresh
  253. can do more optimization,
  254. so it is recommended, but not required, to turn it off.
  255. .Ds
  256. .Fd scrollok win\*,boolf \*m
  257. WINDOW    *win;
  258. bool    boolf;
  259. .De
  260. Set the scroll flag for the given window.
  261. If
  262. .Vn boolf
  263. is FALSE, scrolling is not allowed.
  264. This is its default setting.
  265. .Ds
  266. .Fd touchline win\*,y\*,startx\*,endx
  267. WINDOW    *win;
  268. int    y\*,startx\*,endx;
  269. .De
  270. This function performs a function similar to
  271. .Fn touchwin
  272. on a single line.
  273. It marks the first change for the given line
  274. to be
  275. .Vn startx ,
  276. if it is before the current first change mark,
  277. and
  278. the last change mark is set to be
  279. .Vn endx
  280. if it is currently less than
  281. .Vn endx .
  282. .Ds
  283. .Fd touchoverlap win1\*,win2
  284. WINDOW    *win1, *win2;
  285. .De
  286. Touch the window
  287. .Vn win2
  288. in the area which overlaps with
  289. .Vn win1 .
  290. If they do not overlap,
  291. no changes are made.
  292. .Ds
  293. .Fd touchwin win
  294. WINDOW    *win;
  295. .De
  296. Make it appear that the every location on the window
  297. has been changed.
  298. This is usually only needed for refreshes with overlapping windows.
  299. .Ds
  300. .Fd subwin win\*,lines\*,cols\*,begin\*_y\*,begin\*_x "" "WINDOW *"
  301. WINDOW    *win;
  302. int    lines\*,cols\*,begin\*_y\*,begin\*_x;
  303. .De
  304. Create a new window with
  305. .Vn lines
  306. lines and
  307. .Vn cols
  308. columns starting at position
  309. .Vn begin\*_y\*,begin\*_x ) (
  310. inside the window
  311. .i win .
  312. This means that any change made to either window
  313. in the area covered
  314. by the subwindow will be made on both windows.
  315. .Vn begin\*_y\*,begin\*_x
  316. are specified relative to the overall screen,
  317. not the relative (0\*,0) of
  318. .Vn win .
  319. If either
  320. .Vn lines
  321. or
  322. .Vn cols
  323. is 0 (zero),
  324. that dimension will be set to
  325. .Vn "LINES \- begin\*_y" ) (
  326. or
  327. .Vn "COLS \- begin\*_x" ) (
  328. respectively.
  329. .Ds
  330. .Fd unctrl ch \*m
  331. char    ch;
  332. .De
  333. This is actually a debug function for the library,
  334. but it is of general usefulness.
  335. It returns a string which is a representation of
  336. .Vn ch .
  337. Control characters become their upper-case equivalents preceded by a "^".
  338. Other letters stay just as they are.
  339. To use
  340. .Fn unctrl ,
  341. you may have to have
  342. .b #include\ <unctrl.h>
  343. in your file.
  344.