CHOOSEFILE Method (System)
Description
Displays the "Open File" or "Save As" Windows Common Dialog Box to allow the user to select a file name:
Syntax
FileName = Exec_Method( "FILESYSTEM",
"CHOOSEFILE",
OwnerWindow,
ChooseFileOptions )
Parameters
| Name | Required | Description |
|---|---|---|
| OwnerWindow | No | ID of the parent window for the dialog. This can be null, in which case the parent window is the desktop. |
| ChooseFileOptions | No | Contains an @Fm-delimited dynamic array of options that control the behavior of the dialog. It has the following structure: <1> Mode <2> Filter Mask <3> Filter Index <4> Default File Name <5> Flags <6> Initial Directory <7> Default Extension <8> Title |
Returns
If the dialog used in single- select mode then the full path and name of the selected file is returned.
If the dialog is used in multi-select mode (i.e. the "Flags" option has the OFN_ALLOWMULTISELECT$ flag set) then an @Fm-delimited dynamic array is returned: The first field in the returned list is the selected directory name, while subsequent items are the selected files, i.e.:
<1> Selected Directory
<2> First file
<3> Second file
:
:
<n> (n-1)'th file
Remarks
The ChooseFIleOptions argument is composed of 8 fields which control the behavior of the dialog – each field is described fully below:
| Field | Name | Description |
|---|---|---|
| <1> | Mode | Specifies the dialog mode ("Open" or "Save As" ) bypassing one of the following values: "0" – Open (default mode) "1" – Save As |
| <2> | Filter String | Contains a list of items (file types and filter masks) that determine what files types the dialog will show. • Each item in the list is composed of two elements (delimited by a "/" character): o Text to display in the dialog options. o A set of filters that determine what files to display. Each filter is delimited by a ";" character. • Each item in the list is also delimited by a /" character • The list must be terminated by a "/" character For example, if you wanted to show bmp files, jpg/jpeg files, and "All files" your filter string would look like this: Filter = "Bitmap Files (*.bmp)/*.bmp/" Filter := "Jpeg Files (*.jpg,*.jpeg)/*.jpg;*.jpeg/" Filter := "All Files (*.*)/*.*/" Note that some OS-file based repository types (such as images) have equated constants for filter strings. See the REPOS_IMAGE_EQUATES insert record for an example. |
| <3> | Filter Index | Contains the index if the initial filter string item to use in the dialog. Defaults to 1. |
| <4> | Default File Name | Contains the name of the file to load into the dialog when it is displayed. |
| <5> | Flags | A set of bitmask flags that specify the dialog behavior. These are fully described in the Microsoft documentation for the "flags" member of the OPENFILENAME structure, and equates constants for these flags can be found in the MSWIN_GETOPENFILENAME_EQUATES insert record (See below for an example of using them). |
| <6> | Initial Directory | Specifies the initial directory to display when the dialog is created. |
| <7> | Default Extension | Specifies the default extension to append to the file if the user does not specify one. This string can be any length, but only the first three characters are appended. The string should not contain a period (.). |
| <8> | Title | Caption bar text for the dialog to display. |
The CHOOSEFILE method is basically a wrapper around two Windows API functions:
• GetOpenFileName
• GetSaveFileName
So it is worth examining at the documentation for these functions on the MSDN website to get a better idea of the capabilities of this method.
Equated constants for use with the CHOOSEFILE method can be found in the PS_CHOOSEFILE_EQUATES and MSWIN_CHOOSEFILE_EQUATES insert records.
See Also
N/A
Example
// Use the CHOOSEFILE method to allow the user to select multiple files...
$Insert PS_ChooseFile_Equates
$Insert Repos_Image_Equates
// Show Bitmaps, JPegs and All Files ...
Filter = "Bitmap Files(*.bmp)/*.bmp/"
Filter := "JPeg Files (*.jpg,*jpeg,*.jpe)/*.jpg;*jpeg;*.jpe/"
Filter := "All Files (*.*)/*.*/"
// Allow multiple selections, and ensure that any files
// we select exist - we do this by using the OFN_ flags
Flags = 0;
Flags = BitAnd( Flags, OFN_ALLOWMULTISELECT$ )
Flags = BitAnd( Flags, OFN_FILEMUSTEXIST$ )
CFOptions = ""
CFOptions<1> = CHFILE_MODE_OPEN$
CFOptions<2> = Filter
CFOptions<3> = 1
CFOptions<4> = ""
CFOptions<5> = Flags
CFOptions<6> = Drive() : "\bmps"
CFOptions<7> = ""
CFOptions<8> = "Select Image"
FileList = Exec_Method( "SYSTEM", "CHOOSEFILE", @Window, CFOptions )
If Len( FileList ) Then
// We used a multi-select dialog so the first item in FileList
// is the directory, followed by a list of files
FileDir = FileList[1,@fm]
FileList = FileList[Col2()+1,\00\]
End