💾 Archived View for mirrors.apple2.org.za › archive › ground.icaen.uiowa.edu › upl1998 › Nov98 › VER… captured on 2024-12-18 at 01:57:38.
-=-=-=-=-=-=-
C O=====<====<====<====<====<====<====<====<====<====<====<====<====<====<====<=== @ O=====<====<====<====<====<====<====<====<====<====<====<====<====<====<====<=== ����� � � � � �1 �VersiBox Version 1.3 Documentation Revision 19 �-------------------------------------------------------( �By Michael J. Chinn - 28 July 1993$ �Software And Related Documentation$ �Copyright 1993 by Michael J. Chinn �Apple II Forever! � � �What Is VersiBox? �--------------------------- �I GVersiBox is a short (767 bytes) Applesoft BASIC programmer's utility N Ldesigned to make creating a text screen user interface simpler and faster. O MIt creates several different interface elements, including windows, buttons, H Fhorizontal and vertical lines (like those found in the IIe version of N LShrinkIt, A2FX, and others), and allows easier use of the MouseText and I Ginverse character sets. VersiBox is designed to be used as a set of I Gampersand (&) routines from Applesoft BASIC. The routines can also be P Naccessed from assembly or machine language with a copy of the source code and G Ea little programming skill. (See ...And That's About It below for ; �information on obtaining the source code for VersiBox.) �L JVersiBox runs on an enhanced Apple IIe with MouseText capability, Apple I GIIc, Apple IIgs, or compatible computer. (And, yes, a Mac LC with the % �infamous Apple IIe emulation card.) � � � �Installing VersiBox �----------------------------- �N LVersiBox is designed to nestle between the text screen and your Applesoft N Lprogram. But before you can stuff it in there, you must make a little room I Gfor it. To do so, include the following line at the beginning of your M Kprogram (or load the VersiBox.Shell program from the VersiBox disk and �write your code around it): �E CIF PEEK (104) < > 11 THEN POKE 104,11: POKE 2816,0: PRINT CHR$( 4) �"-YOUR.PROGRAM" �L JThis will reset the Applesoft start of program pointer to 2816 ($0B00) to P Nfool BASIC into thinking this is where the program belongs, put a zero at the M Knew program location, and reload your BASIC program higher in memory. The 1 �next step is to execute the VersiBox routine: � �PRINT CHR$(4)"-VERSIBOX1.3" �K IThis little line loads and executes VersiBox (the hyphen is the ProDOS M Ksmart run command; it will load and attempt to run any runable filetype). L JVersiBox loads itself into the area Line 100 cleared for it between the P Ntext screen and the Applesoft program. VersiBox first checks to be sure it L Jis running on a computer with MouseText capability. If it isn't an error O Mmessage is printed and program execution halts. If VersiBox is running on K Ian enhanced IIe or better, it then examines the ampersand (&) vector and M Kchecks to see if another ampersand routine has already been installed. If P None has, an internal pointer is set to that routine. If VersiBox is unable M Kto understand an ampersand command, it passes the command on to the linked N Lroutine. (If there is no linked routine, an error message is printed or an M Kerror trap is set off.) VersiBox then installs its own pointer, sets up M Kthe 80-column card if it hasn't been initialized already, prints the title K Imessage if VersiBox is running from immediate mode, and returns you to : �BASIC. The VersiBox commands are now at your disposal. � � � #�Tip #1 �---------------- �P NWhen VersiBox installs itself in the newly-freed memory, it leaves behind a N Lbit of garbage -- the title message and initialization routine as well as 1 P Nbyte of unused memory (It's a tight fit!). This garbage is no longer needed M Kby VersiBox and makes a convenient location for a short machine language I Groutine. (I use it for an input-anything routine.) The free space is P Nlocated from address 2736 to 2815 ($0AB0-$0AFF). Remember, this is a version O Mspecific address and the space may not be there at all in version 1.4. Also O Mnote that the routine must be added after VersiBox is installed or it will �be clobbered rather badly. � � � �Using VersiBox �------------------------ �O MVersiBox's commands are easy to use. Each of the commands listed below is G Eaccessed by typing an ampersand (&), a code letter, and the required N Lparameters of the command. The VersiBox routine intercepts the necessary G �information and draws the element or performs the necessary function. �O MFor 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) � �N LThis command creates a VersiBox -- an outlined box with an inverse banner K Iat the top. The Horizontal and Vertical Position parameters are for the J Hupper left inside corner of the box (NOT the left corner of the inverse O Mbanner). The Width and Depth parameters are for the inside dimensions of the L �box. Thus, a full screen box would be created with the following command: � �110 &V,2,2,78,22 �N LOnce the box is drawn, VersiBox sets the text window to the inside of the B �box and clears the new window giving your program a clean slate. � � � #�Tip #2 �---------------- �M KIf you do not want the text window cleared (if you're drawing a box around G Esomething, for example), the following POKES will disable the window �clearing: �2 �POKE 2519, 234: POKE 2520, 234: POKE 2521, 234 �, �To restore the HOMEing, use these POKES: �/ �POKE 2519, 32: POKE 2520, 127: POKE 2521, 8 �P NNote 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) � �H FThis command creates a button with its left-most inside corner at the N Lposition specified by the Horizontal and Vertical Position parameters. Its L Jwidth is that of the Width parameter. The text screen parameters are not N Lreset, but the cursor is placed at the position specified by the Horizontal F �and 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) � �N LThe Text Window command resets the text screen margins easily. This allows L Jyou to type to only one part of the screen, leaving the rest intact. This P Ncommand is used internally by VersiBox to allow printing only to the inside J Hof VersiBoxes. One adverse affect of setting the text window is that N LVersiBox clears the window with a HOME after resetting the margins. This N Lis necessary for the Apple II video firmware to reset its internal pointers O Mproperly. Meaning: Don't reset the window if you want to keep what's inside �it. �F �To return the text margins to the full screen, use the TEXT command. �I GOne warning about resetting the text margins: DO NOT print outside the P Ncurrent text screen margins. It can create very interesting displays, but it P Nis VERY dangerous to the program in memory. (If you are unsure of the values * �of your commands, save your work first!) � � � #�Tip #3 �---------------- �M KTo leave a parameter of the current window the same in a new window, enter L Jzeros in the window call. For example, if the current window was defined P Nwith the call &W,5,5,10,5 and you want to create a window that is two columns M Klarger, 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) � �N LVersiBoxes are wonderful display elements, but they require numerous HTAB M Kand VTAB changes to print text inside them. The position command helps to M �reduce the amount of HTAB and VTAB typing needed to create a large project. �G ETo move the cursor, simply use the position command with the correct M Khorizontal and vertical values. You can also use variable expressions, or 4 �even Booleans (ie "A + B - 6" or "( A = 1 ) * 6"). � � � #�Tip #4 �---------------- �P NThe position command also allows for positioning of the cursor on the current N Lline 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.......................... � �P NThe horizontal line command (The A -- for across -- is only used because V -- M Kfor vertical -- was already used.) is used to create lines of characters. L JThe horizontal and vertical positions are for the beginning of the line. P NNote that the character can only be a literal -- no variables. No quotes are P Nneeded and any printable character can be used. To print a line of MouseText K Icharacters, simply turn on MouseText with the &M command and draw a line O Musing the appropriate MouseText letter. Example: &M: &A,1,1,80,S: &N will 6 �draw 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.......................... � �N LLike its horizontal counterpart, the vertical line command creates vertical G Elines. Again, the character can only be a literal and any printable �character can be used. � � � �Inverse Text: &I �--------------------------- �N LThis command turns on inverse text printing. It has the same effect as the L JApplesoft BASIC command INVERSE and is included to make entering numerous �INVERSE commands easier. � � � �MouseText: &M �------------------------ �M KThis command turns on MouseText printing. MouseText is a auxiliary set of H Fcharacters that Apple included in the ROMs of its newer computers (If P NVersiBox works on your computer, you have MouseText). These characters are N Ldesigned to allow programs to create more sophisticated interfaces. Please J �refer 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... �--------------------- �M KThe skip command allows the use of linked ampersand routines that have the L Jsame command letters as VersiBox routines. For example, if you have an K Iadditional 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. �O M2) Install VersiBox. VersiBox must be installed last as it contains the �chaining routine.@ �3) Call the position routine by using the skip command: &XP... �O MThe skip command moves to the beginning of the other call and then calls the P Nlinked ampersand routine. The skip command need not be used when the routine L Jyou wish to call in the linked routine does not have the same handle as a N LVersiBox routine; VersiBox automatically jumps to the linked routine if ! �it cannot understand a command. � � �! �A Note to Forty Column Users...+ �----------------------------------------- �N LDon't feel left out. VersiBox also works wonderfully on the forty column P Nscreen. The only requirement is that you have an enhanced IIe or better (see N LTip #1). To switch to forty columns, simple use the following line: 210 M KPRINT CHR$(17) To return to eighty columns, use the following: 220 PRINT �CHR$(18) �N LNote that these are the only safe methods of switching back and forth while P NVersiBox is installed. Other methods disconnect the 80-column firmware and �thus disconnect VersiBox. � � � �A Few Simple Warnings...$ �---------------------------------- �J HMy goal in writing VersiBox was to create the smallest, fastest, most N Luseful routine for drawing boxes. In doing so, however, some things had to K Ibe sacrificed -- namely error checking. The VersiBox routine does not J Hcheck for invalid width, height, HTAB, or VTAB values. It is up to the G Eprogrammer to ensure that these values are within the legal limits. M KIrreversible damage can be done to programs and/or data in memory if these I Glimits are not followed. Be sure to save your work before running any % �program to protect your investment. �O MAs with all machine language programs, VersiBox's internal components move O Mfrom version to version. Therefore, it is important that the patches listed M Kin this document be used only on version 1.3 of VersiBox. Unpredictable G �results will occur if the patches are used on the incorrect version. � � � � �...The Customary Disclaimer...* �---------------------------------------- �H FThis software, as with all current software, is fit for no particular P Npurpose. I, Michael J. Chinn, make no warranty, either expressed or implied, O Mabout the function of this product. If it doesn't work for your purpose, my O Mliability is limited to the product's purchase price, which should have been L Jnothing. Some states tend to disagree, and if you live in one that does, �please disregard this notice. � � � �... And That's About It!$ �---------------------------------- �N LFeel free to include VersiBox in any of your works. The only requirement O �is that, somewhere in your program, you should include the following message: � �VersiBox V1.3 �By Michael J. Chinn$ �Copyright 1993 by Michael J. Chinn �N LVersiBox is freeware. Please distribute it as widely as possible, but do O Mnot sell it for more than the reasonable cost of the media and time required M Kto dupe it. Please feel free to upload VersiBox to any and all BBSs and P Non-line services. The only requirements for distribution are that the entire H FVersiBox archive be transmitted and that no part of that archive be �changed, deleted, or added to. �P NIf you like VersiBox and find it useful I would appreciate any donation you M Kcan offer. While VersiBox is not shareware, it does take time to create M Ksuch a work and compensation is always appreciated. Send any donations to P Nthe address listed above. Source code is available with a donation of $10 or �more. Thank you. �N LI am also interested is seeing what you've done with VersiBox. Send your F Dcompleted programs to the address above. All programs will be kept �completely confidential. �J HFor more information on how VersiBox works, or for information on the M Klatest version, write to the author at the address listed above. Comments H Fand suggestion are always welcome. If you would like a reply, send a M Kself-addressed, stamped envelope. If you would like a copy of the current L Jversion, send a disk and a disk mailer with enough postage to get back to �you.��