home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / unix / volume27 / ytalk-3.0 / part01 / term.doc < prev    next >
Encoding:
Text File  |  1993-08-20  |  7.6 KB  |  232 lines
  1. Terminal I/O requirements:
  2.  
  3. Every time a user joins a YTalk connection, he is given a window in
  4. which his output will appear.  This terminal I/O is modularized in such
  5. a way that YTalk should be able to drive any windowing system or terminal,
  6. as long as someone programs a set of primitive functions.
  7.  
  8. When init_term() [in term.c] is called from main(), it will select the
  9. appropriate window system, initialize pointers to the appropriate
  10. primitives, and call the init function for that window system.  After
  11. this initialization, YTalk will transparently communicate with the
  12. window system by using these primitives.  It is therefore important
  13. that each primitive should be implemented exactly the same for each
  14. windowing system.  The purpose of this document is to define the
  15. expected behavior of each of the terminal I/O functions.
  16.  
  17. A valid YTalk 3.0 terminal interface provides an input interface.  Each
  18. time the user sends keyboard input, the input should be given to YTalk
  19. by calling this function in comm.c:
  20.  
  21.     void
  22.     my_input(buf, len)        [in comm.c]
  23.       ychar *buf;
  24.       int len;
  25.  
  26. Note that it is much more optimal to call this function once with a
  27. batch of input characters rather than calling this function once for
  28. each character.
  29.     
  30. A valid YTalk 3.0 terminal interface provides these output functions:
  31.  
  32.     void
  33.     init_???()
  34.  
  35. This is called when the terminal interface has been selected for
  36. use.  It should initialize any static variables and start any necessary
  37. connections.  It should not open or create any user windows.
  38.  
  39. Input processing (ie: calls to my_input() in comm.c) should begin after
  40. this initialization function is called.
  41.  
  42. ----------------------
  43.  
  44.     void
  45.     end_???()
  46.  
  47. This is called before YTalk exits.  All open windows should be shut
  48. down, any memory should be freed, and any connections should be
  49. terminated.  Consider your terminal interface worthy if it can survive
  50. this test indefinitely:
  51.  
  52.     for(;;)
  53.     {
  54.     init_???();
  55.     end_???();
  56.     }
  57.  
  58. ----------------------
  59.  
  60.     int
  61.     open_???(user, title)
  62.       yuser *user;
  63.       char *title;
  64.  
  65. Zero should be returned on success; any other value will be interpreted
  66. as an error.
  67.  
  68. This function should open a new window with the given title and assigned
  69. to the given user.  All future calls which affect this window will be
  70. passed the same user pointer.  Since the yuser structure is not passed
  71. between clients, you may add any variables you wish to the structure
  72. as long as you comment them as part of your terminal interface.
  73.  
  74. The terminal interface should never modify any of the other fields in
  75. the yuser structure, especially the window height and width fields.  These
  76. should only be set by calling the resize_win() [term.c] function.
  77.  
  78. The cursor position should be preset to 0,0.
  79.  
  80. The window size is assumed to be 80 columns by 24 rows.  If this is
  81. not the case, you are required to call the function resize_win() [term.c]
  82. with the appropriate height and width values.  I suggest you always call
  83. resize_win() from within open_???().
  84.  
  85.     void
  86.     resize_win(user, height, width)    [in term.c]
  87.       yuser *user;
  88.       int height, width;
  89.  
  90. ----------------------
  91.  
  92.     void
  93.     close_???(user)
  94.       yuser *user;
  95.  
  96. This will close the window assigned to the given user and free any
  97. attached memory.  Again, imagine the test:
  98.  
  99.     for(;;)
  100.     {
  101.     open_???(user, "test");
  102.     close_???(user);
  103.     }
  104.  
  105. ----------------------
  106.  
  107.     void
  108.     addch_???(user, char)
  109.       yuser *user;
  110.       ychar char;
  111.  
  112. This will add the given character to the window, following the terminal
  113. I/O rules listed below.
  114.  
  115. ----------------------
  116.  
  117.     void
  118.     move_???(user, y, x)
  119.       yuser *user;
  120.       int y, x;
  121.  
  122. This will move the cursor (the next output location) to the given Y,X
  123. coordinates, following the terminal I/O rules listed below.
  124.  
  125. ----------------------
  126.  
  127.     void
  128.     clreol_???(user)
  129.       yuser *user;
  130.  
  131. This will clear all characters from (and including) the current cursor
  132. position to the end of the line.  The cursor position does not change.
  133.  
  134. ----------------------
  135.  
  136.     void
  137.     clreos_???(user)
  138.       yuser *user;
  139.  
  140. This will clear all characters from (and including) the current cursor
  141. position to the end of the screen.  The cursor position does not change.
  142.  
  143. ----------------------
  144.  
  145.     void
  146.     scroll_???(user)
  147.       yuser *user;
  148.  
  149. This will scroll the window up one line, losing the line at the top
  150. of the window and creating a BLANK line at the bottom of the window.
  151. The cursor's X and Y positions do not change.
  152.  
  153. This function can be implemented using the other primitives, so it
  154. is therefore optional.  I strongly recommend that it be included, as
  155. it will no doubt be faster than the version implemented through the
  156. primitives.  If it is not available, then _scroll_term should be
  157. set to NULL in term.c.
  158.  
  159. ----------------------
  160.  
  161.     void
  162.     rev_scroll_???(user)
  163.       yuser *user;
  164.  
  165. This will revserse-scroll the window up one line, losing the line at
  166. the bottom of the window and creating a BLANK line at the top of the
  167. window.  The cursor's X and Y positions do not change.
  168.  
  169. This function can be implemented using the other primitives, so it
  170. is therefore optional.  I strongly recommend that it be included, as
  171. it will no doubt be faster than the version implemented through the
  172. primitives.  If it is not available, then _rev_scroll_term should be
  173. set to NULL in term.c.
  174.  
  175. ----------------------
  176.  
  177.     void
  178.     flush_???(user)
  179.       yuser *user;
  180.  
  181. If your window driver optimizes I/O by queuing updates and sending
  182. batches of changes at a time, this function should flush any pending
  183. output.  If your window driver does not require flushes, then this
  184. function should do nothing.
  185.  
  186. ----------------------
  187.  
  188. Terminal I/O Rules:
  189.  
  190. [ For simplicity, I'll use "maxrows" to mean the maximum number of      ]
  191. [ rows and "maxcols" to mean the maximum number of columns in a window. ]
  192.  
  193. When a window is initially opened, the cursor position should start
  194. at the upper left-hand corner.  This position is Y=0,X=0, or (0,0).
  195. The Y position is always given first and corresponds to the row
  196. number, starting at zero and ending at (maxrows-1).  The X position
  197. is always given second and corresponds to the column number, starting
  198. at zero and ending at (maxcols-1).
  199.  
  200. Every window is required to have at least two rows, and each row should
  201. have at least 20 columns.
  202.  
  203. Every time a character is added to the window, it should be placed
  204. at the cursor's current Y,X position, clearing and overwriting any
  205. character which may already be there.  Then, the cursor's X position
  206. should be incremented by one.  If the X position is now greater than
  207. or equal to maxcols, then the X position should be set back to
  208. (maxcols-1).  THERE IS NO DEFINITION FOR WRAPPING.  The cursor's
  209. Y position is never incremented as a result of X being too large.
  210. Instead, X is maintained at (maxcols-1) until move_???() is called
  211. to move the cursor.
  212.  
  213. Since there is no definition for wrapping, it follows that there is
  214. no definition for automatic scrolling.  A window should only scroll
  215. when scroll_???() is called explicitly.  Note that some terminals
  216. will scroll automatically when a character is placed in the lower
  217. right-hand corner.  If this is the case with your system, I suggest
  218. you tell YTalk that your terminal is actually one row shorter.  You
  219. could tell YTalk it is one column skinnier, but this effect can
  220. be visually displeasing.
  221.  
  222. The terminal interface will only be asked to display printable
  223. characters.  These are the characters in the decimal range from
  224. 32 [space] to 126 [tilde] inclusive.  Therefore, the addch_???()
  225. procedure need not consider how to display control characters or
  226. high-bit characters, because these will never be sent.
  227.  
  228. Similarly, the move_???() procedure will never be called with
  229. Y or X values outside the range of the current window.
  230.  
  231. -- EOF --
  232.