FutureBasic Logo

<<    Index    >> FutureBasic 5

NavDialog   function



NavDialog Functions

NavDialog( dialogType [ + options ], message, typeList | defaultSaveName, callbackFn, userData )

The NavDialog function is similar to the FutureBasic files$ keyword but provides more functionality. Using Navigation Services, the details are hidden in the C runtime, so it is easy to call NavDialog (and several other NavDialogxxxxxx helper functions) as shown in the NavDialog demos.

The parameters

dialogType
_kNavDialogGetFile
_kNavDialogPutFile
_kNavDialogChooseFolder
_kNavDialogChooseFile
_kNavDialogChooseVolume
_kNavDialogChooseObject

options
The programmer may control what the user sees in the dialog and how it is presented. Option constants are combined with the dialogType parameter.

_kNavDialogSheetrequests a sheet dialog attached to a parent window
_kNavDialogMultipleallows the user to select multiple files
_kNavDialogInvisibleallows the user to see and select invisible files
_kNavDialogSupportPackagesallows the user to see packages
_kNavDialogOpenPackagesallows the user to open packages (like MacOS X application packages)

typeList
Used in _kNavDialogGetFile and _kNavDialogChooseFile dialog types. This parameter allows the programmer to filter by file type. The typeList parameter can be a null string. Same operation as similar parameter in FutureBasic's files$

defaultSaveName
Only appropriate with the _kNavDialogPutFile dialog type. This parameter can be a null string. If supplied, this name is automatically supplied in the "save as.." dialog. The user can obviously replace it with a name of their choosing. Same operation as similar parameter in FutureBasic's files$

callbackFn
The address of a programmer created function. This parameter is always required - see below for more details.

userData
Optional data that can be sent to the callbackFn - The NavDialog_demo uses it to pass a window number but could easily pass a windowRef or other data

Overview of NavDialog Process (order of operation)

(1) Prior to the actual call of NavDialog(), the code establishes:

(a) The dialogType - in other words, getting a file, putting a file, choosing a file
(b) The options, userData, defaultSaveName as described above in parameters
(c) The callbackFn - this is where the code processes the user file/folder selection(s)
(d) If a filterFn is used, NavDialog_SetFilterFn is called with the name of the FN that will filter the files (also see NavDialog_SetFilterFn below)

(2) NavDialog() is called. It interacts with the user and collects the files(s)/folders selected

(3) While (2) is executing the filterFn, if used, is busy deciding which files to show to the user in the dialog

(4) When the user dismisses the dialog (presumably having completed their selections), NavDialog passes control to the callbackFn where the selected files are processed

(5) When the callbackFn ends, control returns to the next sequential instruction after the NavDialog() call. Note: If you specify a sheet window, the NavDialog function returns immediately.

The callback function

The programmer identifies a callback function in their own code. This is done simply by passing the address of the FN in the NavDialog call (i.e. @fn MyGetFileHandler). This callback function (FN) is called by NavDialog to process the results of the dialog interaction with the user. So this is where the program would process the file(s) or folder the user picked in the dialog. Example callback function:

local fn MyGetFileHandler( reply as ^NavReplyRecord, userData as pointer )
dim as FSSpec spec

NavDialog_GetItemFSSpec( #reply, 1, _false, @spec )

// do something with file spec

end fn


The callback function always takes two parameters: NavReplyRecord and userData.

Ancillary functions to assist with retrieving results

NavDialog_GetItemCountreturns the number of items selected by the user. Useful if the program allows multiple file selection with _kNavDialogMultiple
NavDialog_GetItemFSSpecreturns the FSSpec of a file/folder selected
NavDialog_GetItemFSRefreturns the FSRef of a file/folder selected
NavDialog_CopyItemCFURLRefreturns the CFURLRef of a file/folder
NavDialog_GetSaveFileNameAsPascalStringwhat it says
NavDialog_CopySaveFileNamereturns the saveFileName as a CFStringRef

Optional helper functions

A few helper functions are provided to add features to NavDialog.

NavDialog_AddUTIPascalStringIf used, must be called before NavDialog(). UTIs are Uniform Type Identifiers and are the modern filtering method. UTIs are broader and more powerful than OSTypes (i.e. TEXT PICT etc.). An overview can be found in the Apple docs at "Introduction to Uniform Type Identifiers Overview" (/Reference Library/Guides/Carbon/Data Management/Uniform Type Identifiers Overview).
NavDialog_SetFilterFnIf used, must be called before NavDialog() and establishes the name of the filter function (i.e. filterFn). A filter function limits which files the user sees. In the NavDialog_demo the filter function uses UTIs to filter.
NavDialog_UTIConformsToMay be used in a filter callback. Used to filter by UTIs. The filter checks to see if the UTI of the item passed (first parameter) "conforms" (or is a member of) the UTI group named in the second parameter. If the item is a member, it returns _true (else _false) so it can be included in the list presented to the user.
Other FunctionsMany other features/functions are available for use and can be found in Subs Files.incl but are not documented here.

See Also:
Appendix A - File Object Specifiers