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