FileSelect

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

SelectedFile := FileSelect(Options, RootDir\Filename, Title, Filter)

Parameters

Options

Type: String or Integer

If omitted, it will default to zero, which is the same as having none of the options below.

Otherwise, it can be 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).

D: Select Folder (Directory). Specify the letter D to allow the user to select a folder rather than a file. The dialog has most of the same features as when selecting a file, but does not support filters (Filter must be omitted or blank).

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. In this case, the return value is an Array instead of a string. 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: 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

Type: String

If present, this parameter contains 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. If omitted or blank, 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 FileSelect).

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

Type: String

The title of the file-selection window. If omitted or blank, it will default to "Select File - " A_ScriptName (i.e. the name of the current script), unless the "D" option is present, in which case the word "File" is replaced with "Folder".

Filter

Type: String

Indicates which types of files are shown by the dialog.

Example: Documents (*.txt)
Example: Audio (*.wav; *.mp2; *.mp3)

If omitted, the filter defaults to All Files (*.*).

Otherwise, the filter uses the indicated string but also provides an option for All Files (*.*) in the dialog's "files of type" drop-down list. To include more than one file extension in the filter, separate them with semicolons as illustrated in the example above.

Return Value

Type: String or Array

If multi-select is not in effect, this function returns the full path and name of the single file or folder chosen by the user, or an empty string if the user cancels the dialog.

If the M option (multi-select) is in effect, this function returns an array of items, where each item is the full path and name of a single file. The example at the bottom of this page demonstrates how to extract the files one by one. If the user cancels the dialog, the array is empty (has zero items).

Remarks

A file-selection dialog usually looks like this:

FileSelect

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

Known limitation: A timer that launches during the display of a FileSelect dialog will postpone the effect of the user's clicks inside the dialog until after the timer finishes. To work around this, avoid using timers whose subroutines take a long time to finish, or disable all timers during the dialog:

Thread "NoTimers"
SelectedFile := FileSelect()
Thread "NoTimers", false

Related

DirSelect, 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

#1

SelectedFile := FileSelect(3, , "Open a file", "Text Documents (*.txt; *.doc)")
if SelectedFile = ""
    MsgBox "The dialog was canceled."
else
    MsgBox "The following file was selected:`n" SelectedFile

#2: Multi-select example.

files := FileSelect("M3")  ; M3 = Multiselect existing files.
if files.Length = 0
{
    MsgBox "The dialog was canceled."
    return
}
for file in files
{
    Result := MsgBox("File #" A_Index " of " files.Length ":`n" file "`n`nContinue?",, "YN")
    if Result = "No"
        break
}

#3: Select Folder.

SelectedFolder := FileSelect("D", , "Select a folder")
if SelectedFolder = ""
    MsgBox "The dialog was canceled."
else
    MsgBox "The following folder was selected:`n" SelectedFolder