Programmer 7500/MAX_PROGRAMMERS.iso/PASCAL/PAVT110.ZIP/PAVATAR1.DOC

Text File | 1991-09-07 | 19.8 KB | 478 lines

                           PAvatar 1.10
                       Preliminary Release
             Turbo Pascal Avatar Level 1 Console Kit
                 Copyright 1991 Gregory P. Smith


Part I.  Introduction
──────────────────────────────────────────────────────────────

    This toolkit represents hundreds of hours of programming
    that resulted in this fast and accurate product.  PAvatar is a
    Turbo Pascal unit (version 5.5 or later) that can provide your
    programs with Avatar level 1 console, extended Avatar level 0+
    (optional ANSI fallback), ANSI-BBS, and ANSI terminal
    emulations.  This is done with a series of procedural hooks
    for screen I/O and cursor control.  This allows you to use the
    procedures of your choice, making the unit the most flexible
    of its type.
    An added bonus to using this unit is DESQview awareness.
    This unit contains facilities for detecting DESQview, giving
    up the time slice, and using DESQview's video buffer.  This is
    especially valuable for communications and bbs type programs
    that are often run under DESQview.


Requirements
─────────────────────────────

        This unit requires that you are using an IBM compatible
    computer and have Turbo Pascal 5.5 or later.  As I have used
    OOP for fast and efficient data management within this unit; I
    regret that I cannot provide a Turbo Pascal 5.0 version of the
    PAvt1 unit.
        Memory requirements within a program using PAvatar have
    been kept to a minimum.  Only 3-4k of heap space as well as
    less than 500 bytes stack space.  The actual code itself only
    requires 16k.


Shareware
─────────────────────────────

        I am distributing this unit under a relaxed shareware
    concept so as to promote Avatar.  You are free to use the
    compiled unit however you want, as long as I'm given credit
    for the terminal emulations somewhere in the documentation or
    in the program itself.  Please let me know of any programs
    that you write using PAvatar so that I can recommend them to
    others.
        If you want the source code to this unit it is available
    for $10 U.S., see the registration form for details.  The
    possible benefits of having source code are described later in
    this document.

Liability
─────────────────────────────

        To use PAvatar you must first agree that I cannot be held
    responsible for any damages or problems that occur from its
    use or misuse.  If you do not agree to these terms don't use
    this unit.


Part II.  QUICK START
──────────────────────────────────────────────────────────────

        First off you must install your unit.  To do so, copy the
    appropriate TPU file into your units directory (the TPU's have
    been renamed to .T55 for TP 5.5 and .T60 for TP 6.0, you must
    rename yours).  Next, copy the demo program A1DEMO.PAS into
    your pascal directory.  Type TPC a1demo or compile it to disk
    from the IDE.  You now have a utility for displaying AVT/1,
    AVT/0+, and ANSI files that is DESQview aware.  Unless you're
    a Sysop, you probably don't have lots of .AVT Avatar files.
    Currently there is no Avatar editor, but you may use my ANSI
    to Avatar/0+ converter to create Avatar files.  It's found on
    BBS's as A2AVTnnn.ZIP where nnn is the version number
    (currently 2.10).  When typing level 0 files, be sure to use
    the /PLUS parameter to indicate that it is not a level 1 file
    (The differences are described later).

Part III.  Interface
──────────────────────────────────────────────────────────────

Procedures
─────────────────────────────

        PAvatar is a self sufficient unit in that only two
    procedures are required to add an Avatar or ANSI terminal to
    your program.  However, there are more than two procedures
    available so that you can take advantage of many special
    features of the unit.  The procedures and definitions follow.

Procedure Parse_AVT1 (ch:char);

             This is the main procedure of the unit.  It takes
         character ch and parses it according to the status.  For
         instance if you pass it a ^V it would go into the Avatar
         command mode in which the next character would represent
         an Avatar command.  If it were an Esc and ANSI was
         enabled, the next character passed to it would  be tested
         for a bracket '[' or a shorter VT52 style ANSI  commands.
         This is the heart of the whole unit.

Procedure ResetTerminal (nc,nl:byte);

             This procedure is used to Reset the Terminal
         emulation with screen dimensions nc columns and nl lines.
         It always takes you back to the original mode with AVT/1
         active, and ANSI fallback turned off.  It has the same
         effect as issuing a ^V^R to the AVT/1 parser.

