CW CHAPTER 2
CHAPTER 2: HANDLING THE FILE SELECTOR -------------------------------------- [NOTE: Words enclosed in asterisks (i.e. *word*) should be read as italicized text. This text file is copyright 1993 by Clayton Walnum. All rights reserved.] As we said in the previous chapter, the AES supplies us with several ready-made forms that we can use in our programs. Now that we know how to use one of the simpler forms, the alert box, we can move on to one of GEM's most frequently used form, the file selector. In this chapter, we'll learn to call up a file selector and to use the information it returns to create a full pathname for any file the user selects. --What Is a File Selector?-- If you've used your ST at all, there's no doubt that you're already familiar with the file selector. Virtually every GEM program written for the ST uses the file selector to get file information from users. The file selector's basic function is simple: it allows the user to select a file. However, because selecting a file requires the ability to move from one directory to another, as well as scroll through a list of filenames too large to fit into the selector's window, things are a little more complicated. Figure 2.1 shows a typical file selector. At the top is the directory line, which shows the directory the user is currently logged into. In the figure, the user is logged into the DEVPAC folder of the D: drive. Notice the *.* following the path. These wild cards mean that the file selector should show every file listed in the directory. If the file portion of the path was changed by the programmer to, say, *.PRG, only programs with a .PRG extension would appear in the file selector's window, as shown in figure 2.2. [INSERT FIGURES 2.1 AND 2.2 HERE] The user cannot change the file-filter portion of the pathname, but he can change the directory. There are three ways to do this: 1) by clicking the directory line, typing the new path, and then clicking the top of the file window; 2) by clicking a directory in the file window to move to that directory; or 3) by clicking the button in the upper- left corner of the file window to move back one directory. To the right of the file window is the filename field. This field is usually blank until the user selects a file. However, the programmer can give GEM a default filename to display when he calls the file selector box. The user can select a file three ways: 1) by typing the file into the filename field and then clicking the OK button; 2) by clicking the filename in the file window and then selecting the OK button; or 3) by simply double-clicking the filename in the file window. Besides its button and file bar, the file window also contains scroll bars, which allow the user to see files that are not currently displayed in the window. This scroll bar is operated by clicking it with the mouse pointer. --The Program-- In the CHAP2 folder of your *ST Assembly Language Workshop* disk, you'll find two files. PROG2.S is the source code for this chapter's sample program, which is reprinted at the end of this chapter. PROG2.PRG is the assembled, runnable program file. If you would like to assemble the program yourself, please consult your assembler's manual or refer to this book's Appendix A. When you run the program, a file selector box appears on the screen. Use the file selector to move from one directory to another. Finally, select a file, and then click the OK or Cancel button. If you select the cancel button the program will return to the desktop. If you select the OK button, the program will display the full pathname for the file you chose. Press Return to return to the desktop. --Getting the Current Drive-- Now, let's look at the program's code, to see what's happening. The program begins just like our previous one, by setting up a stack, releasing unused memory, and initializing the GEM application with a call to *appl_init*. After that, the fun begins. When you call the file selector box, you need to give it a path for its pathname line. This could be any path you like. However, it is standard practice to have the file selector already set to the currently active path, usually the path from which the program was run. To get this information for the file selector, we must first get the current drive letter and the current path. Then we must combine these into a single string. Right after our call to *appl_init*, you'll see the code in which we get the current drive letter. It looks like this: move #DGETDRV,-(sp) trap #1 addq.l #2,sp add #'A',d0 move.b d0,pathname move.b #':',pathname+1 The first three lines are a call to GEMDOS function #25, *Dgetdrv*, which returns in D0 a number representing the currently active drive. A 0 indicates drive A, a 1 indicates drive B, a 2 indicates drive C, and so on. Once we have the drive number in D0, we need to convert it to an ASCII character for our path string. We do this in line 4 above. The *#'A'* is just another way of representing the ASCII value of "A." By adding the ASCII value of "A" to the drive number, we end up with the drive letter we want. We did this type of conversion in volume 1 of *The Assembly Language Workshop*. The last step is to move the drive letter to the first byte of our pathname string, and place a colon in the second byte of the pathname string. This is accomplished in the last two lines above. Note that the label *pathname* represents the address of a 128-byte string. You can find this string in the program's BSS. Why do we need 128 bytes? Because the file selector will use this area to return the user's selected path to us. Because paths can be long, we must be sure to provide plenty of space. Otherwise, other data may get overwritten by the pathname string returned by the file selector. --Getting the Current Path-- Now that we have the current drive letter, we need to get the current path. The five lines of code following the call to *Dgetdrv* accomplish this task. The code looks like this: move #0,-(sp) move.l #pathname+2,-(sp) move #DGETPATH,-(sp) trap #1 addq.l #8,sp The above is a call to GEMDOS function #71, *Dgetpath*. As you can see, the call requires that three parameters be placed on the stack. The first is the number of the drive for which you want to retrieve the path. For this word value, 0 represents drive A, 1 represents drive B, and so on. The second parameter is the address of the buffer where *Dgetdrv* should store the path string. In the second line above, we're giving the function the address of the third byte of our pathname string. Why? Because we've already got the drive letter and a colon on the first two bytes. By giving the function the address of the third byte, it'll not only return the path string to us, but will also automatically tack it onto our drive specifier. The third and final parameter is the function number. --Pathnames, File Selector Style-- Even after we've got the entire pathname, we're still not ready to call up the file selector. We need to add a default file specification to the end of the path. The usual default is \*.*, which will allow the file selector to show every file in the current directory. However, you could use any default. For example, if you were asking the user for a DEGAS picture file, you'd probably want to use the default of \*.PI?, which filters out all files except those with extensions starting with PI. If you look at the sample program, right after the call to *Dgetpath*, you'll see where we add the \*.* to our path string. First, we must search for the end of the string. We do this by scanning the string from the beginning until we find a null. Once we've found the position of the null character, we simply tack on the \*.* characters. --Calling the File Selector-- Now, our pathname string is ready for the file selector box. We now bring up the file selector and let the user choose the file. The code in our sample program that brings up the file selector box looks like this: move #FSEL_INPUT,control0 move #0,control1 move #2,control2 move #2,control3 move #0,control4 move.l #pathname,addr_in move.l #filename,addr_in+4 jsr aes Because the file selector is an AES call (function #90, *fsel_input*), we must initialize the control array, as well as place the necessary values in the other arrays. With this call, the only other arrays we use are addr_in and int_out. We use the addr_in array to tell the file selector where the pathname and filename strings are. The file selector will also use these two strings to return the selected filename and pathname to us. The file selector will use the first two words of the int_out array to return an error code and a button code, respectively. The error code will be 0 if an error occurred or greater than 0 if no error occurred. The button code will be 0 for the cancel button and 1 for the OK button. Note that there is a slightly modified version of the *fsel_input* call for newer versions of GEM (Rainbow TOS) This new call, named *fsel_exinput*, allows the programmer to replace the "Item Selector" string that appears at the top of the file selector box with something more meaningful, such as "Choose file to load." A typical call to the new file selector looks like this: move #FSEL_EXINPUT,control0 move #0,control1 move #2,control2 move #3,control3 move #0,control4 move.l #pathname,addr_in move.l #filename,addr_in+4 move.l #string,addr_in+8 jsr aes There are only three differences between the *fsel_exinput* and the older *fsel_input* call. First, the function number for the new call, represented above by the constant FSEL_EXINPUT, is 91. Second, you must indicate that your addr_in array is three elements long by loading a 3 into control3. Finally, you need to store into the third element of addr_in the address of the string you want at the top of the file selector. Note that, on TOS versions earlier than 1.4, the *fsel_exinput* will generate a run-time error (bad function number). If you want to use this call safely, you must, within your program, check for the version of TOS under which your program is currently running. If the version is earlier than 1.4, you must stick with the old *fsel_input* function. --Constructing the Selected Path-- After the user selects a path and filename with the file selector, he closes the file selector by clicking the OK or Cancel buttons. If the value stored in the second element of int_out indicates that the OK button was pressed, we must build the final, complete pathname, using the information returned by the file selector. The chosen pathname will be in the *pathname* string, and the chosen filename will be in the *filename* string. The first step in constructing the final pathname is to scan the path string for the null that marks the end of the string. Once we've found the null, we must scan backward until we find a backslash character. We need to do this because the path, as returned from the file selector, still includes the default file specification. For example, the path may look like C:\UTILITY\*.*. We of course must replace the *.* with the actual file selected. Once we've found the backslash character, we tack the filename on. Using the example path above, our final path should look something like C:\UTILITY\FILECOPY.PRG. This final pathname contains all the information we need to access the chosen file. In the sample program, the code that creates the final pathname is fairly straight forward and heavily commented. You should have little trouble seeing how it works. After constructing the final pathname, the sample program simply displays the path on the screen and waits for the user to press a key, after which the application terminates and the program returns control to the desktop. --Conclusion-- The file selector is typical of most GEM forms: It provides a convenient way for users to give information to a program. Likewise, it makes it easy for the programmer to request this information, by using an device with which the user is already familiar. Every GEM program you write should use the file selector wherever it's necessary for the user to choose a file. --Summary-- * The GEMDOS function #25, *Dgetdrv*, returns the currently active drive in D0. * The GEMDOS function #71, *Dgetpath*, returns the currently selected path into a string whose address is one of the function's parameters. * The AES call #90, *fsel_input*, brings the file selector box up onto the screen. * On TOS version 1.4 or newer, the AES call #91, *fsel_exinput*, lets you bring up a file selector and replace the standard "Item Selector" string with a string of your own. * When the file selector returns the chosen pathname and filename, it's up to the programmer to use them to create the complete path.
CW_PROG2MAC.S (Source of the chapiter)
CW_PROG2.S (Source of the chapiter)
Back to Assembly_language_tutorials