Developing with Common File Dialogs
Developing with Common File Dialogs
Windows Vista® supplies an updated version of the Common File Dialog to meet the needs of the majority of developers. Not only is it powerful, but it is designed to support customization and extensibility. The Windows Vista Shell provides access to these new file dialogs through IFileDialog and related interfaces. The .NET Framework 3.0 applications for Windows Vista can access this functionality through interoperability support in the Windows SDK. For more information, see "Interoperability & Migration" in the MSDN Library.
Using a Common File Dialog Object
Applications that need to create an instance of the Common File Dialog must obtain one of the following interfaces:
IFileDiaglog—the most generic interface, and the parent of the next two.
IFileOpenDialog—extends IFileDialog to allow applications to control aspects particular to open operations, such as selecting multiple items.
IFileSaveDialog—handles Save As operations and works with metadata.
All file dialogs are modal. Methods in these classes enable developers to get and set UI elements of the dialog (such as SetTitle, SetDefaultFolder, SetFileTypes, and GetCurrentSelection) that are typical when using dialog boxes. Many of the standardized behaviors of the dialog can be controlled through the GetOptions and SetOptions methods by using a set of bit flags. These options can only be set before a dialog is displayed; otherwise the SetOptions method returns an error. The final user selection can be retrieved with the GetResult method or, by using IFileOpenDialog when the FOS_ALLOWMULTISELECT option is enabled.
Working with File Dialog Events
Although instantiating a file dialog object provides the primary UI and functionality of the corresponding Common File Dialog, in some clients practical use of these dialogs requires developers to access events generated by dialog box operations or the individual controls of the dialog box.
The IFileDialogEvents interface provides methods that signal user actions and methods that allow notification of events within a common file dialog. The event members include: OnFileOk, OnFolderChange, OnFolderChanging, OnOverwrite, OnSelectionChange, OnShareViolation, and OnTypeChange. Although most clients do not need to implement the OnFileOk method, at minimum, the method must be implemented to retrieve the results of the user operation. The IFileDialog::GetResult() is the best way for clients to get the result of the dialog. For more information, see "IFileDialog Interface" in the MSDN Library at https://msdn2.microsoft.com/en-us/library/default.aspx.
The IFileDialogControlEvents interface provides methods that enable an application to be notified of events related to controls that the application has added to a common file dialog. The event members include: OnButtonClicked, OnCheckButtonToggled, OnControlActivating, and OnItemSelected.
These interfaces are implemented by the client application that displays the common dialog, and write access to these interfaces is acquired through QI on the interface passed to the Advise() method. If both interfaces are required, then they should be implemented in the same client class, for example:
private class NativeDialogEventSink : IFileDialogEvents, IFileDialogControlEvents
For events that are not of interest, the corresponding implementation method should return E_NOTIMPL. An instance of this event sink class is associated to the common dialog box through the Advise method of the dialog interface (and can be subsequently removed through Unadvise).
Customizing a Common File Dialog
In addition to the UI and behavioral customizations that can be made through the primary dialog interface and the event interfaces, the IFileDialogCustomize interface provided enables developers to add additional common controls to the dialog above or below the set of standard controls for that dialog box. These controls include PushButton, ComboBox, EditBox, CheckBox, and RadioButtonList. The following limitations apply to these developer-added controls:
Controls are added to or removed from the dialog before the dialog is shown. Once the dialog is displayed, the controls are set, but they can still be hidden or disabled at any time.
Controls are ordered automatically on the dialog in the order in which they are added and cannot be reordered.
Other attributes of the control can be changed at any time, for example, label text, check state for check boxes, and so on can be changed at any time.
Items in a container control such items as menus, lists and combo boxes have slightly different rules:
The order that items appear in a container is the order in which they were added.
Items can be added or removed at anytime; however, only their enabled and visible states can be changed. Therefore to change another attribute, such as the text, the item would have to be removed, and then re-added.
With the exception of menus, all container controls always have an item selected by default.
Identifiers (IDs) are scoped to the parent control.
The behavior of the Common File Dialog and the controls used to customize it are agnostic of any particular user interface framework. For more information, see "Shell Interfaces" in the Windows SDK. The SDK also supplies a set of examples—CommonFileDialog.cs, CommonSaveFileDialog.cs, and CommonSaveOpenDialog.cs—that developers can use as templates for implementing Common File Dialogs.