fileSelector()

Opens a file selection dialog and returns the name of the selected file.

Synopsis

int fileSelector(string &fileName [, mapping options | string dir = PROJ_PATH [, bool notUp = true [, string pattern = "" [, bool open = true [, string settingsId = "" [, bool fileActions = true]]]]]])

Parameters

Parameter Description
fileName The path to the file. If OK is clicked in the selection dialog, the file path is saved in fileName. If Cancel is clicked, an empty string is saved.
options

Instead of passing separate optional parameters, a mapping can be used.

Each optional parameter can be used as a key in the mapping. For example, see: Disable File Actions Code Snippet
dir

The target directory for file selection.

This can also be provided as path and filename. In this case, the directory will change to that path, and the filename will be selected.

Note: If the target directory corresponds to a project path or the WinCC OA path, the drive selection combo box in the file selection dialog will be disabled. To enable drive selection, specify a path outside the project.
notUp Prevents access to directories above the dir directory. If notUp is true and dir is, for example, ./temp/dir1/, the user cannot navigate to the ./temp/ directory above it.
Restriction: To stop users from bypassing this restriction, certain characters are blocked. This also means that relative paths cannot be used when notUp is active.
patternstr You can specify a pattern to filter file types. For example, "*.gif" allows only GIF files to be used. To specify multiple types, separate them with a space, e.g., "*.xml *.ds".
open

Determines if only existing files can be selected or if new file names can also be entered.

TRUE: Only existing files can be selected.

FALSE: New file names can also be entered.
settingsId Stores the window settings (position, size) each time the file selection dialog is reopened. This ensures the dialog opens in the same position and size as when it was last closed. This is useful, for example, when using two monitors, so the dialog doesn't always open on the wrong monitor.
fileActions Specifies if file operations, like creating new files or folders, are allowed in the file selector. By default, file actions are allowed.

Return value

If an error occurs, the function returns -1. Otherwise, it returns 0.

Errors

An error message is shown if a directory is selected instead of a file or if an incorrect parameter is provided.

Details

This function opens a file selection dialog and saves the selected file's name in the fileName variable. The dir argument specifies the directory to start the selection from. If notUp is set to true, the selection is restricted to files and directories within dir. By default, notUp is true. The patternstr argument allows filtering file types, such as "*.gif" for GIF files. The fileName variable will contain the absolute file path.

Example

main()
{
  string fileName;
  fileSelector(fileName, PROJ_PATH + "/config", false, "*.*", false, "MyId");
  DebugN("Filename:", fileName);
}

Disable File Actions Code Snippet

main()
{
  mapping options = makeMapping("fileActions", false, "dir", getPath(DATA_REL_PATH));
  string filename;
  fileSelector(filename, options);
}

Assignment

File Functions

Selection and Configuration Dialogs - Functions

Availability

UI