FutureBasic Logo

<<    Index    >> FutureBasic 5

files$   function



Syntax:

(1) For Selecting a File to Open
fileName$ = files$( _FSSpecOpen, [typeListString$], [promptString$], [@]fSpecVar )
fileName$ = files$( _FSRefOpen, [typeListString$], [promptString$], [@]fsRefVar )
fileName$ = files$( _CFURLRefOpen, [typeListString$], [promptString$], [@]cfURLRefVar )

(2) For Selecting a Folder
folderName $ = files$( _FSSpecFolder, [typeListString$], [promptString$], [@]fSpecVar )
folderName $ = files$( _FSRefFolder, [typeListString$], [promptString$], [@]fsRefVar )
folderName $ = files$( _CFURLRefFolder, [typeListString$], [promptString$], [@]cfURLRefVar )

(3) For Selecting a File Name and Folder where a file may be Saved
fileName$ = files$( _FSSpecSave, [typeListString$], [promptString$], [@]fSpecVar )
fileName$ = files$( _FSRefSave, [typeListString$], [promptString$], [@]fsRefVar )
fileName$ = files$( _CFURLRefSave, [typeListString$], [promptString$], [@]cfURLRefVar )

(4) Returns the file type of the last file returned by the files$( open ) functions (see option 1 choices)
fileType$ = files$

Description:
This function is an optional step in the general process to select, open, read/write and close files. It provides three basic functionalities for selecting files and folders and one function to return a file type. These basic functions are:

(1) Ask the user to select a file to open
(2) Ask the user to select a folder
(3) Ask the user to provide a file name and select a folder where a file may be saved.

Within each of the three options the programmer may return a reference to the file as a variable of type FSSpec, FSRef or CFURLRef. The reference allows the programmer to work with the file or folder chosen by the user.

files$ prompts the user via standard Navigation Services dialogs to select an existing file and/or existing folder (and provide a name if the save option is used). If the user selects a file/folder, then the file's name is returned in fileName$, and a reference to the file (either FSRef, FSSpec or CFURLRef) is returned for the programmer's use. If the user cancels the dialog, then the function returns an empty (zero-length) string and the reference does not contain a valid value.
The types of files that appear in the dialog may be limited by specifying up to four file types in typeListString$. For example, if "TEXTPICT" is passed in typeListString$, then only files of type "text" and type "PICT" will be available for selection. If typeListString$ is an empty string, or the parameter is omitted, then all file types will be available for selection.

(4) Returns the file type of the last file returned by a files$( open ) function, as a 4-character string. In some cases this will not return a value: If the user clicked "cancel" in response to the last File Open dialog, or if the files$( open ) function has never yet been executed or the file doesn't have a file type (which is common for modern MacOS X files), then the files$ function returns an empty (zero-length) string. In some cases it's useful to express the file type as a 4-byte long integer rather than as a string. Use the mki$ function and the cvi function to convert between these two forms. Apple has recommended use of Uniform Type Identifiers to replace Type/Creator. See Apple's "Introduction to Uniform Type Identifiers" for more information.

Note:
Using files$ option 1 to select a file does not actually open the selected file. Use the open statement if you need to open the file.
The reference returned is only valid while your program operates and not after it quits. The reference should not be saved to refer to a file/folder at later date. If you need to keep track of a file's location over time, create and save an alias record for the file. The NavDialog() function is a more versatile alternative to files$(). For instance it can create sheets.

See Also:
Appendix A - File Object Specifiers; NavDialog