FilePopup Method
The FilePopup method displays a file selection dialog in the center of the current frame. The dialog lets the user select a file by navigating among various file directories. The dialog contains an Open or Save button and a Cancel button. You may also specify file filters that aid the user in selecting a file.
This method has the following syntax:
integer = ProcExec.FilePopup([messagetext = nvarchar(256), ]reply = StringObject
[, operation = integer][, defaultextension = nvarchar(256)]
[, promptifexists = integer][, allowmultiselect = integer])
The FilePopup method may be invoked from a 4GL procedure or method only when the 4GL procedure or method has been invoked from a user frame.
This method has the following parameters:
messagetext
Contains text that is displayed in the dialog's title bar
reply
(Required) Specifies a default file and one or more file filters. When the user selects a file to open or a file name to save in the dialog, the full name of the selected file is returned in the reply parameter.
operation
Determines whether the selection box has a Save button or an Open button. Possible values are FOP_OPEN or FOP_SAVE. If you do not specify the operation parameter, the file selection box will have an Open button.
defaultextension
Specifies that an extension should be appended to the file name displayed as the default for an FOP_SAVE operation. This extension will change whenever the user switches the filter to be applied. The value provided can be a simple file name including extension, a full file name including path and extension, or an extension in the format *.extension. If the path is included, the popup will navigate to the path folder before opening.
If defaultextension is not set, no extension is displayed.
promptifexists
Specifies that the user will be prompted to continue or cancel if the specified name will overwrite an existing file.
Default: FALSE
allowmultiselect
Specifies that the user may select multiple files in an FOP_OPEN operation. If the user selects multiple files, the reply string contains multiple lines of text, as follows:
• The first line contains the full path of the folder containing these files.
• Each other line contains the file name of one of the selected files.
If the user selects a single file, the reply string contains a single line of text consisting of the full path and file name of the selected file, regardless of the setting of this parameter.
Default: FALSE
The method returns PU_OK if the user clicks OK and PU_CANCEL if the user clicks Cancel. Descriptions of system constant values and their numeric equivalents are listed in
Pop-up Reply Codes).
There are two methods of using the reply parameter: simple and advanced.
Using the reply parameter
Simple Method
The simple method lets you specify a single default file name or a single simple file filter. The following examples illustrate the simple method. All of the following examples use Windows conventions for specifying directories. On non-Windows systems, you must use the conventions of the operating system. Some examples are:
/*
** To specify a single default file, simply
** specify the file name.
** Enclosing the file name in double quotes, as
** in the advanced method, will also work.
*/
reply.Value = 'myfile.txt';
/*
** You may also specify a default directory along
** with the default name.
*/
reply.Value = 'c:\tmp\myfile.txt';
/*
** You may also specify a single simple file
** filter.
*/
reply.Value = '*.txt';
/*
** The filter specification may also include a
** directory.
*/
reply.Value = 'c:\mystuff\*.txt';
In all cases, a filter of All Files (*.*) is automatically included.
Advanced Method
To describe the advanced method, it is useful to introduce some definitions:
filename
Is the name of a single file. The name may include a path. The name must be enclosed in double quotes.
Examples:
"myfile.txt"
"c:\mystuff\myfile.txt"
filespec
Is a wildcard specification of a set of files. The specification may include a directory specification.
Examples:
*.txt
c:\mystuff\w*.txt
tmp?.*
filespeclist
Is a list of filespecs separated by semicolons. If filespecs are specified in the filter, the dialog will display only files matching these specifications.
The first filespec in the list may contain a directory specification. If so, the dialog will display files from this directory.
Examples:
*.txt
*.img; *.bmp; *.ico
c:\source\*.c; *.ccp
ccfilefilter
Is a filespeclist followed by a text string enclosed in brackets ([ … ]). The opening bracket must immediately follow the last filespec with no intervening spaces. The text string within the brackets is a description of the filter.
Examples:
*.txt[Text Files]
*.img; *.bmp; *ico; *.gif[Image Files]
c:\source\*.c; *.ccp[Source Files]
filterlist
Is a list of ccfilefilters separated by spaces or commas. If multiple ccfilefilters are specified, the first one will be applied when the dialog is initially displayed. All the ccfilefilters will be available for selection, and will be applied when the user selects them.
Examples:
*.txt[Text Files], *.doc[Word Document]
*.bmp; *.ico; *gif[Image Files]
c:\source\*,c; *.ccp[Source Files], *.h; *.hpp[Include Files]
Finally, we can describe the advanced form of the reply parameter:
reply.Value = 'filename,' + 'filterlist';
or:
reply.Value = 'filterlist';
The optional filename is the default file for the file selection dialog. If the optional filename is specified, none of the filespecs in the filterlist may contain a directory specification. If no filename is specified, only the first filespec in the filterlist may contain a directory specification. In every case, "All Files" (*.*) is automatically added as a filter.
Some examples are:
/*
** This example specifies a filter for selecting
** a bmp, gif, or ico image
*/
reply.Value = '*.bmp; *.gif; *.ico[Image Files]';
ret = CurFrame.FilePopup
(
messagetext = 'File containing image',
reply = reply
);
if (ret = PU_OK) then
myBitmapObject.FileHandle = reply.Value;
else
/*
** User canceled and did not select a file.
*/
endif;
/*
** In this example there are two filters: the first
** displays only c or ccp filetypes, the second
** displays only h or hpp filetypes. The default
** directory is d:\src.
*/
reply.Value = 'd:\src\*.c; *.ccp[Source Files] ' +
'*.h; *.hpp[Include Files]';
ret = CurFrame.FilePopup(reply = reply);
/*
** In this example there is a single filter.
** The default directory is c:\textfiles and
** the default file is newfile.txt.
*/
reply.Value = '"c:\textfiles\newfile.txt", *.txt';
ret = CurFrame.FilePopup(reply = reply);