GetFilename

Description:

baGetFilename displays a file dialog box and returns the filename selected.

Platforms:

Windows and Macintosh

Usage:

Result = baGetFilename( Operation, StartDir, Filename, Filter, Flags, Instruction, NoFolders, X, Y )

Arguments:

String, string, string, string, integer, string, integer, integer, integer.
Operation is the type of dialog to show. Can be "open" or "save".
StartDir is the initial directory. Use "" for the current directory.
Filename is the initial file name to display.
Filter is the type of files to display. Use "" to show all files.
Flags modifies the behaviour of the dialog.
Instruction is the instruction to display to the user.
If NoFolders is true, the folder selection controls will not be shown.
X is horizontal position of the dialog.
Y is the vertical position of the dialog.

Returns:

String.
Returns the file name selected, or "" if the user cancelled.

Examples:

Director:
filename = baGetFilename( "save", "c:\temp", "newfile.txt", "Text files|*.txt", 0, "Save new file", false, 100, 100 )

Authorware:
file := baGetFilename( "open", "c:\\temp", "", "", 0, "Select data file to open", true, -1, 0 )
 

Notes:

On Windows, the filter argument consists of a series of strings separated by "|" characters. The strings are divided into pairs, the first half of a pair is the description that appears in the drop down box, the second half is the wildcard for the files. Separate multiple wildcards with semi-colons.
"Text files|*.txt" -- shows only text files
"Text files|*.txt|All files|*.*" -- allows the user to display either text files or all files
"Images|*.bmp;*.tif;*.jpg" -- shows different image files

On Macintosh, the filter can be a four character code of the file type eg “TEXT”. Up to 4 types can be specified, eg “TEXT|PICT”. Alternatively, you can specify an extension to filter on. You can specify up to 10 extensions, separated by commas, eg".bmp,.jpg,.jpeg"

Setting the NoFolders option to true will mean that the user will not be able to change the initial directory, and folders will not be shown. This flag is only available on Windows, and if you do not include the OFN_EXPLORER flag.

The X and Y values are the number of pixels from the top left corner of the screen. Set X to -1 to position the dialog in the center of the calling Director/Authorware window. Set X to -2 to position the dialog in the center of the screen. On Macintosh, –3 will position the dialog where the user left it.

The flags argument allows you to change the way the dialog box looks and behaves. On Windows, it can be the combination of any of these values:
 

OFN_READONLY
Causes the Read Only check box to be checked initially when the dialog box is created.

OFN_OVERWRITEPROMPT
Causes the Save As dialog box to generate a message box if the selected file already exists. The user must confirm whether to overwrite the file.

OFN_HIDEREADONLY
Hides the Read Only check box.

OFN_NOCHANGEDIR
Restores the current directory to its original value if the user changed the directory while selecting a file.

32 

OFN_ADDEXTENSION
If the user enters a name without an extension, the first extension listed in the Filter argument will be added to the end of the returned filename.

256 

OFN_RETURNASLIST
If OFN_ALLOWMULTISELECT is specified returns the file names as a list.

512 

OFN_ALLOWMULTISELECT
Specifies that the File Name list box allows multiple selections.

2048 

OFN_PATHMUSTEXIST
Specifies that the user can type only valid paths and filenames. If this flag is used and the user types an invalid path and filename in the File Name entry field, the dialog box function displays a warning in a message box.

4096 

OFN_FILEMUSTEXIST
Specifies that the user can type only names of existing files in the File Name entry field. If this flag is specified and the user enters an invalid name, the dialog box procedure displays a warning in a message box.

8192 

OFN_CREATEPROMPT
Specifies that the dialog box function should ask whether the user wants to create a file that does not currently exist.

32768 

OFN_NOREADONLYRETURN Specifies that the returned file does not have the Read Only check box checked and is not in a write-protected directory.

131072 

OFN_NONETWORKBUTTON Hides and disables the Network button.

262144 

