XJTAG logo
Open search box button
Close search button

SAVE_FILE_DIALOG

The SAVE_FILE_DIALOG function is used to display a Save File dialog to the user and wait for a path to be selected.

In XJRunner a Save File dialog is displayed:

Example Save File dialog in XJRunner

When multiple XJLinks are in use, XJRunner will direct the user's attention to any tab that is trying to display a dialog, but will not display the dialog until the tab is selected. The behaviour is very similar to the ALERT statement.

In XJRun a simple prompt is displayed:

Example save file dialog on the command line

SAVE_FILE_DIALOG was added in XJTAG v3.13.

Syntax

There are two forms of the SAVE_FILE_DIALOG function, depending on whether it is used in an expression or whether it is used as a statement. The statement form has two return parameters: the filename entered and a boolean value that indicates if the Cancel button was pressed. If the function is used in an expression, there is no second return parameter and so there is no explicit way of determining that Cancel was pressed; an empty string is returned in this case. If you need to distinguish between Cancel and an empty string being entered, then use the statement version.

SAVE_FILE_DIALOG( STRING title, STRING[] filters [ , STRING initialPath ] )
SAVE_FILE_DIALOG( STRING title, STRING[] filters [ , STRING initialPath ])( STRING selectedPath, INT cancelled )

Parameters

title
The title displayed on the dialog.
filters

A STRING array containing file type filters to be used in the dialog. A description may be optionally defined, if so this is given before the filter pattern, separated by a vertical bar (|) character, e.g. { "XJEase files|*.xje", "*.txt" }. Multiple patterns can be defined in a single filter, by separating the patterns with a semicolon, e.g. { "Programming files|*.svf;*.stapl" }. Use an empty array to show all files without any filters being applied.

initialPath

This parameter is optional.

A path which will define the initial directory and filename for the dialog. If this is a directory path, then that directory will be the initial directory of the dialog; otherwise, the path is split into directory and filename parts, the directory setting the initial directory of the dialog, and the filename setting the initial filename. The given path may be relative or absolute - if is relative, then it is considered relative to the project directory. If the parameter is omitted or invalid (i.e. it contains invalid characters or defines a directory that does not exist) then the initial directory of the dialog will be the project directory and the initial filename will be empty.

selectedPath

A STRING variable that will receive the path to the file that the user selected in the dialog. This will be given relative to the project if possible; if an absolute path is required, then ABSOLUTE_PATH can be used to convert the relative path to an absolute path. If the dialog is cancelled, then this will be an empty string.

cancelled

An INT variable that will receive a boolean value of TRUE if Cancel was pressed, or FALSE if a file was selected.

Return value

In the first case, when SAVE_FILE_DIALOG is used in an expression, the function returns a STRING value containing the text that the user entered. If the user cancels the input, then an empty string is returned.

Example

// Used as an expression
STRING selectedPath;
selectedPath := SAVE_FILE_DIALOG("Select a save path", { "Project files|*.xje;*.pdd;*.ldd", "All files|*.*" });
IF selectedPath = "" THEN
  PRINT("No path was selected\n");
ELSE
  PRINT("The selected path was ", selectedPath, "\n");
END;

// Used as a statement
STRING selectedPath;
INT cancelled;
SAVE_FILE_DIALOG("Select a save path", { "Project files|*.xje;*.pdd;*.ldd", "All files|*.*" })(selectedPath, cancelled);
IF cancelled THEN
  PRINT("The Save File dialog was cancelled\n");
ELSE
  PRINT("The selected path was ", selectedPath, "\n");
END;

// Setting an initial directory
STRING selectedPath;
INT cancelled;
SAVE_FILE_DIALOG("Select a save path", { "Project files|*.xje;*.pdd;*.ldd", "All files|*.*" }, "C:\\Users\\Public\\Documents")(selectedPath, cancelled);
IF cancelled THEN
  PRINT("The Save File dialog was cancelled\n");
ELSE
  PRINT("The selected path was ", selectedPath, "\n");
END;

// Setting an initial file
STRING selectedPath;
INT cancelled;
SAVE_FILE_DIALOG("Select a save path", { "Project files|*.xje;*.pdd;*.ldd", "All files|*.*" }, "circuittest.xje")(selectedPath, cancelled);
IF cancelled THEN
  PRINT("The Save File dialog was cancelled\n");
ELSE
  PRINT("The selected path was ", selectedPath, "\n");
END;

// Converting the selected path to an absolute path
STRING selectedPath;
STRING absolutePath;
selectedPath := SAVE_FILE_DIALOG("Select a save path", { "Project files|*.xje;*.pdd;*.ldd", "All files|*.*" });
IF selectedPath = "" THEN
  PRINT("No path was selected\n");
ELSE
  absolutePath := ABSOLUTE_PATH(selectedPath);
  PRINT("The absolute path to the selected file is ", absolutePath, "\n");
END;

See Also