s = CS.Path.selectFile(ʃtitle := ...ʅ
ʃ, filter := ...ʅ
ʃ, startDirectory := ...ʅ
ʃ, rootDirectory := ...ʅ
ʃ, showDirectories := ...ʅ) | Argument | Description | Types / Required |
|---|
| title | The title of the dialog. | string
not required |
| filter | A wildcard used to filter the files. | string
not required |
| startDirectory | The path of the directory to be initially shown to the operator. | string
not required |
| rootDirectory | The path of the directory above which the operator cannot navigate. | string
not required |
| showDirectories | If false, the operator will not see subdirectories and will not be able to navigate to a parent directory.
The default value is true. | boolean
not required |
The
Path.selectFile action shows the operator a visual listing of the file system and returns the path of the file the operator selected. Hidden and system files are not shown to the operator.
You can specify a wildcard
filter that filters the files shown in the visual listing. For example,
"*.csdb" would include only the paths of
CSPro DB data sources. You can specify multiple wildcard filters by separating each filter with a semicolon. The filter
"*.jpg;*.jpeg;*.bmp" would include both JPEG and BMP files. In addition to standard wildcard filters, you can use a predefined wildcard expression, specified with the
"|" prefix:
- "|FileType.Audio": Files that the Audio object can read and write.
- "|FileType.Geometry": Files that the Geometry object can read and write.
- "|FileType.Image": Files that the Image object can read and write.
Provide startDirectory to specify the initial directory shown to the operator and rootDirectory to control how much of the file system the operator can browse. Specifying a root directory prevents the operator from moving to a location above the root directory. If neither are provided, the operator will initially see files starting in the directory where the currently running application is located, and will have access to other files on that drive. If a root directory is provided without a start directory, the start directory will be set to the root directory. If both a start and root directory are provided, the root directory must be equal to or above the start directory. Generally both directory paths are directories, but they can also be one of the following special values, specified with the "|" prefix:
- The Android root directory, specified as "|Android".
- An Android Media Store directory, specified as one of the following: "|Media.Audio", "|Media.Images", or "|Media.Video". Note that files in these "directories" can actually reside in multiple directories.
By default, both files and directories are shown to the operator. To hide directories, set
showDirectories to
false.
The
Path.selectFile function can also be used to show a visual listing of the file system to the operator.
The action returns a string containing the fully evaluated path of the selected file, or undefined if no file was selected.
The action throws an exception if any of its arguments are not specified in a valid form or if either the start or root directories do not exist.
// select an image file from the images included in CSPro's html directory
const imagePath = CS.Path.selectFile({
title: "Select an Image",
filter: "|FileType.Image",
rootDirectory: CS.Path.getSpecialPaths().html + "/images"
});
if( imagePath !== undefined ) {
// ... do something with the selected image
}