TweetFollow Us on Twitter

Multifile Dialogs in CPX

Volume Number: 13 (1997)
Issue Number: 7
Column Tag: Toolbox Essentials

Creating Multi-File Dialogs in CPX

by John Shackelford, Tangent Systems

How to build a custom file dialog with CustomGetFile and how to manage the dialog callback routines


The ease that applications are built in CPX often masks the flexibility of writing low-level code for the Macintosh. Prograph CPX ships with a class library called Application Building Classes (ABCs) which, in the world of Macintosh application frameworks, ranks among the richest. However, one particularly useful chunk of code that you will not find in the ABCs is the fancy file dialog you create using CustomGetFile.

You use the CustomGetFile feature to add source files to projects in several popular Macintosh applications like CodeWarrior, Roaster or Symantec Project Manager. The File classes in the ABCs all use the Standard GetFile dialog to retrieve files. This is fine for single file operations, but if your application must provide the ability to manipulate several files at once, CustomGetFile must be used to add controls for collecting the list of files. Surprisingly, when I wrote the code for a CPX version of CustomGetFile, it was difficult to find a complete example in C or Pascal on which to base the design. I did find some chunks or pieces in C and some CPX that I used as a basis for MultiFile.

MultiFile is a CPX section. It provides a class for a multifile dialog of the type shown below. It allows you to navigate, add and subtract several files all in one dialog session. The section also provides a basic file dialog allowing you to specify the user prompt. However, this article focuses on MultiFile Dialog -- it shows you how to use the MultiFile Dialog class and discusses key code snippets.

MultiFile Demo Application

The demo application opens a MultiFile Dialog and allows you to add and subtract files. Its purpose is to demonstrate what a MultiFile Dialog provides (see Figure 1). The demo application is one of those minimal apps. It does not use the ABCs and has no value other than showing you how the MultiFile Dialog looks.

Figure 1. The Demo Application opens a MultiFile Dialog.

The Macintosh Toolbox provides a function called CustomGetFile for creating custom file dialogs. First, I'll show you the top level CPX code for using it. That way, if all you want is to use MultiFile and you don't care about how it works, you'll have all you need to know. I will also show the function prototype and build up the associated functions for it in CPX.

Figure 2. The MultiFile section comes with an example method for using MultiFile.

Using MultiFile is pretty straightforward -- explaining it will be much more difficult. However, as you can see in Figure 2, all you do is create an instance of MultiFile Dialog, setup the type of files you want with the message "/setTypeList" and finally send the message "/multiFileGet" to get the whole process rolling. When the method completes, the list of selected files appears on the output of "/multiFileGet."

How it All Works

I'll first decompose the main method "/multiFileGet," describe the attributes of MultiFile Dialog and then expose in detail the major chunks of code that makes MultiFile Dialog work in support of CustomGetFile -- the Toolbox call we are encapsulating.

MultiFile Dialog Constructor

The first thing to look at is the constructor for MultiFile Dialog (Figure 3). When an instance of MultiFile Dialog is created, several attributes are initialized. The "Files" attribute will end up holding a new instance of File Results. This object will eventually hold the FSSpecs for the selected files, and it provides methods to add and remove FSSpecs from its internal list of FSSpecs. The attribute "Select List" is set to NULL. Eventually, it will hold a pointer to the scroll list item created by a call to LNew. The Persistent called "The Dialog" is set to the current MultiFile Dialog instance. Two other methods are executed -- one creates a Standard File Reply record while the other ("/makeCallbacks") sets up pointers to the callback functions. So by design a "The Dialog" (global) holds the MultiFile Dialog instance. Everything else hangs off of that -- the lower scroll list, StandardReplyRec and the File Results object. The callbacks rely on "The Dialog" to access the scroll list, the File Results object and the StandardReplyRec.

Figure 3. The "Constructor" for MultiFile Dialog sets up 3 Persistants.

The method "/makeCallbacks" (Figure 4) checks each of 4 attributes in MultiFile Dialog and creates a pointer to a callback method if a method name is specified. This provides a nice way for users of the class to specify their own callback methods -- just by specifying their own methods in the initialization list that can be fed to the Constructor. And of course if that does not provide enough flexibility, you can always subclass the whole thing and define "/makeCallbacks" anew.

