CO=====<====<====<====<====<====<====<====<====<====<====<====<====<====<====<===@O=====<====<====<====<====<====<====<====<====<====<====<====<====<====<====<===1VersiBox Version 1.3 Documentation Revision 19 -------------------------------------------------------(By Michael J. Chinn - 28 July 1993$Software And Related Documentation$Copyright 1993 by Michael J. ChinnApple II Forever!What Is VersiBox?---------------------------IGVersiBox is a short (767 bytes) Applesoft BASIC programmer's utility NLdesigned to make creating a text screen user interface simpler and faster. OMIt creates several different interface elements, including windows, buttons, HFhorizontal and vertical lines (like those found in the IIe version of NLShrinkIt, A2FX, and others), and allows easier use of the MouseText and IGinverse character sets. VersiBox is designed to be used as a set of IGampersand (&) routines from Applesoft BASIC. The routines can also be PNaccessed from assembly or machine language with a copy of the source code and GEa little programming skill. (See ...And That's About It below for ;information on obtaining the source code for VersiBox.)LJVersiBox runs on an enhanced Apple IIe with MouseText capability, Apple IGIIc, Apple IIgs, or compatible computer. (And, yes, a Mac LC with the %infamous Apple IIe emulation card.)Installing VersiBox-----------------------------NLVersiBox is designed to nestle between the text screen and your Applesoft NLprogram. But before you can stuff it in there, you must make a little room IGfor it. To do so, include the following line at the beginning of your MKprogram (or load the VersiBox.Shell program from the VersiBox disk and write your code around it):ECIF PEEK (104) < > 11 THEN POKE 104,11: POKE 2816,0: PRINT CHR$( 4) "-YOUR.PROGRAM"LJThis will reset the Applesoft start of program pointer to 2816 ($0B00) to PNfool BASIC into thinking this is where the program belongs, put a zero at the MKnew program location, and reload your BASIC program higher in memory. The 1next step is to execute the VersiBox routine:PRINT CHR$(4)"-VERSIBOX1.3"KIThis little line loads and executes VersiBox (the hyphen is the ProDOS MKsmart run command; it will load and attempt to run any runable filetype). LJVersiBox loads itself into the area Line 100 cleared for it between the PNtext screen and the Applesoft program. VersiBox first checks to be sure it LJis running on a computer with MouseText capability. If it isn't an error OMmessage is printed and program execution halts. If VersiBox is running on KIan enhanced IIe or better, it then examines the ampersand (&) vector and MKchecks to see if another ampersand routine has already been installed. If PNone has, an internal pointer is set to that routine. If VersiBox is unable MKto understand an ampersand command, it passes the command on to the linked NLroutine. (If there is no linked routine, an error message is printed or an MKerror trap is set off.) VersiBox then installs its own pointer, sets up MKthe 80-column card if it hasn't been initialized already, prints the title KImessage if VersiBox is running from immediate mode, and returns you to :BASIC. The VersiBox commands are now at your disposal.#Tip #1----------------PNWhen VersiBox installs itself in the newly-freed memory, it leaves behind a NLbit of garbage -- the title message and initialization routine as well as 1 PNbyte of unused memory (It's a tight fit!). This garbage is no longer needed MKby VersiBox and makes a convenient location for a short machine language IGroutine. (I use it for an input-anything routine.) The free space is PNlocated from address 2736 to 2815 ($0AB0-$0AFF). Remember, this is a version OMspecific address and the space may not be there at all in version 1.4. Also OMnote that the routine must be added after VersiBox is installed or it will be clobbered rather badly. Using VersiBox------------------------OMVersiBox's commands are easy to use. Each of the commands listed below is GEaccessed by typing an ampersand (&), a code letter, and the required NLparameters of the command. The VersiBox routine intercepts the necessary Ginformation and draws the element or performs the necessary function.OMFor specific examples of how to use VersiBox commands, please refer to the demo program.VersiBox: &V,h,v,w,d/---------------------------------------------)h - Horizontal Position..........(2-78))v - Vertical Position............(2-22))w - Width........................(1-78))d - Depth........................(1-22)NLThis command creates a VersiBox -- an outlined box with an inverse banner KIat the top. The Horizontal and Vertical Position parameters are for the JHupper left inside corner of the box (NOT the left corner of the inverse OMbanner). The Width and Depth parameters are for the inside dimensions of the Lbox. Thus, a full screen box would be created with the following command:110 &V,2,2,78,22NLOnce the box is drawn, VersiBox sets the text window to the inside of the Bbox and clears the new window giving your program a clean slate.#Tip #2----------------MKIf you do not want the text window cleared (if you're drawing a box around GEsomething, for example), the following POKES will disable the window clearing:2POKE 2519, 234: POKE 2520, 234: POKE 2521, 234 ,To restore the HOMEing, use these POKES: /POKE 2519, 32: POKE 2520, 127: POKE 2521, 8 PNNote that this also stops the text window from being set to the inside of the "VersiBox, so use with caution.Button: &B,h,v,w/---------------------------------------------)h - Horizontal Position..........(2-78))v - Vertical Position............(2-22))w - Width........................(1-78)HFThis command creates a button with its left-most inside corner at the NLposition specified by the Horizontal and Vertical Position parameters. Its LJwidth is that of the Width parameter. The text screen parameters are not NLreset, but the cursor is placed at the position specified by the Horizontal Fand Vertical Position parameters to make filling in the button easy.Text Window: &W,h,v,w,d/---------------------------------------------)h - Horizontal Position..........(2-78))v - Vertical Position............(2-22))w - Width........................(1-78))d - Depth........................(1-22)NLThe Text Window command resets the text screen margins easily. This allows LJyou to type to only one part of the screen, leaving the rest intact. This PNcommand is used internally by VersiBox to allow printing only to the inside JHof VersiBoxes. One adverse affect of setting the text window is that NLVersiBox clears the window with a HOME after resetting the margins. This NLis necessary for the Apple II video firmware to reset its internal pointers OMproperly. Meaning: Don't reset the window if you want to keep what's inside it.FTo return the text margins to the full screen, use the TEXT command.IGOne warning about resetting the text margins: DO NOT print outside the PNcurrent text screen margins. It can create very interesting displays, but it PNis VERY dangerous to the program in memory. (If you are unsure of the values *of your commands, save your work first!)#Tip #3----------------MKTo leave a parameter of the current window the same in a new window, enter LJzeros in the window call. For example, if the current window was defined PNwith the call &W,5,5,10,5 and you want to create a window that is two columns MKlarger, simply use the call &W,0,0,12,0. VersiBox will take care of the +math and your new window will be created.Position Cursor: &P,h,v/---------------------------------------------)h - Horizontal Position..........(1-80))v - Vertical Position............(1-24)NLVersiBoxes are wonderful display elements, but they require numerous HTAB MKand VTAB changes to print text inside them. The position command helps to Mreduce the amount of HTAB and VTAB typing needed to create a large project.GETo move the cursor, simply use the position command with the correct MKhorizontal and vertical values. You can also use variable expressions, or 4even Booleans (ie "A + B - 6" or "( A = 1 ) * 6").#Tip #4----------------PNThe position command also allows for positioning of the cursor on the current NLline or in the current column. To do so, simply enter a zero for the value )you want to remain the same, like so: 0&P,1,12: PRINT NAME$;: &P,40,0: PRINT ADDRESS$Horizontal Line: &A,h,v,l,c/---------------------------------------------)h - Horizontal Position..........(1-80))v - Vertical Position............(1-24))l - Length.......................(1-80))c - Character..........................PNThe horizontal line command (The A -- for across -- is only used because V -- MKfor vertical -- was already used.) is used to create lines of characters. LJThe horizontal and vertical positions are for the beginning of the line. PNNote that the character can only be a literal -- no variables. No quotes are PNneeded and any printable character can be used. To print a line of MouseText KIcharacters, simply turn on MouseText with the &M command and draw a line OMusing the appropriate MouseText letter. Example: &M: &A,1,1,80,S: &N will 6draw a solid line across the top line of the screen.Vertical Line: &D,h,v,l,c/---------------------------------------------)h - Horizontal Position..........(2-78))v - Vertical Position............(2-22))l - Length.......................(1-80))c - Character..........................NLLike its horizontal counterpart, the vertical line command creates vertical GElines. Again, the character can only be a literal and any printable character can be used.Inverse Text: &I---------------------------NLThis command turns on inverse text printing. It has the same effect as the LJApplesoft BASIC command INVERSE and is included to make entering numerous INVERSE commands easier.MouseText: &M------------------------MKThis command turns on MouseText printing. MouseText is a auxiliary set of HFcharacters that Apple included in the ROMs of its newer computers (If PNVersiBox works on your computer, you have MouseText). These characters are NLdesigned to allow programs to create more sophisticated interfaces. Please Jrefer to the demo program for a listing of all the MouseText characters.Normal Text: &N--------------------------/&N turns off both inverse and MouseText text. !Skip: &X...---------------------MKThe skip command allows the use of linked ampersand routines that have the LJsame command letters as VersiBox routines. For example, if you have an KIadditional position command that uses the &P handle you can still use it withVersiBox.'To do so, follow the following steps:;1) Install the other ampersand routine in the normal way.OM2) Install VersiBox. VersiBox must be installed last as it contains the chaining routine.@3) Call the position routine by using the skip command: &XP...OMThe skip command moves to the beginning of the other call and then calls the PNlinked ampersand routine. The skip command need not be used when the routine LJyou wish to call in the linked routine does not have the same handle as a NLVersiBox routine; VersiBox automatically jumps to the linked routine if !it cannot understand a command.!A Note to Forty Column Users...+-----------------------------------------NLDon't feel left out. VersiBox also works wonderfully on the forty column PNscreen. The only requirement is that you have an enhanced IIe or better (see NLTip #1). To switch to forty columns, simple use the following line: 210 MKPRINT CHR$(17) To return to eighty columns, use the following: 220 PRINT CHR$(18)NLNote that these are the only safe methods of switching back and forth while PNVersiBox is installed. Other methods disconnect the 80-column firmware and thus disconnect VersiBox.A Few Simple Warnings...$----------------------------------JHMy goal in writing VersiBox was to create the smallest, fastest, most NLuseful routine for drawing boxes. In doing so, however, some things had to KIbe sacrificed -- namely error checking. The VersiBox routine does not JHcheck for invalid width, height, HTAB, or VTAB values. It is up to the GEprogrammer to ensure that these values are within the legal limits. MKIrreversible damage can be done to programs and/or data in memory if these IGlimits are not followed. Be sure to save your work before running any %program to protect your investment.OMAs with all machine language programs, VersiBox's internal components move OMfrom version to version. Therefore, it is important that the patches listed MKin this document be used only on version 1.3 of VersiBox. Unpredictable Gresults will occur if the patches are used on the incorrect version. ...The Customary Disclaimer...*----------------------------------------HFThis software, as with all current software, is fit for no particular PNpurpose. I, Michael J. Chinn, make no warranty, either expressed or implied, OMabout the function of this product. If it doesn't work for your purpose, my OMliability is limited to the product's purchase price, which should have been LJnothing. Some states tend to disagree, and if you live in one that does, please disregard this notice.... And That's About It!$----------------------------------NLFeel free to include VersiBox in any of your works. The only requirement Ois that, somewhere in your program, you should include the following message:VersiBox V1.3By Michael J. Chinn$Copyright 1993 by Michael J. ChinnNLVersiBox is freeware. Please distribute it as widely as possible, but do OMnot sell it for more than the reasonable cost of the media and time required MKto dupe it. Please feel free to upload VersiBox to any and all BBSs and PNon-line services. The only requirements for distribution are that the entire HFVersiBox archive be transmitted and that no part of that archive be changed, deleted, or added to.PNIf you like VersiBox and find it useful I would appreciate any donation you MKcan offer. While VersiBox is not shareware, it does take time to create MKsuch a work and compensation is always appreciated. Send any donations to PNthe address listed above. Source code is available with a donation of $10 or more. Thank you.NLI am also interested is seeing what you've done with VersiBox. Send your FDcompleted programs to the address above. All programs will be kept completely confidential.JHFor more information on how VersiBox works, or for information on the MKlatest version, write to the author at the address listed above. Comments HFand suggestion are always welcome. If you would like a reply, send a MKself-addressed, stamped envelope. If you would like a copy of the current LJversion, send a disk and a disk mailer with enough postage to get back to you.