DISPLAY SAVEFILE statement

Purpose

Display a SaveFile selection dialog to return user choices.

Syntax

DISPLAY SAVEFILE [hParent], [xpos&], [ypos&], title$, folder$, filter$, _
start$, defext$, flags& TO filevar$ [,countvar&]

hParent

Handle of the parent window or dialog. If there is no parent, use zero (0) or %HWND_DESKTOP.

xpos&

Horizontal position, in pixels, relative to the parent window. If omitted, PowerBASIC selects the position (offset from the parent, or centered if no parent).

ypos&

Vertical position, in pixels, relative to the parent window. If missing, PowerBASIC selects the position (offset from the parent, or centered if no parent).

title$

The title to be displayed in the title bar of the dialog box. If this parameter is a null string, the title "Save As" is displayed.

folder$

The name of the initial file directory to be displayed. If this parameter is a null string, the current directory is used.

filter$

A string expression containing pairs of null-terminated filter strings. The first string in each pair describes the filter, and the second the filter pattern. For example, if you wish to display BASIC source files, you might use an expression like:

"BASIC" + CHR$(0) + "*.BAS" + CHR$(0)

A simpler method using the unique characteristics of the CHR$() function in PowerBASIC to achieve the same result:

CHR$("BASIC", 0, "*.BAS", 0)

Multiple filters can be designated for a single item by separating filter pattern strings with a semicolon:

CHR$("BASIC", 0, "*.BAS;*.INC;*.BAK", 0)

start$

A string which specifies the starting file name to be used as the initial file selection. This may be disabled by passing a nul, zero-length string ("").

defext$

A default extension to be appended to the selected file name if the user does not enter it. This may be disabled by passing a nul, zero-length string ("").

flags&

The style attributes of the SAVEFILE Dialog. The following values may be used alone or combined, and are predefined in the PowerBASIC compiler:

%OFN_ALLOWMULTISELECT	Multiple selections are allowed. If the user chooses multiple items, the return value consists of multiple file names which are null-terminated.
%OFN_CREATEPROMPT	The user may specify a file which does not exist.
%OFN_ENABLESIZING	The dialog may be resized by the user, but future invocations remember and use the ending size and screen location, rather than honoring xpos and ypos parameter values. The position parameters are ignored.
%OFN_EXPLORER	The dialog uses the Explorer style interface. This is the default condition, even if the flag is not set.
%OFN_FILEMUSTEXIST	The user may not specify a file which does not exist.
%OFN_NODEREFERENCELINKS	The dialog returns the name of the selected shortcut (.LNK) file. If this value is not given, the name of the file referenced by the shortcut is returned.
%OFN_NONETWORKBUTTON	Hides and disables the network button.
%OFN_NOTESTFILECREATE	The file is not created before the dialog is closed.
%OFN_NOVALIDATE	The file name is not validated for invalid characters.
%OFN_PATHMUSTEXIST	The user may type only valid paths and filenames.
%OFN_OVERWRITEPROMPT	The user may select a filename that already exists.
%OFN_SHAREAWARE	If the dialog fails because of a network sharing violation, the error is ignored and the selected filename is returned.
%OFN_SHOWHELP	The help button is displayed.

Return Values

filevar$

If the user selects one file, this variable receives the drive, path, and name of that file. If the user selects no files, an error occurs, or cancel/close is chosen, this variable is set to a nul, zero-length string.

If the user selects multiple files, and specified the flag %OFN_ALLOWMULTISELECT, the returned string consists of the path name (which applies all selected files), followed by each of the file names of the selected files. Each of these text items are delimited in the returned string by a nul - CHR$(0). You can extract each of the multiple names with the PARSE$() function or the PARSE statement.

Windows imposes a text limit of 32K (32,768 bytes) for the returned string value. If it is exceeded, a nul, zero-length string is returned.

countvar&

If this optional long integer variable is included, it receives a count of the number of file names which were selected by the user.

Remarks

The current default directory is never altered by this statement, even if the user changes the directory while searching for files.