Figure 4. "/makeCallbacks" checks each of 4 MultiFile Dialog attributes.

The local method "file filter proc" (Figure 5) is typical of the calls in "/makeCallbacks". An improvement on this local method would be to verify that the universal method is actually defined and if it isn't, then fail into a next case and set the "callback" attribute (in this specific case "File Filter Callback") value to NULL.

Figure 5. This local method is typical for what a "/makeCallbacks" method does.

The method "/multiFileGet" (Figure 6) is composed of three methods itself. The first performs the Toolbox call, the second retrieves the selected files and the final method cleans up.

Figure 6. "/multiFileGet" retrieves a list of file specifications.


The method "/callCustomGet" (Figure 7) makes the Toolbox call "CustomGetFile". The MultiFile Dialog instance carries the values necessary for the function to operate as the user wants.

Figure 7. "/callCustomGet" makes the low level Toolbox call.

Let's first look at the CustomGetFile arguments and what Prograph uses. The calling arguments for CustomGetFile are shown below (bold) with the MultiFile Dialog Attribute (underlined):

FileFilterYDProcPtr FileFilter Callback
A pointer to an optional file filter function, provided by your application, through which CustomGetFile passes files of the specified types.

short Num Types
The number of file types to be displayed. If you specify a "Num Types" value of -1, the first filtering passes files of all types.

SFTypeList /Type List
A list of file types to be displayed. You can define it using the call "/setTypeList" which automatically sets the value of attribute "Num Types" used above.

StandardFileReply * YourDataPointer
The reply record, which CustomGetFile fills in before returning. We create a pointer to a Reply record in the Constructor for MultiFile Dialog.

short DialogID
The resource ID of a customized dialog template. To use the standard template, set this parameter to 0. The MultiFile Dialog defines this value to be 1001. If you want to customize the look of the dialog, create a new dialog resource and set the DialogID to the new value in a subclass of MultiFile Dialog for the "new" dialog.

Point Where
The upper-left corner of the dialog box in global coordinates. This value is predefined to be {-1, -1} which will place it in the middle of the screen.

DlgHookYDProcPtr DialogHook Callback
A pointer to the dialog hook function, which handles item selections received from the Dialog Manager. This is in many ways the "meat" (I suppose I should instead say "fiber" for those vegetarians among us) of the matter; clicks within the dialog get handled by this method.

ModalFilterYDProcPtr ModalFilter Callback
A pointer to your modal-dialog filter function, which determines how the Dialog Manager filters events when called by CustomGetFile. Specify a value of NIL if you are not supplying your own function. We need a modal-dialog filter function because we must provide scroll control for our scrolling list. This method handles clicks in the user-defined lower scroll list. (Control of the upper list "comes" with CustomGetFile.)

short ActiveList

ActivateYDProcPtr Activate Proc Callback

void * YourDataPointer

These last three parameters are not used, and are set to NULL.

Figure 8. The default attributes are defined to work with a dialog resource 1001.

Figure 9 shows the default MultiFile dialog (ID = 1001) and the index numbers for its items.

Figure 9. Default MultiFile dialog (ID = 1001).

When CustomGetFile is called, three methods (all are Universals) take over until the user clicks "Cancel" or "Done" in the dialog window. They are "filterProc", "modalFilterYD" and "dialogHook". We'll describe each in turn.

Filter Proc Method

The "filterProc" method (Figure 10) does one job. It is called whenever the upper scroll list is about to be filled with files (after passing through the internal "types" filter). It gives us a chance to do further processing. The output of this method is a Boolean which determines whether or not the file should appear in the upper list. A TRUE output removes the item from the upper list while a FALSE value allows it to appear in the upper list. This method checks the list of FSSpecs in the File Results object. If the file is in the File Results object, this filter will remove it from the upper list.

Figure 10. "filterProc" is called whenever the upper scroll list is about to be filled with files.

