FutureBasic Logo

<<    Index    >> FutureBasic 5

files$   function



Note: FB releases 5.7.97 and older support the FSRef and FSSpec but are NOT supported starting with release 5.7.99

Syntax:

(1) For Selecting a File to Open

    fileName$ = files$( {_CFURLRefOpen | _URLOpen}, [typeListPascalString], [promptPascalString], [@]cfURLRefVar )

(2) For Selecting a Folder

    folderName $ = files$( {_CFURLRefFolder | _URLFolder}, [typeListPascalString], [promptPascalString], [@]cfURLRefVar )

(3) For Selecting a File Name and Folder where a file may be Saved

    fileName$ = files$( {_CFURLRefSave | _URLSave}, [typeListPascalString], [promptPascalString], [@]cfURLRefVar )

Removed in FB 5.7.99
    fileName$ = files$( _FSSpecOpen, [typeListPascalString], [promptPascalString], [@]fSpecVar )
    fileName$ = files$( _FSRefOpen, [typeListPascalString], [promptPascalString], [@]fsRefVar )
    folderName$ = files$( _FSSpecFolder, [typeListPascalString], [promptPascalString], [@]fSpecVar )
    folderName$ = files$( _FSRefFolder, [typeListPascalString], [promptPascalString], [@]fsRefVar )
    fileName$ = files$( _FSSpecSave, [typeListPascalString], [promptPascalString], [@]fSpecVar )
    fileName$ = files$( _FSRefSave, [typeListPascalString], [promptPascalString], [@]fsRefVar )

(4) Returns the file type of the last file returned by the files$( open ) functions (see option 1 choices)
fileType$ = files$      note: Apple moved away from file types long ago and aren't recommended.

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 CFURLRef. The reference allows the programmer to work with the file or folder chosen by the user. For example, the last component of a CFURLRef will be the chosen file/folder.

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 (as a 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 typeListPascalString. For example, if "TEXTPICT" is passed in typeListPascalString, then only files of type "text" and type "PICT" will be available for selection. If typeListPascalString 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