Club Amiga de Montreal

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

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 514b.lha / ToolLib_v8.1 / Tool.DOC < prev next >

Wrap

Text File | 1991-06-08 | 41.5 KB | 1,184 lines

tool.library version 8.1 © Copyright 1990-91 Jaba Development written with the Devpac Assembler version 2.14 by Jan van den Baard DISCLAIMER ---------------------------------------------------------------------------- The author takes no responsibility as to the suitability or accuracy of this documentation and/or the program(s) it describes. Any damage sustained by the use of this documentation and/or the program(s) it describes is the sole responsibility of the user her/him self. ---------------------------------------------------------------------------- COPYRIGHT ---------------------------------------------------------------------------- tool.library, © Copyright 1990-91 by Jaba Development. All rights reserved. This program may be distributed non-commercially only providing that the source code, documentation and copyright notice remains intact. This program is FREEWARE so no financial donation is necessary (but welcome). ---------------------------------------------------------------------------- This is version 8.1 of a shared library containing 46 useful functions for all kinds of programs. The functions in this library are not of a specific kind but cover a lot of the Amiga facilities. There are functions for ports , sorting, gadgets, memory, string, directory and file handling. This manual is divided into the following sections: THE ROUTINES I. STRUCTURES AND DEFINITIONS II. THE FILEREQUESTER III. HISTORY IV. NOTES V. ---------------------------------------------------------------------------- I. THE ROUTINES ---------------------------------------------------------------------------- NAME Port = CreatePort( Name, Pri ); D0 -30 A0 D0 FUNCTION To allocate and set up a message port. INPUTS Name - A pointer to a NULL terminated string representing the name of the message port or NULL if the port should not be globaly recognizable to other tasks. Pri - A 32 bit integer representing the message port priority. RESULT "Port" will be a pointer to the newly created message port or NULL if an error occurred. NOTE: The message port is only added to the system port-list if you specify a name for it. If you don't the port can not be found by other tasks. NAME DeletePort( Port ); -36 A0 FUNCTION To deallocate and remove a message port. INPUTS Port - A pointer to the message port that is to be deleted. RESULT The message port is removed and deallocated. NAME IOReq = CreateExtIO( Port, Size ); D0 -42 A0 D0 FUNCTION To allocates and initialize an IORequest structure. INPUTS Port - A pointer to the message port which is signalled if a message is executed. Size - A 32 bit integer that represents the size if the IORequest structure. RESULT "IOReq" will be a pointer to the allocated and initialized IORequest structure or NULL if an error occurred. NAME DeleteExtIO( IOReq ); -48 A0 FUNCTION To deallocate an IORequest structure. INPUTS IOReq - A pointer to the IORequest structure to be deallocated. NAME IOReq = CreateStdIO( Port ); D0 -54 A0 FUNCTION To allocate and initialize an IOStdReq structure. INPUTS Port - A pointer to the message port which is signalled if a message is executed. RESULT "IOReq" will be a pointer to the allocated and initialized IOStdReq structure or NULL if an error occurred. NAME DeleteStdIO( IOReq ); -60 A0 FUNCTION To deallocate an IOStdReq structure. INPUTS IOReq - A pointer to the IOStdReq structure to be deallocated. NAME timedelay = CreateTimeDelay(port,seconds,micros); D0 -66 A0 D0 D1 FUNCTION Sets up the timer.device to be able to put a task to sleep for a precise amount of time. INPUTS port - A pointer to a message port which, if this port was signalled, wakes up the task before the time ran out. This may also be NULL but that makes it impossible to stop the delay before the time runs out. seconds - A 32-bit integer representing the amount of seconds to put the task to sleep. micros - A 32-bit integer representing the amount of microseconds to put the task to sleep. RESULT timedelay - A pointer to a TimeDelay structure or NULL if an error occurred. NAME yourmsg = DoTimeDelay(timedelay); -72 A0 FUNCTION To put a task to sleep for a specific time. INPUTS timdelay - A pointer to a TimeDelay structure as returned by "CreateTimeDelay". RESULT "yourmsg" will be TRUE if the routine breaks off because it has been signalled by the message port supplied by you and FALSE if the time ran out. NAME DeleteTimeDelay(timedelay); -78 A0 FUNCTION To deallocate and erase the TimeDelay structure and close all of it's resources. INPUTS timdelay - A pointer to a TimeDelay structure as returned by "CreateTimeDelay". NAME QuickSort( Base, Num, Size, Compar ); -84 A0 D0 D1 A1 FUNCTION To sort an array of elements. INPUTS Base - A pointer to the first element in the array. Num - A 32 bit integer representing the number of elements in the array. Size - A 32 bit integer representing the size of an element. NOTE: The size of an element may NOT be larger than 64 KBytes. Compar - A pointer to a routine that does the comparison between two elements. This is called like this: Compar(a,b); The arguments "a" and "b" are pushed on the stack before calling the routine. Also a pointer to argument "a" is put in A0 and a pointer to argument "b" is put in A1 for the assembler programmers. The routine must return a 32 bit integer. It should return -1, 0 or 1 depending on whether element "a" is to be considered smaller, equal or bigger than element "b". The comparison routine is passed POINTERS to the elements in the array. NAME SwapMem( MemA, MemB, Size ); -90 A0 A1 D0 FUNCTION To exchange two areas of memory. INPUTS MemA - A pointer to the first block of memory. MemB - A pointer to the second block of memory. Size - A 32 bit integer representing the size in bytes of the two memory areas. NOTE: The memory areas swapped can NOT be larger than 64 KByte. NAME Set = TestBits( Value, Bits ); D0 -96 D0 D1 FUNCTION To test whether or not certain bits are set in a value. INPUTS Value - A 32 bit integer representing the value in which the bits are tested. Bits - A 32 bit integer representing the bits to be tested. RESULT Set will be TRUE if the bits where set in "Value" and FALSE if not. NAME SelectGadget( Window, Gadget, Req ); -102 A0 A1 A2 FUNCTION To visually select a gadget. Also the SELECTED flag in the "Flags" field of the gadget will be set. INPUTS Window - A pointer to the window in which the gadget is located. Gadget - A pointer to the gadget which must be selected. NOTE: Only gadget of the "TOGGLESELECT" type will be selected. Req - If the gadget is located in a requester you must put a pointer to that requester here. If no requester is used put NULL here. NAME DeSelectGadget( Window, Gadget, Req ); -108 A0 A1 A2 FUNCTION To visually select a gadget. Also the SELECTED flag in the "Flags" field of the gadget will be cleared. INPUTS Window - A pointer to the window in which the gadget is located. Gadget - A pointer to the gadget which must be de-selected. NOTE: Only gadget of the "TOGGLESELECT" type will be de-selected. Req - If the gadget is located in a requester you must put a pointer to that requester here. If no requester is used put NULL here. NAME MutualExclude( Window, Gadget, From, Req ); -114 A0 A1 A2 A3 FUNCTION To mutually exclude gadgets if a certain gadget is selected. INPUTS Window - A pointer to the window in which the gadgets are located. Gadget - A pointer to the gadget which does the MutualExcluding. The "MutualExclude" field of this gadget represents the gadgets to be mutually excluded. Every set bit represents a gadget that should be de-selected if this gadget is selected. From - A pointer to the first gadget in a list from which the routine starts to look for gadgets to be de-selected. NOTE: Only gadgets of the "TOGGLESELECT" type will be mutually excluded. Req - If the gadgets are located in a requester you must put a pointer to that requester here. If no requester is used put NULL here. NAME MutualInclude( Window, Gadget, From, Req ); -120 A0 A1 A2 A3 FUNCTION To mutually include gadgets if a certain gadget is selected. INPUTS Window - A pointer to the window in which the gadgets are located. Gadget - A pointer to the gadget which does the MutualIncluding. The "MutualExclude" field of this gadget represents the gadgets to be mutually included. Every set bit represents a gadget that should be selected if this gadget is selected. From - A pointer to the first gadget in a list from which the routine starts to look for gadgets to be selected. NOTE: Only gadgets of the "TOGGLESELECT" type will be mutually included. Req - If the gadgets are located in a requester you must put a pointer to that requester here. If no requester is used put NULL here. NAME EraseGadget( Window, Gadget, Req ); -126 A0 A1 A2 FUNCTION To erase a gadget from the window or requester. INPUTS Window - A pointer to the window in which the gadget is located. Gadget - A pointer to the gadget which must be erased. Req - If the gadget is located in a requester you must put a pointer to that requester here. If no requester is used put NULL here. NAME GadgetOn( Window, Gadget, Req ); -132 A0 A1 A2 FUNCTION To enable a gadget to be being clicked. It's basically the same as Intuition's "OnGadget" only this routine first erases the gadget from the display and then refreshes only the gadget switched on. INPUTS Window - A pointer to the window in which the gadget is located. Gadget - A pointer to the gadget which must be switched on. Req - If the gadget is located in a requester you must put a pointer to that requester here. If no requester is used put NULL here. NAME GadgetOff( Window, Gadget, Req ); -138 A0 A1 A2 FUNCTION To disable a gadget from being clicked. It's basically the same as Intuition's "OffGadget" only this routine first erases the gadget from the display and then refreshes only the gadget switched off. INPUTS Window - A pointer to the window in which the gadget is located. Gadget - A pointer to the gadget which must be switched off. Req - If the gadget is located in a requester you must put a pointer to that requester here. If no requester is used put NULL here. NAME sel = SelectTest( Gadget ); D0 -144 A0 FUNCTION To test if a gadget is selected or not. INPUTS Gadget - A pointer to the gadget which is tested. RESULTS "sel" will be TRUE if the gadget is selected and FALSE if not. NAME ShadowGadget( Window, Gadget, Req, Color ); -150 A0 A1 A2 D0 FUNCTION To draw a shadow around the gadget in the specified color. INPUTS Window - A pointer to the window in which the gadget is located. Gadget - A pointer to the gadget at which a shadow is drawed. Req - If the gadget is located in a requester you must put a pointer to that requester here. If no requester is used put NULL here. Color - A 32 bit integer representing the pen number in which the shadow is drawed. NAME OnGList( Window, First, Req, Numgad ); -156 A0 A1 A2 D0 FUNCTION To switch a complete list of gadgets on. INPUTS Window - See GadgetOn First - A pointer to the first gadget in the list to be switched on. Req - See GadgetOn NumGad - A 32 bit integer representing the number of gadgets to be switch on. If you put -1 here all the gadgets in the list are switched on. NAME OffGList( Window, First, Req, Numgad ); -162 A0 A1 A2 D0 FUNCTION To switch a complete list of gadgets off. INPUTS Window - See GadgetOff First - A pointer to the first gadget in the list to be switched off. Req - See GadgetOff NumGad - A 32 bit integer representing the number of gadgets to be switch off. If you put -1 here all the gadgets in the list are switched off. NAME SelectGList( Window, First, Req, Numgad ); -168 A0 A1 A2 D0 FUNCTION To select a complete list of gadgets. INPUTS Window - See SelectGadget First - A pointer to the first gadget in the list to be selected. NOTE: Only gadget of the "TOGGLESELECT" type can be selected. Req - See SelectGadget NumGad - A 32 bit integer representing the number of gadgets to be selected. If you put -1 here all the gadgets in the list are selected. NAME DeSelectGList( Window, First, Req, Numgad ); -174 A0 A1 A2 D0 FUNCTION To de-select a complete list of gadgets. INPUTS Window - See DeSelectGadget First - A pointer to the first gadget in the list to be de-selected. NOTE: Only gadget of the "TOGGLESELECT" type can be de-selected. Req - See DeSelectGadget NumGad - A 32 bit integer representing the number of gadgets to be de-selected. If you put -1 here all the gadgets in the list are de-selected. NAME ShadowGList( Window, First, Req, Color, Numgad ); -180 A0 A1 A2 D0 D1 FUNCTION To draw shadows around a complete list of gadgets. INPUTS Window - See ShadowGadget First - A pointer to the first gadget in the list to be shadowed. Req - See ShadowGadget Color - See ShadowGadget NumGad - A 32 bit integer representing the number of gadgets to be shadowed. If you put -1 here all the gadgets in the list are shadowed. NAME EraseGList( Window, First, Req, Numgad ); -186 A0 A1 A2 D0 FUNCTION To erase a complete list of gadgets from a window or a requester. INPUTS Window - See EraseGadget First - A pointer to the first gadget in the list to be erased. Req - See EraseGadget NumGad - A 32 bit integer representing the number of gadgets to be erased. If you put -1 here all the gadgets in the list are erased. NAME InitMemoryChain(chain,size) -192 A0 D0 FUNCTION To initialize a MemoryChain structure for use. INPUTS chain - A pointer to a MemoryChain structure. size - A 32-bit integer representing the size of a MemoryBlock. NAME memptr = AllocItem(chain,size,reqs); D0 -198 A0 D0 D1 FUNCTION To allocate a chunk of memory in a MemoryChain. INPUTS chain - A pointer to the MemoryChain in which the memory will be allocated. size - A 32-bit integer representing the size of the memory. reqs - A 32-bit integer representing the memory requirements of the allocation. NOTE: The size is always rounded up to the nearest multiple of 8. RESULT memptr - A pointer to the allocated memory or NULL if the allocation failed. NOTE: The memory is always allocated in a longword boundary. NAME FreeItem(chain,memptr,size) -204 A0 A1 D0 FUNCTION To deallocate a chunk of memory allocated with AllocItem from a MemoryChain. INPUTS chain - A pointer to the MemoryChain in which the memory was allocated. memptr - A pointer to the memory. size - A 32 bit integer representing the size to be freed. NAME FreeMemoryChain(chain) -210 A0 FUNCTION To deallocate and re-initialize a complete MemoryChain. INPUTS chain - A pointer to the MemoryChain RESULT All memory allocated for the MemoryChain is deallocated and the MemoryChain structure itself is re-initialized so that it can be used again. NAME Format( Buffer, FString, Args ); -216 A0 A1 A2 FUNCTION To format an output into a specified buffer. INPUTS Buffer - A pointer to a buffer in which the formatted output is copied. NOTE: You must make sure that the buffer is big enough to hold the formatted output. FString - A pointer to a NULL terminated string explaining how to interpret the arguments. The following format specifiers are supported: %lc - the next long word in the argument array is formatted as a 8 bit character. %ld - the next long word in the argument array is formatted as a 32 bit decimal number. %lx - the next long word in the argument array is formatted as a 32 bit hexadecimal number. %ls - the next long word in the argument array is formatted as a pointer to a NULL terminated string. The "l" in these format specifiers is only necessary when the arguments are 32 bit. Following this "l" sign you may also specify the following: -> An optional minus sign to tell the routine to left justify the next formatted item within the field width -> An optional digit string to tell the routine to fill out the formatted item with spaces. If the digit string is preceeded with a "0" character the item will be filled out with "0" characters instead of spaces. -> An optional period sign to separate the field width specifier from the maximum characters specifier. -> An optional digit string (for %ls and %s only) to tell the routine the maximum amount of characters to format from the string. This routine is based on Exec's function "RawDoFmt()" which does NOT support any form of floating point formatting. If you have to format floating point numbers you will have to use "sprintf" from the standard C library. Args - A pointer to an array in which the arguments are stored. NOTE: C programmers must link with "tool.lib" to get the arguments passed correctly to the routine. NAME num = WriteFormat( Handle, FString, Args ); D0 -222 A0 A1 A2 FUNCTION To format an output and writes the result directly to a file. INPUTS Handle - A pointer to an AmigaDOS filehandle to which the formatted result will be written. FString - A pointer to a NULL terminated format string which can hold the same format specifiers as the format string from "Format". NOTE: The formatted output may NOT be larger that 512 bytes (including the terminating 0 byte.). Args - A pointer to an array in which the arguments are stored. NOTE: C programmers must link with "tool.lib" to get the arguments passed correctly to the routine. RESULT "num" will read the exact amount of characters written to the file or -1 if an error occurred. NAME match = MatchPattern( String, Pattern, Case ); D0 -228 A0 A1 D0 FUNCTION To perform a Unix style pattern match on a string. INPUTS String - A pointer to a NULL terminated string which will be matched with the pattern. Pattern - A pointer to a NULL terminated string which represents the pattern to be matched. The pattern may have the following wildcards: "*" - representing any number of characters. "?" - representing a single character. Case - A 32 bit boolean value which must be "CASE" if the routine should also check the character case and "NO_CASE" if not. RESULT "match" will read TRUE if the string matched the pattern and FALSE if not. NAME pat = Isolate( Path, Buffer ); D0 -234 A0 A1 FUNCTION To scan a full pathname for a wildcard expansion and copy it, if found, into a buffer. INPUTS Path - A pointer to a NULL terminated full AmigaDOS pathname. If a pattern was found at the end of the pathname this pattern will be copied into the buffer and the pathname will be truncated at the point where the pattern was found. NOTE: This routine only isolates patterns which has atleast one wildcard in it. Buffer - A pointer to a buffer in which the pattern, if found, is copied. RESULT "pat" will be TRUE if a pattern was found and FALSE if not. NAME BstrToCstr( Bstr, Buffer ); -240 A0 A1 FUNCTION To convert a BSTR string into a standard NULL terminated string. INPUTS Bstr - A BPTR to a BSTR string. Buffer - A buffer in which the string is copied. NAME return = GetDate( DateStamp, Buffer, How); D0 -246 A0 A1 D0 FUNCTION To convert a "DateStamp" structure into an ASCII string. INPUTS DateStamp - A pointer to an initialized DateStamp structure or NULL for the current System time. Buffer - A pointer to a buffer which can hold atleast "MINDATE" bytes. How - A 32 bit integer explaining what to convert. For example lets say that it is thursday 20 september 1990 and it's 13:30:00 hour. The result after a call to GetDate will be: ALL - Thursday 20-09-1990 13:30:00 ONLY_DAY - Thursday ONLY_DATE - 20-09-1990 ONLY_TIME - 13:30:00 RESULTS return will be TRUE if the conversion succeeded or FALSE if it failed "Buffer" contains the converted ASCII form of "DateStamp" or the System time. NAME succes = OpenDir(directory,name); D0 -252 A0 A1 FUNCTION To open a directory. INPUTS directory - A pointer to a Directory structure. name - A pointer to a NULL terminated string representing the name of the directory. RESULT success - this reads TRUE if the directory opens successfully and FALSE if an error occurred. NAME entry = GetEntry(directory); D0 -258 A0 FUNCTION To read the next entry of the directory into memory. INPUTS directory - A pointer to the Directory structure. RESULT entry - this will be a pointer to an EntryInfo structure or NULL. If NULL is returned this could mean that an error occurred. A call to IoErr should read ERROR_NO_MORE_ENTRIES otherwise an error has occurred. NOTE: The directory is automatically UnLocked when the last entry was read. NAME CloseDir(directory) -264 A0 FUNCTION To UnLock the directory. INPUTS directory - A pointer to the directory structure. NAME FreeDir(directory); -270 A0 FUNCTION To deallocate the memory a directory takes up. INPUTS directory - A pointer to the directory structure. NAME string = IoErrToStr() D0 -276 FUNCTION To convert a DOS error into an ASCII form. RESULTS string - this will be a pointer to a string representing the ASCII form of a DOS error or NULL if IoErr returned an unknown code. NAME Freq = AllocFreq(); D0 -282 FUNCTION To allocate and initialize a FileRequester structure. RESULT Freq - this will be a pointer to an allocated and initialized FileRequester structure or NULL if the Allocation failed. NAME FreeFreq( Freq ); -288 A0 FUNCTION To deallocate a filerequester structure. INPUTS Freq - A pointer to the FileRequester structure you want deallocated. NAME error = FileRequest( Freq ); -294 A0 FUNCTION To put up the filerequester. INPUTS Freq - A pointer to an allocated and initialized FileRequester structure. RESULT error - this will be an error code explained in "THE FILEREQUESTER" chapter of this documentation. NAME num = FormatText( RPort, FString, Args ); D0 -300 A0 A1 A2 FUNCTION To format a string and write it in a rastport. INPUTS Handle - A valid pointer to a RastPort. FString - A pointer to a NULL terminated format string which can hold the same format specifiers as the format string from "Format". NOTE: The formatted output may NOT be larger that 512 bytes (including the terminating 0 byte.). Args - A pointer to an array in which the arguments are stored. NOTE: C programmers must link with "tool.lib" to get the arguments passed correctly to the routine. RESULT "num" will read the amount formatted characters written to the rastport or NULL if an error occurred. ---------------------------------------------------------------------------- II. STRUCTURES AND DEFINITIONS ---------------------------------------------------------------------------- A pointer to the ToolBase structure is returned upon a successful call to OpenLibrary(). struct ToolBase { struct Library LibNode; The actual library structure. struct ExecBase *SysBase; A pointer to ExecBase. struct DosLibrary *DOSBase; A pointer to DOSBase. struct IntuitionBase *IntuitionBase; A pointer to IntuitionBase. struct GfxBase *GfxBase; A pointer to GfxBase. LONG SegList; A BPTR to the library code. }; The library-base pointers in this structure can be used by a program to call upon functions of any of those libraries. A pointer to the TimeDelay structure is returned upon a successful call to CreateTimeDelay(). struct TimeDelay { struct MsgPort *td_UserPort; A pointer to your message port. struct MsgPort *td_ReplyPort; Used by the timer.device. struct timerequest *td_TimeRequest; To specify the delay }; The MemoryBlock, MemoryItem, BlockList and ItemList structures are used internally to hold all allocations together in a MemoryChain structure. struct MemoryChain { struct BlockList mc_Blocks; The list of blocks in the chain. struct ItemList mc_Items; The list of items in the chain. ULONG mc_BlockSize; The size of a block. }; The Directory structure is used to hold the entries of a directory together. struct Directory { struct EntryInfo *dr_First; The first entry in the directory. struct EntryInfo *dr_End; Always NULL. struct EntryInfo *dr_Last; The last entry in the directory. struct FileInfoBlock *dr_InfoBlock; Used to read the entries. BPTR dr_Lock; Used to read the entries. ULONG dr_NumEntries; The number of entries in the dir. struct MemoryChain dr_DirMem; The memory used up. }; The EntryInfo structure describes the entry. struct EntryInfo { struct EntryInfo *ei_Next; The next entry. struct EntryInfo *ei_Previous; The previous entry. USHORT ei_Type; The type of entry (see below) UBYTE ei_Name[32]; The entry name. LONG ei_SizeBytes; The size in bytes (only with files) LONG ei_SizeBlocks; The size in blocks (only with files) LONG ei_ProtectionBits; The protection bits struct DateStamp ei_Date; The entry date (not for devices) }; The TOOL_VERSION and TOOL_REVISION defines represent the version and revision number of the tool.library. The LONGALLIGN macro is used by the library memory routines to make the size of the allocation even to a 8 byte boundary. MINDATE is a constant that represents the largest possible output of GetDate(). ALL tells GetDate to convert the complete date. ONLY_DAY tells GetDate only to convert the day of the week. ONLY_DATE tells GetDate only to convert the date. ONLY_TIME tells GetDate only to convert the time. NO_CASE tells MatchPattern to check the character case also. CASE tells MatchPattern not to check the character case. ENTRY_FILE the entry is a file. ENTRY_DIR the entry is a directory. ENTRY_DEV the entry is a device. (only used by the FileRequester) DIRBLOCK The size of a MemoryBlock in a directory. ---------------------------------------------------------------------------- III. THE FILEREQUESTER ---------------------------------------------------------------------------- Before you can call the FileRequester you must first call "AllocFreq" to allocate and initialize a FileRequester structure and it's buffers. If the allocation succeeded you will be returned a pointer to the following data structure: struct FileRequester { char *fr_HeadLine; char *fr_FileName; char *fr_DirName; char *fr_DontShow; USHORT fr_LeftEdge; USHORT fr_TopEdge; struct Window *fr_Caller; struct Screen *fr_Screen; struct Directory *fr_Directory; USHORT fr_Flags; USHORT fr_Colors[4]; BPTR fr_Handle; LONG fr_Reserved; }; The "fr_HeadLine" field points to a buffer in which you can copy the title of the FileRequester window with a maximum of 28 bytes. The "fr_FileName" field points to a buffer in which you can copy the default filename. A maximum of 32 bytes is allowed here. After the FileRequester is closed the last selected filename can be found in this buffer. The "fr_DirName" field points to a buffer in which you can copy the default pathname with or without a wildcard expansion. A maximum of 256 bytes is allowed here. After the FileRequester is closed the last selected pathname can be found in this buffer. The "fr_DontShow" filed points to a buffer in which you can copy a wildcard pattern which tells the FileRequester NOT to list the FILES which match this pattern. A maximum of 32 bytes is allowed here. With "fr_LeftEdge" and "fr_TopEdge" fields you can specify the co-ordinates of the TopLeft corner of the FileRequester window on your screen. You should calculate the position so that the FileRequester will fit on your screen. Using incorrect values will result in a "FREQ_CANT_OPEN" when "FileRequest" is called. You can use the "FREQ_WIDTH" and "FREQ_HEIGHT" constants which specify the FileRequester window width and height to calculate a position on your screen. The default settings are fr_LeftEdge = 10, fr_TopEdge = 15. In the "fr_Caller" field you can put a pointer to a window which calls the FileRequester. If this field is initialized the FileRequester will put a very small requester in the TopLeft corner of this window to disable the window from receiving IDCMP messages while the FileRequester is still up. The requester is removed when the FileRequester is closed. By default this field is set to NULL. When you want the FileRequester to open on a custom screen you must put a pointer to that screen in the "fr_Screen" field. This field defaults to NULL which tells the FileRequester to use the WorkBench screen. The "fr_Directory" field points to a Directory structure which is already allocated and initialized by "AllocFreq" in which the FileRequester stores the directories it reads. This may also hold the last directory read by the FileRequester even after the FileRequester closed depending on whether the "FR_NoPreserve" bit was set or not. (see below). The "fr_Flags" field is used to switch certain functions in the FileRequester on or off. See below for an explanation of the possible flags. This defaults to "FR_ReturnVoid". The "fr_Colors[4]" fields can be used to define your own colors depending on whether the "FR_CustColor" flags is set or not. (see below). The "fr_Handle" field is used to return a FileHandle to you is requested. (see below). Always set the "fr_Reserved" field to NULL because this field might be used future version of the FileRequester/library. THE POSSIBLE FLAGS FR_NoPreserve Normally when the FileRequester is closed the directory last read will be kept in the "fr_Directory" field of the FileRequester structure. This has the advantage that, when the FileRequester is recalled, the directory does not have to be read all over again. This also has the disadvantage that the directory will take up atleast 5 KByte of your memory. When the directory, on disk, changed the directory in memory will not show this change, but if you press the 'HELP' key when the FileRequester is active the complete directory is re-read into memory. FR_NoDevs Setting this flag disables the FileRequester from reading and showing the mounted disk devices. FR_NoSort Setting this flag disables the FileRequester from sorting the entries of a directory by sort and alphabetical. FR_CustColor If this flag is set the FileRequester will set the colors defined in the "fr_Colors[4]" fields of the FileRequester onto the screen it appears on saving the previous colors. When the FileRequester is closed the old colors are reset. FR_ReturnOld Setting this flag tells the FileRequester to try to open the selected file if the user closed the requester with OK. The file will be opened using MODE_OLDFILE and the handle is put in the "fr_Handle" field of the FileRequester structure. FR_ReturnNew Setting this flag tells the FileRequester to try to open the selected file if the user closed the requester with OK. The file will be opened using MODE_NEWFILE and the handle is put in the "fr_Handle" field of the FileRequester structure. FR_ReturnReadWrite Setting this flag tells the FileRequester to try to open the selected file if the user closed the requester with OK. The file will be opened using MODE_READWRITE and the handle is put in the "fr_Handle" field of the FileRequester structure. FR_NoInfo Setting this flag tells the FileRequester not to show the ".info" files. FR_ReturnVoid This specifies NOT to open the selected file. default. POSSIBLE FILEREQUESTER RETURN CODES FREQ_OK -> Everything OK. A file was selected and, if requested, opened. FREQ_CANT_OPEN -> The FileRequester could not be opened. This could mean that not enough memory was available or that the "fr_LeftEdge" and/or "fr_TopEdge" fields contains invalid values. FREQ_FILE_ERROR -> This means that the selected file failed to open. FREQ_CANCELED -> This means that the user selected CANCEL or CLOSEWINDOW. ---------------------------------------------------------------------------- IV. HISTORY ---------------------------------------------------------------------------- VERSION 7-- -> TRASH !!!! VERSION 7.1 -> Still not Released. VERSION 7.2 -> The FileRequester now waits until the user selected a gadget outside the file-selection area before it starts to sort the entries. VERSION 7.3 -> "MatchPattern" had a bug resulting in the matching always being case sensitive. This is now fixed. VERSION 7.4 -> I have put a pointer to the FileRequester window in the "pr_WindowPtr" field of the Process structure which results in the system requester appearing on the same screen as the FileRequester. Also the "DisplayBeep" function is called if a DOS error occurred. VERSION 7.5 -> When the "fr_NoPreserve" is not set and the FileRequester is called the old directory is displayed. When the directory had changed this is not shown in the list. Now you can press the "HELP" key and the directory is re-read. VERSION 7.6 -> MAJOR BUG FOUND !! I did forget to call "Permit()" after a call to "Forbid()" in the ReadDevs routine of the FileRequester what resulted in some very strange situations. This is now fixed (phew!). VERY FIRST RELEASE !!! VERSION 7.7 -> Fixed a few minor problems (NOT BUGS!) in the FileRequester. VERSION 7.8 -> Added "FR_NoInfo" flag for the FileRequester to disable the showing of ".info" files. VERSION 8.1 -> Added the "FormatText" routine. C Headers now includes Lattice pragmas. "AllocItem()" now returns NULL if one try's to allocate a chunk bigger than a memory block. ---------------------------------------------------------------------------- V. NOTES ---------------------------------------------------------------------------- Bug reports and suggestions (please !) too me at the following address: Jan van den Baard Bakkerstraat 176 3082 HE Rotterdam Holland