home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / C / Libraries / stdwin / Doc / man / vt.man < prev    next >
Encoding:
Text File  |  1988-06-23  |  7.2 KB  |  243 lines  |  [TEXT/????]
  1. .TH VT 3
  2. .SH NAME
  3. VT \- virtual terminal package for STDWIN
  4. .SH SYNOPSIS
  5. .nf
  6. .ft C
  7. #include "stdwin.h"
  8. #include "vt.h"
  9.  
  10. VT *vtopen(char *title, int rows, int cols, int saverows);
  11. void vtclose(VT *vt);
  12. void vtansiputs(VT *vt, char *text, int len);
  13. void vtsetcursor(VT *vt, int row, int col);
  14. void vtreset(VT *vt);
  15. bool vtresize(VT *vt, int rows, int cols, int saverows);
  16. bool vtautosize(VT *vt);
  17. VT *vtfind(WINDOW *win);
  18. void vtsend(VT *vt, char *text, int buf);
  19. .ft 1
  20.  
  21. /* The following functions are actually macros */
  22. .ft C
  23. WINDOW *vtwindow(VT *vt);
  24. int vtcwidth(VT *vt);
  25. int vtcheight(VT *vt);
  26. void vtsetnlcr(VT *vt, bool nlcr);
  27. void vtsetlazy(VT *vt, bool lazy);
  28. .ft 1
  29. .fi
  30. .SH DESCRIPTION
  31. .I VT
  32. is a package which emulates one or more virtual terminals in STDWIN
  33. windows.
  34. A VT structure contains a WINDOW pointer and data structures to save the
  35. screen contents, cursor position, etc.
  36. Such a virtual terminal may be used to implement a terminal emulation
  37. program on a micro-computer (which was the original goal of this
  38. programming exercise), or as a tool to simplify interfacing a program
  39. using printf-style output to STDWIN.
  40. The virtual terminal's cursor position is indicated by STDWIN's standard
  41. text caret, appearing to the left of the character at the cursor
  42. position.
  43. This actually feels very natural in most cases.
  44. .PP
  45. The functions you might want to know about are:
  46. .IP vtopen
  47. Creates the window and returns a pointer to a VT struct.
  48. .I Rows
  49. and
  50. .I cols
  51. specify the size of the virtual terminal;
  52. .I saverows
  53. specifies the number of rows saved after they have scrolled off the top
  54. of the terminal.
  55. If something went wrong, a nil pointer is returned.
  56. .IP vtclose
  57. Closes the window and deallocates the data contained in the VT struct.
  58. .IP vtansiputs
  59. Sends an output string to the virtual terminal.
  60. .I Len
  61. specifies the length of the string; if it is negative, the string is
  62. terminated by a null character.
  63. Control character and escape sequence processing is done in the style of
  64. ANSI terminals, with some limitations and extensions.
  65. Warning: unless
  66. .I "vtsetnlcr(vt, 1)"
  67. has been called, both a CR and LF character must be sent to properly
  68. start a new line.
  69. .IP vtsetcursor
  70. Moves the terminal's cursor to the indicated position.
  71. The top left corner of the virtual terminal is position (0, 0).
  72. .IP vtreset
  73. Completely resets the virtual terminal to its initial state.
  74. The cursor is moved to position (0, 0).
  75. The
  76. .I lazy
  77. and
  78. .I nlcr
  79. flags are not changed.
  80. .IP vtresize
  81. Changes the dimensions of the virtual terminal to explicitly given
  82. numbers.
  83. In case of memory shortage, this function may fail irrecoverably,
  84. leaving the VT struct in an unusable state (except to
  85. .IR vtclose ).
  86. .IP vtautosize
  87. Changes the dimensions of the virtual terminal to conform to the new
  88. window size.
  89. If possible, the sum of rows and saverows is kept constant.
  90. The same limitations as for
  91. .I vtresize
  92. apply.
  93. .IP vtfind
  94. Given a window pointer, returns a pointer to the VT struct containing
  95. that window.
  96. Returns a nil pointer if no such VT struct exists.
  97. .IP vtsend
  98. This function is defined in the library, but you might want to write
  99. your own version.
  100. It is called by the library for cases where the virtual terminal must
  101. send a reply back to the computer system.
  102. (This happens in response to certain ANSI escape sequences, in
  103. particular ESC-[-6-n or ESC-[-c.)
  104. You may want to ignore this output, or actually send it down a serial
  105. line if you are implementing a terminal emulator program for a
  106. micro-computer.
  107. The library's default version calls
  108. .I vtansiputs
  109. with the same parameters as passed to
  110. .I vtsend.
  111. .IP vtwindow
  112. Returns a pointer to the window contained in the VT struct.
  113. .IP vtcwidth
  114. Returns the width of characters drawn in the VT's window.
  115. .IP vtcheight
  116. Returns the height of characters drawn in the VT's window.
  117. .IP vtsetnlcr
  118. Turns the
  119. .I nlcr
  120. option on or off.
  121. When on, every LF character received is translated into a CR plus LF.
  122. This is useful if you want to perform C style output to a VT window,
  123. where lines are terminated by a single LF.
  124. Initially this option is off.
  125. .IP vtsetlazy
  126. Turns the
  127. .I lazy
  128. option on or off.
  129. When on, actual output to the terminal is delayed until the window's
  130. draw procedure is called; when off, all output is drawn immediately.
  131. Initially this option is off.
  132. .SH ANSI ESCAPE SEQUENCES
  133. The termcap entries for xterm, vt100, vt100em and versaterm would all
  134. work with the emulated terminal (if you could somehow translate the
  135. output intended for a Unix terminal into calls to
  136. .IR vtansiputs ).
  137. Unrecognized escape sequences and control characters are ignored.
  138. .PP
  139. *** List all implemented escape sequences here. ***
  140. .SH EXAMPLE
  141. .nf
  142. .ft C
  143. #include "stdwin.h"
  144. #include "vt.h"
  145.  
  146. main() {
  147.     VT *vt;
  148.     winit();
  149.     wsetdefwinsize(80*wcharwidth('0'), 24*wlineheight());
  150.     vt= vtopen("VT", 24, 80, 100); /* Should check outcome */
  151.     vtautosize(vt);
  152.     vtsetnlcr(vt, 1); /* Map LF to CR LF */
  153.     vtansiputs(vt, "Hello, world\en", -1);
  154.     eventloop();
  155.     wdone();
  156.     exit(0);
  157. }
  158.  
  159. eventloop(vt) VT *vt; {
  160.     for (;;) {
  161.         EVENT e;
  162.         wgetevent(&e);
  163.         switch (e.type) {
  164.         case WE_SIZE:
  165.             vtautosize(vt); /* Should check outcome */
  166.             break;
  167.         case WE_CHAR:
  168.             { char buf[2];
  169.               buf[0]= e.u.character;
  170.               vtansiputs(vt, buf, 1);
  171.               break; }
  172.         case WE_MOUSE_DOWN:
  173.             vtsetcursor(vt,
  174.                         e.u.where.v / vtcheight(vt),
  175.                         e.u.where.h / vtcwidth(vt));
  176.             break;
  177.         case WE_COMMAND:
  178.             switch (e.u.command) {
  179.             case WC_CLOSE:                              return;
  180.             case WC_RETURN: vtansiputs(vt, "\en", 1);    break;
  181.             case WC_BACKSPACE: vtansiputs(vt, "\eb", 1); break;
  182.             case WC_TAB: vtansiputs(vt, "\et", 1);       break;
  183.             }
  184.             break;
  185.         }
  186.     }
  187. }
  188. .ft 1
  189. .fi
  190. .SH DIAGNOSTICS
  191. .I Vtopen
  192. returns a nil pointer if it can't allocate all the required memory or if
  193. the call to
  194. .I wopen
  195. it makes fails.
  196. .br
  197. .I Vtresize
  198. and
  199. .I vtautosize
  200. return false (zero) if they can't allocate the extra memory required;
  201. in this case the VT struct has been damaged beyond repair.
  202. .SH SEE ALSO
  203. STDWIN documentation
  204. .SH AUTHOR
  205. Guido van Rossum
  206. .SH BUGS
  207. In some versions of STDWIN, the scroll bars won't appear and some other
  208. functionality won't be available unless the program calls
  209. .I wgetevent.
  210. .br
  211. Unless the application calls
  212. .I vtautosize
  213. at all the right moments, it is quite possible that the window size
  214. doesn't match the size of the virtual terminal.
  215. When the window is too small, STDWIN's automatic scrolling will cause
  216. the text to jump around; when it is too large, portions of the
  217. scrolled-away text will remain visible but unreachable by the cursor.
  218. .br
  219. The ANSI terminal implementation is incomplete.
  220. It certainly isn't a full-fledged VT100.
  221. .br
  222. The behaviour of the cursor at the right margin is slightly
  223. unconventional.
  224. .br
  225. Bold output only works on the Macintosh, and requires that a font called
  226. ``Bold'' (9 points) be available in the system file.  This font can be
  227. found in the resources for (some versions of) VersaTerm(TM).
  228. .br
  229. The package makes the assumption that all characters have the same
  230. width.
  231. .br
  232. The order of parameters indicating rows and columns is internally
  233. consistent, but reversed with respect to order used for h and v
  234. coordinates in the rest of STDWIN.
  235. .br
  236. The origin of cursor coordinates passed to
  237. .I vtsetcursor
  238. is (0, 0), even though the origin used by ANSI escape sequences is
  239. (1, 1).
  240. .br
  241. The header file defines functions that aren't really part of the public
  242. interface.
  243.