FileSelectFile

Displays a standard dialog that allows the user to open or save file(s).

FileSelectFile, OutputVar , Options, RootDir\Filename, Title, Filter

Parameters

OutputVar

The name of the output variable in which to store the filename(s) selected by the user. This will be made blank if the user cancels the dialog (i.e. does not wish to select a file).

Options

If blank or omitted, it defaults to zero, which is the same as having none of the options below. Otherwise, specify a number or one of the letters listed below, optionally followed by a number. For example, M, 1 and M1 are all valid (but not equivalent).

M: Multi-select. Specify the letter M to allow the user to select more than one file via shift-click, control-click, or other means. To extract the individual files, see the example at the bottom of this page.

S: Save dialog. Specify the letter S to cause the dialog to always contain a Save button instead of an Open button.

The following numbers can be used. To put more than one of them into effect, add them up. For example, to use 1 and 2, specify the number 3.

1: File Must Exist
2: Path Must Exist
8: Prompt to Create New File
16: Prompt to Overwrite File
32 [v1.0.43.09+]: Shortcuts (.lnk files) are selected as-is rather than being resolved to their targets. This option also prevents navigation into a folder via a folder shortcut.

As the "Prompt to Overwrite" option is supported only by the Save dialog, specifying that option without the "Prompt to Create" option also puts the S option into effect. Similarly, the "Prompt to Create" option has no effect when the S option is present. Specifying the number 24 enables whichever type of prompt is supported by the dialog.

RootDir\Filename

If blank or omitted, the starting directory will be a default that might depend on the OS version (it will likely be the directory most recently selected by the user during a prior use of FileSelectFile). Otherwise, specify one or both of the following:

RootDir: The root (starting) directory, which is assumed to be a subfolder in %A_WorkingDir% if an absolute path is not specified. [v1.0.43.10+]: On Windows XP/2003 and earlier, a CLSID such as ::{20D04FE0-3AEA-1069-A2D8-08002B30309D} (i.e. This PC; formerly My Computer or Computer) may also be specified, in which case any subdirectory present after the CLSID should end in a backslash (otherwise, the string after the last backslash will be interpreted as the default filename, below).

Filename: The default filename to initially show in the dialog's edit field. Only the naked filename (with no path) will be shown. To ensure that the dialog is properly shown, ensure that no illegal characters are present (such as /<|:").

Examples:

C:\My Pictures\Default Image Name.gif  ; Both RootDir and Filename are present.
C:\My Pictures  ; Only RootDir is present.
My Pictures  ; Only RootDir is present, and it's relative to the current working directory.
My File  ; Only Filename is present (but if "My File" exists as a folder, it is assumed to be RootDir).
Title

If blank or omitted, it defaults to Select File - %A_ScriptName% (i.e. the name of the current script). Otherwise, specify the title of the file-selection window.

Filter

If blank or omitted, the dialog will show all type of files and provide the options "All Files (*.*)" and "Text Documents (*.txt)" in the "Files of type" drop-down list.

Otherwise, specify a string to indicate which types of files are shown by the dialog, e.g. Documents (*.txt). To include more than one file extension in the filter, separate them with semicolons, e.g. Audio (*.wav; *.mp2; *.mp3). In this case, the "Files of type" drop-down list has the specified string and "All Files (*.*)" as options.

Error Handling

[v1.1.04+]: This command is able to throw an exception on failure. For more information, see Runtime Errors.

ErrorLevel is set to 1 if the user dismissed the dialog without selecting a file (such as by pressing the Cancel button). It is also set to 1 if the system refused to show the dialog (rare). Otherwise, it is set to 0.

Remarks

A file-selection dialog usually looks like this:

FileSelectFile

If the user didn't select anything (e.g. pressed CANCEL), OutputVar is made blank.

If multi-select is not in effect, OutputVar is set to the full path and name of the single file chosen by the user.

If the M option (multi-select) is in effect, OutputVar is set to a list of items, each of which except the last is followed by a linefeed (`n) character. The first item in the list is the path that contains all the selected files (this path will end in a backslash only if it is a root folder such as C:\). The other items are the selected filenames (without path). For example:

C:\My Documents\New Folder [this is the path in which all the files below reside]
test1.txt [these are the naked filenames: no path info]
test2.txt
... etc.

(The example at the bottom of this page demonstrates how to extract the files one by one.)

When multi-select is in effect, the sum of the lengths of the selected filenames is limited to 64 KB. Although this is typically enough to hold several thousand files, OutputVar will be made blank if the limit is exceeded.

A GUI window may display a modal file-selection dialog by means of Gui +OwnDialogs. A modal dialog prevents the user from interacting with the GUI window until the dialog is dismissed.

[v1.0.25.06+]: The multi-select option "4" is obsolete. However, for compatibility with older scripts, it still functions as it did before. Specifically, if the user selects only one file, OutputVar will contain its full path and name followed by a linefeed (`n) character. If the user selects more than one file, the format is the same as that of the M option described above, except that the last item also ends in a linefeed (`n).

FileSelectFolder, MsgBox, InputBox, ToolTip, GUI, CLSID List, parsing loop, SplitPath

Also, the operating system offers standard dialog boxes that prompt the user to pick a font, color, or icon. These dialogs can be displayed via DllCall() as demonstrated at GitHub.

Examples

Allows the user to select an existing .txt or .doc file.

FileSelectFile, SelectedFile, 3, , Open a file, Text Documents (*.txt; *.doc)
if (SelectedFile = "")
    MsgBox, The user didn't select anything.
else
    MsgBox, The user selected the following:`n%SelectedFile%

A CLSID example. Allows the user to select a file in the recycle bin. Note that this example only works on Windows XP/2003 or earlier.

FileSelectFile, OutputVar,, ::{645FF040-5081-101B-9F08-00AA002F954E}  ; Recycle Bin.

Allows the user to select multiple existing files.

FileSelectFile, files, M3  ; M3 = Multiselect existing files.
if (files = "")
{
    MsgBox, The user pressed cancel.
    return
}
Loop, parse, files, `n
{
    if (A_Index = 1)
        MsgBox, The selected files are all contained in %A_LoopField%.
    else
    {
        MsgBox, 4, , The next file is %A_LoopField%.  Continue?
        IfMsgBox, No, break
    }
}
return