Procedure SetScreen(nc,nl:byte);

             Use this procedure when you want to change the size
         of the terminal screen without resetting everything else
         as in the ResetTerminal procedure.  The only thing this
         does is re-define all of the Avatar windows to have nc
         columns and nl lines.

Procedure AvtInterp (ch:char);

             This procedure is called by the Parser to interpret
         the Avatar codes after DLE's and special considerations
         have been processed.  When in ANSI_Only or AVT/0+ mode
         you can use this instead of Parse_AVT1.  The extra
         overhead of Parse_AVT1 is so small that using this is
         usually not worth it.

Procedure AvtTTY (ch:char);

             This procedure is called by the AVT/1 Parser when a
         character is not part of a control code.  It simply
         writes character ch to the screen following the current
         Avatar window setup (including flow, insert, direction,
         etc..).  The only characters that it processes are CR,
         LF, BS, Tab, and Bell.  You should not need this
         procedure, but it's here if you do.

Procedure Level0_Simulation (fallbck:boolean);

             This procedure places the interpreter into an
         extended AVT/0+ emulation mode.  If fallbck is true ANSI
         fallback will be on.  Internally, this procedure re-
         configures AVT/1's window 0 to have a default color of
         cyan (3), as well as turning cooked mode off.  Using this
         procedure is more effective than sending the equivalent
         codes for defining a level 0 simulation in a certain
         window.  Destructive backspaces are also disabled.

Procedure ANSI_Only;

             Use this procedure when you want to place the
         parser in ANSI Only mode.  It is the equivalent of
         putting the AVT/1 parser to sleep and disabling fallback.
         This is faster than fallback mode.

Procedure AvtSound (note:byte; oct:shortint; dur:byte);

             This procedure is a shortcut to stuff music into
         the Avatar sound buffer without having to send the code
         to the parser.  Note represents the musical note in the
         same method which AVT/1's ^V^S command uses it.  That is
         note is equal to (tone - 'A') * 2 + sharp where tone is
         somewhere between 'A' and 'G'.  Sharp is a 0 or a 1 as
         the case may be.  A pause is generated by a note of 14 or
         greater.  The octave is a signed integer in oct where 0
         represents middle octave and 1 the next highest, -1 the
         next lowest.  Dur is the duration in tenths of a second.
         If two identical notes are queued in a row, they will be
         played legato so that they run together.

Procedure StuffSound (frq,dur:integer);

             This procedure is called by the above procedure.
         It is used to place a sound of frq hertz and dur tenths
         of a second into the Sound buffer.  If the buffer is
         full, it will wait until space is available.

Function DESQview_version: word;

             This is the first of the DESQview supportive
         routines in this unit.  The DESQview major version number
         is in the high byte, while the minor version is in the
         low byte.  A zero is returned if DESQview is not loaded.

Procedure DV_Pause;

             This procedure will give up the current time slice
         if you are in DESQview.  It does nothing otherwise.  Use
         this procedure when your program is not doing anything,
         to give the other programs more processing time.  Do not
         hesitate to use this procedure, it's written in assembler
         so that it's execution time isn't even measurable.

Function ReadKey: char;

             This is a replacement for the Crt unit's ReadKey
         that gives up the current DESQview time slice (via
         DV_Pause) if a key hasn't been pressed.

Procedure SwapVectors;

             If you plan on shelling to DOS or swapping portions
         of your program out, this is a must.  As Avatar uses
         background sound, the unit hooks into interrupt $1C.
         This is an extension of the DOS unit's SwapVectors which
         also restores interrupt $1C.

Variables
─────────────────────────────

    There are only a few non-procedural variables that you can
    use to check or modify the status of the terminal.  They are
    all static variables with defined defaults.

