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 -...
y4r05l4v