home *** CD-ROM | disk | FTP | other *** search
/ Current Shareware 1994 January / SHAR194.ISO / modem / clcom201.zip / CLICKCOM.XXX / BULL.2 < prev    next >
Text File  |  1993-06-06  |  25KB  |  595 lines
  1. [This is actually FSC-0025 and FSC-0037 combined into one file describing
  2.  the Avatar level 0+ terminal.  level 0 alone is obsolete, so be sure to
  3.  read the second half of this document describing level 0+'s features    ]
  4.  
  5. /*   FSC-0025
  6.  
  7.  
  8.  
  9.                                                         Pittsburgh, PA
  10.                                                         23 August 1988
  11.  
  12.  
  13.  
  14.                              A V A T A R
  15.  
  16.       Advanced Video Attribute Terminal Assembler and Recreator
  17.  
  18.                           George A. Stanislav
  19.  
  20.                                  129/39
  21.  
  22.  
  23.  
  24.                           Historical Overview
  25.  
  26.  
  27. Wynn Wagner III, the author of Opus-CBCS, developed a method of storing
  28. video control codes in a file sent to the Opus caller which was meant as
  29. a replacement of ANSI escape codes. Its main advantages were:
  30.  
  31.         o  The codes are smaller than ANSI, thus needing less disk
  32.            storage space.
  33.  
  34.         o  The codes are in the binary form easily interpreted by the
  35.            computer (ANSI sequences use ASCII).
  36.  
  37.         o  The same file can be sent to callers who do or do not have
  38.            the ability of interpreting ANSI codes - in the former case
  39.            the codes are first translated to ANSI, in the latter they
  40.            are ignored.
  41.  
  42. Because of lack of an appropriate name, Wynn temporarily named the codes
  43. oANSI with the understanding that a better name was needed.
  44.  
  45. When I started working on my TinyTerm communications program, I had the
  46. idea that if Opus-CBCS could send the "oANSI" codes directly over the phone
  47. lines, it would speed up the communications considerably. A typical ANSI
  48. sequence contains 4 times as many bytes as the codes developed by Wynn
  49. Wagner.
  50.  
  51. A phone call to Wynn resulted in two things: 
  52.  
  53.         o  TinyTerm can interpret the "oANSI" codes and translate
  54.            them to ANSI, then send them to stdout where they are
  55.            converted to colors by ANSI.SYS.
  56.  
  57.         o  Opus-CBCS, starting with gamma version 1.10.iii, will
  58.            send the codes without converting them to ANSI sequences.
  59.            (It will still send ANSI codes to users without the proper
  60.            terminal software.)
  61.  
  62. I took over the coding of the part of Opus handling the video codes. I
  63. realized the codes were offering us much more power than just translating
  64. them to ANSI escape sequences. I proposed to call the codes AVATAR, the
  65. Advanced Video Attribute Terminal Assembler and Recreator. Wynn readily
  66. accepted the new name.
  67.  
  68.  
  69.  
  70.                      The Two Levels of Avatar
  71.  
  72. Avatar is more than a video attribute controller. It is a protocol which,
  73. if need be, can totally eliminate the interference of line noise. However,
  74. this document is not concerned with the advanced topics of Avatar (which
  75. no program is using as of this writing).
  76.  
  77. A full Avatar session with all its advanced features starts by exchanging
  78. the AVINIT packets. The caller sends a packet which describes the video
  79. capabilities of his/her system. It also contains the caller's name, password
  80. and some other optional information. It also tells the BBS if the user is
  81. calling in person or just emulating a BBS session with an Avatar terminal
  82. program.
  83.  
  84. The called system (the BBS) replies to the AVINIT packet with a packet that
  85. informs the user of his current status, e.g. you can stay till 16:30 GMT,
  86. or you are denied access, or I am processing mail now but you can call back
  87. at 10:43 GMT, etc.
  88.  
  89. Until such AVINIT packets are exchanged, only the Avatar commands that were
  90. part of the original oANSI codes can be sent from the BBS to the caller.
  91. The caller's term program should send no Avatar commands, with the exception
  92. of function key codes, before the AVINIT packets are exchanged. This assures
  93. that a BBS program which does not support full Avatar can still take
  94. advantage of the faster transfer of video codes using Avatar as opposed to
  95. ANSI escape sequences. It also permits the caller whose term program does
  96. not support full Avatar but can interpret the basic codes to take advantage
  97. of the term program's abilities.
  98.  
  99. The two levels of Avatar then are: a full session and a basic session. This
  100. document is concerned with the BASIC Avatar session only. The full session
  101. will be defined in a separate document.
  102.  
  103.  
  104.  
  105.  
  106.                        Basic Avatar Commands
  107.  
  108.  
  109. Before the AVINIT packets are exchanged, the BBS can send the basic Avatar
  110. commands if so permitted by the user's choice, typically recorded in the
  111. user datafile (e.g. USER.BBS). Because Avatar is window oriented, in a
  112. basic session the full screen is considered the default window. Further,
  113. the default color of the window is assumed to be 3 (cyan text on a black
  114. background). All bytes are taken at their face value without escaping.
  115. However, save for one exception described below, no basic Avatar code will
  116. have the high bit set. Therefore, the term program should reset the high
  117. bit of all bytes except as described below.
  118.  
  119. The basic commands are:
  120.  
  121.         <^L>    -       clear the current window and set current attribute
  122.                         to default. In the basic session this means:
  123.                         Clear the screen and set its attribute to 3.
  124.  
  125.         <^Y>    -       Read two bytes from the modem. Send the first one
  126.                         to the screen as many times as the binary value
  127.                         of the second one. This is the exception where
  128.                         the two bytes may have their high bit set. Do
  129.                         not reset it here!
  130.  
  131.         <^V> <^A> <attr> - Set the color attribute to <attr>. The default
  132.                         attribute remains unchanged. However, all text
  133.                         will be displayed in <attr> until the next ^V^A,
  134.                         ^V^B, or ^L.
  135.  
  136.         <^V> <^B>   -   Turn the high bit of current attribute on. In
  137.                         other words, turn blink on.
  138.  
  139.         <^V> <^C>   -   Move the cursor one line up. Do nothing, if you
  140.                         already are at the top line of the current
  141.                         window.
  142.  
  143.         <^V> <^D>   -   Move the cursor one line down. Do nothing if you
  144.                         already are at the bottom line of the current
  145.                         window.
  146.  
  147.         <^V> <^E>   -   Move the cursor one column to the left. Do nothing
  148.                         if you already are at the leftmost column of the
  149.                         current window.
  150.  
  151.         <^V> <^F>   -   Move the cursor one column to the right. Do nothing
  152.                         if you already are at the rightmost column of the
  153.                         current window.
  154.  
  155.         <^V> <^G>   -   Clear the rest of the line in the current window
  156.  
  157.  
  158.                         using the current attribute (not to be confused
  159.                         with the default attribute).
  160.  
  161.         <^V> <^H> <row> <col>   -   Move the cursor to the <row> <col>
  162.                         position within the current window.
  163.  
  164.  
  165. Comments:
  166.  
  167. Current attribute and default atribute are not necessarily the same.
  168. Whenever the window is cleared by the <^L> command, the current attribute
  169. is made equal to the default attribute. There is also another command to
  170. make the current attribute equal to the default attribute. However, this
  171. command is not a part of the basic Avatar command set and therefore cannot
  172. be used before the AVINIT packets are exchanged.
  173.  
  174. Whatever characters are sent to the screen, they should be displayed using
  175. the CURRENT attribute. There is an exception to this, but only after the
  176. AVINIT packets have been exchanged.
  177.  
  178. The attribute byte is an eight-bit value. As basic Avatar can only transfer
  179. 7-bit commands, the high bit of the attribute byte can be set only by the
  180. <^V> <^B> command. The <attr> byte of the <^V> <^A> <attr> command should
  181. be AND-ed with 7F (hexadecimal). The colors set by the attribute byte are
  182. the same as are the colors of the text mode of an IMB color graphics adapter.
  183.  
  184. That means the bits of the attribute byte have the following meaning:
  185.  
  186.      bit:         7   6   5   4   3   2   1   0
  187.                   -   -   -   -   -   -   -   -
  188.                   |   |       |   |           |
  189.                   |   |       |   |           |
  190.                   |   +---+---+   +-----+-----+
  191.                   |       |             |
  192.                   |       |             |
  193.                   |       |
  194.                   |       |         text color
  195.                   |       |
  196.                   |
  197.                   |    background color
  198.                   |
  199.  
  200.                 blink
  201.  
  202. If the blink bit is set, the text is blinking, else it is not blinking.
  203.  
  204. The bits of background color can have values 0 - 7, the bits of the text
  205. color can have values 0 - 15. The value indicates the following colors:
  206.  
  207.                  0      black
  208.                  1      blue
  209.                  2      green
  210.                  3      cyan
  211.  
  212.  
  213.                  4      red
  214.                  5      magenta
  215.                  6      brown
  216.                  7      gray  (i.e. non-itense white)
  217.                  8      dark gray
  218.                  9      light blue
  219.                 10      light green
  220.                 11      light cyan
  221.                 12      light red
  222.                 13      light magenta
  223.                 14      yellow
  224.                 15      white (intense)
  225.  
  226. Colors 8 - 15 are the same as 0 - 7 but with high intensity.
  227.  
  228. Please note that these values are different from the numbers used by ANSI
  229. escape codes.
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.                      The Function Key Codes
  237.  
  238.  
  239.  
  240. An Avatar capable BBS can accept function keys from the remote caller.
  241. This feature is optional (for the term program) but highly recommended.
  242.  
  243. On an IBM (compatible) computer this means that if a caller hits a function
  244. key (e.g., left arrow, page up, F7, insert, alt-H, etc.), the term program
  245. should send two bytes to the Avatar capable BBS: A binary zero followed by
  246. the keyboard scancode. Please note that control keys (^A, ^B, etc.) are not
  247. function keys but have an ASCII value which is the only byte that should be
  248. transfered.
  249.  
  250. There are two keys on the IBM keyboard that do have an ASCII value but also
  251. offer a separate scan code. These are the gray-plus and the gray-minus. If
  252. one of these keys is hit, treat it as a function key - send the binary zero
  253. followed by the scan code. This way if the BBS treats them differently from a
  254. regular plus and minus keys, the caller can take advantage of the keys.
  255. On the other hand, BBS writers who do not want to assign the gray keys
  256. a special value, should watch for their codes and treat them as a regular
  257. plus and minus.
  258.  
  259. Systems that use a different keyboard layout (and scan codes) than IBM can
  260. emulate IBM by declaring which keys are considered the arrows, f-keys, etc.
  261. If you have the arrow keys, for example, but their scan codes are different,
  262. still send the binary zero and the scan code that an IBM keyboard would
  263. assign to that particular key. This should be transparent to the user.
  264.  
  265.  
  266.  
  267. There is an obvious problem here. All terminal programs I have seen use
  268. function keys internally. A switch is needed so the user can decide whether
  269. a function key is meant for the internal use of the term program or it
  270. should be transfered to the BBS. Most but not all IBM clones have a scroll
  271. lock key, some even have an LED indicator on it. The IBM programs could use
  272. that as a switch to know what the user means by hitting a function key.
  273. Since some compatibles do not have a scroll lock key (e.g. Tandy 1000), the
  274. Avatar capable BBS should never expect the <shift> <F1> combination to be
  275. transfered. That way the term program can use <shift> <F1> to switch between
  276. the local and remote use of function keys if the scroll lock key is not
  277. available.
  278.  
  279.  
  280.  
  281.  
  282.                               Conclusion
  283.  
  284.  
  285. This should about summarize the basic Avatar commands. I have written this
  286. document one day before leaving for Fidocon '88 realizing it would be nice
  287. to give the software developers (both of BBS's and term programs) something
  288. before releasing the specs of the full Avatar implementation.
  289.  
  290. Here is also some sample C code. It assumes you have some low level
  291. communications functions of your own. For the screen output it uses Turbo C
  292. library, but you can use anything you want. */
  293.  
  294.  
  295. #include <conio.h>
  296.  
  297. int def_attr = 3;
  298. int cur_attr = 3;
  299. int lastline = 25;
  300. int lastrow  = 80;
  301.  
  302. /* WARNING: This code has not been tested. It is just meant as an example  */
  303.  
  304. void pascal avatar()
  305. {
  306.  int c,i,j;
  307.  
  308.  switch (mgetchar())            /* Read a char from the modem */
  309.   {
  310.         case 12 :       textattr(cur_attr = def_attr);  /* ^L */
  311.                         clrscr();
  312.                         break;
  313.  
  314.         case 25 :       c = mgetchar();                 /* ^Y */
  315.                         j = mgetchar();
  316.                         for (i = 0; i < j; i++)
  317.                                 cprintf("%c",c);        /* print in color */
  318.                         break;
  319.  
  320.         case 22 :       switch(mgetchar())              /* ^V */
  321.                         {
  322.                          case 1 : cur_attr = mgetchar() & 0x7f;
  323.                                   textattr(cur_attr);
  324.                                   break;
  325.  
  326.                          case 2 : cur_attr |= 0x80;
  327.                                   textattr(cur_attr);
  328.                                   break;
  329.  
  330.                          case 3 : if ((i = wherey()) > 1)
  331.                                         gotoxy(wherex(),i - 1);
  332.                                   break;
  333.  
  334.                          case 4 : if ((i = wherey()) < lastline)
  335.                                         gotoxy(wherex(), i + 1);
  336.                                   break;
  337.  
  338.                          case 5 : if ((i = wherex()) > 1)
  339.                                         gotoxy(i - 1,wherey());
  340.                                   break;
  341.  
  342.                          case 6 : if ((i = wherex()) < lastrow)
  343.                                         gotoxy(i + 1,wherey());
  344.                                   break;
  345.  
  346.                          case 7 : cleol();
  347.                                   break;
  348.  
  349.                          case 8 : i = mgetchar();
  350.                                   gotoxy(mgetchar(),i);
  351.                         }
  352.   }
  353. }
  354.  
  355. FSC-0037
  356. Updates: FSC-0025
  357.  
  358.  
  359.  
  360.                                                 Pittsburgh, PA
  361.                                                 1 May 1989
  362.  
  363.  
  364.                           A   V   A   T   A   R
  365.  
  366.         Advanced Video Attribute Terminal Assembler and Recreator
  367.  
  368.                            George A. Stanislav
  369.  
  370.                             Fidonet 1:129/39.0
  371.  
  372.  
  373.  
  374.  
  375.  
  376.          Information
  377.  
  378.             This FSC is being distributed to members of the FidoNet
  379.             community in order to solicit their reactions to the
  380.             proposals contained in it.  While the issues discussed may
  381.             not be directly relevant to FidoNet standards,  they may be
  382.             interesting to implementers.  Distribution of this document
  383.             is unlimited.
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.    Revised on 25 November 1989
  396.  
  397.  
  398.  
  399.                                Definitions
  400.  
  401.  
  402. Avatar, level 0 - The Avatar protocol as presented at Fidocon '88 and
  403.         described in AVATAR0.C, dated 23 August 1989, plus extensions
  404.         defined in this document.
  405.  
  406. AVT/0   -  An abbreviation for Avatar, level 0, suggested by Joaquim
  407.         Homrighausen.
  408.  
  409. Current attribute - Video attribute defined by the last ^V^A, ^V^L, ^V^M or ^L
  410.         AVT/0 command whichever happened last. In AVT/0, ^L sets the value
  411.         of current attribute to 3, ^V^L, ^V^M and ^V^A to an explicit value.
  412.         In addition, ^V^B turns blink on.
  413.  
  414.  
  415.  
  416.                             Extending AVT/0
  417.  
  418.  
  419. It has become clear some of the Avatar commands originally reserved for
  420. AVT/1 would be very useful in AVT/0. I was hesitant to add them for one
  421. simple reason: Any addition on level 0 will break all existing Avatar
  422. emulating software.
  423.  
  424. However, at present there are only three programs I know of that have
  425. implemented Avatar emulation: My own TinyTerm, Joaquim Homrighausen's
  426. FrontDoor and Jason Galanter's Jterm.
  427.  
  428. Both Joaquim and Jason have assured me they would put the new commands in
  429. their programs, thus nothing will be broken. With that assurance in mind,
  430. I feel confident no chaos will result from adding these new commands.
  431.  
  432.  
  433.                 New Commands (brief definitions)
  434.  
  435.         <^V><^I>  -  Turn insert mode ON. It stays on until any other AVT/0
  436.                      command except <^Y> and <^V><^Y> is encountered after
  437.                      which it is turned off;
  438.  
  439.         <^V><^J><numlines><upper><left><lower><right> - scroll area up;
  440.  
  441.         <^V><^K><numlines><upper><left><lower><right> - scroll area down;
  442.  
  443.         <^V><^L><attr><lines><columns>  - clear area, set attribute;
  444.  
  445.         <^V><^M><attr><char><lines><columns>  - initialize area, set attribute;
  446.  
  447.         <^V><^N>        -  delete character, scroll rest of line left;
  448.  
  449.         <^V><^Y><numchars><char>[...]<count>  -  repeat pattern.
  450.  
  451.  
  452.  
  453.                       Detailed Description
  454.  
  455.  
  456. Insert mode: Insert mode controls the way characters are printed on the
  457.         screen. Insert mode is always assumed OFF unless explicitly set ON
  458.         by the ^V^I command after which it stays on until another AVT/0
  459.         command except for ^Y or ^V^Y is encountered. Then it reverses back
  460.         to off.
  461.  
  462.         Whenever insert mode is OFF, characters are printed on the screen
  463.         like this:
  464.  
  465.         1. Print character at current cursor position using current attribute,
  466.            overwriting whatever was previously displayed at current cursor
  467.            position;
  468.  
  469.         2. Move cursor to next position, usually one character to the right.
  470.            At end of the line, move the cursor to next line (possibly
  471.            scrolling the display or current window if in AVT/1).
  472.  
  473.         Whenever insert mode is ON, characters are printed on the screen
  474.         as follows:
  475.  
  476.         1. Starting at current cursor position and going all the way to the
  477.            second last character on current line, scroll the text one
  478.            character to the right;
  479.  
  480.         2. Discard the character previously at the end of the line, do NOT
  481.            move it at the beginning of the next line;
  482.  
  483.         3. Print character at current cursor position using current attribute;
  484.  
  485.         4. Move cursor to next position, precisely as in par. 2 of insert
  486.            mode off.
  487.  
  488. If ^Y or ^V^Y are encountered, the string of characters they compress is
  489. first expanded, then treated as an ordinary stream of characters printed
  490. according to the above rules.
  491.  
  492. Any other AVT/0 command turns insert mode back off. Please note that in
  493. either case the cursor is moved to its next position in an identical manner.
  494. The mere fact the cursor is moved to next line, or even scrolls the screen
  495. a line up, does NOT turn insert mode off. Only an AVT/0 except as mentioned
  496. above can change insert mode on or off.
  497.  
  498. If control characters are a part of the text stream, they are interpreted
  499. indentically in insert mode on and off as follows:
  500.  
  501.         Carriage return  -  move cursor at the beginning of the same line;
  502.  
  503.         Line feed        -  move cursor one line down (scroll screen or
  504.                             window [in AVT/1] if necessary), do not change
  505.                             cursor column;
  506.         Back space       -  move cursor one position to the left. Do NOT
  507.                             overwrite the character at that position.
  508.                             Do nothing if already at the leftmost position;
  509.  
  510.         Tab              -  move cursor to next tab position without
  511.                             overwriting anything. Tab positions are
  512.                             multiples of 8. Do nothing if already at the
  513.                             rightmost position.
  514.  
  515. A space is treated as a character, not as a control character.
  516.  
  517.  
  518. Scrolling an area (^V^J and ^V^K): The area defined by its upper, left, lower
  519.         and right coordinates is scrolled up <^V^J) or down (^V^K) by
  520.         <numlines> lines filling the gap with blank spaces using current
  521.         attribute. If the value of <numlines> is zero or exceeds the actual
  522.         number of lines within the scrolled area, the area is filled with
  523.         blanks using current attribute.
  524.  
  525.         These two commands do NOT change the position of the cursor, nor
  526.         do they define the scrolled area as the default window.
  527.  
  528.         The coordinates are relative to the upper left corner of the screen
  529.         (or current window in AVT/1). The coordinates of upper left corner
  530.         are 1,1. If a coordinate contains 0, it is to be changed to 1.
  531.  
  532. Initializing an area (^V^M): This command contains several steps:
  533.  
  534.         1. Set current attribute to <attr>;
  535.  
  536.         2. Starting at current cursor position (inclusively), ending
  537.            at current cursor position plus number of <lines> and <columns>,
  538.            print <char> at all position inside the defined area. Do not
  539.            move the cursor. If the number of columns or lines exceeds whatever
  540.            is available to the right and below current cursor position,
  541.            truncate the dimensions to fit within the limits of the screen
  542.            (or current window in AVT/1).
  543.  
  544. Clearing an area (^V^L): This is a shortcut version of the ^V^M command.
  545.         The character to be used to initialize the area of the screen is
  546.         assumed to be a blank space. In other words, it sets current
  547.         attribute and clears an area of the screen starting at current
  548.         cursor position (which remains unchanged).
  549.  
  550. Please note that the usual 7-bit restriction applies to ^V^L  That means
  551. that the attribute byte should be anded with 7f hex before applying. If
  552. blinking is desired, ^V^B should be used next.
  553.  
  554. On the other hand, requiring to ignore the high bit in ^V^M would make it
  555. impossible to fill the area of the screen with a blinking pattern (something
  556. I have seen used very creatively by Chris Gaal of PittNet). Therefore, if
  557. bit 7 of attr is set in ^V^M, current attribute is set to <attr> AND 7f hex
  558. and blink is turned on before filling the area with a character.
  559. Deleting a character (^V^N): Starting at the column one character to the right
  560.         of current cursor position all the way to end of the line, scroll
  561.         the text one character position to the left. This effectively
  562.         deletes the character at current cursor position. Print a blank space
  563.         using current attribute at the rightmost end of the line to fill the
  564.         gap. Do not change current cursor position. If the cursor is at the
  565.         end of the line, simply overwrite the last character with a blank
  566.         space using current attribute.
  567.  
  568. Repeat pattern: This is an extension of the ^Y command which allows a group
  569.         of characters to form a repetititious pattern. <numchars> determines
  570.         the number of characters in the pattern, <count> the number of times
  571.         the pattern is to be printed out. The pattern may contain AVT/0 codes.
  572.  
  573. For example, <^V><^Y><#3>ABC<#4> expands to "ABCABCABCABC".
  574.  
  575.  
  576.                         Scrolling Philosophy
  577.  
  578.  
  579. An important philosophical question has not been answered yet: When scrolling
  580. the contents of an area (in the scrolling commands ^V^J and ^V^J, in insert
  581. mode ON and in deleting characters ^V^N) should only the text be scrolled
  582. and the attribute of the scrolled areas remain where they are or should the
  583. attributes move as well.
  584.  
  585. A case can be made for either approach. Obviously, the gaps created by
  586. scrolling are filled with current attribute, therefore, it seems more logical
  587. to scroll the attributes along with the text (else there would be no need
  588. to fill the gaps). Thus we follow a consistent principle of video attributes
  589. belonging to a character (be it a blank, a digit, or a true character), not
  590. to a location. Whenever a character is scrolled to a different location, it
  591. takes its attribute along.
  592.  
  593.  
  594.  
  595.