C!T ROM 2

home *** CD-ROM | disk | FTP | other *** search

/ C!T ROM 2 / ctrom_ii_b.zip / ctrom_ii_b / PROGRAM / PASCAL / PAVT150 / PAVT150.DOC < prev next >

Wrap

Text File | 1993-04-12 | 29KB | 612 lines

PAvatar 1.50 Turbo Pascal Avatar level 1 Console Kit Copyright 1991 - 93 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 (versions 5.5 - 7.0) that can provide your programs with Avatar level 1 console, Avatar level 0+ (optional ANSI fallback), ANSI-BBS, ANSI, and VT-52 terminal emulations. Procedural hooks are used for screen I/O and cursor control, allowing 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 multitasker awareness. The PAvtIO unit contains facilities for detecting DESQview, giving up the time slice to any multitasker, and using DESQview's video & sound buffers. This is especially valuable for communi- cations and BBS programs that are often run under multitaskers. Requirements ───────────────────────── This unit requires a Turbo Pascal 5.5, 6.0, or 7.0 compiler running on an IBM or compatible computer. I have used objects for fast and efficient data management within this unit; I cannot provide a Turbo Pascal version 5.0 unit. Memory requirements within a program using PAvatar have been kept to a minimum. Only 3k of heap space and 500 bytes stack space are required. The actual code itself requires less than 18k. Shareware ───────────────────────── I am distributing this unit under a relaxed shareware con- cept in order to promote Avatar. You are free to use the com- piled unit however you want, as long as I am 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 PAvatar source code it is available for $12 U.S., see the registration form for details. The source code allows you to exclude many options that you may not need via compiler defines (making the code much smaller). 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 you must install the unit. To do so, copy the appro- priate TPU file into your units directory (the TPU's have been renamed according to the compiler version they will work with (.T55 for TP 5.5, .T70 for TP 7.0, etc.) you must rename yours. Next, copy the demo program PAVTDEMO.PAS into your Pascal direc- tory. Type TPC pavtdemo 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. As of this writing TheDraw 4.60 has just been released with support for Avatar level 0 files. I haven't tested it thoroughly but it appears to create good files. You may also use my ANSI to Avatar/0+ converter to create Avatar files. ANS2AVT will convert less common ANSI commands and use level 0+ codes. It's found on BBS's as A2AVTnnn.ZIP where nnn is the version number (currently 2.10). Please note that my ANS2AVT program is now public domain and no longer supported. Part III. Interface ────────────────────────────────────────────────────────────────── Procedures ───────────────────────── The PAvt150 Unit: ───────────────────────── PAvatar is a self sufficient unit in that only two pro- cedures 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 InitUnit; New with version 1.50 of PAvatar is support for partial overlaying of the code. This procedure MUST be called before your program uses any routines from the PAvatar unit! Your program will most likely lock up if you use PAvatar before it is initialized. Procedure Parse_AVT1 (ch:char); This is the main procedure of the unit. It takes character ch and parses it according to the terminal 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 VT-52 style command. 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, ANSI fallback turned off, and the cursor at the home position. It has the same effect as issuing a ^V^R to the AVT/1 parser. Procedure SetTerminal(t:TerminalType); This is the best way to change the type of terminal that the PAvatar unit is emulating. By passing one of the TermXXXX typed constants described below as a parameter you can select which terminal emulation to use. TerminalType = (TermTTY, { TTY: no special emulation } TermANSI, { ANSI: extended ANSI } TermAVT0, { AVT/0+: extended level 0+ w/ANSI fallback } TermAVT1, { AVT/1: full level 1 } TermVT52); { VT-52: Standard VT-52 } Procedure SetScreenSize(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 effect this has is redefining all of the Avatar windows to have nc columns and nl lines. Procedure AvtTTY (ch:char); This procedure is called by the AVT/1 Parser when a charac- ter is not part of a control code. It simply writes character ch to the screen following the current Avatar window setup (includ- ing flow, insert, direction, etc..). The only characters that it processes are CR, LF, BS, Tab, and Bell. Function In_Command: Boolean; Returns a true value if the interpreter is in the middle of processing any Avatar, ANSI, or VT-52 command. This is useful to prevent strange displays or invalid commands when aborting the display of a file. Procedure UpdateCursor(x,y:byte); This procedure is used to update the cursor position within the current Avatar window to x,y. Passing a 0 for either parame- ter will leave that parameter unchanged, but the cursor will be reset to the correct position stored internally by the parser. The PAvtSnd Unit: ───────────────────────── 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. The note is equal to (tone - 'A') * 2 + sharp where tone is somewhere between 'A' and 'G' and sharp is a 0 or a 1 as the case may be. A pause is generated by a note of 14 or greater. oct is a signed integer where 0 represents the middle octave, 1 the next highest, and -1 the next lowest. Dur is the duration of the note in tenths (actually 1/9ths) of a second. If two identical notes are queued in a row, they will be played legato so that they run together. Procedure ANSISound (note:byte; oct:byte; ticks:byte); This procedure is similar to AvtSound. The only differences are as follows. Oct is the octave as used by ANSI music (3 is the middle octave). Ticks is the number of timer ticks the note will play for (a timer tick is approximately 1/18th of a second). Procedure StuffSound (frq,dur:integer); This procedure is called by the above two procedures. It is used to place a sound of frq hertz and dur timer ticks into the Sound buffer. If the buffer is full, it will wait until space is available. Procedure Set_Sound_backg(backg:Boolean); All sounds produced by the PAvt unit, including the ^G bell, will be made in the background if backg is set to true. Other- wise they will be made in the foreground, delaying the program until they finish. Sound defaults to the foreground, but there is usually no reason that you shouldn't set it to background. It is worth noting, however, that with foreground sound the timer interrupt ($1c) is not chained and/or DESQview sound calls are not made. Sound lengths under multitaskers can be unreliable if sounds are produced in the foreground. Procedure Flush_Sound; This will stop any sounds from playing and empty the sound queue. Function Sounds_Left: integer; Sounds_Left will return the number of items (sounds & paus- es) left in the sound queue waiting to be played. Procedure Sound_Finish; This procedure makes use of the previous one. It will not return to it's caller until all sounds in the queue have finished playing. Procedure SoundBell; This stuffs a bell sound into the sound buffer. The TTY processor uses this when a ^G character is received. Procedure Sound2(freq:word); Procedure NoSound2; These routines are identical to the Crt units Sound and NoSound procedures but will generate the sound on an AdLib or compatible sound card if one is present. The PAvtIO Unit: ───────────────────────── 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 IdlePause; This procedure will give up the current time slice if your program is running under a multitasker. Use this procedure when your program is not doing anything to give the other programs more processing time. Function ReadKey: char; This is a replacement for the Crt unit's ReadKey that gives up processor time to a multitasker (via IdlePause) until a key is pressed. Procedure DelayTicks(t:word); This will delay for t timer ticks. The accuracy, however, can only be guaranteed to be within one timer tick. Procedure DV_Sound(freq,dur:word); A sound of freq Hz and dur timer ticks will be stuffed into the background sound buffer provided by DESQview. 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. All variable definitions are contained in the PAvtIO unit. ANSI_BBS : Boolean = True; Use this variable to decide whether PAvatar's ANSI inter- preter will use BBS/DOS style ANSI. When it is true Esc[2J homes the cursor when it clears the screen and Esc[J acts the same as Esc[2J instead of Esc[0J. DOS's own ANSI.SYS works in this way. ANSI_MUSIC : Boolean = True; When this variable is true "ANSI" music commands will be processed. It is recommended that sound be set to background if you wish to support music. In_DV : Boolean = <see text>; This variable is initialized in the PAvtIO unit. If it is true the DESQview multitasker has been detected. Background sounds will be produced using DESQview specific calls. CurrentTerm : TerminalType = TermAVT1; This variable is set by the SetTerminal procedure to identi- fy the currently active emulation. It should not be modified; it is for reference only. Sound_Stat : byte = 3; This variable is used to control which sounds are produced by the unit. If bit 1 is set then the unit can make sounds. Bit 0 only controls the bell (^G) sound. As you can see, the default is to have all sound enabled. IgnoreNULL : Boolean = False; Used by the VT-52 terminal, this variable will cause null (#0) characters to be ignored by the TTY processor. VT52On : Boolean = False; When true and in ANSI mode, commands will be treated as a VT-52 terminal would treat them. ANSI commands which are not overridden by a VT-52 command will remain effective. 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 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 SetScreen- Size 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, PAvatar 1.50 Copr. 1991-93 Gregory P. Smith'+^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. I would appreciate it if you would leave the "PAvatar 1.50" in the string if you do modify it. 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. Def_Cursor : word = <see text>; The normal cursor shape (as used by the BIOS call to set the cursor shape) is stored in this variable. The Normal cursor is usually an underscore but the value will vary depending upon what video card the program is run on. This variable is set to the cursor shape is when the PAvtIO unit initializes at startup. Constants ───────────────────────── The following constants are available for general use in the PAvtIO unit. 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. Other than the main procedures and a few variables most of PAvatar consists of procedural hooks found in the PAvtIO unit. Their definitions follow. The Avatar interpreter does not check for invalid screen coordinates on the hooks that need them. It is important that your hooks check the integrity of the coordinates, otherwise seemingly random lockups can occur when invalid or garbled com- mands are processed. All screen coordinates are one based mean- ing that (1,1) is home position. 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 pavtdemo, 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 charac- ter ch on the screen at location x,y using attribute a. This is the only thing it should do, it should not move 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 provid- ed 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 indi- cated 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 good 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 is 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 attrib- ute a, but the characters on the screen should not be modified. Pauseh : PauseHookT = Procedure (tenths:word); The purpose of this hook is to allow for controlled system pauses. This hook should pause the terminal for tenths 10ths of a second. The reason I didn't use a delay(100) within the unit is for the protection of the user. With avatar, codes could be sent that could conceivably pause the system for several days; the Delay() procedure is also inaccurate in multitaskers. It is up to you to add a method of breaking out of a pause (such as a key press). Cursorh : CursorHookT = Procedure (style:byte); This hook is used to set the cursor shape for the terminal. Style is one of the constants NormCursor, BigCursor or HiddenCur- sor. Each one should, respectively, set the cursor to the normal underscore mode, make a block cursor or make the cursor invis- ible. FlushInputh : Procedure; This hook has a default effect of zeroing the keyboard buffer. If your program has any internal buffers or communica- tions buffer, you may wish to flush them when this hook is called. The Avatar flush input command calls this hook. TTYCharH : Function (ch:char): Boolean; This hook is called by the AvtTTY procedure with the charac- ter to be processed as a parameter. If the hook returns False, AvtTTY will not process the character. The default hook always returns a value of true. Major Changes From 1.17 ───────────────────────── You MUST call the InitUnit procedure found in the main PAvatar unit! I have made the main unit overlayable, meaning that it cannot have an initialization section. Use the SetTerminal() procedure to set the unit to emulate a different terminal. The old ANSI_Only and Level0_Simulation procedures are still available but are no longer supported, and may not exist in future versions. I would like to encourage you to use the TTYCharH hook to the fullest extent possible. It gives you access to the raw ASCII data with the control codes removed. You can easily pro- cess your own special control codes, make readable log files, and implement scroll back buffers with it. There is also a new hook, Cursorh, which should change the cursor shape as describe above. Starting with PAvatar 1.50 and above the small version of the unit has been discontinued. The main unit is now just as fast. Compiler defines can be used to eliminate features you don't want. 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 interpret- er. ANSI fallback should not be used with level 1 (but it will work); a remote program using level 1 codes should know how to switch between sleeping (ANSI) and awake (AVT/1) modes. The main thing you should be concerned about in communica- tions is flow control. AVT/1 has a way to get around interfer- ence with XON/XOFF flow control if the parser is in cooked mode, but if it's switched to raw mode, the results may be disastrous. As AVT/0+ is a raw only terminal, XON/XOFF must be disabled while it is active. Tips & Tricks ───────────────────────── If your program needs to execute a subprogram or shell to DOS there are some special precautions that you must take. You must call the Set_Sound_backg() procedure to restore the timer interrupt. You should also save the exitproc as Set_Sound_backg() only restores it to it's very first state. Here is some sample code for a DOS shell: SavedEP := ExitProc; Set_Sound_backg(False); SwapVectors; Exec(GetEnv('COMSPEC''),''); SwapVectors; Set_Sound_backg(True); ExitProc := SavedEP; Part V. History And Credits ────────────────────────────────────────────────────────────────── I thank Ping Hansen from the FidoNet Pascal echo and an un- known 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. Thanks to Bo Bendtsen (Author of Terminate) for writing the "ANSI" music routines. Last but not least, I thank my parents and girlfriend for understanding my love for computers. Release Sites ───────────────────────── The following is a list of BBS's where you can find the latest version of PAvatar as well as contacting me. (303)779-1634 The Vault, 300-9600, FidoNet: 1:104/332 (303)750-7136 Borealis WildCat, 1200-14.4k, RIME: ->BOREALIS (303)429-9205 Bohemia, 300-14.4k, (Unix: in home/users/gpsmith) Thanks goes to Mark Cook for uncovering most of the bugs hiding in the original versions of PAvatar. ────────────────────────────────────────────────────────────────── Send all questions, comments, problems, ideas, money, etc.. to: Gregory P. Smith 4422 Pali Way Boulder, CO 80301 USA FidoNet: 1:104/332.11 (To: Gregory P. Smith) RIME: ->BOREALIS (To: Gregory P Smith) UseNet/InterNet: smithgr@ucsu.Colorado.EDU also: gpsmith@bohemia.metronet.org CompuServe: Route to an InterNet address.