OFN_NOLONGNAMES
Specifies that long filenames are not displayed in the File Name list box. This value is ignored if OFN_EXPLORER is set.

524288 

OFN_EXPLORER
Creates an Open or Save As dialog box that uses user-interface features similar to the Windows Explorer.

1048576 

OFN_NODEREFERENCELINKS
Directs the dialog box to return the path and filename of the selected shortcut (.LNK) file. If this value is not given, the dialog box returns the path and filename of the file referenced by the shortcut.

2097152 

OFN_LONGNAMES Causes the Open or Save As dialog box to display long filenames. If this flag is not specified, the dialog box displays filenames in 8.3 format. This value is ignored if OFN_EXPLORER is set.

4194304 

OFN_SHOWPLACESBAR
Shows the Places bar. Only available on ME/2000/XP. Has no effect unless OFN_EXPLORER is also specified. Note that if this flag is specified then the Position arguments are ignored - Windows will place the dialog in the last place left by the user.

On Macintosh, they can be:

1 OFN_HIDEBUNDLES
Do not allow bundles to be selected.
2 OFN_OPENBUNDLES
Treat bundles as folders and allow the contents to be displayed and selected.

512 

OFN_ALLOWMULTISELECT
Specifies that the File Name list box allows multiple selections. The files are always returned as a list.

1048576 

OFN_NODEREFERENCELINKS
Directs the dialog box to return the path and filename of the selected shortcut  file. If this value is not given, the dialog box returns the path and filename of the file referenced by the shortcut.

Using a flag of -1 gives a standard dilaog box with the most common options.

To use these values, add the appropriate values together eg

OFN_CREATEPROMPT + OFN_HIDEREADONLY + OFN_NONETWORKBUTTON

If OFN_ALLOWMULTISELECT is specified and OFN_RETURNASLIST is not specified, and the user selects more than one file, the return will be a series of strings, separated by returns. The first line will be the directory selected, the remaining lines will be the selected filenames. In Director, use "the line of" function to retrieve each line. In Authorware, use the "GetLine" function. Note that on Macintosh, it is possible to select files that are not in the same folder, so the return is always a list.

If OFN_RETURNASLIST is specified then the return will be a list with each filename as a separate entry. Each entry will be the full filename, including the path.

The OFN_EXPLORER flag can not be used with the NoFolders option. The NoFolders option is not available on Macintosh. You can use the baGetFiles function to display a files only dialog box.

To make it easier to enter the constants, here are some scripts:

Director:

set OFN_READONLY = 1
set OFN_OVERWRITEPROMPT = 2
set OFN_HIDEREADONLY = 4
set OFN_NOCHANGEDIR = 8
set OFN_ALLOWMULTISELECT = 512
set OFN_PATHMUSTEXIST = 2048
set OFN_FILEMUSTEXIST = 4096
set OFN_CREATEPROMPT = 8192
set OFN_NOREADONLYRETURN = 32768
set OFN_NONETWORKBUTTON = 131072
set OFN_NOLONGNAMES = 262144
set OFN_EXPLORER = 524288
set OFN_NODEREFERENCELINKS = 1048576
set OFN_LONGNAMES = 2097152
set OFN_SHOWPLACESBAR = 4194304

Authorware:

OFN_READONLY := 1
OFN_OVERWRITEPROMPT := 2
OFN_HIDEREADONLY := 4
OFN_NOCHANGEDIR := 8
OFN_ALLOWMULTISELECT := 512
OFN_PATHMUSTEXIST := 2048
OFN_FILEMUSTEXIST := 4096
OFN_CREATEPROMPT := 8192
OFN_NOREADONLYRETURN := 32768
OFN_NONETWORKBUTTON := 131072
OFN_NOLONGNAMES := 262144
OFN_EXPLORER := 524288
OFN_NODEREFERENCELINKS := 1048576
OFN_LONGNAMES := 2097152
OFN_SHOWPLACESBAR := 4194304
 

See also:

baGetFilenameEx
baGetFolder
baGetDisk
baGetFiles