Easylife Command Quick Reference ================================ 1. ZONES & MULTI ZONES ---------------------- X1 = ElZnsx(N) Y1 = ElZnsy(N) X2 = ElZnex(N) Y2 = ElZney(N) These functions return the co-ordinates of screen zone N on the current screen, set with "Set Zone N,X1,Y1 To X2,Y2". X1 = ElZnsx(S,N) Y1 = ElZnsy(S,N) X2 = ElZnex(S,N) Y2 = ElZney(S,N) These functions return the co-ordinates of screen zone N on screen no S. ElZn Shift S,DX,DY ElZn Shift S,DX,DY,FIRST To LAST The first function moves all zones on screen S by DX pixels horizontally, and DY pixels vertically. The second only affects zones FIRST To LAST. NOTE: This function does not actually scroll the graphics in the zone, It just changes the zones co-ordinates quickly, e.g. To keep the zone stationary relative to a scrolling background. ElMz Reserve NUMZONES This command reserves NUMZONES easylife Multi Zones. These are an alternative to standard AMOS screen zones, and cannot be used at the same time on the same screen as AMOS screen zones. The main differences are than multi zones to not just have a number, but a GROUP number, and an ID number, either of which can be between - and 65535. This command sets the total number of zones that space is reserved for - they can have any GROUP/ID number - they don't have to be consecutive. THe main advantags of multi zones are that you can scan for a point being in only one group of zones, and that if they overlap, you can find all the zones a point lies in, not just the first. The disadvantages are that they are slower than AMOS zones, and you must specify the co-ordinates to test - there is no Mouse Zone equivilent. ElMz Set Zone GROUP,ID,X1,Y1 To X2,Y2 ElMz Set Zone GROUP,ID The first of these commands sets the co-ordinates of a multi zone. The second removes a multizone from the reserved zones. =ElMznsx(GROUP,ID) =ElMznsy(GROUP,ID) =ElMznex(GROUP,ID) =ElMzney(GROUP,ID) These return the co-ordinates of a multi zone. ElMz Erase GROUP This command erases all multi zones in a group. =El MZone(X,Y) =El MZone(X,Y,GROUP) The first of these functions returns the first mutli zone containing the point (X,Y). The second only searches the zones of group G. Both return the zone ID number, or 0 if no zone is found that contains the point. e.g. MZ=El MZone(X Screen(X Mouse),Y Screen(Y Mouse)) =El MZoneN This function returns the ID number of the next zone that contains the point given in the previous MZone function, or 0 if there are no more zones that contain the point. =El MZoneG This function returns the GROUP number of the last zone returned by a =ElMZone / =ElMZoneN function. Zone Banks ---------- Zone banks are created by the Zone Editor Accessory Program, and like multi zones, contain zones identifed by GROUP and ID numbers, however in a zone bank, GROUP numbers must be consecutive, as must ID numbers. Elzb Add SCREEN,BANK,GROUP This function erases the AMOS screen zones on SCREEN, and replaces them with all the zones the group identifer GROUP from the zone bank no. BANK. They can then be used as if they can be created with Reserve Zone/Set Zone. Elzb Multi Add BANK,GROUP This function adds the group of zones to the multi zones of the current screen, replacing any existing zones which have the same GROUP & ID as the zones being installed. You must have already reserved an adequate number of multi zones. Elzb Install BANK This command installs all groups from the bank as multi zones on the current screen, erasing all existing zones & multi zones first. 2. CHARACTER SEARCHING - The (E)asy (L)ife (F)ind functions ----------------------------------------------------------- = Elf Asc(S$,A) = Elf Asc(S$,A,P) This function searches for the first occurance of a character with AscII code A in S$. The second variation starts at position P+1. If the character is found, the function returns it's position, otherwise it returns 0. NOTE: The second function begins at position P+1, not P, so if position P contains the character, it is ignored. This may seem wierd behaviour, and is different from AMOS's =Instr, but I find it much more usefull because often you want to find each occurance of the character, and with this arangement, to find the next, you pass the position of the lat in P. = Elf Not Asc(S$,A) = Elf Not Asc(S$,A,P) These is the inverse of the last functions, and return the position of the first character in S$ that doesn't have AscII code A. Usefull for skipping spaces in unformatted input. = Elf Last Asc(S$,A) = Elf Last Asc(S$,A,P) This is similar to =Elf Asc, but searches backwards from the end of the string. (Or position P-1, if P is given). The result is still the position of the character from the start of the string. = Elf Last Not Asc(S$,A) = Elf Last Not Asc(S$,A,P) This variation searches backwards like =Elf Last Asc, for the first occurance of any character other than A. = Elf Nth Asc(S$,A,N) This function returns the position of the Nth occurance of A in S$. = Elf Num Asc(S$,A) This function returns the number of occurances of A in S$. = Elf Char(S$,A$) = Elf Char(S$,A$,P) = Elf Not Char(S$,A$) = Elf Not Char(S$,A$,P) = Elf Last Char(S$,A$) = Elf Last Char(S$,A$,P) = Elf Last Not Char(S$,A$) = Elf Last Not Char(S$,A$,P) = Elf Nth Char(S$,A$,N) = Elf Num Char(S$,A$) The =Elf Char functions are identical to their Elf Asc equivilents defined above, but searcb for any character in A$, instead of the single character with AscII code A. E.g. =Elf Last Not Char("... --- ..-.-","-.") would return 8 - the position of the last space. = Elf Control(S$) = Elf Control(S$,P) This function retrun the position of the first control character (AscII code <32) in S$. Elf Fail Start Elf Fail End After an Elf Fail End command, all these functions return the length of the string instead of 0, if the character beign searched for is not found (Except Elf Num & Elf Control commands). Elf Fail Start changes them back to the default condition of returning 0. 3. COMPRESSION -------------- Easylife can load and save Powerpacked data, using powerpacker.library in standard powerpacker data format, compatabile with powerpackers crunch as data, ppmore, and anything else that uses powerpacker.library ElPp Keep On ElPp Keep Off The first command forces the powerpacker library to remain in memory. The second cancels the forcing, but does not necessarily remove the library. ElPp Load BUF,FILENAME$,FLASH This command loads the file FILENAME$, decrunching it if it is powerpacked into easylife Powerpacker buffer No. BUF. FLASH can be: 0 = Flash colour 0 while decrunching 1 = Flash colour 1 2 = Flash colour 17 (Mouse Pointer colour 1) 3 = Wobble Screen (Has no effect on AMOS screens) 4 = Decrunch invisibly If buffer BUF is already in use, the old data will be overwritten. There are 8 buffers, numbered 0-7. =Elpp Buf(BUF) =Elpp Len(BUF) These functions do for powerpacker buffers what =Start() and =Length() do for AMOS banks. Elpp Free BUF This command erases buffer BUF if it exists. =Elpp Crunch(FILENAME$,START,LENGTH,EFFICIENCY,SPEEDUP) This function crunches the memory between START and START+LENGTH, and saves it to the file FILENAME$. EFFICIENCY is the crunch depth: 0 = Fast Crunch & Poor compressino 1 = / \ | 2 = | | 3 = | \ / 4 = Slowest Crunch & Best compression SPEEDUP is the ammount of memory to allocate to speedup crunching. If the value you select is not availble a smaller value is tried. SPEEDUP does not affect the size of the crunched file. 0 = Large (Approx 200-230k) 1 = Medium (Approx 50-60k) 2 = Small (Approx 10-12k) Elpp Allocate BUFNO,LENGTH This command manually reserves a powerpacker buffer. This is usefull in AMOS Creator as when one program calls another with Prun, the powerpacker buffers are shared, and can be used to pass data between the programs. In AMOS Pro, the powerpacker buffers are not shared. AMOS PRO ONLY ============= The AMOS Pro versino of easylife can also load and save AMOS Banks (Except Sprite & Icon Banks) using XPK compression. XPKMaster.library amd some compressor libraries are required (Get them from aminet in /util/pack) Elxpk Load FILENAME$ Elxpk Load FILENAME$,PASSWORD$ Elxpk Load FILENAME$,BNKNO Elxpk Load FILENAME$,PASSWORD$,BNKNO Loqds an XPK compressed bank from FILENAME$. You must supply a password if the file was crunched with one. The bank is loaded back to the bank number from which it was saved if no BNKNO is given. NOTE: Elxpk Load will not load uncompressed banks, as I save banks as they are stored in memory - not by using the standard AMOS bank file format & compressing it. Elxpk Save FILENAME$,METHOD$,BNKNO Elxpk Save FILENAME$,METHOD$,PASSWORD$,BNKNO These command compress and save BNKNO to a file. METHOD$ must contain the 4 letter name of a compressor to use e.g. "NUKE", or the 4 letter name, followed by a ',' and the compression factor (0-99 99=Best) E.g. "HUFF.23". If no compression factor is supplied the default for the selected compressor is used. If the compressor selected also encrypts, you should use the second form of Elxpk Save, and supply a password. Elxpk Bload FILENAME$,ADDR Elxpk Bload FILENAME$,PASSWORD$,ADDR These commands load XPK crunched data to memory at address ADDR. You must have allocated enough memory for the uncompessed file + 256 bytes. NOTE: ElXpk Bload will also load uncompressed & powerpacked data. = ElXpk Lof(FILENAME$) This returns the length of FILENAME$ when it is uncompressed. It can be used to reserve an appropriate size block of memory for ElXpk Bload. Elxpk Bsave FILENAME$,METHOD$,START To END Elxpk Bsave FILENAME$,METHOD$,PASSWORD$,START To END These commands save a block of memory using the compressor specified in METHID$ (Same format at Elxpk Save). = Elxpk Error When an error occurs in an ElXpk function, AMOS returns the error message 'An XPK error has occured'. This function returns the XPK error number, from which you can find out what went wrong, either manually, or by calling the XPK_ERROR procedure in the examples directory. 4 MEMORY & STRINGS ------------------ = ElMessage$(BANK,GROUP,MSGNO) Reads a message from a message bank, which is sort of like a resource bank for text strings only, but it if referenced by a 2 dimensional (GROUP,MSGNO) identifier, and compiled from an AscII text file by the message bank compiler program. It is also compatable with AMOS 1.36 message banks. = ElMessahe Exists(BANK,GROUP,MSGNO) Returns true if the given message exists. = Elbank Name$(BNKNO) Returns the name string of a bank (Always 8 Characters, padded with spaces). Els Bank Name BNKNO,NAME$ Changes the name of a bank. NAME$ must be 8 characters exactly. Only rename Work/Data banks, as other types may be recognised by their names. =Elmem$(START,LENGTH) =Elmem$(START,LENGTH,CHAR) Copies the memory between START and START+LENGTH into a string, and returns it. The second version only returns the memory from START to the first occurance of a character with AscII code CHAR, if such a character occurs in the first LENGTH memory addresses from START, or returns the entire block otherwise. Elmem START,STRING$ This pokes the string into memory begining at location START =Elmem Inc(START,STRING$) This also pokes the string into memory begining at location start, but returns START+Len(STRING$), enabling a series of strings to be poked into memory consectively with: S=START S=Elmem Inc(S,STRING1$) S=Elmem Inc(S,STRING2$) S=Elmem Inc(S,STRING3$) Elmem S,STRING4$ =Elwtst(BIT,ADDR) Elwset BIT,ADDR Elwclr BIT,ADDR Elwchg BIT,ADDR These are the same as the Btst,Bset,Bclr,Bchg functions, but instead of affecting bits 0-7 of the byte at address ADDR, they affect bits 0-15 of the word at address ADDR =Elltst(BIT,ADDR) Ellset BIT,ADDR Ellclr BIT,ADDR Ellchg BIT,ADDR These are the sameas the previous 4 functions, but modify bits 0-31 of the longword at address ADDR. = Elextb(BYTE) This function sign extends the 1 byte value to a longword AMOS integer. I.E. Bit 7's value is copied into bits 8-31 = Elextw(BYTE) This function sign extends the 1 word value to a longword AMOS integer. I.E. Bit 15's value is copied into bits 16-31 = ElWord$(VALUE) = ElWord(STRING$) The first function returns the value (0-65535 or -32768 - 32767) as a 2-byte string. The second convert the first 2 bytes of STRING$ back to an integer (-32768 - 32767). = ElLong$(VALUE) = ElLong(STRING$) This first function returns the value as a 4 byte string - The second returns the first 4 bytes of the string as a value. = Elpad Asc(STRING$,A,LEN) = Elpad Char(STRING$,A$,LEN) The first function adds characters AscII code A onto the end of STRING$ until it's length is >= LEN. The second function adds the first character of A$. 6. CONSOLE IO ============= = Elin Exists = Elout Exists These returns True if the standard input / standard output for AMOS exist (I.E. The CLI it was run from is open) Elout STRING$ Send the string to the standard output - I.E. prints it in the CLI. All standard AmigaDos formatting codes can be used to control colour, cursor position etc. =Elin$(NUMCHARS) Reads a string from the standard input, up to numchars (Which should be 256 for normal input), or up to the first line feed if that occur first (I.E. Where the user pressed return). =Elin Get$ Gets a single character from the standard input. RETURNCODE = Elexec(FILENAME$) This executes a file with AMOS's standard input and output, and returns the Dos return code (0=No Error). 7. PATTERN MATCHING ------------------- Easylife allows patterm matching on strings, using the pattern library. This makes it slightly different to amigados 2/3 patterns, but does make it 1.3 compatable. The same pattern matching is used by the CSH shell. The following characters may appear in a pattern: An expression in a pattern is a single character, or any string of characters in parenthesis (). Every expression will match itself, and only itself unless it contains control characters. Examples: "a" only matches the string "a" "fred" only matches the string "fred" "(hello) world" only matches the string "hello world" Control Characters: % This character matches the empty string "". Although it seems of little use, can be important when used with the | character ? This character matches any single character, is with AmigaDOS. Example: "b?b" matches the string "bab", but not "baab". # Preceeding any expression with a # means it can be repeated 0 or more times. Example: The pattern "#(ab)" matches the strings "","ab", "abab","ababab" etc. This can be combined with the ? to match anything as with AmigaDos - "#?". NOTE: If a # is the last character of a pattern, any commands attempting to use the pattern will produce an Illegal Function Call error. | This character allows alternative patterns e.g. "ab|cd" will match the strings "ab" and "cd", but nothing else. usually you will have to suround the optional patterns with parenthesis to make them appear to be a single expression. The % character can be used as an alternative to allow the empty pattern - Example: "(ab|cd|%)" matches the strings "","ab","cd" only. NOTE: If any of the alternative patterns is empty, any command using the pattern will produce an illegal function call. * This is a shortcut for the pattern "#?", and means match anything E.g. "a*" matches "a","and", etc. ~ Negates the following expression. E.g. "~(ab*)" matches "","and","bass","can", etc. and anything that doesn't begin with "ab". NOTE: "~ab*" is different to "~(ab*)", as "~ab*" matches anything that doesn't begin with "a", but does have a "b" as the second character. NOTE: If ~ is the last character of the pattern, any commands using the pattern will produce an illegal function call. [] Any string enclosed in square brackets matches any expression in the string. Example: "[abc]" matches "a", "b" and "c", but nothing else. It is a shorthand for "(a|b|c)". Remember that expressions can be single characters (As Above) or parethansised strings - Exmaple: "[(ab)c(de)]" matches "ab","c","de" only. You can also specify character ranges in square brackets, e.g "[0-9]*" will match any positive integer. This means if you want to match the "-" character, it must be either the first or last character in the brackets E.g. "[-0-9a-z ]*" means any lower case word, spaces, digits, and the "-" character. Also, if the first character in the square brackets is a ~, all characters except those in the in the brackets are matched, E.g. "[~a-z]" will match all single characters that are not lower case letters. NOTE: The string in square brackets is always treated as a single expression - you never need to put parenthesis around the square brackets. ' This character "Escapes" the next character. This means that if the next character has a special meaning in a pattern that special meaning is ignored, so "a'*" will only match the string "a*". "'" can be used to escape itself E.g. "''" matches the string "'". NOTE: You can also use ' to escape parenthesis. Important Note: All parenthesis & square brackets must be paired (Unless they are escaped), otherwise any command using the pattern will produce an illegal function call. = Elpat Case(PATTERN$,STRING$) = Elpat NoCase(PATTERN$,STRING$) These Return true if the string matches the pattern. The first is case sensitive, the second isn't. = Elpat Set Case(PATTERN$) = Elpat Set NoCase(PATTERN$) These functions set the default pattern to compare strings to. If more than one string is to be compared to the same pattern it is much quicker to use these functions than to repeadly call Elpat Case/Elpat Nocase as the pattern has to be compiled by it is compared to the string, and using these commands will only compile it once. = Elpat Def(STRING$) Returns True if the string matches the default pattern set with Elpat Set Case/Nocase. The default pattern is not affected if Elpat Case/Elpat Nocase commands are used in between seting the default pattern, and testing against it. Elpat Free This command frees the memory that holds the default pattern. =Elpat Test(PATTERN$) =Elpat Remove(PATTERN$) =Elpat Test returns True if the pattern needs to be tested with the ElPat commands. If this function returns false, then the string returned by =Elpat Remove(PATTERN$) can be used in normal AMOS string comparissons to do the pattern matching, as the pattern contained no unescaoed control characters. =Elpat Escape(STRING$) This function returns the string with all pattern control characters escaoed. 8. MISCELANOUS -------------- ElReset EXTNUM Performs the AMOS Default command on the given AMOS extension only (EXTNUM = 16 for easylife). The documentation for the extension should say what happens when it defaults. For easylife: - All fonts are unlocked. - All Powerpacker Buffers are cleared. - The Pattern library is unlocked. - The Easy Life Find commands return to Find Fail Start mode. = ElBnk Here(BNKNO) Returns true if the given bank has been reserved. = Elprotect(FILENAME$) Returns an integer representing the file protection bits of a file Bit Set Clear 0 Undeletable Deletable 1 Unwritable Writable 2 Can't Execute Can Execute 3 Unreadable Readable 4 Archived Not Archived 5 Pure Not Pure 6 Is A Script Is not a Script 7 Is Hidden Is not hidden Is you can see, the default '----rwed' will return 0. Els Protect FILENAME$,BITS This command sets the protection bits of the file to the integer BITS, the format of which is described above. =Ellock Font(FONTNAME$,FONTSIZE) This command loads the given font at the given size into memory, and prevents it from being removed by the system memory manager. It returns the true size of the font, which is in some cases different from the filename in the FONTS: directory which you specify in FONTSIZE. You may lock up to 32 fonts. Unlock Fonts This command unlocks all locked fonts. Fonts are also unlocked by the El Reset, AMOS Default and System Commands, as well as by re-runing the program. = El Base(EXTNUM) This function returns the base address of an extensions Internal Data Zone. Do not change anything there if you don't know what you are doing. If EXTNUM is 0, the address of the main AMOS data zone is returned. NOTE: Negative parameters to =El Base are accepted, but return various pointers to debug easylife, and should not be used. Raster Wait SCANLINE Waits until the raster beam that udpated the picture is on a particular scanline. it is similar to AMOS Turbo's Vbl wait, but is not limited to scanlines 0-256 - It works for lines 0-511 theoretically, although on most monitors, they only go up to around 280-370, depending on the type. =Elpro Returns True if your program is running under AMOS Pro - False if from AMOS Creator. =Elcompiled Returns True if your program has been compiled - False if it hasn't. I know the compiler extension also provides this function, but it is a bit useless if you want to distribute the uncompiled program to someone without the compiler! =El Overlap(A1,B1,A2,B2 To X1,Y1,X2,Y2) =El Lapsx =El Lapsy =El Lapex =El Lapey =El Overlap returns true if the rectangles (A1,B1)-(A2,B2) and (X1,Y1)- (X2,Y2) overlap, and false if they don't. A1 must be less than A2 etc. If =El Overlap returned true, the other functions return the co-ordinates of the overlapping region.