Path.selectFile Function

Format

s = Path.selectFile(ʃmessageʅ);

s = Path.selectFile(ʃtitle := message,ʅ
ʃfilter := wildcard,ʅ
ʃstartDirectory := start_directory_path,ʅ
ʃrootDirectory := root_directory_path,ʅ
ʃshowDirectories := show_directories_flagʅ);

Description

The Path.selectFile function 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 in the visual listing.

In the first version, an optional string expression message specifies the title of the dialog that shows the file listing. 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.

The second version, accessed by using named arguments, gives you control over the location and kind of files that the operator can choose. The string expression message specifies the title of the dialog that shows the file listing.

You can specify a string expression, wildcard, that is applied to filter the files shown in the visual listing. For example, "*.csdb" would show only CSPro DB files. You can specify multiple wildcard filters by separating each filter with a semicolon. The filter "*.jpg;*.jpeg;*.bmp" would show both JPEG and BMP files. Instead of using a string expression, you can also use a predefined wildcard expression:

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.

To specify the initial directory shown to the operator, you can specify a start_directory_path. You can also specify a root_directory_path. 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. Both directory paths can be one of the following:

A string expression specifying a directory.
One of the path types documented in the pathname function.
A media type, which will show the files of the specified media type on Android. These files can reside in multiple directories.

By default, both files and directories are shown to the operator. To hide directories, set the numeric expression show_directories_flag to false.

The Path.selectFile action can also be used to show a visual listing of the file system to the operator.

Return Value

The function returns a string with the path of the selected file, or a blank string is no file was selected.

Example 1

string pff_filename = Path.selectFile(title := "Select an Application to Execute",
filter := "*.pff");

if pff_filename <> "" then
execpff(pff_filename);
endif;

Example 2

string data_directory = Path.concat(application, "../Data");
string current_region_data_directory = Path.concat(data_directory, maketext("%v", REGION));

string data_filename = Path.selectFile(title := "Select a Data File To Process",
filter := "*.csdb",
rootDirectory := data_directory,
startDirectory := current_region_data_directory);

Example 3

string image_filename = Path.selectFile(title := "Select Your Favorite Image",
rootDirectory := Media.Images);