Getting or save a file, using standard dialog window¶
get_filename() |
Get or save a file, using standard dialog window |
SYNTAX
get_filename(window_id, title, start_directory, default_file, filters, flags)
Opens the standard Get File or Save File Windows dialog, enabling the user to select a filename. The default is Get File; an option flag may be set in the flags argument to specify a Save File dialog. The dialog window uses the style and appearance of the native Windows environment. The dialog is terminated when the user either selects a file or cancels the operation.
The function returns the name of the file selected. This is blank if the dialog was cancelled without a file being chosen.
All arguments except the window_id are optional. To leave an argument blank, put either an empty string (“”) or the value NULL at the relevant place.
window_id |
The identifier of the window that is to be the parent of the dialog window. This must be provided. In practice the main task window wintask can always be used. The only effect of using a different window is to change the position of the dialog, which is always placed at the top left of the parent window, or, if this does not allow the whole dialog to fit on the screen, as near to this point as possible. |
title |
A text string specifying the title of the dialog window. If this is blank, the default title (Open for a Get File dialog, or Save As for a Save File dialog) is used. |
start_directory |
The directory to be initially displayed. If this is left blank, or if an invalid directory path is provided, it defaults to the current directory. Relative or absolute pathnames may be used. Remember that the backslash character ( “\” ) is used as an escape character in text strings, and therefore wherever it appears in a directory pathname two consecutive backslashes must be used - the first to indicate that the second is actually to be treated as a backslash, and has no special meaning. This may be avoided by using the forward slash character “/” in place of the backslash, e.g.: “/usr/fred/sculptor” (equivalent to “\\\\usr\\\\Fred\\\\sculptor”)
“../../data”
|
default_file |
The file to be selected initially as the default. The name of this file is displayed in the File name box when the dialog window opens. This parameter is optional and may be left blank, in which case there is no default file. The default remains displayed until the user types over it or clicks on a different file. |
filters |
An optional argument used to restrict the files available for selection. Described fully below under Filters. |
flags |
Special options, described fully below under Flags. |
Illustration¶
A program, getfile.f, which demonstrates the function, is available in the directory $SCULPTOR/demo/dialogs. This illustration shows the Get File dialog running under Windows.
A Read-only checkbox and a Help button may optionally be included in the dialog by means of option flags.
Filters¶
The optional filters argument is used to restrict the files available for selection. If used, it must be the name of an alphanumeric temporary field with two dimensions, which contains the filters to be used and their descriptions.
A typical definition of a temporary field used for this purpose would be:
!temp Filter,,a30[8,2]
The first subscript defines how many filters can be used concurrently. In the example above, 8 filters can be used.
The second subscript should always be 2.
The first value in each pair of elements (i.e. tmp.Filter[1,1], tmp.Filter[2,1]…) contains a brief text description of the file filter, such as “Text files”, “Program files”. The size of the alphanumeric field (in this case 30 bytes) should be enough to accommodate the longest such description used.
The second value in each pair (i.e. tmp.Filter[1,2], tmp.Filter[2,2]…) specifies the file filter or filters corresponding to the description in the first value, e.g. “*.txt”. If multiple filters are included in a single element, they should be separated by semi-colons, e.g. “*.f; *.r”. The filters are not displayed - they can, of course, be added to the description, as in the example below, where the filters described in these paragraphs are assigned to the array:
tmp.Filter[1,1] = "Text files (*.txt)"
tmp.Filter[1,2] = "*.txt"
tmp.Filter[2,1] = "Sculptor source files (*.f; *.r)"
tmp.Filter[1,2] = "*.f;*.r"
The first filter in the array is applied when the dialog window first opens.
The filters are listed in the Files of type listbox. The user can select a different filter from the list, and the displayed files change accordingly.
An empty description (“”) cannot be included in the list. If one is encountered, that filter and any subsequent ones are ignored. However, it is valid to include a description with no corresponding filter. This enables the option to display all files (use no filters) to be included in the list. Assign a description such as “All files” and leave the corresponding filter blank.
To include all files, set the filters argument to ” “.
If the get_filename function is called with the GFN_GETSAVEFILE flag and a list of filters, then, if the user types a file name without an extension, the extension for the currently selected filter is appended automatically to the file name returned by the function. If the currently selected filter contains multiple extensions, the first extension listed is appended.
Note
A filter only determines which files are displayed. The user can type in the name of a file even if it is excluded by the filter.
Flags¶
The flags argument allows one or more special options to be specified. These options are listed in the include file $SCULPTOR/include/files.h, and have the prefix GFN_. If more than one option flag is required, the flags should be separated by the | character, e.g.
GFN_ALLOWNEWPATH | GFN_SHOWHELP
If none of the available options is required, set flags to 0.
All flags are off by default.
The options are:
GFN_SHOWHELP |
This flag causes a Help button to be displayed in the dialog window. |
GFN_SHOWREADONLY |
Include an Open as read-only checkbox in the dialog window. This option is for future use. |
GFN_READONLY |
If this option is set the Open as read-only checkbox is checked when the dialog window opens. The default is for it to be initially unchecked. This flag is ignored if GFN_SHOWREADONLY is not set. |
GFN_ALLOWNEWFILE |
If this flag is not set, then entering the name of a non-existent file in a Get File dialog causes an information window to open, warning the user that the filename is invalid:
Setting GFN_ALLOWNEWFILE allows the user to enter the name of a file that does not currently exist, without warnings or error messages being generated. If GFN_CREATEPROMPT is also set, the user is prompted as to whether they wish to create a new file (see below). Otherwise the dialog closes and the function terminates. |
GFN_ALLOWNEWPATH |
If this flag is set, the user is allowed to type in a file name with a directory path which does not currently exist. Note however that if such a file name is entered the function returns a blank string. To create a new directory during a get_filename dialog, click on the Create New Folder button. |
GFN_CREATEPROMPT |
If this flag is set for a Get File dialog, and the user enters the name of a file which does not currently exist, a prompt window opens to ask if the file should be created:
If the No button is pressed control returns to the Get File Name dialog. The prompt is issued regardless of the value of GFN_ALLOWNEWFILE. |
GFN_GETSAVEFILE |
This flag causes the dialog to open as Save File, rather than Get
File. The default title changes, and certain boxes and buttons have
different labels:
|
GFN_OVERWRITEPROMPT |
This flag causes a prompt window to be opened if GFN_GETSAVEFILE is set and the user selects or enters the name of a file which already exists:
If the flag is omitted, the user can overwrite an existing file without warning. This flag is ignored unless GFN_SAVEFILE is set. |
GFN_ALLOWMULTISELECT |
Allow selection of multiple filenames. This option is not currently supported by Sculptor. |
EXAMPLE
This example opens a Get File dialog, starting in the directory “/sculptor/progs” with the file “system.f” displayed as the default, and displays the selected file name in a prompt when the dialog closes.
!temp DefaultFileName,,a60
!temp Filter,,a20[8,2]
!temp StartDir,,a60
tmp.Filter[1,1] = "Program Files"
tmp.Filter[1,2] = "*.f;*.r"
tmp.Filter[2,1] = "Include Files"
tmp.Filter[2,2] = "*.h"
tmp.Filter[3,1] = "Compiled Files"
tmp.Filter[3,2] = "*.g;*.q"
tmp.Filter[4,1] = ""
tmp.DefaultFileName = "system.f"
tmp.StartDir = "/sculptor/progs"
prompt " Selected filename: " + \
get_filename(wintask, "Open File", tmp.StartDir, tmp.DefaultFileName, tmp.Filter, 0) / " "
exit
RELATED TOPICS |