The Open Dialog Box


Figure 17.8 shows the Open dialog box that the common dialog box control produces.

FIG. 17.8

The Open dialog box lets users select a file to open.

The Open dialog box ensures that users select a valid computer (in a networked environment), drive, path name, and file name.

Although you don't have to set any Flags values before displaying the Open dialog box, Table 17.3 lists the optional Flags values you might want to set before triggering the dialog box's ShowOpen method.

Table 17.3 The Open and Save Dialog Boxes' Flags Values

Named Literal

Flags Value

Description

cdlOFNAllowMultiselect

&H200

Lets the File Name list box accept multiple file selections. The FileName property then returns a string that contains all the selected file names (names in the string are delimited by spaces).

cdlOFNCreatePrompt

&H2000

Prompts users to create a file that doesn't currently exist. This flag automatically sets the cdlOFNPathMustExist and cdlOFNFileMustExist flags.

cdlOFNExplorer

&H80000

Uses the Explorer-like Open a File dialog box template.

cdlOFNExtensionDifferent

&H400

Indicates that the extension of the returned file name is different from the extension specified by the DefaultExt property. This flag isn't set if the DefaultExt property contains Null, if the extensions match, or if the file has no extension. You can inspect this flag's value after the dialog box is closed.

cdlOFNFileMustExist

&H1000

Lets users enter only names of existing files. If this flag is set and users enter an invalid file name, a warning is displayed. This flag automatically sets the cdlOFNPathMustExist flag.

cdlOFNHelpButton

&H10

Displays the dialog box's Help button.

cdlOFNHideReadOnly

&H4

Hides the Read Only check box.

cdlOFNLongNames

&H200000

Allows long file names.

cdlOFNNoChangeDir

&H8

Forces the dialog box to set the current directory to what it was when the dialog box was opened.

cdlOFNNoDereferenceLinks

&H100000

Disallows dereferencing of shell links (also known as shortcuts). By default, choosing a shell link causes it to be dereferenced by the shell.

cdlOFNNoLongNames

&H40000

Disallows long file names.

cdlOFNNoReadOnlyReturn

&H8000

Specifies that the returned file won't have the Read Only attribute set and won't be in a write-protected directory.

cdlOFNNoValidate

&H100

Allows invalid characters in the returned file name.

cdlOFNOverwritePrompt

&H2

Causes the Save As dialog box to generate a warning message box if the selected file already exists (users then choose whether to overwrite the existing file).

cdlOFNPathMustExist

&H800

Lets users enter only valid paths. If this flag is set and the users enter an invalid path, a warning message is displayed.

cdlOFNReadOnly

&H1

Selects the Read Only check box when the dialog box is created. This flag also indicates the state of the Read Only check box after the dialog box is closed.

cdlOFNShareAware

&H4000

Indicates that possible sharing violation errors will be ignored.

When you display an Open dialog box, you may want to specify a filter for the file-name extensions that the box shows. This determines the file types that the users see in the Files of Type text box, but they can override these extensions. To specify the filter, type the desired extensions in the Filter property. The file types appear in the Files of Type text box, separated by semicolons. The filter, if you specify one, is a string and must conform to this format:

"FilterDescrip1 | extension1 | FilterDescrip2 | extension2 | FilterDescrip3 | extension3"

For example, the following statement assigns a filter that shows only Word and Excel documents when the Open dialog box appears:

cmdFiles.Filter = "Word Docs (*.doc)|*.doc|

[ccc]Excel Docs (*.xls)|*.xls"

Don't confuse the file extensions in the description with the actual extensions in the filter. In the example, Word Docs (*.doc) is text to be displayed to users, and the *.doc following the first pipe symbol is the dialog box's first actual filtering instruction.

You can supply multiple filters by including multiple strings for the Filter property. If you specify more than one filter, you must set the FilterIndex property to the filter you want to use for the current Open dialog box. The first filter has a FilterIndex of 1; this number is incremented if you supply additional filters.

The common dialog box control's FileName property holds the selected file name after users close the dialog box.