Club Amiga de Montreal

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

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 073.lha / FileIO / FileIO.doc < prev next >

Wrap

Text File | 1987-06-02 | 37.8 KB | 1,001 lines

FileIO Requester User and Programmer Manual From the Amiga Programmer's Suite Book 1, by RJ Mical Copyright (C) 1987, Robert J. Mical This document describes the FileIO Requester, both for users of the requester and for programmers who will create the requester. The main sections of this document are: o FROM THE USER'S POINT OF VIEW o PROGRAMMER'S REFERENCE o DEMO PROGRAM NOTES o TECHNICAL REFERENCE o USING THE AMIGA PROGRAMMER'S SUITE o APPENDIX A: FileIO Function Calls ============================================================================ === FROM THE USER'S POINT OF VIEW ========================================== ============================================================================ This section presents the FileIO Requester from the user's point of view. This is a rough example of the sort of documentation that might be supplied to the end user of this FileIO Requester. === Welcome to the FileIO Requester ======================================== The FileIO Requester allows you an easy way to select which file you want to use for input or output. This section describes how you go about using the FileIO Requester. The FileIO Requester consists of several parts: o the "Select a Name" gadgets which allow you to choose a file name simply by scrolling through a list of names until you find the one you want, pointing at the name and clicking the left mouse button o the OK! gadget which you use to acknowledge that the name you've chosen is the one you wanted o 3 string gadgets which allow you to type in the name directly rather than using the "Select a Name" gadgets to find the file you want o a NEXT DISK gadget which allows you to examine one disk after another o the CANCEL gadget, which you use to when you've decided you don't want to select a file after all The "Select a Name" gadgets present you with a list of file names and allow you to use the mouse to scan easily through the list and select one of the filenames simply by pointing at it and clicking. The "Select a Name" gadgets consist of: o a box of where some of the list of file names are displayed o a slider which lets you scan quickly through the list of files o an up gadget and a down gadget which allow you to move through the file list one name at a time There are 3 types of entries in the list of file names. At the top of the list are the file names that you can choose. These names are listed in alphabetical order. At the bottom of the list there are special entries which allow you to move around through the drawers of a disk, much like you move around through drawers on the Workbench display. The entries that start with the ">>>>" characters allow you to "open" a drawer and examine the names of the files in that drawer. For example, when examining a Workbench disk, at the bottom of the list you would find an entry that looked like ">>>> Demos" which means that you can go into the drawer named "Demos". If you selected ">>>> Demos" you would see, after a short pause, a new list of file names: the names of the files that are in the "Demos" drawer. In the "Demos" drawer you would also find a special entry, "<<<< PRIOR DRAWER". If you select this entry, you will move back to the drawer that contained your current drawer. An alternate way to change drawers is to type the name of the drawer you want in the string gadget labelled "Drawer" and located to the right of the "Select a Name" gadgets. You select the gadget, type in the name, and hit return. Once you have a list of file names to choose from in the file name box, there's a slider gadget to help you scroll around through the names. The slider is to the right of the file names. It has a knob which you move to scroll through the names. The knob will be different sizes depending on the number of names in the file list. If the knob is small, this means that you can see only a small number of the total file names. The smaller the knob, the more names there are to see. On the other hand, if you can see all the names in the list, the knob will fill up the entire slider and you won't be able to move it. To view the file names, you "grab" the slider's knob and move it up and down. You grab the knob by pointing at it and pressing and holding the left mouse button. When you have grabbed the knob, you can move the pointer and scan quickly through the list of file names. Also, you can view the list of names one page at a time by clicking in the area of the slider outside of the knob. If you want fine control of your movement through the file list, the up and down gadgets let you adjust the list of names one name at a time. Once you have found the file name that you want to choose, you select it by pointing at it and clicking. When you do this, the name will be highlighted and it will appear in a box to the right of the "Select a Name" gadgets. When you've decided that this is really the name you wanted to choose, pick the OK! gadget. Another way to tell the program that you're sure you want to select a certain file name is by double-clicking on the file name in the same way that you double-click on a Workbench icon. Double-clicking is exactly the same as selecting a name and then OK! If you don't want to use the "Select a Name" gadgets, you can select a name by typing the name into the string gadget labelled "Or Type a Name" and then hitting return or clicking on the OK! gadget. Hitting return after typing the name you want is the same as selecting OK! If you know what file name you want and you intend on typing it into the string gadget, you can start typing as soon as the requester appears. You don't have to select the string gadget before you start typing, and you don't have to wait for the wait pointer to change before you hit return! To view the files of a different disk, select the NEXT DISK gadget. When you do, the name of the next disk is displayed in the Disk string gadget and the disk is then searched. If this disk isn't the one you wanted, you can press NEXT DISK again even though you may be seeing the wait pointer. You can press NEXT DISK as many times as you want until you see the name of the disk you want in the Disk gadget. You can also type the name of the disk you want directly into the Disk string gadget if you like. You might notice that the ZZZ-cloud wait pointer looks a little different from ones you're used to on the Amiga. The File IO Requester's ZZZ-cloud pointer has a small tab at the top left which allows you to continue pointing and making selections even though the ZZZ-cloud is displayed. The File IO Requester's ZZZ-cloud tells you that it's working, but it doesn't make you wait. You might notice also that the file names start appearing one by one in the Select a Name gadget. You can select one of these names even before all of the names have been added to the list, though this can be a bit tricky as they move around a lot. While the list is being built you can use the slider to look at what names have already been added. If you see the name that you want to select, you can stop the building of the file name list by clicking on a spot inside the requester but outside of all the gadgets; for instance, if you click between the OK! and CANCEL gadgets this will stop the list from being constructed. Then you can select the name you want as usual. To restart the building of the file name list, click on either the Drawer or Disk string gadget and hit return. ============================================================================= === PROGRAMMER'S REFERENCE ================================================== ============================================================================= This section is for the programmer who wants to use the FileIO Requester routines in her or his program. Also, it's an introduction for those who intend in delving into the guts of these routines. For an overview of the FileIO Requester routines, refer to the TECHNICAL REFERENCE section. The Workbench names for DOS objects have been used in the FileIO Requester, and are used throughout this document for simplicity. For your reference, a directory is referred to as a "drawer" and volumes, or DOS filesystem devices, are referred to as "disks". The phraseology on the requester itself was left vague intentionally so that the same requester could be used to select names for both input and output. These are the subsections of this section: o Basic Operation o Multiple FileIOSupport Structures o Workbench-style Filename Operations o If You Don't Want Workbench-style Filename Operations o FileIOSupport Flags o GetFileIOName() is non-reentrant o Procedure for Adding the FileIO Requester to Your Program === Basic Operation ======================================================== The FileIO routines base all of their work on a data structure called the FileIOSupport structure. You are allocated one of these structures when you call the GetFileIOSupport() routine. The structure is initialized with reasonable default values for you. The FileIOSupport structure is used when calling the GetFileIOName() routine, which is the routine that actually presents the requester to the user and gets the user's filename selection. There are several flags and data fields in the FileIOSupport structure that you may choose to initialize before calling GetFileIOName(). By setting or clearing these flags, you define how information is to be presented to the user of your requester. These flags are described below in "FileIOSupport Flags". Also, you may choose to give a title to your FileIO requester, which title can illuminate the function of the requester. For instance, you may want to have one FileIOSupport structure used for input and another for output. You could give one the title "- SELECT INPUT FILE -" and the other "- SELECT OUTPUT FILE -". The title you supply is centered at the top of the requester. You supply a title by setting the ReqTitle field of your FileIOSupport structure to point to a null-terminated text string. You can also set this field to NULL, which is the default. If this field is NULL, a default title is displayed. The GetFileIOName() function returns a BOOL value of TRUE or FALSE, depending on whether the user completed or cancelled the filename selection process. If the return value is TRUE, you can find the filename selected by the user in the FileName[] field of your FileIOSupport structure. The pathname to the file can be constructed by calling the BuildFileIOPathname() function or by using the DiskName[] and DrawerName[] fields. You can call GetFileIOName() any number of times with the same FileIOSupport structure. The data in the FileIOSupport structure usually remains valid between calls to GetFileIOName(), so with subsequent calls the filename list doesn't have to be constructed anew. This allows the requester to appear very quickly because the usually-lengthy process of accessing the disk is avoided. The GetFileIOName() routine uses the GOOD_FILENAMES flag to discern whether the data contained in your FileIOSupport structure is valid. If GetFileIOName() sees that the flag is not set it builds the filename list from scratch. If the GOOD_FILENAMES is set, the list is not recreated. When GetFileIOSupport() creates a support structure for you, this flag is cleared to specify that the support structure doesn't contain good filenames. Thus the first call to GetFileIOName() causes the filename list to be constructed. The GetFileIOName() function normally sets this flag (unless the user has done something unusual or if GetFileIOName() failed for some reason such as "out of memory"), so that subsequent calls to GetFileIOName() work much more efficiently. But you must do a bit work to support this efficiency. You are obliged to watch for IDCMP events of class DISKINSERTED and to clear the GOOD_FILENAMES flag in any of your FileIOSupport structures whenever you see this event. The DISKINSERTED event occurs when the user has switched around the disks. When the user has changed disks you can't be sure that your FileIO filename list is still valid, so as a courtesy to the user you must cause the filename list to be reconstructed. You can use the FileIO Requester to get the name of a file to be used for output. If you do and the specified file doesn't currently exist, AmigaDOS will create it anew when you open it. From the FileIO Requester point of view, this means that a file now exists that isn't in your FileIOSupport list. To get the name in the list, you can use the AddFileIOName() routine. This routine adds a file name to the list of file names currently in the specified FileIOSupport structure. The next time the FileIOSupport structure is used for a call to GetFileIOName(), the new file name will apppear alphabetized in with the other file names. If the name is already in the list when you call AddFileIOName() then nothing happens. This allows you to call AddFileIOName() without worrying about duplicate name redundancy, so you can skip checking whether or not AmigaDOS has created a new file. Finally, when you're finished with your FileIOSupport structure (usually not until your program is terminating) then you call ReleaseFileIO() to deallocate the structure and all the resources that it's accumulated. === Multiple FileIOSupport Structures ======================================= Your program can have more than one FileIOSupport structure at a time. An example of why you would want more than one FileIOSupport structure: you might want to have separate structures for getting input filenames and output filenames from the user. Another example: you might have one structure for letting the user select text files and another for the selection of graphics files. If you have more than one FileIOSupport structure, remember that you must clear the GOOD_FILENAMES flag in all of them whenever you see Intuition's DISKINSERTED IDCMP event class. Also, regarding new disks, there's an extra procedure that you must follow. If the user changes the disk while you've called GetFileIOName(), you won't actually see a DISKINSERTED event (as the event will have been processed by GetFileIOName() before control is returned to you). So how will you know to clear the GOOD_FILENAMES flag in your other structures? Well, GetFileIOName() records the fact that a DISKINSERTED event was handled by setting the DISK_HAS_CHANGED flag in your FileIOSupport structure. So on return from a call to GetFileIOName() you should check to see whether your FileIOSupport structure has the DISK_HAS_CHANGED flag set. If it does, you should clear the DISK_HAS_CHANGED flag in the structure and then clear the GOOD_FILENAMES flag in all of your other FileIOSupport structures. This assures that when you call GetFileIOName() with any of your other support structures, the filename lists will be reconstructed, as they should. === Workbench-style Filename Operations ===================================== You can have file names appear in the FileIO Requester using the same rules that govern how files appear on the Workbench display, by using the Workbench .info file mechanism. If you intend on using Workbench pattern matching (or if you are going to give the user the option) you must make sure that the constant WBENCH_CODE is defined in the fileio.h file. This includes the Workbench code in the FileIO files when they are being compiled. To attempt to match Workbench patterns at run time, you must set the WBENCH_MATCH flag in your FileIOSupport structure, as described below. (By the way, if you don't intend on using Workbench-style pattern matching and are interested in saving about 500 bytes of code size, make sure you comment out the WBENCH_CODE definition.) The Workbench .info file mechanism is a detailed topic that will not be delved into here. Please read the Amiga ROM Kernel Manual for a description of the Workbench operation and data types. What follows is a cursory description of the Workbench technique, which is described only well enough to explain how you can interact with it via your FileIOSupport structure. The Workbench program examines the directory of a disk and displays icons for the files it finds that end with a ".info" suffix (hereafter referred to as .info files). The file names displayed beneath the icons have the ".info" suffix removed. The Workbench .info files contain information regarding what type of data is contained in the file (executable program, project data, et cetera). You can choose to have only .info files displayed to the user (with the ".info" suffix removed) in the same way that the Workbench does. You get this by setting the WBENCH_MATCH flag. You can further filter the names that appear if you wish. There are two techniques that you can employ for filtering which file names will be added to the list: you can ask for only those files that match a particular Workbench object type and only those files that match a particular tool type. You elect to match the object type by setting the MATCH_OBJECTTYPE flag in your FIleIOSupport structure. The object types typically of interest are WBTOOL and WBPROJECT. By selecting one of these types, your filename list will consist only of executable files or data files respectively (except that all .info drawer names are always displayed). If this is confusing, refer to the ROM Kernel manual for a discussion of object types. You can also request to match a Workbench tool type. By matching tool types, you can, for instance, have your file list display only those data files that were created by a specific application. See the section entitled "The ToolTypes Array" in the Workbench chapter of the ROM Kernel manual for a description of how tool types work. You elect to match tool types by setting the MATCH_TOOLTYPES flag in your FileIOSupport structure. The ToolTypes text that you must supply should be written into the ToolTypes[] field of your FileIOSupport structure. === If You Don't Want Workbench-style Filename Operations =================== If you don't intend on using the Workbench-style pattern matching as described above, then make sure you comment out the WBENCH_CODE definition. This will result in a savings of about 500 bytes of code size. If you comment out the WBENCH_CODE definition, then setting the WBENCH_MATCH flag in your FileIOSupport structure will have no effect. === FileIOSupport Flags ===================================================== GOOD_FILENAMES This flag designates whether the filename data contained in the FileIOSupport is valid. The flag is cleared by the GetFileIOSupport() function, and is usually set by the GetFileIOName() function. When GetFileIOName() is called, this flag is checked and if it's set then the disk isn't reexamined for file names. You should clear this flag in your FileIOSupport structures in two instances. First, when you receive an Intuition IDCMP event of DISKINSERTED you should clear this flag in all of your FileIOSupport structures. Second, if you have more than one FileIOSupport structure then on return from a call to GetFileIOName() you should check whether your support structure has the DISK_HAS_CHANGED flag set and if so you should clear the DISK_HAS_CHANGED flag in the structure and clear the GOOD_FILENAMES flag in all of your other FileIOSupport structures. USE_VOLUME_NAMES When you leave this flag set, the AmigaDOS volume names will be used for the disk names in the requester. If you clear this flag, the device names will be used instead. What's a volume name and what's a device name? Well, if you have your Workbench disk in the Amiga's internal drive, then the volume name of that disk is "Workbench:" and the device name is "DF0:". Which you choose to use is up to you. Programmers are more familiar with device names. The typical end-user is more familiar with volume names. The default is to follow the Workbench convention and use volume names. DISK_HAS_CHANGED If the user changes the disk while the FileIO Requester is being displayed, this flag is set in the FileIOSupport structure. The only time you must pay attention to this flag is when you have multiple FileIOSupport structures. If you find that this flag has been set, you must clear this flag in your FileIOSupport structure and then clear the GOOD_FILENAMES flag in all of your other FileIOSupport structures. DOUBLECLICK_OFF Normally, the user can double-click on a filename to select it. You may choose to disable this feature, for instance, when you want the user to be very certain about the filename selection (perhaps if the file is about to be destroyed, or something equally drastic). To disable double-clicking, set the DOUBLECLICK_OFF flag. Then the user will have to explicitly select OK! or type and filename and hit return for the selection to be made. WBENCH_MATCH You set this flag to specify that you want Workbench-style .info file logic to be used when constructing the filename list. If you set this flag, only directory names and file names that pass the .info file tests will be displayed in the file name list. See the "Workbench-style Filename Operations" section above for complete information. This flag is cleared when your FileIOSupport structure is first created. MATCH_OBJECTTYPE When you set this flag (and the WBENCH_MATCH flag), the DiskObjectType field of your FileIOSupport structure will be compared with the do_Type field of the .info file's DiskObject structure. If they match, the file will be displayed. Both the MATCH_TOOLTYPE and the MATCH_OBJECTTYPE flags can be set at the same time. See the "Workbench-style Filename Operations" section above for complete information. MATCH_TOOLTYPE If you set this flag (and the WBENCH_MATCH flag), then Workbench-style ToolType pattern matching will be performed and must be successful before the filename will be included in the list. You specify your selection of ToolType in the FileIOSupport structure's ToolType[] field. Both the MATCH_TOOLTYPE and the MATCH_OBJECTTYPE flags can be set at the same time. See the "Workbench-style Filename Operations" section above for complete information. === GetFileIOName() is non-reentrant ======================================= If your program doesn't create tasks, or if you have multiple tasks but only one of your tasks will call GetFileIOName() (which is almost always the case), you can ignore the following information. The GetFileIOName() routine is non-reentrant. For the sake of memory efficiency, it uses global data and variables rather than creating local copies of these for each caller. What this means is that if you have created a program that has more than one task, GetFileIOName() cannot be called by more than one task at a time. This is not a problem for the grand majority of programs. But if you have some application that would require calling this routine asynchronously from multiple tasks, you'll have to implement some quick semaphore arrangement to avoid collisions. No big deal, actually. See Exec semaphores for everything you need. === Procedure for Adding the FileIO Requester to Your Program =============== This section presents a step-by-step procedure for incorporating the FileIO Requester code into your own program. Copy these FileIO files into your directory (and include them in your makefile): alerts.c chipdata.c fileio.c filename.c filesupp.c global.c opendata.c pointers.c reqsupp.c strings.c volname.c fileio.h eglobal.c You have to include fileio.h in every file that refers to your FileIOSupport structure. #include "fileio.h" Are you going to provide your users with Workbench-style .info file pattern matching? If so, then go into fileio.h and make sure that WBENCH_CODE is defined. #define WBENCH_CODE If you're not going to provide Workbench .info file pattern matching, verify that WBENCH_CODE isn't defined. This make the FileIO code about 500 bytes smaller. /* #define WBENCH_CODE */ Declare a pointer to a FileIOSupport structure, and then fill that pointer with the address of one of the structures. struct FileIOSupport *FileIOSupp; FileIOSupp = GetFileIOSupport(); Your NewWindow structure should have the DISKINSERTED flag set along with your other IDCMP flags. Whenever you receive a DISKINSERTED event, you should clear the GOOD_FILENAMES flag in every FileIOSupport structure you control. The following code could be added to the case switch where you handle IDCMP events. switch (imessageclass) { case DISKINSERTED: /* You should clear the GOOD_FILENAMES flag * whenever you detect that a new disk was * inserted. */ if (FileIOSupp) ClearFlag(FileIOSupp->Flags, GOOD_FILENAMES); break; } When you want to present the FileIO Requester to the user, call GetFileIOName(). If this routine returns TRUE, the user did not cancel the operation. The following code is an example of presenting the FileIO Requester to the user and then reacting to the result. if (FileIOSupp) if (GetFileIOName(FileIOSupp, window)) { UBYTE name[128]; BuildFileIOPathname(FileIOSupp, &name[0]); /* Here do something like read or write the file. * If you write the file, you should call * AddFileIOName() if you've created a new file * or if you don't want to bother checking * whether or not it was a newly-created file. */ if (writefile) AddFileIOName(FileIOSupp, &name[0]); } Finally, when you're done with your FileIOSupport structure (usually when you're program is exiting), you can free up the structure and its resources with a simple call to ReleaseFileIO(), like this: if (FileIOSupp) ReleaseFileIO(FileIOSupp); ============================================================================= === DEMO PROGRAM NOTES ====================================================== ============================================================================= This section briefly describes the demo program that drives some of the FileIO Requester's features. If you invoke the program without a second argument, a window will be opened in the Workbench screen. If you invoke the program with any second argument, a low-res screen will be opened for the requester window. The program uses two FileIOSupport structures to demonstrate the techniques that you should use when managing multiple FileIOSupports. These techniques include processing DISKINSERTED events and discovering on return from GetFileIOName() that the DISK_HAS_CHANGED flag is set. The first support structure, fileio1, is used in its vanilla state as created by GetFileIOSupport(). The other support structure, fileio2, is initialized to do Workbench-style .info file handling where the filename list will consist of only .info objects of type WBPROJECT. Also, every time you insert a disk, the USE_VOLUME_NAMES flag in the support structures is toggled, so that first you see volume names and then you see device names. This is for demonstration only; it's not suggested that you use this technique in a real program. Finally, when you do any of the selection techniques where you accept your selection, the pathname to your selection is displayed in an autorequester. If you choose CANCEL to end the requester, nothing happens. To stop the program, click in the window close gadget. ============================================================================= === TECHNICAL REFERENCE ===================================================== ============================================================================= This section gives you a brief outline of the FileIO software system files, plus some scanty supplementary information. Please refer to the source code itself. The routines are commented and, hopefully, reasonably laid out. The FileIO files include: alerts.c Autorequester alert routines for emergency and shortcut communications chipdata.c Data for the Open requester that must be in chip memory eglobal.c External global variable declarations fileio.c FileIO interface routines: GetFileIOSupport(), GetFileIOName(), BuildFileIOPathname(), AddFileIOName(), and ReleaseFileIO() fileio.h The FileIO structure and constants definitions filename.c Routines that build the filename list filesupp.c Routines that create and manage the Open Requester global.c Global variable declarations main.c Demonstration program opendata.c Open Requester declarations pointers.c Pointer routines of the Amiga Programmer's Suite reqsupp.c DoRequest() routine of the Amiga Programmer's Suite strings.c RJ's general crude string manipulation routines volname.c Routines that build the volume list === USING THE AMIGA PROGRAMMER'S SUITE ====================================== The Amiga Programmer's Suite Book 1 is copyrighted but freely distributable. All copyright notices and all file headers must be retained intact. The Amiga Programmer's Suite Book 1 may be compiled and assembled, and the resultant object code may be included in any software product. However, no portion of the source listings or documentation of the Amiga Programmer's Suite Book 1 may be distributed or sold for profit or in a for-profit product without the written authorization of the author, RJ Mical. If you use the Amiga Programmer's Suite, I wouldn't mind if you gave me some mention somewhere. Good luck! Program hard, program well. -RJ Mical === APPENDIX A: FileIO Function Calls ====================================== CONTENTS: AddFileIOName() BuildFileIOPathname() GetFileIOSupport() GetFileIOName() ReleaseFileIO() *** AddFileIOName() ****************************************************** NAME AddFileIOName -- Add a file name to the names in a FileIOSupport SYNOPSIS AddFileIOName(FileIOSupport, FileName); FUNCTION This routine adds a file name to the list of file names currently in the specified FileIOSupport structure. The next time the FileIOSupport structure is used for a call to GetFileIOName(), the new file name will apppear alphabetized in with the other file names. This routine will most often be used after a call to GetFileIOName() or some other routine where the user is allowed to specify the name of a file to be opened for output. If the file is opened successfully, this routine will make sure that the name of the file is in the FileIOSupport structure. This is important if the output file has been newly created; otherwise, without calling this routine, the next time the FileIOSupport structure is used the new file name would not appear even though the file exists. If the name is already in the list when you call AddFileIOName() then nothing happens. This allows you to call AddFileIOName() without worrying about duplicate name redundancy. Here's a typical sequence of events leading up to a call to AddFileIOName(): First, get a FileIOSupport structure: fileio = GetFileIOSupport(...); When the user wants to write data, use GetFileIOName() to provide a convenient and consistent interface to the filesystem: goodfile = GetFileIOName(...); If the user has selected a name for output (in this example, goodfile will equal TRUE if the user selected a name), then open the file (possibly creating it) and then call AddFileIOName() to make sure the name is in the FileIOSupport structure's list: if (goodfile) { UBYTE filename[80]; BuildFileIOPathname(fileio, &filename[0]); ... open filename, write it, close it ... if (filename opened successfully) AddFileIOName(fileio, &filename[0]); } INPUTS FileIOSupport = the address of a FileIOSupport structure FileName = the address of null-terminated text that is either a simple file name or a valid AmigaDOS pathname. RESULT None SEE ALSO GetFileIOName() GetFileIOSupport() *** BuildFileIOPathname() ************************************************ NAME BuildFileIOPathname -- Build a file pathname using a FileIO struct SYNOPSIS BuildFileIOPathname(FileIOSupport, Buffer); FUNCTION Builds the text for a pathname using the FileName[], DrawerName[] and DiskName[] fields of the specified FileIOSupport structure after the support structure has been used in a successful call to GetFileIOName(). Writes the text into the Buffer. INPUTS FileIOSupport = the address of a FileIOSupport structure Buffer = address of the buffer to receive the file pathname RESULT None SEE ALSO GetFileIOName() *** GetFileIOSupport() *************************************************** NAME GetFileIO -- Allocate and initialize a FileIOSupport structure SYNOPSIS struct FileIOSupport *GetFileIOSupport(); FUNCTION Allocates and initializes a FileIOSupport structure for use with calls to GetFileIOName(). You may want to further initialize the structure before calling GetFileIOName(). Refer to the FileIO documentation for more information. When you're done with the structure, call ReleaseFileIO(). INPUTS None RESULT If all goes well, returns the address of a FileIOSupport structure. If anything goes wrong (usually out of memory), returns NULL. EXAMPLE struct FileIOSupport *fileio; fileio = GetFileIOSupport(); GetFileIOName(fileio, window); ReleaseFileIO(fileio); BUGS None known SEE ALSO GetFileIOName(), ReleaseFileIO() *** GetFileIOName() ****************************************************** NAME GetFileIOName -- Gets a file name for input/output from the user SYNOPSIS BOOL GetFileIOName(FileIO, Window); FUNCTION This routine creates a filename requester which allows the user to browse through the AmigaDOS filesystem and select one of the filenames found there. The FileIO argument is a pointer to a FileIOSupport structure, which is allocated and initialized for you via a call to GetFileIOSupport(). You may preset the FileIO parameters before calling this routine, or you may leave them set at their default values. See the FileIO documentation for complete details. The Window argument is the pointer to the window structure returned by a call to Intuition's OpenWindow() function. As this routine opens a requester and requesters open in windows, you must have already opened a window before calling this routine, even if it's a window opened for no other purpose than to call this routine. This routine returns a BOOL value of TRUE or FALSE, depending on whether the user chose to accept or cancel the filename selection operation. If TRUE, the filename selected by the user can be found in the FileIO structure FileName[] field. This filename will have all leading and trailing blanks removed (in case the user typed in a filename with extraneous spaces). Likewise, the pathname to the disk and drawer can be found in the text fields DiskName[] and DrawerName[]. You can construct the pathname using these text strings. Also, you can call BuildFileIOPathname() to build the pathname automatically. There's a *lot* more to be said about this function. Please read the documentation. NOTE: This routine is not re-entrant. What this means is that if you have created a program that has more than one task, this routine cannot be called by more than one task at a time. This is not a problem for the grand majority of programs. But if you have some application that would require calling this routine asynchronously from multiple tasks, you'll have to implement some quick semaphore arrangement to avoid collisions. No big deal, actually. See Exec semaphores for everything you need. INPUTS FileIO = pointer to a FileIOSupport structure, as allocated via a call to GetFileIOSupport() Window = pointer to a Window structure, as created via a call to Intuition's OpenWindow() RESULT TRUE if the user decided that the filename selection was successful, FALSE if the user chose to cancel the operation EXAMPLE if (GetFileIOName(fileio, window)) ProcessFileName(&fileio->FileName[0]); BUGS None known, though there could be some, and the disk selection subsystem logic is not perfectly polished (though it's believed to be bug-free). SEE ALSO BuildFileIOPathname(), GetFileIOSupport(), ReleaseFileIO() *** ReleaseFileIO() ****************************************************** NAME ReleaseFileIO -- Release the FileIO structure and all local memory SYNOPSIS ReleaseFileIO(FileIO); FUNCTION Releases the FileIO structure by freeing all local memory attached to the structure and then freeing the structure itself. INPUTS FileIO = the address of a FileIO structure RESULT None SEE ALSO GetFileIOSupport()