TweetFollow Us on Twitter

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.


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 fShown should be set false. Now this leads to another problem because a view does not show up if its window does not show. We fixed this by introducing a TSFPView class that overrides TView.Shown().
  4. The window should not handle mouse downs but pass them directly to the added view.
  5. When our window updates itself, it should not set the updateRgn to empty afterwards. This is because part of the update region 'belongs' to Standard File. Therefore, we need to restore that part of the update region.

The methods necessary to implement these changes are done in the TWindow subclass TSFPWindow. For completeness, TSFPWindow also keeps a Boolean field fNeedRefresh. If you set this field, an sfHookRebuildList event will be generated in the dialog hook routine.

Whenever one of the Custom…() or SFP…() routines is called, the system loads one of the 'DLOG' resources that contains the dialog items for that routine (sfGetDialogID, getDlgID, sfPutDialogID, putDlgID).

Now, if we know the number of the 'View' resource to add to the dialog, we can change the rectangle of that dialog to accommodate our added items. This is done in TSFPWindow.LocateAndResize().

The view hierarchy that we add to this window must always have one top view of class TSFPView and an identifier 'DLOG'. This is needed so that we can:

  1. Easily locate the added views and resize the Standard File dialog box with the dimensions of that top view.
  2. Add a couple of abstract 'callback' methods to this top view. These methods are called from within our dialog hook routine on sfHookNullEvent events. These callbacks (WantToUpdate() and SetOkEnable()) pass information on the currently selected file or folder and information on the state of the Save/Open button.
  3. Override TView.Shown(). It should not ask its window, but instead use its own fShown field.

Putting It All Together: USFP.cp and USFP.h

The implementation is available in the source files USFP.cp and USFP.h. Functionality for overriding Standard Get File and Standard Put File is combined, although you could split it up if necessary. We use a set of globals (all beginning with "pSFP") to store some global references. This is necessary so that we can use them from within our call back routines.

The dialog hook routine is called SFPDialogHook(). During sfHookFirstCall processing in our dialog hook procedure we create an instance of our special window TSFPWindow. We also create our view hierarchy and adapt the size and location of Standard File's dialog (in TSFPWindow.DoLocateAndResize()).

During sfHookNullEvent we call TSFPView.WantToUpdate() with information on the currently selected file or folder. We also determine whether the Save/Open button is currently enabled and pass this information to our view in TSFPView.SetOkEnable(). In sfHookLastCall we can clean up any views that we have added:

static pascal short SFPDialogHook(short item, DialogPtr theDialog, void *)
    short returnItem = item;
    switch (item) {
    case sfHookFirstCall:
    // set reference to Standard File Dialog
        pSFPDialog = theDialog;
    // Install the MacApp world.
        if (! pSFPWindow && pSFPViewID) {
            pSFPWindow = new TSFPWindow;
            if (pSFPWindow) {
                pSFPWindow->ISFPWindow(NULL, GrafPtr(theDialog));
                gViewServer->DoCreateViews(NULL, pSFPWindow,
                        pSFPViewID, gZeroVPt);
                pSFPWindow->GetSFPView()->Show(true, false);
    case sfHookNullEvent:
        if (pSFPWindow) {

            // see if list of files needs updating
            if (pSFPWindow->GetNeedRefresh()) {
                returnItem = sfHookRebuildList;
            } else {
            // get added view
                TSFPView *view = pSFPWindow->GetSFPView();
            // focus on window

                // update view depending on OK state
                Handle  dialogItem;
                CRect   itsBox;
                short   itemType;
                ::GetDItem(theDialog, pSFPGetPutOK, itemType,
                        dialogItem, itsBox);
                Boolean okEnabled =         
                        != 255);

                // update view with information on current reply

    case sfHookLastCall:
        if (pSFPWindow) {
        // throw out allocated view hierarchy
            pSFPWindow = NULL;
    } // end of switch()
    return returnItem;

The dialog filter routine is called SFPDialogFilter(). In our dialog filter callback we detect mouseDowns inside our added view and pass these events directly to that added view. We handle update events for our special TSFPWindow (which shares the window manager port of Standard File) by drawing our added view hierarchy and passing on the update event to Standard File:

static pascal Boolean SFPDialogFilter(DialogPtr theDialog,
        EventRecord& theEvent, short& itemHit, void *yourDataPtr)
    Boolean result = false;
    switch (theEvent.what) {

        case mouseDown: { 
        // mouse down events the MacApp way.
            Boolean oldObjectPerm;
            oldObjectPerm = AllocateObjectsFromPerm(FALSE);
            TToolboxEvent* theToolBoxEvent = new TToolboxEvent;
            theToolBoxEvent->IToolboxEvent(gApplication, theEvent);

            // get mouse location
            CPoint theMouse = theEvent.where;
            TSFPView *view = pSFPWindow->GetSFPView();

            // convert to local coordinates
            VPoint theVMouse = theMouse;
            if (view->ContainsMouse(theVMouse) &&
                view->HandleMouseDown(theVMouse, theToolBoxEvent,
                gStdHysteresis)) {
                result = true;

        case updateEvt:
            if (WindowPtr(theEvent.message) != theDialog) {
            // update MacApp windows
            result = true;
        } else {
        // update MacApp part and pass update to Stand File
    return result;

Last, our file filter call back SFPFileFilter() will get information about the file to test, makes that into a TFile object and calls a method of our TSFPApplication:

pascal Boolean SFPFileFilter(ParmBlkPtr p, void *)
// no #define for stationary bit
const short isStationery = 0x0800;
// get current volume
ParamBlockRec oldVol;
oldVol.volumeParam.ioNamePtr = NULL;
::PBGetVol(&oldVol, false);

// get current directory
WDPBRec     WDRec;
WDRec.ioNamePtr     = NULL;
WDRec.ioVRefNum     = p->fileParam.ioVRefNum;
WDRec.ioWDProcID    = 'ERIK';
WDRec.ioWDDirID     = *kCurDirStorePtr;
::PBOpenWD(&WDRec, false);
::PBSetVol(&oldVol, false);

// name of file to test is passed in
CStr63 name = p->ioParam.ioNamePtr;
// create TFile
TFile *aFile = new TFile;
        WDRec.ioWDDirID, name);
::PBCloseWD(&WDRec, false);

// set type and creator
FInfo finderInfo;
if (aFile->GetFinderInfo(finderInfo) == noErr) {
    aFile->fFileType = finderInfo.fdType;
    aFile->fCreator = finderInfo.fdCreator;
    if (finderInfo.fdFlags & isStationery) {
        aFile->fStationery = TRUE;

// pass it to the application object
Boolean returnVal =
    ((TSFPApplication *)gApplication)->FileFilter(aFile);
return returnVal;

Examples: UMySFP.cp and UMySFP.h

As an example of how you can use these extensions, we developed a small application called UMySFP. This application overrides both Standard Get File and Standard Put File.

In Standard Get File, we show a 'preview' of AppleLink documents, where the preview consists of the sender followed by '•', followed by the subject, e.g. "SCHALK1 • Not So Standard File". As you can see in the sources, we define a subclass TOpenAppleLink of TSFPView with a method TSFPView.WantToUpdate(). We also subclass TSFPApplication and implement TMySFPApplication.ExtraViewID() to return the ID of the 'View' to add. As a bonus, we also change TSFPApplication.FileFilter() so that we filter out all files that have already been opened (see Figure 1):

pascal short TMySFPApplication::ExtraViewID(CommandNumber)
    return kOpenAppleLinkViewID;
pascal void TOpenAppleLink::WantToUpdate(SFReply &aSFReply,
        StandardFileReply& aCustomReply)
    CStr255 aPreview;
// create "originator • subject"
    this->CreatePreView(aSFReply, aCustomReply, aPreview);
// and set in text field
pascal Boolean TMySFPApplication::FileFilter(TFile *aFile)
    if (inherited::FileFilter(aFile) ||
            (aFile->fCreator != 'GEOL') ||
            gApplication->FindDocument(aFile)) {
        return true;
    return false;

The second part customizes Standard Put File. We add a couple of radio buttons and a popup menu to select the type of file to save. Again we use a subclass TSaveAppleLink of TSFPView. We subclass our TMySFPFileBasedDocument from TSFPFileBasedDocument and give it an ExtraViewID() method to yield the id of the 'View' resource to add. Note that you would have methods in your TSaveAppleLink class to let your application know which type of document was selected. This is not implemented (see Figure 2).

pascal short TMySFPFileBasedDocument::ExtraViewID(CommandNumber)
    return kSaveAppleLinkViewID;

The views themselves are created in a ViewEdit file. Don't forget to give them a top-level view of a subclass of TSFPView and to set its identifier to 'DLOG'


  • New Inside Macintosh : Files
  • New Technical Notes M.FL.SFCustomize
  • MacApp ™ Drafter on E.T.O. 9

Community Search:
MacTech Search:

Software Updates via MacUpdate

ExpanDrive - Access cloud storag...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
Markly 1.5.3 - Create measurement and de...
Markly is a measurement and design-spec plugin/extension for Photoshop and Sketch. It is made for modern Web designers and app front-end developers. You can add specification marks simply by clicking... Read more
Suitcase Fusion 6 17.3.0 - Font manageme...
Suitcase Fusion 6 is the creative professional's font manager. Every professional font manager should deliver the basics: spectacular previews, powerful search tools, and efficient font organization... Read more
Nisus Writer Pro 2.1.2 - Multilingual wo...
Nisus Writer Pro is a powerful multilingual word processor, similar to its entry level products, but brings new features such as table of contents, indexing, bookmarks, widow and orphan control,... Read more
calibre 2.40.0 - Complete e-book library...
Calibre is a complete e-book library manager. Organize your collection, convert your books to multiple formats, and sync with all of your devices. Let Calibre be your multi-tasking digital librarian... Read more
Vivaldi - An advanced browser...
Vivaldi is a browser for our friends. In 1994, two programmers started working on a web browser. Our idea was to make a really fast browser, capable of running on limited hardware, keeping in mind... Read more
OmniPlan 3.0 - Robust project management...
With OmniPlan, you can create logical, manageable project plans with Gantt charts, schedules, summaries, milestones, and critical paths. Break down the tasks needed to make your project a success,... Read more
Yummy FTP 1.11 - FTP/SFTP/FTPS client fo...
Yummy FTP is an FTP + SFTP + FTPS file transfer client which focuses on speed, reliability and productivity. Whether you need to transfer a few files or a few thousand, schedule automatic backups, or... Read more
Tweetbot 2.1 - Popular Twitter client. (...
Tweetbot is a full-featured OS X Twitter client with a lot of personality. Whether it's the meticulously-crafted interface, sounds and animation, or features like multiple timelines and column views... Read more
MacPilot 8.0 - Enable over 1,200 hidden...
MacPilot gives you the power of UNIX and the simplicity of Macintosh, which means a phenomenal amount of untapped power in your hands! Use MacPilot to unlock over 1,200 features, and access them all... Read more

Balloony Land offers a fresh twist on th...
Balloony Land by Palringo offers a fresh twist on the match three genre and is out now on iOS and Android. First-off, you'll be popping balloons instead of crushing candy and the balloons will float up and fill the empty spaces instead of dropping... | Read more »
Graphic - vector illustration and design...
Graphic - vector illustration and design 1.0 Device: iOS iPhone Category: Productivity Price: $2.99, Version: 1.0 (iTunes) Description: Autodesk Graphic is a powerful full-featured vector drawing and illustration application right in... | Read more »
Sago Mini Babies (Education)
Sago Mini Babies 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: Introducing the Sago Mini babies. Boys and girls love caring for these adorable characters. Feed Robin her favorite mush... | Read more »
PAUSE - Relaxation at your fingertip (H...
PAUSE - Relaxation at your fingertip 1.1 Device: iOS iPhone Category: Healthcare & Fitness Price: $1.99, Version: 1.1 (iTunes) Description: | Read more »
Super Sharp (Games)
Super Sharp 1.1 Device: iOS Universal Category: Games Price: $1.99, Version: 1.1 (iTunes) Description: Your finger has never been so sharp! Cut with skill to complete the 120 ingenious physics levels of Super Sharp and become a cut... | Read more »
Assembly - Graphic design for everyone...
Assembly - Graphic design for everyone 1.0 Device: iOS Universal Category: Photography Price: $2.99, Version: 1.0 (iTunes) Description: Assembly is the easiest most powerful design tool on the App Store. Create anything you can... | Read more »
Dub Dash (Games)
Dub Dash 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: ARE YOU READY FOR THE ULTIMATE CHALLENGE? UNIQUE SYMBIOSIS OF MUSIC AND GRAPHICS | Read more »
Leave Me Alone (Games)
Leave Me Alone 1.0 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0 (iTunes) Description: 33% off launch sale!!! Somewhere between the 1980s and 1990s there exists a world that never was. A world of skatepunks,... | Read more »
YAMGUN (Games)
YAMGUN 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: The invasion has begun! Protect the walls of the citadel against waves of enemies! But watch out, you will soon run out of ammo...... | Read more »
Chesh (Games)
Chesh 1.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0 (iTunes) Description: It’s like chess, only not at all. ***40% off for a limited time to celebrate our launch!*** Chesh is a game of skill, strategy, luck,... | Read more »

Price Scanner via

TP-LINK Next-Gen Routers Support a Large Numb...
TP-LINK, specialists in consumer and business networking products, have announced the availability of Archer C2600, the company’s next-generation router featuring wireless AC, multi-user MIMO, and 4-... Read more
Apple’s Education discount saves up to $300 o...
Purchase a new Mac or iPad using Apple’s Education Store and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free, and... Read more
Save up to $350 with Apple refurbished iMacs
Apple has Certified Refurbished iMacs available for up to $350 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 27″ 3.5GHz 5K iMac – $1949 $350 off MSRP - 27... Read more
Mac Pros on sale for up to $300 off MSRP
B&H Photo has Mac Pros on sale for up to $300 off MSRP. Shipping is free, and B&H charges sales tax in NY only: - 3.7GHz 4-core Mac Pro: $2818.99, $181 off MSRP - 3.5GHz 6-core Mac Pro: $3699... Read more
5K iMacs on sale for up to $150 off MSRP, fre...
B&H Photo has the 27″ 3.3GHz 5K iMac on sale for $1899.99 including free shipping plus NY tax only. Their price is $100 off MSRP. They have the 27″ 3.5GHz 5K iMac on sale for $2149, $150 off MSRP... Read more
Twelve South Redesigns BookArc For Today’s Sm...
Twelve South has announced a redesigned version of their very first product, BookArc for MacBook. Tailored specifically for the newest generation of MacBooks, BookArc holds the new, smaller Apple... Read more
Phone 6s Tips & Tricks – Tips Book For iP...
Poole, United Kingdom based Tap Guides Ltd. has announced the release and immediate availability of iPhone 6s Tips & Tricks, an in-depth eBook available in the iBookstore that’s priced just $2.99... Read more
Apple refurbished 2014 13-inch Retina MacBook...
Apple has Certified Refurbished 2014 13″ Retina MacBook Pros available for up to $400 off original MSRP, starting at $979. An Apple one-year warranty is included with each model, and shipping is free... Read more
13-inch 2.5GHz MacBook Pro on sale for $994,...
Best Buy has the 13″ 2.5GHz MacBook Pro available for $994.99 on their online store. Choose free shipping or free instant local store pickup (if available). Their price is $105 off MSRP. Price valid... Read more
Is The iPad Pro Really A Serious Laptop Repla...
Probably not, at least for productive professionals and other power users. Steve Jobs declared that we’d entered the “post-PC Era” with the advent of the original iPad in 2010, a phrase we don’t hear... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (US) - A...
Job Description:SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, you're Read more
*Apple* Solutions Consultant -Bilingual, Chi...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
*Apple* Solutions Consultant - Retail Sales...
**Job Summary** As an Apple Solutions Consultant (ASC) you are the link between our customers and our products. Your role is to drive the Apple business in a retail Read more
SW QA Engineer - *Apple* TV - Apple (United...
**Job Summary** The Apple TV team is looking for experienced Quality Assurance Engineers with a passion for delivering first in class home entertainment solutions. **Key Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.