The field "ioNamePtr" holds a pointer to a Pascal string. The first byte in a Pascal string must be the length of the string. we execute "get-integer" to determine the length of the string, and then we execute "get-text" using that value and start at byte 1 of the buffer. We then check the list of file names held by the File Results object (retrieved with "getFiles"). If a matching file name is found, the primitive "(in)" will return an integer greater than 0 indicating the files position in the list. In that case the method outputs TRUE. Otherwise it will output FALSE.

Modal Filter yd Method

The "modalFilterYD" method (Figure 11) is called as part of the event processing in the window. It is needed to control scrolling of the lower scroll list (the "Select List"). It is written such that it will only handle clicks within the scroll lists vertical control.

Figure 11. "modalFilterYD" controls scrolling of the lower scroll list.

Dialog Hook Method

The "dialogHook" is the biggest of these three methods. It installs the lower scroll list the first time the method is called. It also handles all clicks in the dialog. So for example when the "Add" button is clicked, the dialog hook method defines what happens in the window.

Instead of going through every case of this method (there are 15 cases), I'll just provide an overview of what the method is supposed to do:

First Time Through -- Creates the lower scroll list and installs it in the dialog window.

Add -- Adds the filename of the selected file to lower list. The file is removed from the upper the list through the file filter function. The FSSpec for the file is added to the File Results object.

Add All -- The names of all available files in the upper scroll list are added to the lower list. The FSSpecs are added to the File Results object. All files that get successfully added to the File Results are filtered from the upper list display by the file filter method.

Remove -- Enabled if an item is selected in the lower list. The selected item is removed from the File Results object, removed from the lower list and added to the upper list by the file filter method.

Remove All -- Enabled if there are any files in lower list. All files in the File Results object are removed, all items in the lower list are removed. The file filter method then allows available files to appear in the upper list.

Cancel -- Deletes all FSSpecs from the File Results object, then closes the dialog.

Done -- Closes the dialog.

Here is the code of two interesting cases to drive home how things work: what happens the first time though -- that's when we create and install the lower scroll list -- and how Add works. I leave the other cases as a review exercise for you and your CPX Debugger.

First Time Through

The first time "dialogHook" is executed, we must detect that this is the first time and display the lower list box.

Figure 12. The First Time Through case creates the lower scroll list item.

Figure 13. "initList" creates a new scroll list and places it in the position of window item 18 in the dialog resource.

The Toolbox call "LNew" creates a new scroll list. We define the rectangle for the list by getting the rectangle for window item 18 (see Figure 9). We "send" the new scroll list to the MultiFile Dialog in the message "/setSelectList".

Add file

The Add file case duplicates the FSSpec representing the selected file and sends that FSSpec as an argument in the call to "addFile".

Figure 14. The "Add" case calls "addFile" universal.

Figure 15. "addFile" universal also enables item 19 in the dialog window.

The "addFile" universal method performs several tasks. It first checks if the file can really be added. If so, it continues on by getting the value of the name field in the FSSpec and asking the File Results object for the number of items in its files list to form an index. It send those two values (name and index) as arguments to "addCell" which adds a new cell to the "Select List". It then sends the FSSpec to the File Results object in a message "/addItem" which adds the FSSpec to the File Result object. After all that, the lower scroll list is redrawn in method "updateScrollList" and window item 19 (Remove All) is enabled.

At this point "dialogHook" case 12:15 (Figure 14) outputs "sfHookRebuildList" and the method ends. The new item now appears in the lower scroll list and disappears from the upper list. The multifile dialog window waits for the next event.


This article describes the CPX code in the MultiFile section. MultiFile contains classes for creating special file dialogs that don't come out of the box with CPX. These classes are useful if you need a file dialog that can deal with several files at once or if you want to specify a unique prompt in a standard file dialog.

With the information in this article, CPX developers can now start using CustomGetFile based file dialogs in their applications. Simply add the MultiFile section to your project, create an instance of MultiFile Dialog, and send it the message "/multiFileGet". All of your problems will be solved.

Bibliography and References

Apple Computer's Inside Macintosh: Files, page 3-51.

