<<< jlib >>> Version 1.0 A set of Enhancements for AmigaBASIC Copyright (C) by john everett PeopleLINK ID JAE 321 Hodges Memphis, TN 38111 (901)-432-2560 =============================================================================== These commands are an alternative to the BMAPs for accessing the library routines on the Amiga. Most do more than just access the normal library routine, they do the work of some small subprograms. This saves programming time and program space. Following you will find instructions for setting up these routines, and short descriptions of each. =============================================================================== The first thing you must do is declare all of the function names as variables: at&=0:text&=0:printat&=0:shadow&=0:sxy&=0:scolr&=0:sbox&=0:dbox&=0 drawmode&=0:title&=0:loadfont&=0:usefont&=0:killfont&=0:style&=0 refresh&=0:iffload&=0:iffsave&=0:loadRGB&=0:saveRGB&=0:request&=0 checkfile&=0:bload&=0:bsave&=0:bopenr&=0:bopenw&=0:bread&=0:bwrite&=0 seek&=0:bclose&=0:getmem&=0:freemem&=0:zero&=0:copy&=0:w7&=0:bye&=0 These variables may be renamed to anything you like, but they MUST be declared together in one group, with the `&', and in the correct order. You must not insert any other variables in between them. Next, you DIM an array to hold the loader program, load it in, and call it. You may ERASE the array afterwards, as it will no longer be needed. mlsize=200 mlsize=mlsize/2-1 DIM ml(mlsize) OPEN "ml_loader" FOR INPUT AS #1 FOR i=0 TO mlsize:ml(i)=CVI(INPUT$(2,1)):NEXT CLOSE #1 ml&=VARPTR(ml(0)):ml& SADD("jlib"+nl$),VARPTR(at&),WINDOW(7) ERASE ml This short routine reserves some non-relocatable memory, then loads the main routine, and tells it to initialize itself and the variables to the proper addresses. It then returns control to BASIC. This entire process takes only a couple of seconds, very little of your BASIC program space, and gives you a LOT of power to dress up and speed up your programs. =============================================================================== NOTES ON COMMAND DESCRIPTIONS: All of the following commands may be called using the syntax given, or with the alternate form using the CALL keyword. ex. CALL at&(x,y) This syntax MUST be used when calling after the keywords THEN or ELSE, or when used at the beginning of a line where they might be confused as labels. In all instances where you see `SADD(msg$)', msg$ must be a NULL terminated string. You may accomplish this in any of a number of ways, including (using text& as an example): NULL$=CHR$(0) - (declared at beginning of program) text& SADD("Hello World!"+NULL$) text& SADD("Hello World!"+CHR$(0)) msg$="Hello World!":text& SADD(msg$+NULL$) msg$="Hello World!"+NULL$:text& SADD(msg$) or any of many other possible combinations. You could also use a SUB program to place the NULL$ for you: txt something$ (or `txt "Hello World!"' etc.) SUB txt(msg$) STATIC SHARED text& text& msg$+CHR$(0) END SUB ===================================================================== COMMAND: at& USAGE: at& x,y This command positions the current text (or drawing) position using the library function Move&. This is similar to LOCATE, but places the position to a particular pixel position. COMMAND: text& USAGE: text& SADD(msg$) This command writes text to the screen using the library function Text&. This is MUCH faster than the basic PRINT command, and displays italics properly, while PRINT doesn't. msg$ must be a null terminated string COMMAND: printat& USAGE: printat& x,y,SADD(msg$) This command combines at& and text& into one command. This saves execution time (every time you return to basic, basic must interpret at least one command, which slows your program down). It also makes thing a bit easier, since you will almost always need to use both commands together. Compensation is made for the baseline of whatever font is being used so that the x,y position denotes the top left corner of the text. This command will also automatically center text in the drawing area of a window if x is a negative number (this may make it appear to be a little off to the left if your window has a sizing gadget). COMMAND: shadow& USAGE: shadow& x,y,SADD(msg$) This command prints text with a shadow behind it. All the features of printat& are also included in this command. This routine should prove even faster than using the BMAPs and libraries, as basic must compute length, shadow position, etc., requiring several return to basic and lost execution time. COMMAND: sxy& USAGE: sxy& x,y This command sets the relative position of the shadow for the shadow command. Default settings are 5,2. COMMAND: scolr& USAGE: scolr& foreground,shadowcolor This command sets the colors to be used for shadow printing. Default settings are 1,2. COMMAND: sbox& USAGE: sbox& x,y,border,SADD(msg$) This command prints shadow text inside a box. This could be used for gadget- type thingies. x and y are the top left coordinates and border is the color used to draw the box outline. The inside of the box is the current background color (set with the normal COLOR fg,bg command). The text is printed with the current shadow colors. If x is negative the box will be centered. Box size will self-adjust for different fonts. COMMAND: dbox& USAGE: dbox& x,y,fg,bg,SADD(msg$) This command is similar to sbox& above, except it draws a double box around the text, and does not use a shadow. The text is printed with the current shadow colors. If x is negative the box will be centered. Box size will self-adjust for different fonts. COMMAND: drawmode& USAGE: drawmode& mode This command sets the drawmode. JAM1=0:JAM2=1:complement=2:inversevideo=3 COMMAND: title& USAGE: title& SADD(msg$) This command sets both the window and screen titles to the given text. COMMAND: loadfont& USAGE: loadfont& SADD(fontname+NULL$),size,VARPTR(pointer&) This command loads a font into memory. Fontname is a valid font (such as `topaz'), size is the fontheight, and pointer& is a pointer to be used for calling setfont& and killfont&. It is recommended you use descriptive names such as `topaz8&'. These pointers must be declared (topaz8&=0) before being used in the command, or you will get an error. It is also recommended that you load all the fonts you will be using at the beginning of your program so that program execution will not be interupted by the font loading process. COMMAND: usefont& USAGE: usefont& pointer& This command changes the current font. Fonts must have been previously loaded using loadfont& (this includes the default topaz8 font if you wish to return to it after using another font). COMMAND: killfont& USAGE: killfont& pointer& This command removes a font when you are done using it. Don't forget to call this command before exiting your program, or the memory will not be released to the system until a re-boot. COMMAND: style& USAGE: style& style This command sets the current text style. normal=0:underline=1:bold=2:italics=4 These may be added together to combine styles. COMMAND: refresh& USAGE: refresh& This command will refresh the window frame. You might want to call this after loading a picture file that destroys the window frame. COMMAND: iffload& USAGE: iffload& SADD(file$+NULL$) This command will load an IFF picture file. The iff.library (by Christian A. Weber, of Zurich, Switzerland - Thanks Christian!) must be present in the LIBS: directory for this command to work. COMMAND: iffsave& USAGE: iffsave& SADD(file$+NULL$) This command will save an IFF picture file. The iff.library (by Christian A. Weber, of Zurich, Switzerland - Thanks Christian!) must be present in the LIBS: directory for this command to work. COMMAND: loadRGB& USAGE: loadRGB& VARPTR(RGBarray(0)),number This command loads a colortable into memory. RGBarray() is a colortable which is probably best set up by using the normal PALETTE command to set your colors, then saving with saveRGB&. You could then bload& this file into an array, and loadRGB& it into memory. You could then delete the PALETTE statements from your program and save some space and execution time. By keeping a set of standard RGB files handy you could save a lot of programming time. This command could also make some color cycling routines very easy (using several RGBarrays). Number is the number of colors in the array. It does not seem to hurt anything to load all 32 colors even if you don't have that many bitplanes (you won't be able to use the extra colors, however). COMMAND: saveRGB& USAGE: saveRGB& SADD(file$+NULL$),number This command will save a colortable to disk. COMMAND: request& USAGE: request& x,y,SADD(greet$+nl$),SADD(file$),colr This command will call the ARP file requester. x and y are the coordinates of the top left corner of the requester. The requester is 320 by 128 pixels, so make sure there is room for it or the function will fail. On a 320 pixel wide screen this means x must be set to 0! greet$ is the text that will be displayed on the titlebar (32 character maximum). file$ must be set up as a sufficiently long string to accomodate the returning path/filename. 360 characters is recommended. file$ may also specify a default directory going in to the function. I recommend a line something like: file$=directory$+STRING$(360,0) before the request command. This will provide a sufficiently long string and NULL terminate the directory$. If directory$="" or if it is left out altogether, the default directory will be the current directory. colr may be set to 0 for default requester background color, or anything else for the alternate color. Convention calls for the second color to be used for saves and the default for loads. COMMAND: checkfile& USAGE: checkfile& SADD(file$+NULL$),VARPTR(flag&) This command will check to see if a file or directory exists on a disk. flag& must be declared (flag&=0) before calling this routine, and will return -1 if file$ is a directory, the file size if it exists as a file, or 0 if not found. COMMAND: bload& USAGE: bload& SADD(file$+NULL$),address,size A VERY useful routine for speeding up loading of large arrays, etc. `address' is the starting address where you will be loading the data [ex. SADD(msg$) or VARPTR(array(0)) ]. `size' is the size (in bytes) of the data you will be loading. COMMAND: bsave& USAGE: bsave& SADD(file$+NULL$),address,size This command is the same as bload&, only the data direction has been changed (to protect the innocent?). It saves instead of loads the data. I must note here that you will probably need to set up these arrays in a normal fashion during program development, then bsave them. You can then bload them the next time you run the program and save a lot of time setting up or loading data. After you have the arrays set as you need them you can DELETE the original lines you set up the arrays with, and save program space too. COMMAND: bopenr& USAGE: bopenr& SADD(file$+NULL$) This will open a previously existing file (the `r' is for read, but you could write to it also). Only one file may currently be open at a time. COMMAND: bopenw& USAGE: bopenw& SADD(file$+NULL$) This will open a new file and erase any previously existing file by the same name (the `w' is for write, but you could read from it also). Only one file may currently be open at a time. COMMAND: bread& USAGE: bread& address,size This command reads from a previously opened file. address and size are the same as in bload& above. COMMAND: bwrite& USAGE: bwrite& address,size This command reads from a previously opened file. address and size are the same as in bload& above. COMMAND: seek& USAGE: seek& distance,mode This command sets the file pointer in the disk file. distance is the number of bytes to move the pointer. If mode is -1 then distance will be relative to the beginning of the file, 0 would make it relative to the current position, and 1 makes it relative to the end of the file. COMMAND: bclose& USAGE: bclose& This command will close a command previously opened with bopen&. COMMAND: getmem& USAGE: getmem& VARPTR(buffer&),amount,type This command allocates system memory. amount is the number of bytes needed, and type is 0 for any available, 1 for non-relocatable, 2 for chip, 4 for fast, and 65536 if you want it cleared. You may add values together. buffer& will be the address of your memory, or 0 if unsuccessful. buffer& must have been previously declared (buffer&=0). COMMAND: freemem& USAGE: freemem& buffer& This command releases the memory previosly allocated at buffer&. COMMAND: zero& USAGE: zero& address,size This command will write zeroes to the specified memory. It is useful for clearing large arrays. Using a basic loop is WAY too slow, and ERASEing and reDIMming the array can even be slow if you have a lot of other arrays, etc. This will do the job in much less time. size is size in words (2 bytes). COMMAND: copy& USAGE: copy& source,destination,size This command uses copies data from one place to another. Size is in words. This may only be useful in a few limited situations, but it has come in handy a few times for me. COMMAND: window7& USAGE: window7& WINDOW(7) This command must be called if you open a new window and want any graphics related routines to go to that window. The WINDOW or WINDOW OUTPUT command has no effect these commands, so you must use w7&. COMMAND: bye& USAGE: bye& This command should be called before exiting your program! It will release the memory it has commandeered and reset the command variable names to zero (to prevent the GURU from visiting if you try to use one after there is no code there to execute). If you do not call this routine before you are done the memory will not be released until you re-boot your machine. If you were to keep re-running your program this way, it would hopelessly fragment your memory.