>Wongck at 15:35, 12 October 2011

2011-10-12T15:35:43Z

← Older revision		Revision as of 11:35, 12 October 2011
Line 313:		Line 313:

	Back to [[Assembly_language_tutorials]]		Back to [[Assembly_language_tutorials]]
	[[Category:~~Programming~~]]		[[Category:Assembly Language Workshop]]

>Silver Surfer: Added category

2009-05-02T17:22:44Z

Added category

← Older revision		Revision as of 13:22, 2 May 2009
Line 313:		Line 313:

	Back to [[Assembly_language_tutorials]]		Back to [[Assembly_language_tutorials]]
			[[Category:Programming]]

>Zorro 2 at 13:47, 24 October 2006

2006-10-24T13:47:32Z

New page

<pre>

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.

</pre>

[[CW_PROG2MAC.S]] (Source of the chapiter)

[[CW_PROG2.S]] (Source of the chapiter)

Back to [[Assembly_language_tutorials]]

CW CHAPTER 2 - Revision history

>Wongck at 15:35, 12 October 2011

>Silver Surfer: Added category

>Zorro 2 at 13:47, 24 October 2006