January 93 - Children of the DogCow
Children of the DogCow
Kent Sandvik and Jeroen Schalk
In MacApp 3.0 it is relatively easy to add extra dialog items to Standard Get File and
Standard Put File. However, youhave to use normal 'DLOG' and 'DITL' resources to
ac-complish this. It would be much nicer if you were able to add 'View' resources to
Standard File.
Using MacApp 2.0, Danie Underwood had already created a number of patches for his
MacApp Drafter application that implemented this feature. We decided to implement
his ideas in MacApp 3.0 and add some extra features.
You will find that these changes are easy to add to your application. You just have to
subclass your application object from TSFPApplication and your document from
TSFPFileBasedDocument and override a couple of methods.
As a bonus, file filtering is also implemented as a method. There is no longer a need to
write a low level file filter function. Just override the TSFPApplication.FileFilter()
method.
Changing Standard File
This article won't explain in detail how to change the behavior of Standard File. A
number of resources are available that explain the principle and give example code on
how to do it. Suffice it to say that up to four call back routines can be installed with the
Standard File routines. These callbacks are invoked by Standard File as part of its
event processing:
• The first callback is the Dialog Hook routine. It is called whenever
anything significant happens in Standard File. Of importance for us are the
events sfHookFirstCall, sfHookLastCall and sfHookNullEvent. sfHookFirstCall
is the first event that happens (before the Standard File dialog is shown). It
gives us the opportunity to add items to the dialog. sfHookLastCall gives us the
opportunity to do some cleanup, e.g. delete the added view hierarchy.
sfHookNullEvent is called repeatedly while the dialog is on screen. The current
selection in the Standard File dialog is available for application use during this
'idle time' process.
• The second call back is the dialog filter routine. It provides raw event data
to your routine and gives you the opportunity to intercept events and handle
them yourself. We want to intercept update and mouse events that are meant
for our added view hierarchy and forward these to the MacApp event handling
code.
• The third callback is the File Filter routine. It is used in Standard Get File
to determine which files should be displayed. It is an extension to the filtering
on file type that the MacApp framework provides.
• The fourth callback is an activation callback that can be used if extra edit
items have been added to the Standard File. We ignore this callback in our code.
It is only available under System 7.0.
The prototype of these callbacks is as follows under System 7.0:
typedef pascal short (*DlgHookYDProcPtr)(short item,
DialogPtr theDialog, void *yourDataPtr);
typedef pascal Boolean (*ModalFilterYDProcPtr)(DialogPtr theDialog,
EventRecord *theEvent, short *itemHit, void *yourDataPtr);
typedef pascal Boolean (*FileFilterYDProcPtr)(ParmBlkPtr PB,
void *yourDataPtr);
typedef pascal void (*ActivateYDProcPtr)(DialogPtr theDialog,
short itemNo, Boolean activating, void *yourDataPtr);
For System 6.0, the same type of callbacks are present except for the activate
callback, but they lack the last parameter. This last parameter (void *yourDataPtr)
allows you to pass a user defined data structure to your callback.
Strategy
Given these callbacks, our strategy is as follows:
1. Install a dialog filter routine that will create a 'View' resource on
sfHookFirstCall and add it to the Standard File dialog. Clean up is done on
sfHookLastCall, and on sfHookNullEvent we let our application know which file
or folder is cur-rently selected. Note that on Standard Put file, the "selected
file" is the name of the file that the user is specifying.
2. Install a dialog hook routine that will intercept selected events. We choose
to intercept only the mouseDown and update events. If this mouseDown event
occurs within the extent of the 'View' we have added, we will dispatch it to this
view. Update events have to be first dispatched to our view hierarchy so that
we can refresh the parts that Standard File can not reach. After that, we hand
the update event back to Standard File so that it can redraw its own dialog
items.
3. Install a File Filter routine that creates a TFile object from the
information it gets and calls one of our application methods to do the actual file
filtering. This third step is relevant only for Standard Get File.
Use Of Standard File in MacApp 3.0
Standard File routines are used in two locations in MacApp 3.0. MacApp uses either the
Custom routines found in System 7.0 or later releases or the old SFP (Standard File
Programmer) routines.
The first use of Standard File routines is in TApplication.ChooseDocument() that is
called whenever the user chooses "Open" from the File menu. It calls
TApplication.GetStandardFileParameters() to get a reference to a file filter routine, a
modal dialog filter routine and a dialog hook routine. It then uses either
CustomGetFile() or SFPGetFile() to pose the Standard Get File dialogs.
The second use is in TFileHandler.RequestFileName(). This one calls
TFileHandler.SFPutParms() to get a modal dialog filter routine and a dialog hook
routine and subsequently calls CustomPutFile() or SFPPutFile().
MacApp uses a trick so that the same call back routines can be used in both the
Custom() and the SFP() cases. In the SFP() case, it packages the call back routines in a CallBack data structure. This data structure actually contains some
assembler code that reserves space for the extra parameter, pushes that extra
parameter and jumps to the original callback.
Note that there are some bugs in how this is implemented in MacApp 3.0. First of all,
it can't handle the situation where you have more than one callback (as will be the case
in our code). Only the modal dialog filter routine was packaged, not the other ones. A
second bug could occur if you returned NULL for this modal dialog filter routine in
your override of GetStandardFileParameters() or SFPutParms(). The CallBack data
structure would make the code jump to zero. Not a good idea. The first thing we had to
do was fix these potential problems.
Based on the use of Standard File in MacApp 3.0, we chose the following strategy to
implement our changes:
1. The class TSFPApplication was introduced. It overrides
TApplication.GetStandardFileParameters() and
TApplication.ChooseDocument(). We also added a method
TSFPApplication.ExtraViewID() to determine the id of the 'View' resource to
add and a method TSFPApplication.FileFilter() to implement a higher level file
filter method.
2. The class TSFPFileHandler was introduced. It overrides
TFileHandler.RequestFileName().
3. The class TSFPFileBasedDocument was introduced that overrides
TFileBasedDocument.SFPutParms() and attaches an instance of a
TSFPFileHandler to it in TDocument.DoMakeFileHandler(). We also added a
method TSFPFileBasedDocument.ExtraViewID() to determine the id of the
'View' resource to add in and a method TSFPFileBasedDocument.GetPrompt()
to determine the prompt to use.
The method ExtraViewID() that determines the ID of the view to add gets the command
number used to open or save as a parameter. This means you can test this parameter to
add a different dialog if you have more than one command number to open a file. An
example is if you want to open a help file as well as a normal document. You could
install a view with a "Search Help" button.
TSFPWindow and TSFPView
In order to add a view hierarchy to Standard File, we need to treat the Standard File
window as one of our own TWindows. This turns out to be relatively straightforward if
you consider the following:
1. Standard File disposes of the window manager port, and so does
TWindow.Free(). We need to override TSFPWindow.Free() to prevent this
from happening.
2. MacApp draw code erases the port rectangle before drawing. Standard File
is not aware of this and would not refresh these erased parts. This problem can
be fixed by removing the erase adorner from our window. This is done in the
TSFPWindow.ISFPWindow() method.
3. The window itself should NOT draw as Standard File takes care of that. So