ANSI_BBS : boolean = False;

             Use this variable to decide whether the ANSI
         portion of the unit will use the "BBS" style.  The only
         differences when this is true are that Esc[2J also homes
         the cursor and Esc[J acts the same as Esc[2J instead of
         Esc[0J.  DOS's own ANSI.SYS is infamous for processing
         Esc[2J this way.

Fallback : boolean = False;

             This variable controls whether ANSI fallback will
         be on during Avatar emulations.  It is best not to mess
         with this variable when using AVT/1 as it is designed
         primarily for use with AVT/0+.

ScrnLines : byte = 25;

             This variable simply defines the number of lines
         that you want on your terminal screen.  Modifying this
         variable can produce strange results.  It is recommended
         that you use the Terminal Reset procedure to define the
         screen size.

ScrnColumns : byte = 80;

             This variable is the partner of the above one.  It
         defines the number of columns you want on your terminal
         screen.  The same restrictions apply with this variable
         as on the above.

QueryReply : string[80] = 'AVT1, Avatar/1 Console Copr.  1991 Greg Smith. Ver 1.10'+^M;

             When the Avatar terminal id request is received
         this is the string that will be returned.  The "AVT1," at
         the beginning is important to the remote terminal.  It is
         used to define the capabilities of the terminal.
         Everything else is just your own logo or program ID.  In
         level 0+ simulation mode the AVT1 is changed to AVT0.

Dest_BS : boolean = True;

             As the name implies, this variable controls the
         behavior of the backspace (^H) character.  The AVT/1
         specifications require a Destructive backspace while the
         AVT/0 specifications require that it is non-destructive.

Constants
.

    The following constants are available for general use.

             Esc = ^[;
             DLE = ^P;
             FS = #28;
             GS = #29;
             RS = #30;
             US = #31;
             SP = #32; { space }


User Hooks
─────────────────────────────

        The interface for this unit has been designed to be as
    flexible as possible without hindering the performance of the
    unit.  Besides the main procedures and a few variables most of
    it is procedural hooks.  Their definitions follow.

Query_Hook : ReplyProc = Procedure (S:String);

             This hook is used for all terminal queries or
         responses such as the Avatar driver query and the ANSI
         report cursor position.  Usually these replies will be
         placed in the keyboard buffer or sent out the comm port.
         In a1demo, the hook is left at its null procedure setting
         as there is no use for it in that type of utility.  Note
         that information passed to this hook should be inserted
         immediately into the input or output buffer so that it is
         the next thing to be processed if you wish to comply
         fully with the AVT/1 specifications.

WriteATh : WriteATHookT = Procedure (x,y,a:byte;ch:char);

             This hook is simple and important.  It should write
         character ch on the screen at location x,y using
         attribute a.  This is the only thing it should do, it
         should not mess with the cursor or scroll the screen.

GotoXYh : GotoXYHookT = Procedure (x,y:byte);

             This hook is used to set the cursor position.
         Often this routine will call the Crt unit's GotoXY
         procedure.  It is provided for flexibility and the
         possibility of using PAvatar in a virtual screen or
         window.  Full checking against ScrnLines and ScrnColumns
         is performed internally.

Scrollh : ScrollHookT = Procedure (dir,x1,y1,x2,y2,n,a:byte);

             This hook is important to Avatar's power.  It
         scrolls the screen region of (x1,y1)-(x2,y2) n lines in
         the direction indicated in dir (1=up, 2=down, 3=left,
         4=right).  The empty area created by the scroll should be
         filled with blank spaces of color attribute a.  Most
         decent windowing toolkits have a procedure suitable for
         this.

FillAreah : FillHookT = Procedure (x1,y1,x2,y2,a:byte;ch:char);

             This hook is used to fill the screen region of
         (x1,y1)- (x2,y2) with character ch in attribute a.  If
         your scrolling procedure doesn't support a fill color for
         the newly exposed area, this is a good procedure to use
         for it.

GetATh : GetCharHookT = Procedure (x,y:byte;var a:byte;var c:char);

             This hook is the opposite of the WriteATh hook in
         that its purpose it to retrieve information from the
         screen.  Variable parameters c and a should be set to the
         character and attribute at the coordinates of x,y
         respectively.

HighAreah : HighHookT = Procedure (x1,y1,x2,y2,a:byte);

             Similar to FillAreah, this hook fills an area of
         the screen.  The area defined by (x1,y1)-(x2,y2) should
         be filled with attribute a, but the characters on the
         screen should not be disturbed.

Pauseh : PauseHookT = Procedure (tenths:word);

             The only purpose of this hook is to allow for
         controlled system pauses.  This hook should pause the
         terminal for tenths tenths of a second.  The reason I
         didn't just use a delay(100) within the unit is for the
         protection of the user.  With avatar, codes could be sent
         that could conceivable pause the system for several days.
         It is up to you to add a method of breaking out of a
         pause such as a key press.

FlushInputh : Procedure;

             This hook has a default effect of zeroing the
         keyboard buffer.  If your program has any internal
         buffers or communications buffer, you may wish to flush
         them when this hook is called.  The Avatar flush input
         command calls this hook.

The PAvt0 Small Version
─────────────────────────────

        Now included with the Pavt package is a PAvt0 Small version
    of the unit.  This unit is an AVT/0+ and ANSI-BBS terminal
    only.  It is much faster that the AVT/1 unit as there are no
    flow and window controls.  The primary use for this unit is
    for BBS door programs which won't be using AVT/1.  Overall the
    code there is 10.5k less code and 650 bytes less data as well
    as a minimal heap usage.
        The PAvt0 unit is designed as a drop in replacement for the
    PAvt1 unit.  However there are a few procedures and variables
    which don't exist in the PAvt0 unit.  The Pauseh and
    FlushInputh hooks are not available, the Level0_Simulation and
    Parse_AVT1 procedures are not available (AvtInterp should be
    used instead), and the ANSI_BBS variable is gone.  All of
    these were removed as they served no purpose in AVT/0+.  In
    addition, this unit parses tab characters (^I) as 8 spaces
    instead of the definable (defaults to 8 char tabs) tab stops
    of the full unit.


Part IV.  Special Considerations
──────────────────────────────────────────────────────────────

Avatar 1 Console
─────────────────────────────

        The Avatar level one console is a very powerful terminal
    emulation.  Naturally it goes without saying that there are a
    few things that must be considered if you wish to comply with
    the full AVT/1 console specifications.  I've already mentioned
    the need to insert the query replies first into the input or
    output buffer.  Secondly, AVT/1 features a sleep mode for its
    interpreter, so ANSI fallback should not be used as a remote
    program using level 1 codes should know how to switch between
    sleeping (ANSI) and awake (AVT/1).
        The main thing you should be concerned about in
    communications is flow control.  AVT/1 has a way to get around
    interference with XON/XOFF flow control if the parser is in
    cooked mode, but if it's switched to raw mode, the results
    will be disastrous.  As AVT/0+ is a raw only terminal,
    XON/XOFF must be disabled while it is active.


Tips & Tricks
─────────────────────────────

        The AvtInterp procedure is actually a procedural variable
    that is passed a character as its only parameter.  This should
    let you know a lot about how PAvatar works internally, as well
    as add flexibility.  If you wish to add your own terminal,
    just assign your own procedures to AvtInterp.  This will work
    when you are calling AvtInterp directly instead of Parse_AVT1.
    Of course, remember to call the parser when you switch to
    AVT/1.
        That is the only "hidden" feature I will expose right now,
    but expect more in upcoming versions.


Part V.  History And Credits
──────────────────────────────────────────────────────────────

        I thank Ping Hansen in the FidoNet pascal echo and an
    unknown someone in the FidoNet communications echo for
    sparking my interest in terminal emulations and Avatar.  I
    also would like to thank G. Adam Stanislav for taking on the
    project of updating the Avatar specification past its original
    Opus level commands.  Last but not least, I would like to
    thank my parents for putting up with me being on the computer
    so many hours.

Release Sites
─────────────────────────────

        The following is a list of BBS's where you can find the
    latest version of PAvatar as well as contacting me.

[phone]  CMOS BBS line 1,  300-9600, Fido: 1:104/441
[phone]  CMOS BBS line 2,  300-9600, Fido: 1:104/469
[phone]  Bohemia BBS Sys,  300-2400, Fido: 1:104/120
[phone]  Borealis WildCat, 1200-9600, RIME: ->BOREALIS
[phone]  Wizardry line 1, 1200-9600. Fido: 1:104/630

Mark Cook, Sysop of Wizardry, is my only beta tester at this time.  I will acquire more as I feel the need.


──────────────────────────────────────────────────────────────

Send all questions, comments, problems, ideas, money, etc.. to:

    Gregory P. Smith
    4422 Pali Way
    Boulder, CO. 80301 USA

Fidonet:  1:104/441,120,477,630
RIME: ->BOREALIS
UseNet/InterNet: [e-mail]
CompuServe: Route to above internet address.