John Shackelford is the founder of Tangent Systems - a software development company based in San Diego. When he's not playing with his 3 children, he's busy writing CPX code or playing the piano. He can be reached at You can find Tangent Systems on the world wide web at


Community Search:
MacTech Search:

Software Updates via MacUpdate

Chromium 54.0.2840.71 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. Version 54.0.2840.71: Release notes were unavailable... Read more
Firetask 3.8.1 - Innovative task managem...
Firetask uniquely combines the advantages of classical priority-and-due-date-based task management with GTD. Stay focused and on top of your commitments - Firetask's "Today" view shows all relevant... Read more
Yep 3.8.0 - $23.99
Yep is a document organization and management tool. Like iTunes for music or iPhoto for photos, Yep lets you search and view your documents in a comfortable interface, while offering the ability to... Read more
Data Rescue 4.3.1 - Powerful hard drive...
Use Data Rescue to recover: crashed, corrupted or non-mounting hard drive deleted, damaged, or lost files reformatted or erased hard drive One powerful new feature found in Data Rescue 4 is... Read more
Yep 3.8.0 - $23.99
Yep is a document organization and management tool. Like iTunes for music or iPhoto for photos, Yep lets you search and view your documents in a comfortable interface, while offering the ability to... Read more
Data Rescue 4.3.1 - Powerful hard drive...
Use Data Rescue to recover: crashed, corrupted or non-mounting hard drive deleted, damaged, or lost files reformatted or erased hard drive One powerful new feature found in Data Rescue 4 is... Read more
PDFpen 8.2.1 - $74.95
PDFpen allows users to easily edit PDF's. Add text, images and signatures. Fill out PDF forms. Merge or split PDF documents. Reorder and delete pages. Even correct text and edit graphics! Features... Read more
TextMate 2.0-beta.12.25 - Code/markup ed...
TextMate is a versatile plain text editor with a unique and innovative feature set which caused it to win an Apple Design Award for Best Mac OS X Developer Tool in August 2006. A rapidly growing... Read more
TunnelBear 3.0.4 - Subscription-based pr...
TunnelBear is a subscription-based virtual private network (VPN) service and companion app, enabling you to browse the internet privately and securely. Features Browse privately - Secure your data... Read more
QuickBooks R9 - Financial ma...
QuickBooks helps you manage your business easily and efficiently. Organize your finances all in one place, track money going in and out of your business, and spot areas where you can save. Built for... Read more

Latest Forum Discussions

See All

Best Fiends Forever Guide: How to collec...
The fiendship in Seriously's hit Best Fiends has been upgraded this time around in Best Fiends Forever. It’s a fast-paced clicker with lots of color and style--kind of reminiscent of a ‘90s animal mascot game like Crash Bandicoot. The game... | Read more »
5 apps for the budding mixologist
Creating your own cocktails is something of an art form, requiring a knack for unique tastes and devising interesting combinations. It's easy to get started right in your own kitchen, though, even if you're a complete beginner. Try using one of... | Read more »
5 mobile strategy games to try when you...
Strategy enthusiasts everywhere are celebrating the release of Civilization VI this week, and so far everyone seems pretty satisfied with the first full release in the series since 2010. The series has always been about ultra-addictive gameplay... | Read more »
Popclaire talk to us about why The Virus...
Humanity has succumbed to a virus that’s spread throughout the world. Now the dead have risen with a hunger for human flesh, and all that remain are a few survivors. One of those survivors has just called you for help. That’s the plot in POPCLAIRE’... | Read more »
Oceans & Empires preview build sets...
Hugely ambitious sea battler Oceans & Empires is available to play in preview form now on Google Play - but download it quickly, as it’s setting sail away in just a few days. [Read more] | Read more »
Rusty Lake: Roots (Games)
Rusty Lake: Roots 1.1.4 Device: iOS Universal Category: Games Price: $2.99, Version: 1.1.4 (iTunes) Description: James Vanderboom's life drastically changes when he plants a special seed in the garden of the house he has inherited.... | Read more »
Flippy Bottle Extreme! and 3 other physi...
Flippy Bottle Extreme! takes on the bottle flipping craze with a bunch of increasingly tricky physics platforming puzzles. It's difficult and highly frustrating, but also addictive. When you begin to master the game, the sense of achievement is... | Read more »
Plants vs. Zombies Heroes guide: How to...
Plants vs. Zombies Heroes surprised us all, presenting a deep deck building experience. It's a great CCG that stands up well to the competition. There are a lot of CCGs vying for players' attention at the moment, but PvZ Heroes is definitely one... | Read more »
Arcane Online takes Online RPG’s to anot...
If you think that you need a desktop to enjoy high quality MMO gaming then Arcane Online hopes to prove you emphatically wrong. An epic fantasy Online RPG set in the land of Eldine, Arcane Online offers an abundance of features and content that... | Read more »
It’s time to step up and start your spoo...
So you’ve just downloaded Seekers Notes: Hidden Mystery, and you obviously want to hit the ground running. Well you’re in luck because you just so happen to be reading our very useful guide to playing. First released in July last year, the game has... | Read more »

