Classes Class XbpFileDialog() :open()

Method XbpFileDialog():open() Foundation

Activates the file dialog to open a file.

Syntax 
:open( [<cDefaultFile>],  ;
       [<lCenter>],       ; 
       [<lAllowMultiple>],;
       [<lCreateNewFiles>] ) --> cFileName | aFileNames | NIL
Parameters
<cDefaultFile>
An optional character string can be specified for the <cDefaultFile> parameter. If a string is specified and contains a valid path, the respective folder is set as the initial directory displayed by the file dialog. If it contains a file name (either with or without path information), it is displayed in the entry field "File name:" of the file dialog and denotes the default file name for the file to be opened.
On some Windows platforms, the default folder displayed in the dialog is determined by the operating system.
Windows 2000, XP and 2003 Server systems - If no path is specified in <cDefaultFile> and the application has opened a file dialog in the past, the path most recently is used as the initial directory of the dialog. Path info is stored by the operating system only for a certain time period. Once the time period has elapsed, or if no file dialog has been opened by the application, the current directory is used if the directory contains files of the required type. Otherwise, the "Personal Files" folder is used.
Windows 98, ME systems - If no path is specified in <cDefaultFile>, the current directory is used as the initial directory if the directory contains files of the required type. Otherwise, the "Personal Files" folder is used.
All other Windows platforms - If no path is specified in <cDefaultFile>, the current directory is used as the initial directory displayed by the dialog.
<lCenter>
The optional parameter <lCenter> determines whether the file dialog is centered in the parent window. This parameter must be a logical value and its effect is identical to the :center instance variable. If <lCenter> is specified, the :center instance variable is ignored.
If <lCenter> is set to .T. (true), the dialog window is centered within the parent window. If this is .F. (false), the file dialog is displayed at the upper left corner of the parent window.

Beginning with Windows Vista, the operating system uses a classic/compatible window style for dialogs which are customized in any way. For this reason, passing .T. in <lCenter> or setting :center to .T. is discouraged on Windows Vista and newer operating systems.

<lAllowMultiple>
The optional parameter <lAllowMultiple> specifies whether the user should be allowed to select more than one file in the file dialog. If this parameter is .T. (true), :open() returns a list of files selected by the user. If it is .F. (false), selecting multiple files is not allowed. This parameter defaults to .F. (false).
<lCreateNewFiles>
Parameter <lCreateNewFiles> specifies how the file dialog should handle names of files that do not exist. This parameter is optional. If no value or the value NIL is passed for this parameter, the file dialog does not distinguish between existing and non-existing files. If the value .T. (true) is passed for <lCreateNewFiles>, the user is informed if a file does not exist and is asked whether it should be created. If .F. (false) is passed, file names that denote non-existing files are rejected. This parameter defaults to NIL.
Return

The return value of this method depends on the value passed for the <lAllowMultiple> parameter. If .F. (or nothing) was passed for this parameter, :open() returns the name of the file selected by the user as a character string. If <lAllowMultiple> was set to .T., return is an array of character strings with the list of files names selected. The file name(s) returned always include path information, that is, the drive and directory the file or files are located in. If the dialog is not closed using the "OK" pushbutton, this method returns NIL.

Description

The :open() method displays and activates the file dialog. This dialog allows the user to select a file or a list of files in any directory on any drive. The user indicates a selection by pressing the "OK" pushbutton. This also closes the dialog and this method returns the selected file name(s), including drive and directory information. The dialog can also be closed using the "Cancel" pushbutton or the dialog's window menu. In either of these cases, no file has been selected and this method returns NIL.

The file dialog is generally activated using :open() when a user needs to select a file to open. When a file is to be saved (or saved with a different name), the file dialog is generally activated using the method :saveAs().

For compatibility reasons, parameter <cDefaultFile> may also contain the asterisk wildcard character (*). However, usage of this feature is discouraged. In order to display only certain kinds of files within a file dialog, use file filters instead. See the :fileFilters instance variable for further information.

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.