Customizing Your Interface
If your application requires it, you can customize the user interface for identifying
files.
Note: Alter the dialog boxes only if necessary. Apple, does not guarantee future
compatibility if you use a customized dialog box.
To customize a dialog box, you should
• design your display and create the resources that describe it
• write callback routines, if necessary, to process user actions in the
dialog box
customized dialog boxes and pointers to the callback routines
Whether or not you change the dialog box display, you can write your own dialog hook
callback function to handle user actions in the dialog box.
Customized Dialog Boxes
To describe a dialog box, you must supply a 'DLOG' resource that defines the box itself
and a 'DITL' resource that defines the items in the dialog box.
The following code example shows the resource definition of the default Open dialog box, in Rez input format. (Files in Rez format may be used with SARez and SADeRez,
provided with Think C.)
The definition of the default Open dialog box resource 'DLOG' (-6042, purgeable)
{
{0, 0, 166, 344}, dBoxProc, in visible, noGoAway, 0,
-6042, "", noAutoCenter
};
The next code example shows the resource definition of the default Save dialog box, in
Rez input format.
The definition of the default Save dialog box
resource 'DLOG' (-6043, purgeable)
{
{0, 0, 188, 344}, dBoxProc, in visible, noGoAway, 0,
-6043, "", noAutoCenter
};
contains 'dctb' resources with the same resource IDs as the default dialog boxes, so that
the Dialog Manager uses color grafPorts for the default dialog boxes. (See the Dialog Manager for a description of the 'dctb' resource.) If you create your own dialog boxes, include 'dctb' resources.
You must provide an item list (in a 'DITL' resource with the ID specified in the 'DLOG'
resource) for each dialog box you define. Add new items to the end of the default lists.
CustomGetFile expects the first nine items in a customized dialog box to have the same functions as the corresponding items in the StandardGetFile dialog box; CustomPutFile expects the first twelve items to have the same functions as the corresponding items in the StandardPutFile dialog box. If you want to eliminate one of the standard items from the display, leave it in the item list but place its
coordinates outside the bounds of the dialog box rectangle.
The next code example shows the dialog item list for the default Open dialog box, in Rez input format. The constant statements in the next section, Callback Routines,
list which elements the items represent in the dialog boxes.
The item list for the default Open dialog box resource 'DITL'(-6042) { {
{135, 252, 155, 332}, Button { enabled, "Open" },
{104, 252, 124, 332}, Button { enabled, "Cancel" },
{0, 0, 0, 0}, HelpItem { disabled, HMScanhdlg {-6042}},
{8, 235, 24, 337}, UserItem { enabled },
{32, 252, 52, 332}, Button { enabled, "Eject" },
{60, 252, 80, 332}, Button { enabled, "Desktop" },
{29, 12, 159, 230}, UserItem { enabled },
{6, 12, 25, 230}, UserItem { enabled },
{91, 251, 92, 333}, Picture { disabled, 11 },
} };
The dialog item list for the default Save dialog box, in Rez
resource 'DITL'(-6043)
{ {
{161, 252, 181, 332}, Button { enabled, "Save" },
{130, 252, 150, 332}, Button { enabled, "Cancel" },
{0, 0, 0, 0}, HelpItem { disabled, HMScanhdlg {-6043}},
{8, 235, 24, 337}, UserItem { enabled },
{32, 252, 52, 332}, Button { enabled, "Eject" },
{60, 252, 80, 332}, Button { enabled, "Desktop" },
{29, 12, 127, 230}, UserItem { enabled },
{6, 12, 25, 230}, UserItem { enabled },
{119, 250, 120, 334}, Picture { disabled, 11 },
{157, 15, 173, 227}, EditText { enabled, "" },
{136, 15, 152, 227}, StaticText { disabled, "Save as:" },
{88, 252, 108, 332}, UserItem { disabled },
} };
The third item in each list (HelpItem) supplies Apple's Balloon Help for items in the dialog box. HelpItem specifies the resource ID of the 'hdlg' resource that contains
the help strings for the standard dialog items. To provide Balloon Help for your own items, supply a second 'hdlg' resource and reference it with another help item at the
Callback Routines
You can supply callback routines that control these elements of the user interface:
• determining which files the user can open
• handling user actions in the dialog boxes
• highlighting the display when keyboard input is directed at a
customized field defined by your application
You can also supply data of your own to be passed into the callback routines through a
new parameter, yourDataPtr, that you can pass to CustomGetFile and A file filter function determines which files appear in the display list when the user
functions.
it checks the file type of each file and filters out files whose types do not match your
application's specifications. Your application can specify which file types are to be
CustomGetFile. If your application also supplies a file filter function, the acceptable type. The file filter function receives a pointer to the file's catalog
information record described in the File Manager .It evaluates the catalog entry and returns a Boolean value that determines whether the file is filtered (that is, a value of TRUE suppresses display of the filename, and a value of FALSE allows the display). The
a file filter function of your own.
A file filter function to be called by StandardGetFile must use this syntax: When your file filter function is called by CustomGetFile, it can also receive a pointer to any data that you passed in through the call to CustomGetFile. A file filter A dialog hook function handles item hits in the dialog box. It receives a dialog record and an item number from the ModalDialog procedure by means of the Your dialog hook function checks the item number of each item hit, and then either
immediately after calling ModalDialog. It passes your function the item number returned by ModalDialog, a pointer to the dialog record, and a pointer to the data received from your application, if any. The dialog hook function must use this syntax:
pascal short MyDlgHook ( short item, DialogPtr theDialog, void *myDataPtr); Your dialog hook function returns an item number or the sfHookNullItem constant as
its function result. If it returns one of the item numbers in the following list of
dialog hook function does not handle an item hit, it should pass the item number back to
item number.
When your application handles the item hit, it should return the sfHookNullEvent
item number that it doesn't recognize from a dialog hook function, it does nothing.
You must write your own dialog hook function to handle any items you have added to
the dialog box.
later in this section) to map user actions during the dialog onto the defined item
numbers. Some of the mapping is in direct. A click on the Open button, for example, is mapped to sfItemOpenButton only if a file is selected in the display list. If a folder or
sfHookOpenFolder.
The lists that follow summarize when various items are generated and how they are
handled. The lists describe the simplest mouse action that generates each item; many of
the items can also be generated by keyboard actions, as described in
The first twelve defined constants represent the items in the Save and Open dialog boxes. The constants that represent disabled items (sfItemBalloonHelp,
sfItemDividerLinePict, and sfItemPromptStaticText) have no effect, but they are
defined in the header files for the sake of completeness. Except under extraordinary
circumstances, your dialog hook function always passes any of the first twelve item
Constant Cause Effect
sfItemOpenButton The user clicks Open or reply record
(setting sfGood to
TRUE), removes the
dialog box, and
returns.
to FALSE, removes
the dialog box, and
returns.
the display list to
show the contents of
the folder that is one
level up the
hierarchy (that is,
the parent directory
of the current
parent directory).
volume that is
currently selected.
button in a customized dialog Package displays box defined by one of the earlier the contents of the
procedures. You never receive next drive.
this item number with the new
procedures; when the user clicks
is mapped to the item