A.C.E. 1

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

/ A.C.E. 1 / ACE CD 1.iso / files / docs / blitzbad.lha / BlitzBasic2V1.3Part3.doc < prev next >

Wrap

Text File | 1994-12-14 | 126.3 KB | 3,464 lines

Part Three Statement: PrtText -------------------------------------------------------------------------- Syntax: PrtText <STRING> Mode : AMIGA Description: PrtText: Prints the text 'STRING' at your printer... It' s the same like WriteFile(0,"PRT:"), but why have the AMIGA a own printer.device... So I think we should use it, right? Statement: Hardcopy -------------------------------------------------------------------------- Syntax: Hardcopy ScreenPointer,X,Y,Width,Height,PrtWidth,PrtHeight,Flags Mode : AMIGA Description: Prints the screen or a part of it at your printer. ScreenPointer: Adress of the screen (Addr Screen(x)) X............: \ Are the corners of the screen where we Y............: / want to start printing it to paper... Width........: Width of the screen part you want to print Height.......: Height of the screen part you want to print PrtWidth.....: Width of the print(on the paper) PrtHeight....: Height of the print(on the paper) Flags........: Printerflags... Have a look to a documantation aout it, the most importent(?) ones: $40 - Centre graphic $10 - Weidth= Maximum $20 - Height = Maximum $100,$200,$300,$400 - Printing quality($400 = Heighest) Bugs: Hm, it seems that the flags are not 100% taken...I haven' t find out why, but might be you do...I still working on it! But however, it works.. BTW: This library is copyright 1992/93 by Andre Bergmann. Use it on your own risk, I don' t take the responsibility for using it! This source is PD, feel free to update it! Please send me updates done by you and Bug Reports! Andre Bergmann Am Pannesbusch 39a 42281 Wuppertal 2 Germany Tel: 0049/0202/702606 CONSOLE LIBRARY -------------------------------------------------------------------------- ConsoleLib (a little buggy yet): OPENCONSOLE PRINTCON NPRINTCON CLOSECONSOLE Command: OpenConsole -------------------------------------------------------------------------- Syntax : OpenConsole Window#,Console# Description: Open a CON: Port for the window, so ANSI output is possible. Command: PrintCon -------------------------------------------------------------------------- Syntax: PrintCon Console#,Expression Description: Write text to window-console. Command: NprintCon -------------------------------------------------------------------------- Syntax: NPrintCon Console#,Expression Description: Write text to window-console, and add a Linefeed. Command: CloseConsole -------------------------------------------------------------------------- Syntax: CloseConsole Console# Description: Close the CON: Port, but NOT the window itself! Note: These command work if you use them only for ONE window...If you wanna use the CON's for more windows, so that object are use it doesn' t work anymore... Ya see, I need ya help, please... CRUNCH LIBRARY Available Commands: IMPLODE DEPLODE CRMDECRUNCH PPDECRUNCH Function: Implode -------------------------------------------------------------------------- Syntax: Implode Error/CrunchedLen=Bufferadr,DataLen,?Callback Description: Crunch a buffer using the Imploder algorythm. The ?Callback could be a 0 for no own routine or a pointer to an own routine for display or abort checking. If the Imploder command jump to the callback in register d0 the current crunch position is presend. The callback itself have to return True for cont crunching or False for a break! The command return the crunched buffer len or of course a break or an error. If a <0 is returned the callback returned a userbreak, a return of 0 means an error happens. Else the new buffer len is returned. Function: Deplode -------------------------------------------------------------------------- Syntax: Deplode Success=Startadr Description: Decrunch a Imploder-Crunched buffer. There is no need to give the crunched buffer len to the command, imploder handle this by itself. But be careful, if the alloceted buffer hasn' t enought space the program crash. The buffer has to have a header like this: Type Offset Contents Function LONG 0 "IMP!" To recongnize crunched files LONG 4 Original Len Datalen before packing LONG 8 Crunched Len-$32 Datalen after packing So $a is the start of the datas... The decrunch routine NEED this header to decrunch!!! Do memoryallocation for the buffer using a allocate for the Startadr+$4 size. Command: CrMDecrunch -------------------------------------------------------------------------- Syntax: CrMDecrunch Bufferadr [,Destinationadr] Description: If the only parameter is the Bufferadr this routine works like the Deplode command, but decrunch a CrunchMania crunched file. If you use it with to parameters the decrunch will be done from Bufferadr to Destinationadr, so 2 buffers have to been allocated. The header for CrunchMania files have to look like this: Type Offset Contents Function -------------------------------------------------------------------- LONG 0 "CrM!"/"CrM2" To recongnize crunched files. WORD 4 Minimum Security Distance To savely decrunch Data when Source AND Dest is in the same Memoryblock. LONG 6 Original Len Datalen before packing LONG 10 ($a) Crunched Len Datalen after packing without header. So at $d is the data startadress. This header is NEEDED for decrunching! Command: PPDecrunch -------------------------------------------------------------------------- Syntax: PPDecrunch Bufferadr,Bufferend,Destinationadr Description: This command decrunch a PowerPacker crunched file. PowerPacker need two buffers for decrunching. Also the lenght of the buffer must be given! Sorry, I can' t find my PowerPacker archive where the header is descripted...Like Imploder and CrunchMania PowerPacker also support his own file header. Please have a look at the PowerPacker(.library) documentation! LOCALE LIBRARY -------------------------------------------------------------------------- Available commands: ISLOCALE USECATALOG FREECATALOG GETLOCALESTR Function: IsLocale -------------------------------------------------------------------------- Syntax: result=IsLocale Description: There is now way to check the ROM-Version of the Kickstart for locale presents. Both, OS 2.0 and 2.1 have the ROM-Version 37.175! So the command returns if the locale.library exists on the system. Command: UseCatalog -------------------------------------------------------------------------- Syntax: UseCatalog Catalogname Description: Opens the catalog for your programm. Might by your program is called BB2Program the catalog should be called BB2Program.catalog. But you're also able to open a catalog from an other program, like Term.catalog. The catalog files are in an IFF format!!! Read the Commodore documentation of it... Command: FreeCatalog -------------------------------------------------------------------------- Syntax: FreeCatalog Description: Removes the catalog that you opened with UseCatalog. Function: GetLocaleStr -------------------------------------------------------------------------- Syntax: GetLocaleStr #StringNumber,DefaultString$ Description: Read a string from the catalog that you opened with UseCatalog. You have to give a defaultstring to that command. If the asked string could be find in the catalog the default string will be returned. Else the string from the catalog will be returned. REQUESTER LIBRARY -------------------------------------------------------------------------- Available Commands: Function: EasyRequest -------------------------------------------------------------------------- Syntax: EasyRequest Result=EasyRequest([#Window,]title$,body$,gtext$) Description: A intuition system requester will be open. Optional you could give a window number. The title$ is the displayed string in the top. body$ is the displayed text in the requester, a Chr$(10) means a linefeed. gtext$ is the text for the gadgets. Every gadgettext will be added by a '|'. Examples: "Ok" will only display one gadget in the requester. "Ok|Cancel" add two gadgets to it. "1|2|3|4|5" five gadgets are displayed. AMIGA SUPPORT LIBRARY -------------------------------------------------------------------------- Available Commands: ALLOCMEM FREEMEM ISEVEN SEARCHSTRING Function: AllocMem -------------------------------------------------------------------------- Syntax: MemoryBlock=AllocMem(Size,Type) Description: Unlike calling Exec's AllocMem_ command directly Blitz2 will automatically free any allocated memory when the program ends. Programmers are advised to use the InitBank command. Flags that can be used with the memory type parameter are: 1=public ;fast is present 2=chipmem 65536=clear ;clears all memory allocated with 0's Command: FreeMem -------------------------------------------------------------------------- Syntax: FreeMem MemoryBlock,ByteSize (long) (long) Description: Deallocates memory obtained with AllocMem Function: IsEven -------------------------------------------------------------------------- Syntax: Result=IsEven(Expression) (bool) (byte,word,long) Description: Returns true if Expression is even. Of use when requesting a value from a user that MUST be even. Function: SearchString -------------------------------------------------------------------------- Syntax: result=SearchString(StringPointer,StartAddress,BlockLength) (long) (&string) (long) (long) Description: Finds a string in the given memory block and returns its address. Returns False otherwise. BUM #6 contains almost all the PD commands of Elmore and some more. DOS ELMORE LIBRARY HARDWARE ELMORE LIBRARY MATH ELMORE LIBRARY ARRAY ELMORE LIBRARY SYS ELMORE LIBRARY STRING ELMORE LIBRARY LIBRARY PROGRAMMING New in BUM7 : INCLUDE LIBRARY (For the uninitiated:) NOTE ON FUNCTIONS, STATEMENTS and COMMANDS: ------------------------------------------- "FUNCTIONS" are Blitz2 tokens that require parameters in parentheses, and return a value: n=ABS(m) "STATEMENTS" are Blitz2 tokens that only perform an action but do not return a value. Their arguments do not require parentheses: PRINT "HELLO!" "COMMANDS" are Blitz2 tokens that can be used as either a FUNCTION or a STATEMENT, depending upon whether the arguments were in parentheses or not. [Function form:] n=REQUEST("TITLE","SELECT YES OR NO","YES|NO") [Statement form:] REQUEST "TITLE","SELECT OK TO CONTINUE","OK" DOS.ELMORE LIBRARY -------------------------------------------------------------------------- CHDIR ENTRYHOUR PATHLOCK ENTRYMINS COPYFILE ENTRYSECS SETCOPYBUFFER ENTRYCOMMENT$ NAMEFILE ANALYZEDISK MAKEDIR DISKUNIT MOREENTRIES DISKERRS ENTRYNAME$ DISKCAPACITY ENTRYDIR DISKUSED ENTRYBIT$ DISKFREE ENTRYSIZE DISKBLOCKS ENTRYDATE DIRECTORY EXAMPLE Command: CHDIR -------------------------------------------------------------------------- Syntax: CHDIR "Path:" -or- IF CHDIR("Path:") Then... This command will change the current working directory for ALL disk- related commands. Used as a function, a value of TRUE will be returned if the directory change was successful, or FALSE if it was unsuccessful. Function: PATHLOCK -------------------------------------------------------------------------- Syntax: Lock.l=PATHLOCK This function will return the BCPL pointer to the lock of the current directory. You should NEVER "Unlock_" this lock, but it is useful to use command "NameFromLock_" with it to determine the full pathname of the current directory, for example. (NOTE: NameFromLock_ requires 2.0 and above!) Command: COPYFILE -------------------------------------------------------------------------- Syntax: COPYFILE "First","SECOND" -or- IF COPYFILE("FIRST","SECOND") Then... This command will copy files, much like the CLI command "Copy." In the function form, it will return TRUE for success, and FALSE for failure. Note that the speed at which it copies can be increased by increasing the "CopyBuffer," which defaults to 8192 bytes. (See below) Statement: SetCopyBuffer -------------------------------------------------------------------------- Syntax: SetCopyBuffer BUFFERSIZE This statement is used to set the size of the COPYFILE command's memory buffer. The default size is 8192 bytes, but this can be adjusted from 256 bytes to nearly all your free memory. A larger buffer will normally increase the speed at which the COPYFILE command operates, but only up to the size of the largest file you're copying. For example, if the largest file you need to copy is 25000 bytes, then it will be useless to set the COPYBUFFER above 25000. Command: NAMEFILE -------------------------------------------------------------------------- Syntax: NAMEFILE "Oldname","Newname" -or- IF NAMEFILE("Oldname","Newname") Then... This command returns FALSE for failure, TRUE for success: The file "oldname" is renamed to "newname," if possible, and may be moved to other directories within the same volume. It is not yet possible to use NAMEFILE to move a file from one volume to another, however. Command: MAKEDIR -------------------------------------------------------------------------- Syntax: NAMEFILE "Path:Dir" -or- If NAMEFILE("Path:Dir") Then... This command will attempt to create a new directory with the given pathname. It is only possible to create one level at a time, however. For example, MAKEDIR will fail if you attempt to MAKEDIR "RAM:New/Data" if the directory "RAM:New" does not yet exist. Used as a function, MAKEDIR returns TRUE for success, and FALSE for failure. Command: MOREENTRIES -------------------------------------------------------------------------- Syntax: MOREENTRIES -or- If MOREENTRIES Then... This command will read the next entry in the current directory for inspection with other "ENTRY" commands. Used within a loop, it is easy to read an entire directory with these commands, similar to the "DIR" or "LIST" commands of AmigaDOS. (See below. An example follows) Function: ENTRYNAME$ -------------------------------------------------------------------------- Syntax: n$=ENTRYNAME$ This function returns the name of the current directory entry. If used before the fist "MOREENTRIES" command, it will return the name of the current directory. (Just the current directory's name, not the full path name) Function: ENTRYDIR -------------------------------------------------------------------------- Syntax: If ENTRYDIR Then... This function returns TRUE if the current entry is a sub-directory, or FALSE if it is a file. Function: ENTRYBITS$ -------------------------------------------------------------------------- Syntax: n$=ENTRYBITS$ This function returns a string containing the protection-bits status of the current file or directory. An example may be "----RWED" the same format as given by the AmigaDOS "LIST" command. Possible bit settings are HSARWED: H=HIDDEN, S=SCRIPT, A=ARCHIVED, R=READABLE, W=WRITEABLE, E=EXECUTEABLE, D=DELETEABLE. Any bits that are not set will have the "-" character in their place. Function: ENTRYSIZE -------------------------------------------------------------------------- Syntax: n.l=ENTRYSIZE This function returns the size in bytes of the current directory entry. Note that sub-directories return a size of zero whether they are empty or not. Function: ENTRYDATE -------------------------------------------------------------------------- Syntax: d$=DATE$(ENTRYDATE) This function returns the date the current entry was last modified, in the same format as SYSTEMDATE uses. (The number of days since 1/1/1978) Thus, you may use the DATE$ and DATEFORMAT commands to translate it into a string with a more human-readable string. Function: ENTRYHOUR, ENTRYMINS, ENTRYSECS -------------------------------------------------------------------------- Syntax: h=ENTRYHOUR:m=ENTRYMINS:s=ENTRYSECS ENTRYHOUR: This function is related to ENTRYDATE, above, but returns the hour of the day (0-23) at which the entry was last modified. ENTRYMINS: Returns the minute (0-59) of the time at which the entry was modified. ENTRYSECS: Returns the second (0-59) of the time at which the entry was modified. Function: ENTRYCOMMENT$ -------------------------------------------------------------------------- Syntax: c$=ENTRYCOMMENT$ This function will return the string containing the filenote for the current directory entry, or "" if there is none. ********************* * DIRECTORY EXAMPLE * ********************* This example will list the entries in RAM: in a format very similar to the AmigaDOS "LIST" command. Note that you need to "ChDir" to a directory in order to read it from the first entry again. ChDir "RAM:" While MoreEntries Print LSet$(EntryName$,30) If EntryDIR then Print "Dir " Else Print LSet$(Str$(EntrySize),6) Print EntryBits$," ",Date$(EntryDate)," " Print EntryHour,":",Right$("0"+Str$(EntryMins),2),":" NPrint Right$("0"+Str$(EntrySecs),2) Wend MouseWait Command: ANALYZEDISK -------------------------------------------------------------------------- Syntax: ANALYZEDISK "DRIVE:" -or- If ANALYZEDISK "DRIVE:" Then... This command returns FALSE if the specified device or pathname was not valid. If successful, details about the specified drive can be read with the following "DISK" functions. The values for these functions will not change until ANALYZEDISK is executed again, either on the same drive or another one. Note: If given a full pathname, such as "DF0:System/Utilities" this command will still know enough to analyze the disk "DF0:" Function: DISKUNIT -------------------------------------------------------------------------- Syntax: n=DISKUNIT This function will return the unit number of the most recently analyzed disk. DF0: for example, would return zero, while DF1: would return 1. Function: DISKERRS -------------------------------------------------------------------------- Syntax: n=DISKERRS This function will return the number of soft errors DOS knows about on the last analyzed disk. This should normally be zero. Function: DISKCAPACITY -------------------------------------------------------------------------- Syntax: n=DISKCAPACITY This function returns the capacity in bytes of the last analyzed drive. For example, a fastfilesystem-formatted disk's max capacity is 837K, so DISKCAPACITY would return 857904, which divided by 1024 is 837. Function: DISKUSED -------------------------------------------------------------------------- Syntax: n=DISKUSED This function returns the number of bytes actually in-use on the last analyzed drive. Function: DISKFREE -------------------------------------------------------------------------- Syntax: n=DISKFREE The opposite of DISKUSED, DISKFREE returns the number of bytes free on the disk. This function would be very useful, for example, in a program that needed to save information to disk. You would be able to first determine if the specified SAVE disk had sufficient space. Function: DISKBLOCKS -------------------------------------------------------------------------- Syntax: n=DISKBLOCKS This function returns the number of bytes each block on a disk uses, making it possible to convert the byte-values of the above functions to number of blocks. BUM7 MAIN DOC Updates and Fixes to Blitz2 v1.9 NEW COMMANDS NEW LIBRARY'S INCLUDED Stability -------------------------------------------------------------------------- Several improvements have been made to the stability of Blitz2 programs. First up all string commands have been fixed to both work properly with the null-termination system introduced in v.18 (our apologies here) and error checking has been added. No longer will system crashes be caused with illegal size parameters in mid$() etc. Also, the ASMEND command has been added. Using assembler in statements and functions use to require the use of UNLK A4 and RTS. This system did not work properly when runtime errors were enabled. A fullproof method is now available, simply use the ASMEND command in place of any RTS commands. Blitz2 will look after the unlinking of A4, allow for runtime errors and then do an RTS. Finally my darts demo runs with runtime errors enabels (yipeeee!). And finally, runtime error checking has been added for square bracket arrays. Yup, out of range checking has been incorporated for those of us whose first guess at why our programs were crashing was to go through and check such usage manually. This with the new string checking and the sexy new debugger should return a few people to using Blitz2's runtime debugging features. Thanks to all those and their abuse for helping us get these problems resolved. Debugging -------------------------------------------------------------------------- The debugger is now a separate program that is launched by Blitz2 when a prgram is run (runtime errors enabled of course). The gadgets in the window allow the programmer access to the standard debugging features. CtrlAltC can still be used to halt programs, especially those using Slices and Displays in Blitz mode. By increasing the size of the window the program listing can be viewed. A PANIC! button has also been introduced once a program is launched from the editor. Yup, programs are now launched not run so those into weird system crashes may be able to return to Ted leaving their programs disabled in memory. A REBOOT button may have been more useful... The source code for the default debugger is included in the acidlibsrc directory of the libsdev archive. It is extremely well documented by Mark so those wanting to extend the functionality of the system are most welcome. Serial port support for using a remote terminal would be very nice. Interupts and BlitzKeys -------------------------------------------------------------------------- BlitzKeys, BlitzKeys, BlitzKeys. A common profanity used by those of us use to keyboard lock ups in keyboard based Blitz games (especially SkidMarks). Well no more! Blitz now leaves Amiga interupts enabled in Blitz mode. This means that not only is the system keyboard interupt still running (thank the lord) but any SetInts initiated in Amiga mode will continue. Other advantages are that Blitz mode is now more acceptable to the CD32 environment and RawStatus can be used in Amiga mode for keyboard games not wanting to run in Windows (yuck). Blitzkeys On now does a bit of a "BlitzkeysInput" for one character inputs only, any other inputs use the previously defined Input channel. Blitzkeys Off no longer exists. BlitzRepeat has gone (no repeating keys). Serial Stuff -------------------------------------------------------------------------- Peter Tavinor has upgraded the Serial Library. ReadSerial now return a word (read unsigned byte) so chr$(255) is acceptable. WriteSerialString includes flags for DoIO and True String (not null terminated). ReadSerial has a new flag "WaitForChar" GadTools -------------------------------------------------------------------------- The GTPalette has had several default tags removed as they crashed under 2.0 (yeh, great, just what tags are suppose to avoid). AttachGTList had a minor problem in some situations (now fixed). Another bug that has been found in GadTools under 2.0 is that GTLists actually allocate gadget id's for internal use. Besides being completely unethical (and fixed in 3.0) it means that programmers should use id values of greater than 50 to avoid this system bug. Adding GTLists last in your list should also work although their id's should be more than the number of lines of text they should display (no I am not going to explain further). ScreensLib -------------------------------------------------------------------------- The Screen command now rounds the width up to the nearest multiple of 16 rather than causing the error "Screen Width Must be a multiple of 16". Common sense I think. ValLib -------------------------------------------------------------------------- Val() now accepts hex and binary strings (preceeded by "$" and "%" of course.) Because Val() returns a float it should not be used to evaluate 32 bit integers (longs). Display Library -------------------------------------------------------------------------- A quick version of the InitCoplist command has been included which calculates the number of colours, sprites and size depending on just the type parameter. As promised the Display library now sports new commands for palette effects and so forth. There are two varieties of copper based commands, the first allows the user to insert a new palette or copperstring at a certain line of the display, the other allows control of each and every line of the display. For line based effects a negative value should be used in combination with the numcustoms parameter of the InitCopList command. Color splits, bitmap scrolling, scan doubling/trebling/quadrupling and custom copper strings can now be acheived on a line by line basis. Palette Library. -------------------------------------------------------------------------- A number of commands have been added to the Palette library for use mainly with the display library. Fades and Colour cycling can now be performed on palette objects themselves (rather than on screens and slices) and hence can be used in conjunction with the DisplayPalette command. Banks and Decoding. -------------------------------------------------------------------------- Decode commands have been added to allow programmers to both include shapes, sounds, palettes, music and ILBM's (IFF bitmaps) in their programs or from preloaded files (mainly using the LoadBank command or unpacking type commands). To include such files in the program the incbin command is used. Typically a list of included files will be situated at the bottom of the listing (with and End statement just above to be safe). Each IncBin will be preceeded by a label and the ?label syntax would be used to pass the location of each included file to the appropriate Decode command at the top of the program. Those unhappy with the slow but memory unhungry LoadBitMap command can take advantage of the fast but memory hungry method of loading iff/ilbm files with the code listed in the DecodeILBM command description. Argslib fixes -------------------------------------------------------------------------- This library processes arguments passed to it. A few fixes have mainly been made over the old one. 1) Quoted arguments count as one argument. EG "One arg" will give your program both words as one argument, not 2. 2) Mulitple workbench arguments are allowed now. If you are to use workbench arg handling, you MUST have WBSTARTUP at the top of your program!! Here are all the new library's included with BUM7: AARONSICONLIB RICOMMODITIESLIB ELMORELIBS RIENCRYPTLIB ELMOREINCLIB RIFXLIB FUZZIESREQLIB RIGFXLIB NEILSCIATRACKERLIB RIPACKLIB NEILSPROGRESSLIB RIREQLIB NEILSREQTOOLSLIB RITOOLTYPESLIB RIAMOSFUNCLIB RITRACKDISKLIB RIANIMLIB RIZONEJOYLIB RIAPPLIB/WBLIB ROMULUSLIBS Look for these commands in: CRUNCHLIB PRINTERLIB REQUESTERLIB LOCALE LIB CONSOLE LIB Library Name: riencryptlib #55 Authors : ReflectiveImages, 17 Mayles Road, Southsea, Portsmouth, Hampshire, UK PO4 8NP OverView : Another Reflective Images Library, good for war games? Authors Docs: RIEncryptLibrary Date sent: 26-AUG-1994 -------------------------------------------------------------------------- You can have this little library if you like. Sorry there are no full docs in the archive - the lib was done in a hurry for someone. It performs Enigma compression and is very cute ;-). The archive contains the source code for the library. I'm sure it wouldn't take you a second to have a look at it ;-). Commands in the library: Encrypt memadr,len[,wheel1,wheel2,wheel3] This will encrypt a block of memory starting at the address and running through to addresslength-1. The optional wheel parameters allow you to specify the start positions of the three wheels. If you leave these out then the wheels' start positions will be randomised. GetWheel n This will tell you the position that wheel n stopped at after encrypting a file. n can range from 1 to 3 - YOU MUST REMEMBER THESE POSITIONS IF YOU WANT TO DECRYPT THE FILE (at the moment at least). Decrypt memadr,len,wheel1,wheel2,wheel3 Same Encrypt except that it does the opposite and the wheel positions ARE NOT OPTIONAL. The positions should be the ones you wrote down after encrypting the file. I may, in future, change it so that you can also specify the start wheel positions instead of the end ones (shouldn't be tooooo hard ;-)). Oh well, have a look and tell us what you think............ Library: neilsreqtoolslib #54 Author: Neil O'Rourke, 6 Victoria St, TAMWORTH, NSW 2340, AUSTRALIA Overview: Access to the ReqTools library. RTEZREQUEST RTEZGETSTRING RTEZFLAGSREQUEST RTLOCKWINDOW RTEZFONTREQUEST RTUNLOCKWINDOW RTEZSCREENMODEREQUEST RTVERSION RTEZPALETTEREQUEST RTREVISION RTEZLOADFILE ISREQTOOLSACTIVE RTEZSAVEFILE RTASYNCREQUEST RTEZPATHREQUEST RTCHECKASYNCREQUEST RTEZMULTILOADFILE RTENDASYNCREQUEST RTEZRNEXTPATHENTRY RTASYNCPALETTEREQUEST RTEZSETDEFAULTDIRECTORY RTCHECKASYNCPALETTEREQUEST RTEZSETPATTERN RTENDASYNCPALETTEREQUEST RTEZFREEPATTERN RTREQUEST RTEZGETLONG RTFILEREQUEST RTEZGETLONGRANGE Author's Documentation ReqToolslib V1.70b Neil O'Rourke ** BETA FOUR ** This is an implementation of Nico Franco's ReqTools library. There are two different implementations of each function, a simple one (denoted by EZ (pronounced E-Zee) in the command name), and a complex one. The simple implementation has bog standard requesters that the programmer has little (if any) control over. The purpose of these is to get your programs working fast (or it could be that you don't need all the fancy options that are available), with a minimum of setup for the requesters. That isn't to say the requesters aren't powerful; on the contrary, ReqTools requesters leave ASL requesters in the dust when it comes down to sheer power. The more complex implementation requires you to build a TagList and supply it to the requester. This shouldn't really be needed, as all the EZ requesters have a resonable set of defaults and options to avoid this. All the ReqTools requesters attach themselves to the window that DOS errors are. To do this, simply make your window the current window with Use Window WindowNum, then CatchDosErrs. By default, the requesters will go to the Workbench. Compatibility ~~~~~~~~~~~~~ All ReqTools requesters, with the exception of the ScreenMode request, are compatible with KickStart 1.3. DO NOT CALL RTEZSCREENMODEREQUEST IF YOU ARE RUNNING 1.3!! THIS IS YOUR RESPONSIBILITY! Future Directions ~~~~~~~~~~~~~~~~~ The recent releases of ReqTools have included a preferences program to control the behaviour of requesters. This does not sit well with the pre-programmed options that my interface code uses. It could be that future releases of ReqToolsLib will not set these, but this is early days and only time and user feed-back will indicate the path to go. The doc file was so much damaged that I could not convert it....If somebody has a good file, please send or mail it to me! Function: RTEZRequest -------------------------------------------------------------------------- Syntax : result=RTEZRequest(Title$,BodyText$,GadgetText$ [,ReqPosition [, DefaultResponse, Flags]]) Description: Opens a simple requester in the center of your screen. You can have multiple gadgets in Gadget$, seperate the by a bar (|). To have multiple lines in your gadget, seperate them by a Chr$(10). Title$ can be whatever you want. If it is left blank, the title of the calling window will be used. The requester auto-adjusts its size to the length of the body text. Also, the requester will block any input to the calling window, and if the user selects that window he will see the usual wait pointer. The requester returns the number of the gadget selected, gadget zero is the extreme right hand gadget (usually Cancel), and numbered from one starting from the left hand side of the requester. The optional parameter ReqPos allows relative positioning of the requester. You can have the requester open up in the center of the screen (the default position), or the center of the window, or the TopLeft corner of the screen or window. The valid flags are: #REQPOS_POINTER =0 Relative to MousePointer #REQPOS_CENTERWIN =1 Center of window #REQPOS_CENTERSCR =2 Center of screen (default) #REQPOS_TOPLEFTWIN =3 TopLeft of the window #REQPOS_TOPLEFTSCR =4 TopLeft of the screen (Amiga default) There are two further options: DefaultResponse allows you to change what gadget is selected when the Return key is hit, and this is by default the left hand gadget (1) Flags controls a few other items in the requester. #EZREQB_NORETURNKEY =1 Turns off the return key as positive response #EZREQB_LAMIGAQUAL =2 Keyboard shortcuts are limited to LA-V and LA-B #EZREQB_CENTERTEXT =4 Centers the text in the requester. You can make keyboard shortcuts for the gadgets by placing an underscore character '_' before the character you wish to have as the shortcut, for example your "Ok" gadget could be defined as "_Ok", and Right Amiga-O would then satisfy the requester. Function: RTEZFlagsRequest -------------------------------------------------------------------------- Syntax : result=RTEZFlagsRequest(Title$,BodyText$,GadgetText$, IDCMPFlags[,ReqPos]) Description: This requester is similar to the standard RTEZRequest, but it can also be satisfied by an IDCMP flag (eg DiskInserted). Either the gadget number or the IDCMP flag will be returned in result. This requester also supports no gadgets, by supplying "" as the Gadget Text$. Since the window is locked, the user cannot proceed until the request is satisfied. Use this at your own peril! This requester can force the user to take an action he may not want to, if you don't supply any gadgets. Think, have second thoughts, and then think some more. With enough thought, you *will* come to the conclusion that the user needs at least one gadget. The ReqPosition flag is also available for this requester, as is the keyboard shortcuts. Function: RTEZFontRequest -------------------------------------------------------------------------- Syntax : *MyFont.TextAttr=RTEZFontRequest(Title$) Description: Brings up the Font requester, and returns a pointer to a TextAttr structure. The Font requester has had a total rewrite for the V1.7 release of ReqToolsLib. Using it is just the same, but it now returns a saner structure. The structure is defined: NewType.TA Name.s YSize.w Style.b Flags.b End Newtype Function: RTEZScreenModeRequest -------------------------------------------------------------------------- Syntax : *MyScreenMode =RTEZScreenModeRequest(Title$ [,DisplayFlags]) Description: Returns a pointer to the following structure: NEWTYPE.MyScreenMode DisplayID.l DisplayWidth.w DisplayHeight.w DisplayDepth.w OverscanType.w AutoScroll.l End NEWTYPE The DisplayFlags field allows you to have control over what options you offer the user. By default, the requester has a resonable set of options, but you may wish to add too (or subtract from) these. Allowable flags are: #SCREQF_OVERSCANGAD - Add an overscan cycle gadget to the requester. After the requester returns you may read the overscan type in '\OverscanType' If this is 0 no overscan is selected (Regular Size), if non-zero it holds one of the OSCAN_... values defined in the include file 'intuition /screens.[h|i]'. #SCREQF_AUTOSCROLLGAD- Add an autoscroll checkbox gadget to the requester. After the requester returns read '\AutoScroll' to see if the user prefers autoscroll to be on or off. #SCREQF_SIZEGADS - Add width and height gadgets to the requester. If you do not add these gadgets the width and height returned will be the default width and height for the selected overscan type. #SCREQF_DEPTHGAD - Add a depth slider gadget to the requester. If you do not add a depth gadget, the depth returned will be the maximum depth this mode can be opened in. #SCREQF_NONSTDMODES - Include all modes. Unless this flag is set RTEZScreenModeRequest() will exclude nonstandard modes. Nonstandard modes are presently HAM and EHB (ExtraHalfBrite). So unless you are picking a mode to do some rendering in leave this flag unset. Without this flag set the mode returned will be a normal bitplaned mode. #SCREQF_GUIMODES - Set this flag if you are getting a screen mode to open a user interface screen in. The modes shown will be standard modes with a high enough resolution (minumum 640 pixels). If this flag is set the SCREQF_NONSTDMODES flag is ignored. Do not attempt to call this requester under WB1.3. Function: RTEZPaletteRequest -------------------------------------------------------------------------- Syntax : SelectedColour.w=RTEZPaletteRequest(Title$,FirstColour) Description: Brings up the Palette requester. Returns the last colour the user selected, or -1 if the user hit cancel. If the user changed the colours, they are reflected in the viewport that the window is attached to. Function: RTEZLoadFile -------------------------------------------------------------------------- Syntax : name$=RTEZLoadFile(Title$,FileName$) Description: This brings up the standard file requester. The directories are buffered, so it doesn't have to reload the directory each time it is called. Note that FileName$ must be at least 108 characters long (use the MaxLen function of this). Note that by default, pattern matching is not enabled. If you want to match a particular pattern, use the RTEZSetPattern command described below. Also, the file name isn't copied to FileName$. You can have a default file name by writing to FileName$, but this will be cleared after the call finishes. This is also true of the SaveFile requester. Function: RTEZSaveFile -------------------------------------------------------------------------- Syntax : name$=RTEZSaveFile(Title$,FileName$) Description: A seperate requester, the SaveFile requester is different from the LoadFile requester in a number of ways. First, it has a seperate buffer from the LoadFile requester. Second, the OK text is changed to Save. Third, the user cannot double-click a file to select it, to prevent accidental deletions. Finally, if the user types in a non-existent directory, he will be asked if he would like that directory created. FileName$ must be at least 108 bytes long as well. Note that by default, pattern matching is not enabled. If you want to match a particular pattern, use the RTEZSetPattern command described below. Function: RTEZPathRequest -------------------------------------------------------------------------- Syntax : name$=RTEZPathRequest(Title$) Description: Prompts the user to select a path. This is also a seperate requester to the LoadFile and SaveFile requesters, and maintains its own directory list. Function: RTEZMultiLoadFile -------------------------------------------------------------------------- Syntax : ret.l=RTEZMultiLoadFile(Title$) Description: Allows the user to select multiple files for loading (this makes no sense for saving). ret is either True for a list having been selected, or False if the user cancelled. If you call RTEZMultiLoadFile, any previous FileList that was loaded is deleted, even if the user cancels the requester. Function: RTNextPathEntry -------------------------------------------------------------------------- Syntax : name$=RTNextPathEntry Description: This function returns the next file from a RTEZMultiLoadFile call, or a null string is there is no entry, so you can safely loop about until an empty string is returned. Statement: RTEZSetDefaultDirectory -------------------------------------------------------------------------- Syntax : RTEZSetDefaultDirectory Requester#,Directory$ Description: This can be used to set a default directory for the user. Directory$ is the default path, and Requester# is one of the following: 0 - EZLoadFile 1 - EZSaveFile 2 - EZPathRequest 3 - EZMultiLoadFile Statement: RTEZSetPattern -------------------------------------------------------------------------- Syntax : RTEZSetPattern Requester#,Pattern$ Description: Enables and sets the pattern matching in LoadFile and SaveFile requesters. Valid requesters are: 0 - EZLoadFile 1 - EZSaveFile 3 - EZMultiLoadFile Statement: RTEZFreePattern -------------------------------------------------------------------------- Syntax : RTEZFreePattern Requester# Description: Turns off pattern matching in the requester. Valid requester numbers are: 0 - EZLoadFile 1 - EZSaveFile 3 - EZMultiLoadFile Function: RTEZGetLong -------------------------------------------------------------------------- Syntax : result.l=RTEZGetLong(Title$,BodyText$ [,DefaultValue]) Description: This prompts the user for a number. BodyText$ can be formatted with chr$(10) if needed. DefaultValue can be supplied to suggest a value to the user. Function: RTEZGetLongRange -------------------------------------------------------------------------- Syntax : result.l=RTEZGetLongRange(Title$,BodyText$,Min.l,Max.l [,DefaultValue]) Description: Like RTEZGetLong, but this imposes an inclusive minimum and maximum on the number entered. Again, DefaultValue can be used to suggest a value to the user. Function: RTEZGetString -------------------------------------------------------------------------- Syntax : returned$=RTEZGetString(Title$,BodyText$,MaxChars [,DefaultString]) Description: Prompts the user to enter a string (which can be up to MaxChars in length). As usual, you can format the BodyText$ with chr$(10) and supply a default string. If you do supply one, then make sure that the length of the string is less than MaxChars, otherwise you could corrupt innocent memory. Function: RTLockWindow -------------------------------------------------------------------------- Syntax : WinLock=RTLockWindow(Window#) Description: This locks the numbered window, blocks all input to that window except depth arranging (and the Zip gadget, under 2.0), and put up the standard wait pointer. If you have some utility to make the hands spin or something like that, then that happens as well. WinLock must be saved! Statement: RTUnlockWindow -------------------------------------------------------------------------- Syntax : RTUnlockWindow Window#,WinLock Description: Unlocks the window that you locked with RTLockWindow. Functions: RTVersion and RTRevision -------------------------------------------------------------------------- Syntax : ver=RTVersion and ver=RTRevision Description: Both these functions return the version number and revision number of the ReqTools library that this code interfaces to. Of no real use at the moment, but future developments in ReqTools may require a minimum library version to work. ReqToolsLib will always open whatever ReqTools are available. Function: IsReqToolsActive -------------------------------------------------------------------------- Syntax : result=IsReqToolsActive Description: Returns True if ReqTools was able to initialise, and False if it wasn't (eg not available). Function: RTASyncRequest -------------------------------------------------------------------------- Syntax : ret.l=RTASyncRequest(Title$,BodyText$,GadgetText$) Description: This function puts up a request, locks the window and returns immediately. If the requester couldn't be put up, ret is False. The program is now free to continue, but the user can have the option of aborting a lengthy operation if required. Important Note: Do not attempt to have two asyncronous requesters up. Note: As of V1.41b, RTASyncRequest uses the current window for the requester. Function: RTCheckASyncRequest -------------------------------------------------------------------------- Syntax : ret.l=RTCheckASyncRequest Description: Checks the status of the asyncronous requester, and returns True if it is still up. Statement: RTEndASyncRequest -------------------------------------------------------------------------- Syntax : RTEndASyncRequest Description: Ends the asyncronous request, under program control, and unlocks the calling window. NOTE: Do not call this finction if the user has hit the gadget in the request! The requester automatically frees its self. These three commands require a demonstration to illustrate: NoCli:WBStartup WbToScreen 0 Window 0,10,10,100,100,$8|$1000|2|4,"RTTest window",2,1 CatchDosErrs ret.l=RTASyncRequest("Hi There!","Please Wait...","Cancel") If ret ;The requester opened OK For x.w=10 To 1 Step -1 WLocate 0,10 NPrint "Seconds:",x VWait(50) ret1.l=RTCheckASyncRequest ;Is the requester still up? If NOT ret1 ;No, so end this processing Pop If:Pop For:Pop If Goto cancelled EndIf Next x RTEndASyncRequest ;Normal finish EndIf End cancelled: a.l=RTEZRequest("Oi!","You cancelled!?!","Sure Did") End Function: RTASyncPaletteRequest -------------------------------------------------------------------------- Syntax : ret.l=RTASyncPaletteRequest(Title$,FirstColour) Description: Similar to RTEZPaletteRequest, this command puts up a palette requester and returns immediatly. Note, however, that the calling window is NOT locked, unlike all other ReqTools requesters. This allows you to launch a seperate palette requester and continue processing. Function: RTCheckASyncPaletteRequest -------------------------------------------------------------------------- Syntax : ret.l=RTCheckASyncPaletteRequest Description: Returns True if the requester is still up, False if the user hit Ok or Cancel. NOTE: There is no way to detect exactly how the user exited the command. Statement: RTEndASyncPaletteRequest -------------------------------------------------------------------------- Syntax : RTEndASyncPaletteRequest Description: Closes the requester. A short demonstration program to illustrate: WbToScreen 0 Window 0,0,0,200,100,$40,"Hi there",2,1 CatchDosErrs ret.l=RTASyncPaletteRequest("Play with these",1) count.l=0 If ret While count<100 count+1 WLocate 0,0 NPrint "Seconds:",count If NOT RTCheckASyncPaletteRequest Then Goto quit Delay_ 60 Wend RTEndASyncPaletteRequest EndIf quit: Free Window 0 Function: RTRequest -------------------------------------------------------------------------- Syntax : ret=RTRequest(BodyText$,GadgetText$,TagList) Description: This is the standard form of the ReqTools Requester. You must supply the tag list to control the requester. The requester title, if not specified in the tag list, will be "Information" if you have only one response gadget, or "Request" if you have two or more responses. If you don't supply a tag list, ReqTools will use its own defaults. It is *your* responsibility to ensure the TagList is correctly set up. Most of the tags of interest are included in RTEZRequest and RTEZFlagsRequest as standard. Acceptable tags are: #RT_Window - *name.Window Window that will be used to find the screen to put the requester on. You *MUST* supply this if you are a task calling this function and not a process! This is because tasks don't have a pr_WindowPtr. #RT_IDCMPFlags - (LONG) Extra idcmp flags to return on. If one these IDCMP flags causes the requester to abort the return code will equal the flag in question. #RT_ReqPos - (LONG) One of the following: #REQPOS_POINTER - requester appears where the mouse pointer is (default). #REQPOS_CENTERSCR - requester is centered on the screen. #REQPOS_CENTERWIN - requester is centered in the window (only works if the pr_WindowPtr of your process is valid or if you use RT_Window). If RT_Window is NULL the requester will be centered on the screen. #REQPOS_TOPLEFTSCR - requester appears at the top left of the screen. #REQPOS_TOPLEFTWIN - requester appears at the top left of the window (only works if the pr_WindowPtr of your process is valid or if you use RT_Window). The requester will always remain in the visible part of the screen, so if you use the Workbench 2.0 ScreenMode preferences editor to enlarge your Workbench screen and you scroll around, the requester will always appear in the part you can see. REQPOS_CENTERSCR and REQPOS_TOPLEFTSCR also apply to the visible part of the screen. So if you use one of these the requester will be appear in the center or the top left off what you can see of the screen as opposed to the entire screen. REQPOS_CENTERWIN and REQPOS_TOPLEFTWIN fall back to REQPOS_CENTERSCR or REQPOS_TOPLEFTSCR respectively when there is no parent window. So you can safely use these without worrying about the existence of a window. #RT_LeftOffset - (LONG) Offset of left edge of requester relative to position specified with RT_ReqPos (does not offset the requester when RT_ReqPos is REQPOS_POINTER). #RT_TopOffset - (LONG) Offset of top edge of requester relative to position specified with RT_ReqPos (does not offset the requester when RT_ReqPos is REQPOS_POINTER). #RT_PubScrName - (*string) Name of public screen requester should appear on. When this tag is used the RT_Window tag will be ignored. If the public screen is not found the requester will open on the default public screen. Only works on Kickstart 2.0! reqtools.library does not check this, it is up to you *NOT* to use this tag on Kickstart 1.3 or below! Note that the 1.3 version of reqtools.library also understands and supports this tag (on 2.0). #RT_Screen - (*name.Screen) Address of screen to put requester on. You should never use this, use RT_Window or RT_PubScrName. #RT_ReqHandler - (struct rtHandlerInfo **) Using this tag you can start an "asynchronous" requester. ti_TagData of the tag must hold the address of a pointer variable to a rtHandlerInfo structure. The requester will initialize this pointer and will return immediately after its normal initialization. The return code will not be what you would normally expect. If the return code is _not_ equal to CALL_HANDLER an error occurred and you should take appropriate steps. If the return code was CALL_HANDLER everything went ok and the requester will still be up! See the explanation for rtReqHandlerA() below for the following steps you have to take. #RT_WaitPointer - (BOOL) If this is TRUE the window calling the requester will get a standard wait pointer set while the requester is up. This will happen if you used the RT_Window tag or if your process's pr_WindowPtr is valid. Note that after the requester has finished your window will be ClearPointer()-ed. If you used a custom pointer in your window you will have to re-set it, or not use the RT_WaitPointer tag and put up a wait pointer yourself. If your program requires ReqTools V38 it is advised you use RT_LockWindow instead. Defaults to FALSE. #RT_LockWindow - (BOOL) [V38] If this is TRUE the window calling the requester will get locked. It will no longer accept any user input and it will get standard wait pointer set. This will happen only if you used the RT_Window tag or if your process's pr_WindowPtr is valid. RT_LockWindow will restore a custom pointer if you have used one (unlike RT_WaitPointer). So you do not have to worry about having to restore it yourself. It is advised you use this tag as much as possible. Defaults to FALSE. #RT_ScreenToFront - (BOOL) [V38] Boolean indicating whether to pop the screen the requester will appear on to the front. Default is TRUE. #RT_ShareIDCMP - (BOOL) [V38] Boolean indicating whether to share the IDCMP port of the parent window. Use this tag together with the RT_Window tag to indicate the window to share IDCMP with. Sharing the IDCMP port produces less overhead, so it is advised you use this tag. Defaults to FALSE. #RT_Locale - (struct Locale *) [V38] Locale to determine what language to use for the requester text. If this tag is not used or its data is NULL, the system's current default locale will be used. Default NULL. #RT_IntuiMsgFunc - (struct Hook *) [V38] The requester will call this hook for each IDCMP message it gets that doesn't belong to its window. Only applies if you used the RT_ShareIDCMP tag to share the IDCMP port with the parent window. Parameters are as follows: A0 - (struct Hook *) your hook A2 - (struct rtReqInfo *) your requester info A1 - (struct IntuiMessage *) the message After you have finished examining the message and your hook returns, ReqTools will reply the message. So do not reply the message yourself! #RT_Underscore - (char) [V38] Indicates the symbol that precedes the character in the gadget label to be underscored. This is to define a keyboard shortcut for this gadget. Example: to define the key 'Q' as a keyboard shortcut for "Quit" and 'N' for "Oh, No!" you would use the tag RT_Underscore, '_' and pass as gadfmt "_Quit|Oh, _No!". Do not use the symbol '%' as it is used for string formatting. The usual character to use is '_' like in the example. IMPORTANT: the shortcuts defined using RT_Underscore take precedence of the default shortcuts! It is for example not wise to use a 'N' for a positive response! Pick your shortcuts carefully! #RT_TextAttr - (struct TextAttr *) [V38] Use this font for the requester. Default is to use the screen font. Note that the font must already be opened by you. ReqTools will call OpenFont() on this TextAttr, _not_ OpenDiskFont()! If the font cannot be opened using OpenFont() the default screen font will be used. #RTEZ_ReqTitle - (char *) Title of requester window, default is "Request" unless the requester has less than 2 responses, then the default title is "Information". #RTEZ_Flags - (ULONG) Flags for rtEZRequestA(): #EZREQF_NORETURNKEY - turn off the RETURN key as shortcut for positive response. #EZREQF_LAMIGAQUAL - keyboard shortcuts are limited to Left Amiga 'V' and 'B', ESC and RETURN. #EZREQF_CENTERTEXT - centers each line of body text in the requester window. Useful for about requesters. #RTEZ_DefaultResponse - (ULONG) Response value that will be returned when the user presses the return key. Will be ignored if the EZREQF_NORETURNKEY flag is set. The text for this response will be printed in bold. Default is 1. Function: RTFileRequest -------------------------------------------------------------------------- Syntax : name$=RTFileRequest(Title$,FileName$,TagList) Description: This is the standard ReqTools requester, and is seperate from the LoadFile, SaveFile and PathRequest requesters. No setup is done, but the file name etc is returned as per the above requesters. Most of the tags that you would set normally are included as standard in the RTREZxFile requesters. It is *your* responsibility to ensure that the TagList is correctly set up. Acceptable tags are: #RT_Window - see rtEZRequestA() #RT_ReqPos - see rtEZRequestA() #RT_LeftOffset - see rtEZRequestA() #RT_TopOffset - see rtEZRequestA() #RT_PubScrName - see rtEZRequestA() #RT_Screen - see rtEZRequestA() #RT_ReqHandler - see rtEZRequestA() #RT_WaitPointer - see rtEZRequestA() #RT_LockWindow - [V38] see rtEZRequestA() #RT_ScreenToFront - [V38] see rtEZRequestA() #RT_ShareIDCMP - [V38] see rtEZRequestA() #RT_Locale - [V38] see rtEZRequestA() #RT_IntuiMsgFunc - (struct Hook *) [V38] The requester will call this hook for each IDCMP message it gets that doesn't belong to its window. Only applies if you used the RT_ShareIDCMP tag to share the IDCMP port with the parent window. Parameters are as follows: A0 - (struct Hook *) your hook A2 - (struct rtFileRequester *) your requester A1 - (struct IntuiMessage *) the message After you have finished examining the message and your hook returns, ReqTools will reply the message. So do not reply the message yourself! #RT_Underscore - (char) [V38] Indicates the symbol that precedes the character in a gadget's label to be underscored. This will also define the keyboard shortcut for this gadget. Currently only needed for RTFI_OkText. Usually set to '_'. #RT_DefaultFont - (struct TextFont *) This tag allows you to specify the font to be used in the requester when the screen font is proportional. Default is GfxBase->DefaultFont. #RT_TextAttr - (struct TextAttr *) [V38] Use this font for the requester. Must be a fixed width font, _not_ a proportional one. Default is to use the screen font or the default font (if the screen font is proportional). Note that the font must already be opened by you. ReqTools will call OpenFont() on this TextAttr, _not_ OpenDiskFont()! If the font cannot be opened using OpenFont() or if the font is proportional the default screen font will be used (or the font set with RT_DefaultFont). #RTFI_Flags - (ULONG) Several flags: #FREQF_NOBUFFER - do _not_ use a buffer to remember directory contents for the next time the file requester is used. #FREQF_MULTISELECT - allow multiple files to be selected. rtFileRequest() will return a pointer to an rtFileList structure which will contain all selected files. Use rtFreeFileList() to free the memory used by this file list. #FREQF_SELECTDIRS - set this flag if you wish to enable the selecting of dirs as well as files. You *must* also set FREQF_MULTISELECT. Directories will be returned together with files in rtFileList, but with StrLen equal to -1. If you need the length of the directory's name use strlen(). #FREQF_SAVE - Set this if you are using the requester to save or delete something. Double-clicking will be disabled so it is harder to make a mistake and select the wrong file. If the user enters a non- existent directory in the drawer string gadget, a requester will appear asking if the directory should be created. #FREQF_NOFILES - Set this if you want to use the requester to allow the user to select a directory rather than a file. Ideal for getting a destination dir. May be used with FREQF_ MULTISELECT and FREQF_SELECTDIRS. #FREQF_PATGAD - When this is set a pattern gadget will be added to the requester. #RTFI_Height - (ULONG) Suggested height of file requester window. #RTFI_OkText - (char *) Replacement text for "Ok" gadget, max 6 chars long. #RTFI_VolumeRequest - (ULONG) [V38] The presence of this tag turns the file requester into a volume/assign disk requester. This requester can be used to get a device name ("DF0:", "DH1:",..) or an assign ("C:", "FONTS:", ...) from the user. The result of this requester can be found in the filereq->Dir field. The volume can also be changed with rtChangeReqAttrA() and the RTFI_Dir tag. Note: that the user may edit the disk/assign names, or enter a new one. Note also that the real device name is returned, not the name of the volume in the device. For example "DH1:", not "Hard1:". The tag data (ULONG) is used to set following flags: #VREQF_NOASSIGNS - Do not include the assigns in the list, only the real devices. #VREQF_NODISKS - Do not include devices, just show the assigns. #VREQF_ALLDISKS - Show _all_ devices. Default behavior is to show only those devices which have valid disks inserted into them. So if you have no disk in drive DF0: it will not show up. Set this flag if you do want these devices included. NOTE: Do *NOT* use { RTFI_VolumeRequest, TRUE }! You are then setting the VREQF_NOASSIGNS flag! Use { RTFI_VolumeRequest, 0 } for a normal volume requester. NOTE: If you use the RTFI_FilterFunc described below the third parameter will be a pointer to a rtVolumeEntry structure rather than a pointer to a FileInfoBlock structure! Tech note: the DOS device list has been unlocked, so it is safe to e.g. Lock() this device and call Info() on this lock. NOTE: A file requester structure allocated with rtAllocRequest() should not be used for both a file and a volume requester. Allocate two requester structures if you need both a file and a volume requester in your program! #RTFI_FilterFunc - (struct Hook *) [V38] Call this hook for each file in the directory being read (or for each entry in the volume requester). Parameters are as follows: A0 - (struct Hook *) your hook A2 - (struct rtFileRequester *) your filereq A1 - (struct FileInfoBlock *) fib of file OR (struct rtVolumeEntry *) device or assign in case of a volume requester. If your hook returns TRUE the file will be accepted. If it returns FALSE the file will be skipped and will not appear in the requester. IMPORTANT NOTE: If you change your hook's behavior you _MUST_ purge the requester's buffer (using rtFree ReqBuffer())! IMPORTANT NOTE: When this callback hook is called from a volume requester the pr_WindowPtr of your process will be set to -1 so *no* DOS requesters will appear when an error occurs! #RTFI_AllowEmpty - (BOOL) [V38] If RTFI_AllowEmpty is TRUE an empty file string will also be accepted and returned. Defaults to FALSE, meaning that if the user enters no filename the requester will be canceled. You should use this tag as little as possible! Library Name: fuzziesreqlib #53 Author: Peter Tavinor, 22 Tuhangi St, Kamo, Whangarei, New Zealand Commands: COLOURREQUEST CON_BASE DOS_BASE FILEFILTER FILEREQSIZE FILESTRUCTURE GETSTRING$ GFX_BASE INT_BASE MAXSELECT$ NEXTFILE$ REQCOLOURS REQFILEREQUEST$ REQFONTSIZE REQ_BASE REX_BASE TEXTREQUEST TEXTTIMEOUT OverView: Not only has Peter Tavinor (King Fuzzy) kindly fixed up and added stuff to our own libraries (seriallib especially) he has also sent us this library which is one of three that take advantage of the ReqLibrary. Fuzzy has also cludged up Ted with hotkeys and stuff, if you want to get hold of this version I suggest writing to him at the above address. Anyway, sorry I couldn't fit more of his stuff in this issue. Authors Docs: Req Library Ver 1.1 By King Fuzzy No. 201 $VER: Req Library extention Docs version 1.1 by King Fuzzy The following commands are in the Reqlib library and they require the req.library To get the Requests on a custom window use CatchDosErrs (see Reference Manual) Function: ColourRequest -------------------------------------------------------------------------- Syntax : Colour=ColourRequest(Colour) Description: This function brings up a handy little palette and allows the user to select a colour using Colour as the default. Example: c=ColourRequest(1) Function: Con_Base -------------------------------------------------------------------------- Syntax : cl.l=Con_Base This Returns pointer to Console.device. Used for jsr calls mainly rawkey to cookedkey Function: Dos_Base -------------------------------------------------------------------------- Syntax : dl.l=Dos_Base This Returns pointer to Dos.Library used in jsr calls Statement: FileFilter -------------------------------------------------------------------------- Syntax : FileFilter Show$,Hide$ This sets the Hide and Show filters in the req file requester FileFilter "Req.*","*.Bak" This will show all files starting with 'Req.' but not ones ending with '.Bak' Statement: FileReqSize -------------------------------------------------------------------------- Syntax : FileReqSize Lines High,File Length,Device Length Description: This sets the size of the Req File Requester. The defaults are 8,16,10 FileReqSize 20,25,12 Function: FileStructure -------------------------------------------------------------------------- Syntax : Fs.l=FileStructure Description: Returns a pointer to the req file requester structure Function: GetString$ -------------------------------------------------------------------------- Syntax : String$=GetString$(Title$,Default$,Visable size,Max length) Description: This brings up a string requester allowing the user to enter a string The maximum length and the visable length are set with Max length and Visable size The default string must have a maximum length of at least Max length Returns a null string if cancel is selected MaxLen d$=40 s$=GetString$("Type something",d$,30,40) Function: Gfx_Base -------------------------------------------------------------------------- Syntax : gl.l=Gfx_Base Description: This Returns pointer to Graphics.Library used in jsr calls Function: Int_Base ---------------------------------------------------------------------------- Syntax : il.l=Int_Base Description: This Returns pointer to Intuition.Library used in jsr calls Statement: MaxSelect$ -------------------------------------------------------------------------- Syntax : Path$=MaxSelect$(Title$,File$,Path$,Flags,number of files) Select the number of files that can be selected with the extended selector see ReqFile Requestor for more information Function: NextFile$ -------------------------------------------------------------------------- Syntax : f$=NextFile$ Description: Returns the next file in the extended file structure Statement: ReqColours -------------------------------------------------------------------------- Syntax : ReqColours Text,Detail,Block[,File,Dir,Device[,GadText,GadBox, StringName,StringBox,Frame]] Description: Text,Detail and Block are for both the req file requester and the text requester File,Dir,Device,GadText,GadBox,StringName,StringBox and Frame are only for the req file requester Try changing the colours one at a time to see what they change ReqColours 1,2,3 ReqColours 1,2,3,3,2,1 ReqColours 1,2,3,3,2,1,1,2,3,4,5 Function: ReqFileRequest$ -------------------------------------------------------------------------- Syntax: selectedfile$=ReqFileRequest$(Title$,File$,Path$,Flags) Yes it's another file/font requester, No it won't bring up the blitz requester if it fails the maximum length of File$ must be 32 and Path$ must be 132 The Flags are as follows (Clipped from reqbase.i) FRQSHOWINFOB EQU 0 = 1 ;Set this in Flags if you want .info files to show. They default to hidden. FRQEXTSELECTB EQU 1 = 2 ;Set this in Flags if you want extended select. Default is not. FRQCACHINGB EQU 2 = 4 ;Set this in Flags if you want directory caching. Default is not. FRQGETFONTSB EQU 3 = 8 ;Set this in Flags if you want a font requester rather than a file requester. FRQINFOGADGETB EQU 4 = 16 ;Set this in Flags if you want a hide-info files gadget. FRQHIDEWILDSB EQU 5 = 32 ;Set this in Flags if you DON'T want 'show' and 'hide' string gadgets. FRQABSOLUTEXYB EQU 6 = 64 ;Use absolute x,y positions rather than centering on mouse. FRQCACHEPURGEB EQU 7 = 128 ;Purge the cache whenever the directory date stamp changes if this is set. FRQNOHALFCACHEB EQU 8 = 256 ;Don't cache a directory unless it is completely read in when this is set. FRQNOSORTB EQU 9 = 512 ;Set this in Flags if you DON'T want sorted directories. FRQNODRAGB EQU 10 =1024 ;Set this in Flags if you DON'T want a drag bar and depth gadgets. FRQSAVINGB EQU 11 =2048 ;Set this bit if you are selecting a file to save to. FRQLOADINGB EQU 12 =4096 ;Set this bit if you are selecting a file(s) to load from. ;These two bits (save and load) aren't currently used for ;anything, but they may be in the future, so you should ;remember to set them. Also, these bits make it easier if ;somebody wants to customize the file requester for their ;machine. They can make it behave differently for loading ;vs saving. FRQDIRONLYB EQU 13 =8192 ;Allow the user to select a directory, rather than a file. Just add together what you want and use it. EG. 6 is Caching and extended select Also see: FILEREQSIZE FILEFILTER REQCOLOURS$ FILESTRUCTURE MAXSELECT$ NEXTFILE$ MaxLen fl$=32 : MaxLen dr$=132 f$=ReqFileRequest$("Select a file",fl$,dr$,4) FRQEXTSELECTB is not used Returns a null string if user aborts Function: ReqFontSize -------------------------------------------------------------------------- Syntax : sz=ReqFontSize This Returns the size of the last font selected with the font requester Function: Req_Base -------------------------------------------------------------------------- Syntax : rl.l=Req_Base This Returns pointer to Req.Library used in jsr calls Function: Rex_Base -------------------------------------------------------------------------- Syntax : rxl.l=Rex_Base This Returns pointer to RexxSys.Library I think, It says RexxSysBase in the req library docs Function: TextRequest -------------------------------------------------------------------------- Syntax : Button=TextRequest(Text,Title,Left Text[,[Middle Text,]Right Text]) This brings up a text requester with Text as the message and Title in the titlebar It can have 1, 2 or 3 buttons to select from The requester's colours can be changed: See REQCOLOURS Left button Left and Right buttons Left, Middle and Right buttons The text in the buttons is determined by Left Text,Middle Text and Right Text the value returned is 1 left button 2 middle button 0 right button Button=TextRequest("I am a simple requester","Blitz Prog","Left","Middle","Right") Statement: TextTimeout -------------------------------------------------------------------------- Syntax : TextTimeout Timeout Seconds Its surpose to set the timeout for the text requester but it don't work yet Library Name: elmoreinclib #111 -------------------------------------------------------------------------- Author: Richard T Elmore, HeadSoft, 126 STATE ST. #20, SPEARFISH, SD 57783, USA OverView: This is a crippled version of a library which Richard has put a whole heap of time into. It basically allows you to include compressed object data into your programs which you can unpack at your leisure. Please see the registration material at the bottom of this file if you like what you see. Demo, util and lh.library are in userlibprogs/elmore. Commands: INCSOUND INCNEXTSHAPE FREEINCDATA INCBITMAP INCTEXT$ SAVEINCDATA INCMOD INCDATA INCMED INCSIZE INCSHAPE INCDATAABS USING THE INCLUDE-UTIL PROGRAM Author's Docs: ABOUT INCLUDE.ELMORELIB ========================= The Include library by Richard T. Elmore of HeadSoft Software enables Blitz2 programmers to make stand-alone files that don't require special directories, external IFF files, etc. to run. To achieve this in the most efficient manner possible, the incredible efficiency and speed of the LH.Library is used (in the INCLUDE-UTIL tool, which is freely distributeable.) At present, the Include library supports Bitmaps, (up to 8 bitplanes!) sound effects, MED music modules, IFF brushes for Blitz2 SHAPES, Blitz2 SHAPES-FILES for multiple shapes, (as created by the SAVESHAPES command or with the SHAPESMAKER utility) entire ASCII text files, or raw binary data which gives the advanced programmer the ability to include other object types or other data such as executeable programs, variable arrays for cosine tables, etc. The library was designed with Blitz2's INCBIN compiler directive, but may also be used with data loaded with READMEM or similar commands, to conserve disk space when you don't mind having external files, not to mention they will be made next to impossible to "rip" by anyone without the Include Library! NOTE: Your executeables do NOT require the "lh.library" to run... They will have their own self-contained decrunching routine (which is much faster than the crunching routine in lh.library!) USING THE INCLUDE-UTIL PROGRAM ================================ In order to include the above-mentioned data in your Blitz2 executeables, the original data files must be converted and packed so that the resulting runtime program consumes the least memory possible. This also allows the data to be stored in public or "fast" memory, not just CHIP ram. The INCLUDE-UTIL program is supplied with the library to convert the data for you. First, ensure the "LH.Library" file resides in your LIBS: directory. The INCLUDE-UTIL program will crash if it isn't availble. In order to run the program, just click on it's icon, and a custom screen will appear containing icons representing the types of data you wish to convert to includeable data. Note that the ST/NT Module button is ghosted, as this data type is not supported in the public domain release of the library. You may note there is a gadget to "quit" even though there is also a "close" gadget in the top-left of the main window. Clicking the close- gadget will NOT quit the program, it will merely close the window and screen, then an icon will appear on the Workbench screen. Simply click the icon to reactivate the program. (While in this idle mode, INCLUDE- UTIL uses no processor time and consumes less memory.) Upon clicking one of the other icons, a file requester will appear prompting you to select a source file (the IFF, text, MOD, whatever) to convert. Note that you may load either IFF brushes *OR* BB2 shapes-files in the SHAPES filerequester, the appropriate INCLUDE-OBJECT type will be created. After the file has been converted to it's INCLUDE-OBJECT form, you will be given a filerequester to SAVE the object with. Note that an INCLUDE- OBJECT extension will be appended to the filename to help you more easily recognise the object types in a directory listing. They are: .ISFX - Sound effects .IBMP - Bitmaps .ISHP - Single shapes .ISHPS - Multiple shapes .IMED - MED modules .IBIN - Either binary or text (IncText$, IncDataABS, IncData, etc.) The INCLUDE-UTIL program accepts tooltypes for default paths. Then whenever you click on an appropriate gadget the file requester will use the path you prefer. The following keywords identify the paths: SOUNDS=pathname BITMAPS=pathname SHAPES=pathname MODULES=pathname BINARIES=pathname SAVE=pathname (This is the same path for saving all object types) You should keep the name of this utility "INCLUDE-UTIL" or the tooltype preferences will not be available. A few features are available under OS2.0 and above only: Notably, when you iconify INCLUDE-UTIL, it uses a real appicon, so you can drag objects onto it to have them automatically identified and loaded. You can also simply double-click the icon without dragging anything if you just want to wake the program up. Now that you have your INCLUDE-OBJECTs, how do you go about making them part of your Blitz2 executeables? It is relatively simple, but you must be careful to follow these guidelines unless you know EXACTLY what you're doing or you'll crash your Amiga! 1. Place a copy of Include.ElmoreLib in your Blitzlibs:Userlibs directory, then optionally create a new DEFLIBS file. 2. Write and debug your program using normal loading routines until you're satisfied with it. No need to use INCLUDE-OBJECTs during debugging, as it will only slow down development. (Before being made executeable, Blitz2 will both load the objects from disk AND decrunch them.) 3. Go to the end of your sourcecode (usually the safest place) and select a different program label for EACH INCLUDE-OBJECT to be decrunched at run-time. Directly following the label, enter INCBIN "filename" which should reference the name you saved the INCLUDE-OBJECT as from INCLUDE-UTIL. See page 8-3 of your Blitz2 reference manual for details on INCBIN and INCDIR commands if you're not familiar with them. 4. Ensure you have an "END" statement or some such before your fist INCLUDE-OBJECT's label. If program flow continues into the data, you will almost surely have a crash. 5. Replace your Blitz2 DOS-based loading commands with the approriate Include library versions. It's wise to check the results of those commands that return "success" or "failure" (TRUE or FALSE) so that your program can exit gracefully if there isn't enough memory, etc. when its run. 6. That's all! You should be able to run your program normally, and executeables you create will run fine with graphics, sounds, whatever you want, and *NO* external files needed!! Of course since all the data is included in the size of the executeable, it will be much larger than usual. (Size of INCLUDE-OBJECTs+normal executeable size) You may have some success crunching the entire executeable with PowerPacker or similar programs, but if the percentage of INCLUDE-OBJECT data in the executeable is very high, most crunchers will choke on it, since most of the program is already crunched by INCLUDE-UTIL. Function/Statement: Incsound -------------------------------------------------------------------------- Syntax: success=IncSound(Sound#, ?Label) IncSound Sound#, ?Label Description: Ensure you put the question mark before the label name or you'll have errors! The actual include-object should be INCBINed directly after the label, and be careful to put an END statement somewhere above your INCBIN data or you'll crash! Example: If IncSound(0,?Mysound)=False Then End ;Unpack the sound or end! Sound 0,15 ;Play it back! Mousewait ;pause for the user.... End Mysound: IncBin "RAM:SoundEffect.isfx" NOTE: In the above example the FUNCTION version was used so you could test it with an IF/THEN statement to see if it was successful... If you don't think you'll need to be so careful, the STATEMENT version would be: Example: IncSound 0,?Mysound ;Unpack the sound (Note no parentheses for statement!) Sound 0,15 ;Play it back! Mousewait ;pause for the user.... End Function/Statement: IncBitmap -------------------------------------------------------------------------- Syntax: success=IncBitmap(bitmap#,?Label) IncBitmap bitmap#,?Label Description: Nearly identical in useage to IncSound (above) Note that if the bitmap already exists, it should be the same dimensions such as 640x256x4 or IncBitmap will return FALSE (for failure) if you don't know for sure, you can let IncBitmap create the bitmap exactly like it was Included by doing FREE BITMAP 0 or some such before you INCBITMAP it. Example: Blitz If IncBitmap(0,?Mypicture)=0 Then End Slice 0,32,4 Show 0 Mousewait:end Mypicture: IncBin "RAM:Picture.ibmp" Function/Statement: IncMod -------------------------------------------------------------------------- Syntax: success=IncMod(ST-NT Module#,?Label) IncMod Module#,?Label Description: Like the above examples, only for music mods. You could then use StartModule etc. just as if you had loaded it from disk. ----------- NOTE: This function is a bit buggy, so it has been temporarily disabled with this release of the library! (Sorry!) -------------------------------- Function/Statement: IncMed -------------------------------------------------------------------------- Syntax: success=IncMed(MEDModule#,?Label) IncMed MedModule#,?Label Description: For including MED modules. Usage is otherwise the same as IncMod. Function/Statement: IncShape -------------------------------------------------------------------------- Syntax: success=IncShape(Shape#,?Label[,Cookiecut?]) IncShape Shape#,?Label[,Cookiecut?] ^^^^ OPTIONAL DUMMY VALUE Description: The one you've been waiting for! Will retrieve the shape# for BLITTING... Along with the command below, IncNextShape, you can even include several shapes in one step! I will be adding multiple shapes as an option in the INCLUDE-UTIL program as well... For now, just INCBIN as many shapes as you want (only need label for the first one) Note: If you don't need a cookiecut for the shape, you can leave out the CookieCut parameter. Any number placed in the cookiecut parameter will cause a cookiecut to be made for the shape when it is made however. If you plan to do BLITs etc. you should always use the cookiecut. Function: IncNextShape -------------------------------------------------------------------------- Syntax : success=IncNextShape [CookieCut?] ^^^^^^^^^^^^ OPTIONAL DUMMY VALUE Example: ;Include shape #0 IncShape(0,?Shapes,1) ;Will loop 3 times from shape #1 to #3 in this case While IncNextShape(1):Wend ;(Do your blitting stuff etc. here) End Shapes: IncBin "Shape0.ISHP" IncBin "Shape1.ISHP" IncBin "Shape2.ISHP" IncBin "Shape3.ISHP" ;(Note this is a FUNCTION only, no statement version) Function: IncText$ -------------------------------------------------------------------------- Syntax : string$=IncText$(?Label[,optional length]) Description: Used with BINARY include types.... You can then put whole text files into strings. The optional LENGTH will limit then string length to whatever number you want, similar to the LEFT$ function. It will only return a null-string "" in case of failure. Example: a$=IncText$(?text) Nprint a$ b$=IncText$(?text2,32) Nprint b$ Mousewait:End text: IncBin "Message.IBIN" text2: IncBin "Greetz.IBIN" Function/Statement: SaveIncData -------------------------------------------------------------------------- Syntax: success=SaveIncData(Filename$,?Label) SaveIncData Filename$,?Label Description: This will write to disk the unpacked version of whatever BINARY include-object you specify. One good use of this is to save programs to RAM and then EXECUTE them, and DELETE them again. Of course there are hundreds of uses.... If SaveIncData("Ram:newfile",?executeable)=0 Then End Execute_ "Ram:Newfile" KillFile "Ram:Newfile" End executeable: IncBin "myprog.ibin" Function: IncData -------------------------------------------------------------------------- Syntax : Address=IncData(?Label,memory type) Description: This allows you to include BINARY data for any number of uses that aren't provided with the other functions. Memory types are: 0- Any kind of memory (preferably FAST RAM) 2- CHIP RAM ONLY! This function will return the address of the binary data in memory, or 0 for failure.... Example of including a pure ASM routine object file for execution: asmloc.l=IncData(?mlroutine,0) Call asmloc End mlroutine: IncBin "Ram:MLRoutine.IBIN" Function: IncSize -------------------------------------------------------------------------- Syntax : size.l=IncSize(?Label) Description: Returns the size in bytes of the BINARY object at the specified label Among other uses, you need it if you want to FREE the uncrunched binary data. (It will automatically be freed when your program ends) Statement: FreeIncData -------------------------------------------------------------------------- Syntax : FreeIncData Size,Address Description: If you wanted to free up the memory allocated by the above IncData function, here is how you'd do it: FreeIncData IncSize(?mlroutine),asmloc Function: IncDataAbs -------------------------------------------------------------------------- Syntax : bytesize=IncDataAbs(?Label,Destination Address) Description: *********************************************************** ** ** ** A D V A N C E D : Use with caution! ** ** ** *********************************************************** This command will unpack the binary data directly to the area of memory you specify, so if you're not sure what you're doing you'll probably GURU the Amiga! However, it is very useful to fill arrays, uncrunch data directly to Banks, or whatever. Just be careful! It will return zero for failure, or the number of bytes in the binary object. I'll provide a better example of making use of this function later.... (Filling up array variables, etc.) InitBank 0,1000,0 size.l=IncDataAbs(?Binary,BankLoc(0)) Mousewait:End Binary: IncBin "binarydata.IBIN" Library Name: aaronsiconlib #62 Author : Aaron Koolen, Vision Software, 15 Day Street, Newton, Auckland, NZ OverView: Not only has Aaron kindly fixed up passing of argumens in our cliargslib but has also donated this library which similar to the Reflective Images version allows access to information from the programs workbench icon. Commands: GETICONINFO ICONTOOL$ ICONSUBTOOL$ ICONTYPE ICONSTACK ICONDEFTOOL$ Authors Documentation: AaronsIconLib ============= This library is for processing the icon (.info) files. It only provides routines for reading the data from icons, not for writing or creating new icons, which may be added later. It is most useful when used in conjunction with the ArgsLib. You can set the maximum number of allowed icon info's in the options. Also to free an IconInfo object, after a GetIconInfo use Free IconInfo # Function: GetIconInfo -------------------------------------------------------------------------- Syntax: boolean.w=GetIconInfo(icon#,iconname$) Description: This examines a .info file so you can get information about it. 'iconname$' is the name of the icon without the .info suffix and icon# is the number of the IconInfo object you want to put the data under. It will return FALSE (0) if it failed, or TRUE (-1) if it succeeded. Function: IconTool$ -------------------------------------------------------------------------- Syntax: tool$=IconTool$(icon#,toolname$) Description: Returns the respective data of the tooltype specified by 'toolname$' of IconInfo object icon#. EG If IconTool$(0,"CX_POPUP")="YES" Then Gosub PopUpWindow Function: IconSubTool$ -------------------------------------------------------------------------- Syntax: boolean.w=IconSubTool$(toolname$,subtool$) Description: Returns TRUE (-1) or FALSE (0) if the sub tool type 'subtool$' exists within the tool 'toolname$' EG If IconSubTool$(0,IconTool$(0,"FILETYPE"),"ILBM") Then file type of file was ILBM. A Subtool (My word) is one that resides in a tool type but is separated by bars (|). EG FILETYPE=PaintProgram|ILBM (PaintProgram and ILBM are "Sub Tools") IconTool$ will return the PaintProgram|ILBM part and you can then use IconSubtool$ to see if things like ILBM or PaintProgram exist in that string. NOTE: This does not require the passing if an IconInfo object, it simply requires 2 strings, so you can use it for other things too. Function: IconType -------------------------------------------------------------------------- Syntax: type.w=IconType(icon#) Description: Returns the type of IconInfo object icon#. EG NPrint IconType(0) 'type' is one of the list from workbench/workbench.bb2. Function: IconStack -------------------------------------------------------------------------- Syntax: stackSize.l=IconStack(icon#) Description: Returns the stack sie setting of the icon. Function: IconDefTool$ -------------------------------------------------------------------------- Syntax: deftool$.w=IconDefTool$(icon#) Description: Returns the default tool of the icon. EG NPrint IconDefTool$(icon#) May print something like "blitz2:blitz2" if icon# references a Blitz2 source program. ALLOCMEM FREEMEM BANK FROMCLI BLOCKSCROLL GAMEB CLIPBLITMODE GTARROWSIZE CUSTOMCOLORS GTSTATUS CUSTOMSTRING INITPALETTE CYCLEPALETTE INITSHAPE DECODEILBM LOADBANK DECODEMEDMODULE NUMPARS DECODEPALETTE PALETTERANGE DECODESHAPES PAR$ DECODESOUND PARPATH$ DISPLAYDBLSCAN POPINPUT DISPLAYRAINBOW POPOUTPUT DISPLAYRGB READSERIALMEM DISPLAYSCROLL SAVEPALETTE DISPLAYUSER SETPERIOD DUPLICATEPALETTE WRITESERIALMEM FADEPALETTE Function: Bank -------------------------------------------------------------------------- Syntax : Bank(Bank#) Returns the memory location of the given memory Bank, replaces the older and more stupidly named BankLoc command. Statement: BlockScroll -------------------------------------------------------------------------- Syntax : BlockScroll X1,Y1,Width,Height,X2,Y2[,BitMap#] library: scrolllib Description: Same as the Scroll command except that BlockScroll is much faster but only works with 16 bit aligned areas. This means that X1, X2 and Width must all be multiples of 16. Useful for block scrolling routines that render the same blocks to both sides of the display, the programmer can now choose to render just one set and then copy the result to the other side with the BlockScroll command. Statement: ClipBlitMode -------------------------------------------------------------------------- Syntax : ClipBlitMode BPLCON0 Library : 2dlib Description: Same as BlitMode except applies to the ClipBlit command. Another oversight now fixed. Statement: CustomColors -------------------------------------------------------------------------- Syntax : CustomColors CopList#,CCOffset,YPos,Palette,startcol,numcols Library : displaylib Using the custom copper space in a display, CustomColors will alter the displays palette at the given YPos. The number of customcops required is either 2+numcols for ecs displays and 2+n+n+n/16 for aga displays. In aga, numcols must be a multiple of 32. Note that large AGA palette changes may take several lines of the display to be complete. Statement: CustomString -------------------------------------------------------------------------- Syntax : CustomString CopList#,CCOffset,YPos,Copper$ Library : displaylib Description: CustomString allows the user to insert their own copper commands (contained in a string) into the display's copper list at a given vertical position. The amount of space required is equal to the number of copper instructions in the Copper$ (length of string divide by 4) plus 2 which of course have to be allocated with InitCopList before CustomString is used. Statement: CyclePalette -------------------------------------------------------------------------- Syntax : CyclePalette Palette# Library : palettelib Description: CyclePalette uses the standard color cycling parameters in the palette object to cycle the colors. Unlike the Cycle command which copied the resulting palette to the current screen the CyclePalette command just modifies the palette object and can hence be used with the DisplayBitmap command in the new Display library. Statement: DecodeILBM -------------------------------------------------------------------------- Syntax : DecodeILBM BitMap#,MemoryLocation Library : ilbmifflib Description: A very fast method of unpacking standard iffilbm data to a bitmap. Not only does this command allow a faster method of loading standard IFF files but allows the programmer to "incbin" iff pictures in their programs. See the discussion above for using DecodeILBM on both files and included memory. Statement: DecodeMedModule -------------------------------------------------------------------------- Syntax : DecodeMedModule MedModule#,MemoryLocation Library : medlib Description: DecodeMedModule replaces the cludgemedmodule, as med modules are not packed but used raw, DecodeMedModule simply checks to see the memorylocation passed is in ChipMem (if not it copies the data to chip) and points the Blitz2 MedModule object to that memory. Statement: DecodePalette -------------------------------------------------------------------------- Syntax : DecodePalette Palette#,MemoryLocation[,Palette Offset] Library : palettelib Description: DecodePalette allows the programmer to unpack included iff palette information to Blitz2 palette objects. Statament: DecodeShapes -------------------------------------------------------------------------- Syntax : DecodeShapes Shape#[,Shape#],MemoryLocation Library : shapeslib Description: DecodeShapes, similar to DecodeMedModule ensures the data is in chip and then configures the Shape object(s) to point to the data. Statement: DecodeSound -------------------------------------------------------------------------- Syntax : DecodeSound Sound#,MemoryLocation Library : audiolib Description: DecodeSound similar to the other new Decode commands allows the programmer to include sound files within their program's object code. Statement: DisplayDblScan -------------------------------------------------------------------------- Syntax : DisplayDblScan CopList#,Mode[,copoffset] Library : displaylib Description: DisplayDblScan is used to divide the vertical resolution of the display by 2,4,8 or 16 using Modes 1,2,3 and 4. This is most useful for fast bitmap based zooms. A Mode of 0 will return the display to 100% magnification. As with the DisplayRainbow, DisplayRGB, DisplayUser and DisplayScroll commands DisplayDblScan uses the new line by line copper control of the display library. To initialise this mode a negative parameter is used in the CustomCops parameter of the InitCopList command. DisplayDblScan requires 2 copper instructions per line (make CustomCops=-2). Statement: DisplayRainbow -------------------------------------------------------------------------- Syntax : DisplayRainbow CopList#,Register,Palette[,copoffset] Library : displaylib Description: DisplayRainbow is used to alter a certain colour register vertically down a display. It simple maps each colour in a palette to the coresponding vertical position of the display. ECS displays require one copper instruction per line while AGA displays require 4. Statement: DisplayRGB -------------------------------------------------------------------------- Syntax : DisplayRGB CopList#,Register,line,r,g,b[,copoffset] Library : displaylib Description: DisplayRGB is a single line version of DisplayRainbow allowing the programmer to alter any register of any particular line. As with DisplayRainbow ECS displays require 1 copper instruction while AGA requires 4. Statement: DisplayScroll -------------------------------------------------------------------------- Statement: DisplayScroll CopList#,&xpos.q(n),&xpos.q(n)[,Offset] Library : displaylib Description: DisplayScroll allows the program to dynamically display any part of a bitmap on any line of the display. DisplayScroll should always follow the DisplayBitMap command. The parameters are two arrays holding a list of xoffsets that represent the difference in horizontal position from the line above. AGA machines are able to use the fractional part of each entry for super hiresolution positioning of the bitmap. Three instructions per line are required for the DisplayScroll command. Statement: DisplayUser -------------------------------------------------------------------------- Syntax : DisplayUser CopList#,Line,String[,Offset] Library : displaylib Description: DisplayUser allows the programmer to use their own Copper$ at any line of the display. Of course copper instructions have to be allocated with the number of copper instructions in the InitCoplist multiplied by -1. Statement: DuplicatePalette -------------------------------------------------------------------------- Syntax : DuplicatePalette SrcPalette#,DestPalette# Library : palettelib Description: DuplicatePalette simply creates a new Palette which exactly matches the SrcPalette. Statement: FadePalette -------------------------------------------------------------------------- Syntax : FadePalette SrcPalette#,DestPalette#,Brightness.q Library : palettelib Description: FadePalette multiplies all colours in a Palette by the Brightness argument and places the result in the DestPalette. Statement: FreeMem -------------------------------------------------------------------------- Syntax : FreeMem location,size Library : banklib Description: Used to free any memory allocated with the AllocMem command. Function: FromCLI -------------------------------------------------------------------------- Function: FromCLI Library : cliargslib Description: Returns TRUE (-1) if your program was run from the CLI, or FALSE (0) if run from the WorkBench. Function: GameB -------------------------------------------------------------------------- Syntax : GameB(por#) Library : gameiolib Description: Returns button state of cd32 style game controllers - values returned are: 1 = play/pause 2 = reverse 4 = forward 8 = green 16 = yellow 32 = red 64 = blue If more than one button is held down, values are added together. For example, a value of 6 means both the forward (4) and reverse (2) buttons are held down. Use an 'and' to isolate the status of a single button, like this - ;check RED button on port 1... ; if gameb(1) & 32 ; ;RED button is down... ; else ; ;RED button is NOT down... ; endif Statement: GTArrowSize -------------------------------------------------------------------------- Syntax : GTArrowSize size Library : bbgtlib Description: Allows the size of GTScroller arrows to be preset. Default size is 16. Function: GTStatus -------------------------------------------------------------------------- Syntax : GTStatus(GTList#,Id) Library : bbgtlib Description: GTStatus returns the status of and gadtools toggle gadgets, a value of 1 means the the gadget is selected, 0 deselected. Statement: InitPalette -------------------------------------------------------------------------- Syntax : InitPalette Palette#,NumColors Library : palettelib Description: InitPalette simply initialises a palette object to hold NumColors. All colors will be set to black. Statement: InitShape -------------------------------------------------------------------------- Syntax : InitShape Shape#,Width,Height,Depth Library : shapeslib Description: InitShape has been added to simple create blank shape objects. Programmers who make a habit of using ShapesBitMap to render graphics to a shape object will appreciate this one for sure. Statement: LoadBank -------------------------------------------------------------------------- Syntax : LoadBank Bank#,FileName$[,MemType] Description: The LoadBank command has been modified, instead of having to initialise the bank before loading a file, LoadBank will now initialise the bank to the size of the file if it is not already large enough or has not been initialised at all. Function: NumPars -------------------------------------------------------------------------- Syntax : NumPars Library : cliargslib Description: Returns the number of parameters passed to your program. Statement: PaletteRange -------------------------------------------------------------------------- Syntax : PaletteRange Palette#,StartCol,EndCol,r0,g0,b0,r1,g1,b1 Library : palettelib Description: PaletteRange creates a spread of colors within a palette. Similar to DPaint's spread function PaletteRange takes a start and end colour and creates the color tweens between them. Function: Par$ -------------------------------------------------------------------------- Syntax : Par$(parameter#) Library : cliargslib Description: Returns the string value of a parameter. NOTE: If the parameter asked for is a directory/device/volume etc (IE NOT A FILE) then Par$(#) will return an empty string. This is a one way you can check to see if a file was passed or not. Function: ParPath$ -------------------------------------------------------------------------- Syntax : ParPath$ (parameter,type) Library : cliargslib Description: This returns the path that this parameter resides in. 'type' specifies how you want the path returned. 0 You want only the directory of the parameter returned. 1 You want the directory along with the parameter name returned. EG: If you passed the parameter "FRED" to your program from WorkBench, and FRED resides in the directory "work:mystuff/myprograms" then ParPath$(0,0) will return "work:mystuff/myprograms", but ParPath$(0,1) will return "work:mystuff/myprograms/FRED". CAVEAT The way WB handles argument passing of directories is different to that of files. When a directory is passed as an argument, ArgsLib gets an empty string for the name, and the directory string holds the path to the passed directory AND the directory name itself. EG Passing the blitz2 directory to a program will result in: Par$(x) Being an empty string. ParPath$(x,0) Being something like work:Basic/blitz2. ParPath$(x,1) Being work:Basic/blitz2/ YES! The / is appended! This is because to keep things simpler, and more uniform ParPath$(x,1) Is the concatenation of 1) The directory string passed by Workbench AND 2) A / followed by the name given by WorkBench. So you can see why the / followed by the empty string occurs. The easy way around this is simply to check Par$(x), if it is empty, then use ParPath$(x,0), if it isn't (IE a file was passed) use ParPath$(x,1) and you will have the entire pathname of the file OR directory. See the demo program, which handles both cases. NOTE 2: Is only useable from WorkBench, you will get an error if your program was run from the CLI and you try to call ParPath$. Statement: PopInput & PopOutput -------------------------------------------------------------------------- Library : inputoutputlib Description: After input or output has been re-directed (eg using windowoutput/ fileoutput), these two commands may be used to return the channel to it's previous condition. Statement: ReadSerialMem -------------------------------------------------------------------------- Syntax : ReadSerialMem Unit#,Address,Length Library : seriallib Description: ReadSerialMem will fill the given memory space with data from the given serial port. Statement: SavePalette -------------------------------------------------------------------------- Syntax : SavePalette Palette#,FileName$ Library : iffmakelib Description: Creates a standard IFF "CMAP" file using the given Palette's colors. Statement: SetPeriod -------------------------------------------------------------------------- Syntax : SetPeriod Sound#,Period Library : audiolib Description: Hmmm, not sure why we never included this command in the original audiolib, SetPeriod simply allows the user to override the frequence information (period) of the sound object after it has been loaded. To alter a sound's pitch while playing programmers should hit the audio hardware direct (hardware locations are listed at the back of the reference manual). Statement: WriteSerialMem -------------------------------------------------------------------------- Syntax : WriteSerialMem Unit#,Address,Length Library : seriallib Description: WriteSerialMem send the given memory space out the given serial port. All the commands are now sorted, few that was a lot of work! But what the hell, it's finished now (until a new BUM is released) Choose a letter: A N B O C P D Q E R F S G T H U I V J W K X L Y M Z - A - ACTIVESCREEN ANIMLOOP ACTIVEWINDOW APPEVENT ADDAPPICON APPICONEVENT ADDAPPMENU APPICONFILE ADDAPPWINDOW APPICONHIT ADDVALUE APPMENUEVENT AGABLUE APPMENUFILE AGAFILLPALETTE APPMENUHIT AGAGREEN APPWINDOWEVENT AGAPALBLUE APPWINDOWFILE AGAPALGREEN ASLFILEREQUEST AGAPALRED ASLFONTREQUEST AGAPALRGB ASLSCREENREQUEST$ AGARED ATTACHGTLIST AGARGB AVG ALLFIRE AVG.L ALLOCMEM AVG.Q ANALYZEDISK - B - BANK BEEPSCREEN BIN# BITMAPTOWINDOW BITPLANESBITMAP BLITCOLL BLOAD BLOCK BLOCKSCROLL BSAVE BUTTONGROUP BUTTONID - C - CACHEOFF CLOSEDISK CRMDECRUNCH CACHEPCF CLOSESCREEN CUSTOMCOLORS CHARCOUNT CLOSESERIAL CUSTOMSTRING CHDIR CLOSEWINDOW CXAPPEAR CHECKAGA CLUDGESHAPES CXCHANGELIST CHECKPRT CLUDGESOUND CXDISABLE CHECKSUM COLOURREQUEST CXDISAPPEAR CHIPFREE COMMODITIEBASE CXENABLE CHUNKHEADER COMMODITYEVENT CXKILL CHUNKYTOPLANAR CON_BASE CXUNIQUE CIPHER$ COPYBYTE CYCLEPALETTE CLEARBITMAP COPYFILE CLEARREXXMSG COPYLONG CLEARTOOLTYPES COPYWORD CLICKMOUSE CREATEARGSTRING CLIPBLIT CREATEDISPLAY CLIPBLITMODE CREATEMSGPORT CLOSECONSOLE CREATEREXXMSG - D - DATE$ DEREZ DISPLAYUSER DATEFORMAT DISABLE DOSBASE DAYS DISKBLOCKS DOS_BASE DECODEILBM DISKCAPACITY DUPLICATEPALETTE DECODEMEDMODULE DISKERRS DECODEPALETTE DISKFONTBASE DECODESHAPES DISKFREE DECODESOUND DISKUNIT DECRYPT DISKUSED DEICE DISPLAYADJUST DELAPPICON DISPLAYBITMAP DELAPPMENU DISPLAYCONTROLS DELAPPWINDOW DISPLAYDBLSCAN DELETEARGSTRING DISPLAYPALETTE DELETEMSGPORT DISPLAYRAINBOW DELETEREXXMSG DISPLAYRGB DEPLODE DISPLAYSCROLL DEPTH DISPLAYSPRITE - E - EASYREQUEST EXCHANGEDISABLE ENABLE EXCHANGEDISAPPEAR ENCRYPT EXCHANGEENABLE ENTRYBIT$ EXCHANGEKILL ENTRYCOMMENT$ EXCHANGEMESSAGE ENTRYDATE EXCHANGEUNIQUE ENTRYDIR EXECVERSION ENTRYHOUR EXISTS ENTRYMINS ENTRYNAME$ ENTRYSECS ENTRYSIZE ERASE ERASEALL EVENTCODE EVENTQUALIFIER EXCHANGEAPPEAR EXCHANGECHANGELIST - F - FADEINBITMAP FNSLENGTH FREEINCDATA FADEPALETTE FNSLOAD FREEMEM FASTFREE FNSORIGIN FREEPCFCACHE FFPBASE FNSOUTPUT FREEZONETABLE FILEFILTER FNSPREFS FREQ FILEREQSIZE FNSPRINT FROMCLI FILESIZE FNSSETTAB FILESTRUCTURE FNSSLOT FILLMEM FNSUNDERLINE FILLPALETTE FNSUNLOAD FILLREXXMSG FNSVERSION FINDTOOLNUMBER FNSWIDTH FINDTOOLTYPE FORCENTSC FINDTOOLVALUE FORCEPAL FNSCLIP FORMATTRACK FNSCLIPOUTPUT FRAMES FNSHEIGHT FREECATALOG FNSINK FREEICONOBJECT - G - GAGETSTATUS GTCHANGELIST GAMEB GTGADPTR GETICONINFO GTSETATTRS GETICONOBJECT GTSTATUS GETLOCALESTR GTTAGS GETMEDINSTR GETMEDNOTE GETMEDVOLUME GETRESULTSTRING GETREXXCOMMAND GETREXXRESULT GETSTRING$ GETSUPERBITMAP GETWHEEL GFX_BASE GRAPHICSBASE GTARROWSIZE GTBEVELBOX - H - HARDCOPY HEX# HIDESCREEN HOTKEYHIT HOURS - I - ICONBASE INCSHAPE ICONDEFAULTTOOL INCSIZE ICONDEFTOOL$ INCSOUND ICONRENDER INCTEXT$ ICONSTACK INITANIM ICONSUBTOOL$ INITCOPLIST ICONTOOL$ INITPALETTE ICONTYPE INITSHAPE ILBMGRAB INITZOOMXY ILBMPALETTE INSTALLFNS ILBMVIEWMODE INTUITIONBASE IMPLODE INT_BASE INCBITMAP ISEVEN INCDATA ISLOCALE INCDATAABS ISREQTOOLSACTIVE INCMED ISREXXMSG INCMOD INCNEXTSHAPE - J - JFIRE JHORIZ JOYC JUMPMED JVERT - K - KEYCODE - L - LARGEST LARGEST.L LARGEST.Q LARGESTFREE LENGTH LISA LOADANIM LOADFONT LOADIFF LOADIFF LOADMEDMODULE LOADPCF LOADSHAPE - M - MAKECOMMODITY MAKEDIR MATCHTOOLVALUE MAX MEMFREE MIN MINS MONTHS MOREENTRIES MOTOROFF MOTORON MOVESCREEN - N - NAMEFILE NEWPALETTEMODE NEWTOOLTYPE NEWZONETABLE NEXTBANK NEXTFILE$ NEXTFRAME NPRINTCON NULL NUMDAYS NUMPARS - O - OPENCONSOLE OPENDISK OPENSERIAL - P - PALADJUST PLOAD PALBLUE POLY PALETTEINFO POLYF PALETTERANGE POPINPUT PALGREEN POPOUTPUT PALRED POSITIONSUPERBITMAP PAR$ PPDECRUNCH PARPATH$ PRINTCON PATHLOCK PROCESSOR PCFDEPTH PRTCOMMAND PCFHEIGHT PRTTEXT PCFINFO PUTICONOBJECT PCFVERSION PUTSUPERBITMAP PCFWIDTH PEEKTO$ PHONETICSPEAK PLANARTOCHUNKY PLAYMED - Q - QUIET - R - READSECTOR REQUEST RTEZFLAGSREQUEST RTREQUEST READSERIAL REQ_BASE RTEZFONTREQUEST RTREVISION READSERIALMEM RESERVE RTEZFREEPATTERN RTUNLOCKWINDOW READSERIALMEM RESETTIMER RTEZGETLONG RTVERSION READSERIALSTRING REXXERROR RTEZGETLONGRANGE RUNERRSOFF REBOOT REXXEVENT RTEZGETSTRING RUNERRSON REDUCEX2 REXXSYSBASE RTEZLOADFILE REMAP REX_BASE RTEZMULTILOADFILE REMOVEFNS RIANIMINIT RTEZPALETTEREQUEST RENAME RINEXTANIMFRAME RTEZPATHREQUEST REPEATS RRANDOMIZE RTEZREQUEST REPLYREXXMSG RRND RTEZRNEXTPATHENTRY REQCOLOURS RTASYNCPALETTEREQUEST RTEZSAVEFILE REQFILELOC RTASYNCREQUEST RTEZSCREENMODEREQUEST REQFILEREQUEST RTCHECKASYNCPALETTEREQUEST RTEZSETDEFAULTDIRECTORY REQFILEREQUEST$ RTCHECKASYNCREQUEST RTEZSETPATTERN REQFONTSIZE RTENDASYNCPALETTEREQUEST RTFILEREQUEST REQOUTPUT RTENDASYNCREQUEST RTLOCKWINDOW - S - SAVEINCDATA SETMEDVOLUME SPACE$ SAVEPALETTE SETPERIOD SPEAK SCREENHEIGHT SETSERIALBUFFER SPRITEMODE SCREENTAGS SETSERIALLENS START SCREENWIDTH SETSERIALPARAMS STARTMEDMODULE SEARCHBEGIN SETSTATUS STOPMED SEARCHEND SETTOOLVALUE SYSTEMDATE SEARCHSTRING SETVOICE SECS SETZONE SENDREXXCOMMAND SHAPEGADGET SERIALEVENT SHAPETOICON SETBPLCON0 SHOWBITMAP SETCOPYBUFFER SHOWPALETTE SETGADGETSTATUS SHOWREQUESTORS SETHOTKEY SMALLEST SETICONHIT SMALLEST.L SETICONTYPE SMALLEST.Q SETMEDMASK SORTLIST - T - TEXTREQUEST TEXTTIMEOUT TICKS TIMER TRANSLATE$ - U - UNPACKIFF UNPACKPCF USECATALOG USEZONETABLE - V - VOICELOC VPOS VWAITPOS - W - WAIT WAITFOR WBDEPTH WBHEIGHT WBLIT WBVIEWMODE WBWIDTH WEEKDAY WINDOW WPRINTSCROLL WRITEBOOT WRITESECTOR WRITESERIAL WRITESERIALMEM WRITESERIALMEM WRITESERIALSTRING WTITLE - X - XOR XOR - Y - YEARS - Z - ZONE ZONEINIT ZONETABLE ZONETABLESIZE ZONETEST ZOOMX2 ZOOMX4 ZOOMX8 ZOOMXY