# cDialog class
{: .no_toc }

Shows the Windows Open, Save As and Browse For Folder dialogs, builds the file-type list of the first two, takes file paths apart, and opens a file in the program that Windows associates with it.

Properties set the options of a dialog before it is shown. **cDialog** works in 32-bit and in 64-bit programs. [**ShowOpen**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/ShowOpen.md), [**ShowSave**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/ShowSave.md) and [**ShowBrowseForFolder**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/ShowBrowseForFolder.md) show the dialogs and return the path that the user chose. A cancelled dialog returns an empty string. **ShowOpen** and **ShowSave** also store the path in [**FileName**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/FileName.md); several files chosen with [**MultiSelect**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/MultiSelect.md) come back as an array, and **FileName** is then empty.

```tb check_build
Dim dlg As New cDialog
Dim path As String

dlg.DialogTitle = "Open a text file"
dlg.SetCommonFilters
path = dlg.ShowOpen()

If Len(path) > 0 Then
    Debug.Print "Chosen: " & path
    Debug.Print "Name: " & dlg.GetFileName(path)
End If
```

The options are the members and flags of the Win32 structures that the dialogs take: [OPENFILENAME](https://learn.microsoft.com/en-us/windows/win32/api/commdlg/ns-commdlg-openfilenamew) for **ShowOpen** (`GetOpenFileNameW`) and **ShowSave** (`GetSaveFileNameW`), and [BROWSEINFO](https://learn.microsoft.com/en-us/windows/win32/api/shlobj_core/ns-shlobj_core-browseinfow) for **ShowBrowseForFolder** (`SHBrowseForFolder`). Each property page names the flag it sets and the dialogs in which it takes effect, and the table [below](#which-dialog-uses-which-property) lists them all.

> [!NOTE] 1.1.0.0
> The property names follow VB6's **CommonDialog** control, but **cDialog** is a class with a smaller set of members. It has no **Flags** property (each option is a **Boolean** property of its own), no **FilterIndex** (the first filter is always selected, and the filter that the user chose is not reported), no **CancelError** (a cancelled dialog returns an empty string), no **FileTitle** or **MaxFileSize**, and no owner window. **InitialDir** is the control's **InitDir**. **ShowOpen** returns the file name, as well as storing it in **FileName**, and there is no Color, Font or Print dialog in this class (the package has a class for each of them, listed on its [landing page](/tB/Packages/Contributed/TBMANLIB_Dialog/index.md)). The [**cDialogEx**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialogEx.md) class of this package has a **FilterIndex** and an owner window. The [**CommonDialog**](/tB/Packages/Contributed/VBComDlg/CommonDialog.md) class of the VBComDlg package has **Flags**, **FilterIndex**, **CancelError**, **FileTitle**, **MaxFileSize** and those dialogs.

## Defaults

A new **cDialog** starts with these values, and [**Reset**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/Reset.md) restores them.

| Property | Starting value |
|---|---|
| [**DialogTitle**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/DialogTitle.md), [**InitialDir**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/InitialDir.md), [**DefaultExt**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/DefaultExt.md), [**FileName**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/FileName.md), [**Filter**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/Filter.md) | An empty string |
| [**MultiSelect**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/MultiSelect.md), [**ReadOnly**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/ReadOnly.md), [**NoChangeDir**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/NoChangeDir.md), [**CreatePrompt**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/CreatePrompt.md) | **False** |
| [**OverwritePrompt**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/OverwritePrompt.md), [**PathMustExist**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/PathMustExist.md), [**FileMustExist**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/FileMustExist.md), [**HideReadOnly**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/HideReadOnly.md), [**NewDialogStyle**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/NewDialogStyle.md) | **True** |

```tb check_build check_run
Dim dlg As New cDialog
Debug.Print dlg.MultiSelect      ' False
Debug.Print dlg.FileMustExist    ' True
Debug.Print dlg.NewDialogStyle   ' True
Debug.Print Len(dlg.Filter)      ' 0
```

## Which dialog uses which property

*yes* means that the class passes the value to Windows for that dialog. A property marked *ignored* is stored and returned, and the dialog does not receive it. **ShowOpen** and **ShowSave** read and write [**FileName**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/FileName.md); **ShowBrowseForFolder** writes [**InitialDir**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/InitialDir.md) when the user chooses a folder, and does not read it.

| Property | Win32 member or flag | ShowOpen | ShowSave | ShowBrowseForFolder |
|---|---|---|---|---|
| [**DialogTitle**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/DialogTitle.md) | `lpstrTitle`, `lpszTitle` | yes | yes | yes |
| [**InitialDir**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/InitialDir.md) | `lpstrInitialDir` | yes | yes | written, not read |
| [**DefaultExt**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/DefaultExt.md) | `lpstrDefExt` | yes | yes | ignored |
| [**FileName**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/FileName.md) | `lpstrFile` | read and written | read and written | ignored |
| [**Filter**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/Filter.md) | `lpstrFilter` | yes | yes | ignored |
| [**MultiSelect**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/MultiSelect.md) | `OFN_ALLOWMULTISELECT` | yes | ignored | ignored |
| [**OverwritePrompt**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/OverwritePrompt.md) | `OFN_OVERWRITEPROMPT` | yes | yes | ignored |
| [**PathMustExist**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/PathMustExist.md) | `OFN_PATHMUSTEXIST` | yes | yes | ignored |
| [**FileMustExist**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/FileMustExist.md) | `OFN_FILEMUSTEXIST` | yes | ignored | ignored |
| [**HideReadOnly**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/HideReadOnly.md) | `OFN_HIDEREADONLY` | yes | yes | ignored |
| [**ReadOnly**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/ReadOnly.md) | `OFN_READONLY` | yes | ignored | ignored |
| [**NoChangeDir**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/NoChangeDir.md) | `OFN_NOCHANGEDIR` | yes | yes | ignored |
| [**CreatePrompt**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/CreatePrompt.md) | `OFN_CREATEPROMPT` | yes | ignored | ignored |
| [**NewDialogStyle**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/NewDialogStyle.md) | `BIF_USENEWUI` | ignored | ignored | yes |

Windows documents some of these flags for one kind of dialog only. `OFN_OVERWRITEPROMPT` is documented for Save As, and `OFN_FILEMUSTEXIST` for Open. The class passes **OverwritePrompt** to **ShowOpen** all the same.

## Settings without a property

Some settings cannot be changed.

- **ShowOpen** and **ShowSave** always set `OFN_LONGNAMES`, `OFN_EXPLORER` and `OFN_ENABLESIZING`. Windows documents the effect of `OFN_LONGNAMES` and `OFN_ENABLESIZING` for old-style dialogs, hooks and templates, none of which the class uses. `OFN_EXPLORER` selects the layout of the buffer that a multiple selection returns ([**MultiSelect**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/MultiSelect.md)).
- **ShowOpen** and **ShowSave** always select the first pair of the [**Filter**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/Filter.md) list (`nFilterIndex` is 1) and do not report the pair that the user chose.
- **ShowOpen** and **ShowSave** pass no hook procedure, no custom template and no custom filter. The flags that the dialog returns are not read, so the choice of *Open as read-only* (see [**HideReadOnly**](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/HideReadOnly.md)) is not available after the dialog closes.
- **ShowBrowseForFolder** always sets `BIF_RETURNONLYFSDIRS`, so only a folder of the file system can be chosen, and passes no root folder and no callback.
- No dialog has an owner window: the class passes 0 for `hwndOwner` in both structures.

## Properties

- [CreatePrompt](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/CreatePrompt.md) -- asks before the Open dialog accepts a file that does not exist
- [DefaultExt](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/DefaultExt.md) -- the extension that Windows adds to a file name typed without one
- [DialogTitle](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/DialogTitle.md) -- the text that the dialogs show as their title
- [FileMustExist](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/FileMustExist.md) -- lets the Open dialog accept only the name of an existing file
- [FileName](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/FileName.md) -- the file name shown when a dialog opens, and the path that the last Open or Save As dialog returned
- [Filter](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/Filter.md) -- the file-type list of the Open and Save As dialogs
- [HideReadOnly](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/HideReadOnly.md) -- hides the read-only choice of the Open dialog
- [InitialDir](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/InitialDir.md) -- the folder in which the Open and Save As dialogs start
- [MultiSelect](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/MultiSelect.md) -- lets the Open dialog select more than one file
- [NewDialogStyle](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/NewDialogStyle.md) -- selects the resizable Browse For Folder dialog with an edit box
- [NoChangeDir](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/NoChangeDir.md) -- keeps the current folder of the program as it was
- [OverwritePrompt](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/OverwritePrompt.md) -- asks before the Save As dialog accepts the name of an existing file
- [PathMustExist](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/PathMustExist.md) -- lets the Open and Save As dialogs accept only paths that exist
- [ReadOnly](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/ReadOnly.md) -- sets the read-only flag of the Open dialog, which has no visible effect

## Methods

- [AddFilter](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/AddFilter.md) -- appends a description and a pattern to the filter
- [ClearFilter](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/ClearFilter.md) -- empties the filter
- [GetFileExtension](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/GetFileExtension.md) -- returns the part of a path from its last period
- [GetFileName](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/GetFileName.md) -- returns the part of a path after its last backslash
- [GetFileNameWithoutExt](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/GetFileNameWithoutExt.md) -- returns the file name of a path without its extension
- [GetFilePath](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/GetFilePath.md) -- returns the part of a path before its last backslash
- [OpenFile](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/OpenFile.md) -- runs a shell verb, by default `open`, on a file or a program
- [PathCombine](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/PathCombine.md) -- joins two path parts with one backslash
- [Reset](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/Reset.md) -- restores every property to its starting value
- [SelectAndOpenFile](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/SelectAndOpenFile.md) -- shows the Open dialog and opens the chosen file or files
- [SelectFiles](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/SelectFiles.md) -- shows the Open dialog and returns the chosen files as a collection
- [SetCodeFilters](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/SetCodeFilters.md) -- replaces the filter with one for source code files
- [SetCommonFilters](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/SetCommonFilters.md) -- replaces the filter with Text Files and All Files
- [SetDocumentFilters](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/SetDocumentFilters.md) -- replaces the filter with one for office documents
- [SetImageFilters](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/SetImageFilters.md) -- replaces the filter with one for image files
- [ShowBrowseForFolder](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/ShowBrowseForFolder.md) -- shows the Browse For Folder dialog and returns the chosen folder
- [ShowOpen](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/ShowOpen.md) -- shows the Open dialog and returns the chosen file
- [ShowSave](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialog/ShowSave.md) -- shows the Save As dialog and returns the chosen file name

## See Also

- [TBMANLIB_Dialog](/tB/Packages/Contributed/TBMANLIB_Dialog/index.md) package -- overview
- [cDialogEx](/tB/Packages/Contributed/TBMANLIB_Dialog/cDialogEx.md) class -- the same dialogs in the style of Windows Vista and later
- [CommonDialog](/tB/Packages/Contributed/VBComDlg/CommonDialog.md) class -- the fuller alternative, with flags, a filter index, cancel errors and the Color, Font and Print dialogs
