ctl32_openfiledialog, ctl32_savefiledialog
Links
http://msdn.microsoft.com/en-us/library/system.windows.forms.filedialog.aspx
http://msdn.microsoft.com/en-us/library/system.windows.forms.openfiledialog.aspx
http://msdn.microsoft.com/en-us/library/system.windows.forms.savefiledialog.aspx
Espaņol:
http://msdn.microsoft.com/es-es/library/system.windows.forms.filedialog.aspx
http://msdn.microsoft.com/es-es/library/system.windows.forms.openfiledialog.aspx
http://msdn.microsoft.com/es-es/library/system.windows.forms.savefiledialog.aspx
Overview
ctl32_openfiledialog and ctl32_savefiledialog are child classes of the abstract class ctl32_filedialog. Most of the code and properties reside in the ctl32_filedialog class.
This classes try to emulate the equivalent .NET classes.
If you read the information contained in the .NET links, you will have a pretty good idea of how to use these classes. I have added a few properties that are missing in the original .NET classes
Class Hierarchy
ctl32
ctl32_commondialog
ctl32_filedialog
ctl32_openfiledialog
ctl32_openpicturedialog
ctl32_savefiledialog
ctl32_savepicturedialog
ctl32_folderbrowserdialog
Better than GETFILE() and PUTFILE()
Both GETFILE and PUTFILE return file names in ALL CAPS. These classes use the proper original case of the file name and path.
GETFILE can only return one file name. ctl32_openfiledialog allows multiselect, you can select up to thousands of files.
GETFILE and PUTFILE and the .NET classes do not let you choose the initial view style of the file list. These classes allow you to choose an initial display style, for example Thumbnails, by setting the ctlInitialView property. This setting does not work in Windows Vista.
GETFILE and PUTFILE only let you filter files by extension. These classes let you filter by using any valid filter expression that includes the file names and the extensions.
In Windows Vista, you can optionally use the new style open and save dialog boxes, just by setting the ctlAutoUpgradeEnabled property.
The "Places Bar" can be removed from the dialog.
Quick Guide
To use the ctl32_openfiledialog, drop the ctl32_openfiledialog class in a form, or create an instance of it. Set the desired properties of the class, then call ctlShowDialog. This method returns the number of files selected, or 0 if no files where selected. Check the returned value to decide what to do!
The ctlFileCount property contains the number of files selected, or 0 if no file was selected.
The ctlFileName property contains the full filename of the selected file.
The ctlSafeFileName contains only the file name without the path.
The ctlDirectory contains the path of the selected file
If ctlMultiselect was set to TRUE and more than one file was selected, then the ctlFilenames(n) array property contains the full filename of the selected files, sorted by full filename.
The ctlSafeFileNames(n) contains only the file names without the path.
Properties, Events and Methods
Specifies if the dialog box automatically adds an extension to a file name if the user omits the extension.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
The extension added to a file name depends on the currently selected file filter and the value of the ctlCheckFileExists property.
If the ctlCheckFileExists property is true, the dialog box adds the first extension from the current file filter (ctlFilter) that matches an existing file. If no files match the current file filter, the dialog box adds the extension specified in the ctlDefaultExt property.
If the ctlCheckFileExists property is false, the dialog box adds the first valid file name extension from the current file filter. If the current file filter contains no valid file name extensions, the dialog box adds the extension specified in the ctlDefaultExt property.
Specifies if the selected file should be added to the Recent Documents menu item.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Specifies if the dialog should automatically upgrade appearance and behavior when running on Windows Vista.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
If this property is false, the class will have a Windows XP-style appearance and behavior on Windows Vista.
On Windows XP, this property does not have any effect.
Specifies the Cancel button caption.
VALUE TYPE
Character.
DEFAULT VALUE
None.
READ/WRITE
Yes.
REMARKS
This has no effect on Windows Vista when ctlAutoUpgradeEnabled is set to TRUE.
Specifies if the dialog box displays a warning if the user specifies a file name that does not exist.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
The default value is TRUE for ctl32_openfiledialog and FALSE for ctl32_savefiledialog.
Specifies if the dialog box displays a warning when the user specifies a path that does not exist.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Specifies if the dialog box prompts the user for permission to create a file when the user specifies a file that does not exist.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Specifies the default file name extension.
VALUE TYPE
Character.
DEFAULT VALUE
None.
READ/WRITE
Yes.
REMARKS
Do not include a period in the extension.
Specifies whether the dialog box returns the location of the file referenced by the shortcut or whether it returns the location of the shortcut (.lnk).
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
If the return value of ctlShowDialog is <> 0, specifies the selected directory, the path to the selected file(s).
VALUE TYPE
Character.
DEFAULT VALUE
None.
READ/WRITE
Read only.
REMARKS
-
Specifies the number of files selected. If no file is selected, the return value is 0.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Specifies the file name of the selected file in the file dialog box. If more than one file was selected, only the first file name is returned.
VALUE TYPE
Character.
DEFAULT VALUE
None
READ/WRITE
Read only.
REMARKS
The file name includes both the file path and the extension. If no files are selected, this property returns an empty string ("").
This property can only be the name of one selected file. If you want to return an array containing the names of all selected files in a multiple-selection dialog box, use ctlFileNames.
Array with ctlFileCount elements. Specifies the file name(s) of the selected file(s) in the dialog box.
VALUE TYPE
One column array. Character
DEFAULT VALUE
None
READ/WRITE
Read only.
REMARKS
Each file name includes both the file path and the extension. If no files are selected, the value of this property is undefined.
ctlFileOK()Occurs when the user clicks on the Open or Save button on a file dialog box.
REMARKS
-
Gets or sets the current file name filter string, which determines the choices that appear in the "Save as file type" or "Files of type" box in the dialog box.
The following is an example of a filter string:
Text files (*.txt)|*.txt|All files (*.*)|*.*
You can add several filter patterns to a filter by separating the file types with semicolons, for example:
Image Files(*.BMP;*.JPG;*.GIF)|*.BMP;*.JPG;*.GIF|All files (*.*)|*.*
The filter does not have to be only based on the file extension: Images|Img*.bmp is a valid filter.
VALUE TYPE
Character.
DEFAULT VALUE
"All files|*.*"
READ/WRITE
Yes.
REMARKS
The default filter description will be in the language of the operating system, since it is extracted from shell32.dll
For each filtering option, the filter string contains a description of the filter, followed by the vertical bar (|) and the filter pattern. The strings for different filtering options are separated by the vertical bar.
The following is an example of a filter string:
Text files (*.txt)|*.txt|All files (*.*)|*.*
You can add several filter patterns to a filter by separating the file types with semicolons, for example:
Image Files(*.BMP;*.JPG;*.GIF)|*.BMP;*.JPG;*.GIF|All files (*.*)|*.*
Use the ctlFilterIndex property to set which filtering option is shown first to the user.
Specifies the index of the filter currently selected in the file dialog box.
VALUE TYPE
Numeric.
DEFAULT VALUE
1
READ/WRITE
Yes.
REMARKS
Use the ctlFilterIndex property to set which filtering option is shown first to the user. You can also use the value of ctlFilterIndex after showing the file dialog to perform special file operations depending upon the filter chosen.
Returns the default filter string in the operating system language. For example: "All files (*.*)|*.*"
PARAMETERS
None.
DESCRIPTION
-
RETURN VALUE
Character.
REMARKS
The default filter description is extracted from shell32.dll
Specifies the Help button caption.
VALUE TYPE
Character.
DEFAULT VALUE
None
READ/WRITE
Yes.
REMARKS
This has no effect on Windows Vista when ctlAutoUpgradeEnabled is set to TRUE.
Occurs when the user clicks the Help button on a common dialog box.
REMARKS
-
Specifies the initial directory displayed by the file dialog box.
VALUE TYPE
Character.
DEFAULT VALUE
None
READ/WRITE
Yes.
REMARKS
The ctlInitialDirectory property is typically set using one of the following sources:
A path that was previously used in the program, perhaps retained from the last directory or file operation.
A path read from a persistent source, such as an application setting, a Registry or a string resource in the application.
Standard Windows system and user paths, such as Program Files, MyDocuments, MyMusic, and so on (which you can obtain using the GetFolderPath method)
A path related to the current application, such as its startup directory (which you can obtain using properties on the Application object).
On Windows Vista, if ctlInitialDirectory is set to a full file name instead of just a directory path, the initial directory will default either to the application path, or to the directory from which the user last selected a file.
Specifies the initial file name displayed by the file dialog box.
VALUE TYPE
Character.
DEFAULT VALUE
None
READ/WRITE
Yes.
REMARKS
-
Specifies the initial view of the file pane.
VALUE TYPE
Numeric.
DEFAULT VALUE
0
READ/WRITE
Yes.
REMARKS
-
Gets or sets a value indicating whether the dialog box allows multiple files to be selected.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Gets or sets the OK button caption.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Raises the FileOk event.
PARAMETERS
None.
DESCRIPTION
-
RETURN VALUE
None.
REMARKS
-
Raises the HelpRequest event.
PARAMETERS
None.
DESCRIPTION
-
RETURN VALUE
None.
REMARKS
-
Infrastructure. Gets values to initialize the FileDialog.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Gets or sets a value indicating whether the Save As dialog box displays a warning if the user specifies a file name that already exists.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Gets or sets a value indicating whether the read-only check box is selected.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Resets the properties of a common dialog box to their default values.
PARAMETERS
None.
DESCRIPTION
-
RETURN VALUE
None.
REMARKS
-
Gets or sets a value indicating whether the dialog box restores the current directory before closing.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
When overridden in a derived class, specifies a common dialog box.
PARAMETERS
None.
DESCRIPTION
-
RETURN VALUE
None.
REMARKS
-
Gets the file name and extension of the first selected file in the dialog box. The file name does not include the path.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Gets an array of file names and extensions for all the selected files in the dialog box. The file names do not include the path.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
ctlShowDialog()
This is the main method that displays the file dialog. Runs a common dialog box.
PARAMETERS
None.
DESCRIPTION
-
RETURN VALUE
None.
REMARKS
-
Gets or sets a value indicating whether the Help button is displayed in the file dialog box.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Specifies is hidden files are shown.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Gets or sets a value indicating whether the Places Bar is displayed in the file dialog box.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Gets or sets a value indicating whether the dialog box contains a read-only check box.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
ctlSupportMultidottedExtensions
Gets or sets whether the dialog box supports displaying and saving files that have multiple file name extensions.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Gets or sets the file dialog box title.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Gets or sets a value indicating whether the dialog box accepts only valid Win32 file names.
VALUE TYPE
Logical.
DEFAULT VALUE
TRUE
READ/WRITE
Yes.
REMARKS
-
Carlos Alloatti