Price Scanner via

PixelStyle Inexpensive Photo Editor For Mac W...
PixelStyle is an all-in-one Mac Photo Editor with a huge range of high-end filters including lighting, blurs, distortions, tilt-shift, shadows, glows and so forth. PixelStyle Photo Editor for Mac... Read more
13-inch MacBook Airs on sale for $100-$140 of...
B&H has 13″ MacBook Airs on sale for $100-$140 off MSRP for a limited time. Shipping is free, and B&H charges NY sales tax only: - 13″ 1.6GHz/128GB MacBook Air (sku MMGF2LL/A): $899 $100 off... Read more
2.8GHz Mac mini available for $988, includes...
Adorama has the 2.8GHz Mac mini available for $988, $11 off MSRP, including a free copy of Apple’s 3-Year AppleCare Protection Plan. Shipping is free, and Adorama charges sales tax in NY & NJ... Read more
21-inch 3.1GHz 4K on sale for $1379, $120 off...
Adorama has the 21″ 3.1GHz 4K iMac on sale $1379.99. Shipping is free, and Adorama charges NY & NJ sales tax only. Their price is $120 off MSRP. To purchase an iMac at this price, you must first... Read more
Check Apple prices on any device with the iTr...
MacPrices is proud to offer readers a free iOS app (iPhones, iPads, & iPod touch) and Android app (Google Play and Amazon App Store) called iTracx, which allows you to glance at today’s lowest... Read more
Apple, Samsung, Lead J.D. Power Smartphone Sa...
Customer satisfaction is much higher among smartphone owners currently subscribing to full-service wireless carriers, compared with those purchasing service through a non-contract carrier, according... Read more
Select 9-inch Apple WiFi iPad Pros on sale fo...
B&H Photo has select 9.7″ Apple WiFi iPad Pros on sale for up to $50 off MSRP, each including free shipping. B&H charges sales tax in NY only: - 9″ Space Gray 256GB WiFi iPad Pro: $799 $0 off... Read more
Apple refurbished 13-inch Retina MacBook Pros...
Apple has Certified Refurbished 13″ Retina MacBook Pros available for up to $270 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free: - 13″ 2.7GHz... Read more
Apple refurbished 15-inch Retina MacBook Pros...
Apple has Certified Refurbished 2015 15″ Retina MacBook Pros available for up to $380 off the cost of new models. An Apple one-year warranty is included with each model, and shipping is free: - 15″ 2... Read more
Apple refurbished 11-inch MacBook Airs availa...
Apple has Certified Refurbished 11″ MacBook Airs (the latest models), available for up to $170 off the cost of new models. An Apple one-year warranty is included with each MacBook, and shipping is... Read more

Jobs Board

Security Data Analyst - *Apple* Information...
…data sources need to be collected to allow Information Security to better protect Apple employees and customers from a wide range of threats.Act as the subject Read more
*Apple* Retail - Multiple Positions (Multi-L...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions- New Yor...
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- Yonkers...
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
Senior Manager, Security Engineering - *Appl...
Changing the world is all in a day's work at Apple . If you love innovation, here's your chance to make a career of it. You'll work hard. But the job comes with more Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.