All DatabasesMacTech Vol 03-1987
File Dialog
Volume Number: 3
Issue Number: 2
Column Tag: ToolBox Tricks
Not So Standard File Dialogs
By Paul Snively, Contributing Editor, Icom Simulations, Inc.
Last month I discussed how INIT resources could be debugged using TMON, as I did
in developing my Set/Boot Paths desk accessory, used in TML Pascal 2.0. Set Paths
allows the user to specify what path to use via what I prefer to call the
Not-So-Standard File dialog. It's Not-So-Standard because it doesn't display file
names at all, only folder names. That's not so weird (nor is it particularly difficult to
code), but the "Open" button has become "Select" and, the tricky part, double-clicking
on a folder name opens it exactly the way you'd expect, whereas highlighting a folder
name and clicking on "Select" returns you to your program with pertinent information
about the selection.
Experienced Standard File hackers may knot their brows at this (as I did when I
was asked to do it that way) because they know that the Standard File internally
coerces double-clicks on names to be a single click followed by a click on the "Open
button, so that the Standard File hook can filter double-clicks. The trick, then, is
being able to use a user-written Standard File hook to distinguish between a
double-clicked name and a selected name followed by a "Select" click.
Note that my solution is a kludge by just about any definition of the word, and
would be universally spurned (even by me) were it not for one simple, overriding
fact: it does NOT rely on internal knowledge of Standard File's workings AT ALL, and it
was simple and obvious enough to have gone from concept to implementation in less
than twelve hours (an important consideration for me; I modemed the resultant files to
TML Systems Sunday evening; TML Pascal 2.0 started shipping the next day)!
To start off on an embarrassing note, in the process of writing Set Paths I
discovered a bug in my McAssembly Pascal interface macros. Those were published in
MacTutor Vol. 2, No. 3, in March 1986, which says two things to me: I need to be
more careful in my testing of things before I publish them, and no one has done
anything significant with those macros, otherwise they would have encountered the bug
and, hopefully, written a letter to the editor about it! I'm profoundly disappointed
Anyway, the bug is in the "Exit" macro. There's a line which is responsible for
adjusting the stack back to normal by dropping input parameters. It says:
add.l #.fsize-.parms,sp
This is a definite boo-boo, because it totally neglects the space that we allocated
for the stacked A6 register and the return address of the function. The line SHOULD
read:
add.l #.fsize-.parms-8,sp.
Boy, do I feel appropriately chastized!
Having cleared that up, I can talk safely about using those macros to implement
the Not-So-Standard File dialog.
First we need to come up with a way to display NO files at all. The first time I
tackled this, ol' Paul thought he'd be tricky and just set the numTypes parameter to
_SFGetFile to zero, thereby forcing _SFGetFile to ignore all files, right? Wrong!
Even though I had a typeList consisting of all zeros and a numTypes of zero, _SFGetFile
insisted on displaying ALL files on the volume, and it took forever to do it, too!
I decided to do something about the INCREDIBLY slow response I was getting from
the above scheme. Besides, it didn't work! I changed numTypes to one and used a
fileType of '????' to get as few files as possible (theoretically zero). Since every so
often you will indeed see a file of type '????' it behooved me to ensure that they didn't
show up in the file list. To do that I had to use that fileFilter that I had tried to avoid.
The fileFilter proc is, like most such things for the Macintosh, designed with the
expectation that it will be written conforming to Pascal-style parameter passing
conventions. It is (in Pascal terms, anyway) a function, not a procedure, since it
returns a value. It takes one parameter, a pointer to a low-level parameter block a lá
the file system, and returns a boolean. It seems a little backwards: the boolean should
be TRUE if the file is NOT to be displayed, and FALSE if the file IS to be displayed. So,
since we want to display NO files, we should simply set the boolean to TRUE and we are
done! In Pascal this would look something like this:
FUNCTION MyFileFilter(PB : ParamBlockRec;) : BOOLEAN;
BEGIN {MyFileFilter}
MyFileFilter := TRUE;
END; {MyFileFilter}
In McAssembly, with my Pascal macros, it's almost as easy: (See MacTutor Vol.
2, No. 3 March 1986 for the definition of these Macros.)
MyFileFilter EQU *
;
SFBegin
WordResult MyFilterResult
Long MyParamBlock
SFEnd
;
Enter
move.w #-1,MyFilterResult
Exit
The combination of the file type of '????' and the above fileFilter works like a
charm; by golly, no files show up!
SFHook
The remaining magic is in an underdiscussed piece of code called a SFHook. Apple
describes the SFHook as something that can be used to make a non-standard get or put
file (which I almost do) or to make the normal one behave in non-standard ways
(which is EXACTLY what I do)!
The SFHook is also a Pascal-like entity; it takes two parameters; the item
number (an integer), and the DialogPtr to the Standard File dialog. It returns an
integer (an item number also, although it may or may not be the same as the one that
was passed to it)!
The SFHook is called constantly throughout the operation of the Standard File
dialog; it's called before the dialog is drawn, it's called when there are significant
events, and it's even called when there are NO significant events!
The key to understanding the Standard File dialog as it applies to writing a SFHook
is the item number. The item number is ordinarily simply the item number of
whatever the user clicked on in the dialog box. In addition to that there have always
been a few "phony" items numbers, such as item # 100 (which is what was passed
when nothing interesting was going on) or keystrokes (item # 1000 plus the ASCII
value of the key). Another useful value is -1, which is the value passed before the
dialog is displayed. By trapping on this value we can do neat things like changing the
title of the "Open" button to "Select." You'll see an example of that a bit later.
The introduction of HFS added a whole new wrinkle to the issue of the Standard
File dialog. It had to be expanded in a way that retained the power and flexibility of the
original design, yet also remain upwardly compatible. WDRefNum's and a few new
phony item numbers fit the bill rather nicely.
As all users of the Standard File dialog are aware of at one level or another,
"Opening" a folder doesn't return you to the application, it simply makes that folder
the current directory and shows you the files in it, etc. You must open a FILE to get
back from _SFGetFile.
Internally what happens is that opening a folder passes a phony item # 103 to
the SFHook, as opposed to a file open, which passes item # 1 (the item # of the "Open
button). So we could catch the 103, coerce it to a 1, and pass it back. The problem
there, of course, is the one mentioned before: double-clicks on filenames and filename
select/"Open" click sequences are equivalent by the time you get to the SFHook! The
result is that double-clicking on a foldername returns from _SFGetFile just as surely
as selecting one and clicking "Open" does!
Argh!!!
Ok, enough beating around the bush. Obviously the solution to the problem is to
find out which item we clicked on, the file list or the "Select" button. I decided that the
Mac was fast enough that I could determine within the SFHook where the mouse was,
check to see if it was over the file list and, if it was not, coerce the 103 to a 1.
Fortunately, one of the things passed to the SFHook is the DialogPtr, making calls to
_GetDItem possible. Among other things, _GetDItem returns the viewRect of the item
- just what the doctor ordered! _GetMouse gives us our mouse location in local
coordinates (another stroke of luck) and _PtInRect answers the burning question: are
we pointing to this item or aren't we?
Pulling it all together into a nice, not-so-neat package gives us the following:
UseSF move.w #100,-(sp) Top = 100
move.w #100,-(sp) Left = 100
pea PromptString Use promptstring
pea myFileFilter Use brief fileFilter
move.w #1,-(sp) No. of filetypes
pea MyList Point to my list
pea myDlgHook Point to our dlgHook
pea myReplyRec Point to reply rec
_SFGetFile Use std file dialog
myDlgHook
;
sfbegin Declare stack frame
wordresult myDlgResult Function result
word mySFItem Which item was hit?
long theDialog SFGetFile dialog ptr
sfend That's all!
;
enter Set up stack frame
move.w mySFItem,d0 Get the item#
cmp.w #-1,d0 Is this first time?
bne NotFirst Go if not
sub.l #14,sp Room for VAR params
move.l theDialog,-(sp) Stack DialogPtr
move.w #getOpen,-(sp) Stack item # of "Open
pea 18(sp) VAR itemType
pea 18(sp) VAR itemHandle
pea 14(sp) VAR dispRect
_GetDItem Tell me about button
movea.l 8(sp),a0 Get handle
add.l #14,sp Drop data structure
move.l a0,-(sp) Stack item handle
pea myTitle Pass title address
_SetCTitle Make title = STR
moveq #-1,d0 Make sure we're here
NotFirst equ *
cmp.w #103,d0 Was it "Select?
bne.s NotSelect Go if not
;***********************************************************
;*** This is where we will do all kinds of nifty magic ***
;**********************************************************
sub.l #14,sp Room for VAR params
move.l theDialog,-(sp) Stack DialogPtr
move.w #7,-(sp) Stack File List item#
pea 18(sp) VAR itemType
pea 18(sp) VAR itemHandle
pea 14(sp) VAR dispRect
_GetDItem Tell me about File List
clr.l -(sp) Room for pt
pea (sp) Point to the point
_GetMouse Here, mousie, mousie...
pea 4(sp) Point to the rect
_PtInRect Are we in File List?
move.w #103,d0 Just to make sure
move.b (sp)+,d1 Get answer
add.l #12,sp Drop remaining data
bne.s NotSelect If in File List, leave
move.w #1,d0 Treat like file open
NotSelect equ *
move.w d0,myDlgResult Store function result
exit Exit the function
;
myFileFilter equ *
loc New locals here; needed for McAssembly
;
sfbegin Stack Frame Begin
wordresult myFilterResult A boolean
long parmBlkPtr A pointer
sfend Stack Frame End
;
enter Set up stack frame
move.w #-1,myFilterResult TRUE;
exit Clean up and leave
;
PromptString equ *
text # "Highlight a folder and click /"Select/
align
myTitle equ *
text # "Select" title for "Open" button
align
myList equ *
text "????" Any old file type will do
dcb.b 12,0 Remaining are nulls
Now that I've given the code that does the trick, I should probably say a few words
about how the replyRec looks when you've opened a folder instead of a file.
First of all, you can forget about the fName field. It won't be valid. Instead,
vRefNum will contain the vRefNum of the folder, just like it does for a file, and - get
this - fType will return the DirID of the folder ("Sorry about the type conflict," says
Apple in the software supplement...obviously talking to Pascal programmers). Of
course, the vRefNum and DirID are sufficient for all HFS OSTraps that deal with
folders or files within a specific folder. Another thing that you can do if you want or
need to is convert the vRefNum and DirID to a pathname extending from the root to the
folder (or more precisely, from the folder to the root). One implementation of that
algorithm appeared in MacTutor's special HFS issue (January '86). It was written in
C by Mike Schuster. Translating it to the language of the reader's choice is an exercise
left to the reader (the assembler version is actually rather simple).
That just about covers it. Feel free to use the Not-So-Standard File dialog
anytime you have a reason to want to select a folder instead of a file!
Referenced by (9):