The DIALOG_PICKFILE function allows the user to interactively pick a file, or multiple files, using the platform's own native graphical file-selection dialog. The user can also enter the name of a file that does not exist (see the description of the WRITE keyword, below).
Result = DIALOG_PICKFILE( [, DEFAULT_EXTENSION=string] [, /DIRECTORY] [, DIALOG_PARENT=widget_id] [, DISPLAY_NAME=string] [, FILE=string] [, FILTER=string/string array] [, /FIX_FILTER] [, GET_PATH=variable] [, GROUP=widget_id] [, /MULTIPLE_FILES] [, /MUST_EXIST] [, /OVERWRITE_PROMPT] [, PATH=string] [, /READ | , /WRITE] [, RESOURCE_NAME=string] [, TITLE=string] )
DIALOG_PICKFILE returns a string array that contains the full path name of the selected file or files. If no file is selected, DIALOG_PICKFILE returns a null string.
Set this keyword to a scalar string representing the default extension to be appended onto the returned file name or names. If the returned file name already has an extension, then the value set for this keyword is not appended. The string value set for this keyword should not include a period (.).
| Note |
Set this keyword to the widget ID of a widget to be used as the parent of this dialog.
Set this keyword to display only the existing directories in the current directory. Individual files are not displayed.
Set this keyword equal to a string that specifies the name of the X Windows display on which the dialog should be displayed. This keyword is ignored on Microsoft Windows platforms.
Set this keyword to a scalar string that contains the name of the initial file selection. This keyword is useful for specifying a default filename.
On Windows, this keyword also has the effect of filtering the file list if a wildcard is used, but this keyword should be used to specify a specific filename. To list only files of a certain type, use the FILTER keyword.
Set this keyword to a string value or an array of strings specifying the file types to be displayed in the file list. This keyword is used to reduce the number of files displayed in the file list. The user can modify the filter unless the FIX_FILTER keyword is set. If the value contains a vector of strings, multiple filters are used to filter the files. The filter *.* is automatically added to any filter you specify.
For example, to display only files of type .jpg, .tif, or .png in the file selection window, you could use the following code:
filters = ['*.jpg', '*.tif', '*.png'] file = DIALOG_PICKFILE(/READ, FILTER = filters)
The filter list shown above is displayed as five options in the dialog:
*.jpg, *.tif, *.png *.jpg *.tif *.png *.*
Multiple file types can be included in a single filter by providing a semicolon-separated list of types within the string. For example, to account for different extensions used for similar file types, you could use the following code:
filters = ['*.jpg;*.jpeg', '*.tif;*.tiff', '*.png'] file = DIALOG_PICKFILE(/READ, FILTER = filters)
The filter list shown above is displayed as five options in the dialog:
*.jpg, *.jpeg, *.tif, *.tiff, *.png *.jpg, *.jpeg *.tif, *.tiff *.png *.*
The FILTER keyword can optionally be set equal to an n x 2 array. In this case, the first vector contains the file types, and the second vector contains a list of descriptions that are displayed in the dialog in place of the file type strings. For example:
filters = [['*.jpg;*.jpeg', '*.tif;*.tiff', '*.png', '*.*'], $ ['JPEG', 'TIFF', 'Bitmap', 'All files']] file = DIALOG_PICKFILE(/READ, FILTER = filters)
The filter list shown above is displayed as four options in the dialog:
JPEG TIFF Bitmap All files
| Note |
*.* filter is not automatically added to the list. If you want this filter included in the list, you must include it explicitly.
Under Microsoft Windows, the user cannot modify the displayed filter. The user can enter a filter string in the Filename field to interactively update the list of files displayed. For example, entering *.pro in the Filename field causes only .pro files to be displayed.
When this keyword is set, only files that satisfy the filter can be selected. The user has no ability to modify the filter and the filter is not shown.
Under Microsoft Windows, the filter string can never be modified, but the user can enter a filter string in the Filename field to interactively update the list of files displayed even if FIX_FILTER is set.
Set this keyword to a named variable in which the path of the selection is returned.
This keyword is obsolete and has been replaced by the DIALOG_PARENT keyword. Code that uses the GROUP keyword will continue to function as before, but we suggest that all new code use DIALOG_PARENT.
Set this keyword to allow for multiple file selection in the file-selection dialog. When you set this keyword, the user can select multiple files using the platform-specific selection method. The currently selected files appear in the selection text field of the dialog. With this keyword set, DIALOG_PICKFILE can return a string array that contains the full path name of the selected file or files.
Set this keyword to allow only files that already exist to be selected.
If this keyword is set along with the WRITE keyword and the user selects a file that already exists, then a dialog will be displayed asking if the user wants to replace the existing file or not. For multiple selections, the user is prompted separately for each file. If the user selects No the file selection dialog is displayed again; if the user selects Yes then the selection is allowed. This keyword has no effect unless the WRITE keyword is also set.
Set this keyword to a string that contains the initial path from which to select files. If this keyword is not set, the current working directory is used.
Set this keyword to make the title of the dialog "Select File to Read".
Set this keyword equal to a string containing an X Window System resource name to be applied to the dialog.
Set this keyword to a scalar string to be used for the dialog title. If it is not specified, the default title is "Please Select a File".
Set this keyword to make the title of the dialog "Select File to Write".
Create a DIALOG_PICKFILE dialog that lets users select only files with the extension `pro'. Use the `Select File to Read' title and store the name of the selected file in the variable file. Enter:
file = DIALOG_PICKFILE(/READ, FILTER = '*.pro')
Introduced: 5.0