Archives
-
Windows Vista for Developers – Part 6 – The New File Dialogs
Just as Aero wizards enable a better user experience compared to traditional wizards and task dialogs enable a better user experience compared to the age-old message box, so the new file dialogs provide a fresh new look and a welcome replacement for the aged GetOpenFileName and GetSaveFileName functions. Not only do the new file dialogs provide a very consistent appearance relative to the Windows Vista shell but they are also exposed through a brand new COM interface, simplifying their use and opening the door for future improvements.
In this part 6 of the Windows Vista for Developers series, we are looking at the new file dialogs API that is exposed through IFileDialog and friends. We’ll first examine the various interfaces and then take a look at a C++ class template that simplifies their use considerably. Before we dive into the code let’s take a look at appearances to see what benefit users gain from this change.
User Experience
The following window clipping presents the traditional open dialog created using the GetOpenFileName function:
Most users are familiar with this dialog, however users who are learning to use Windows for the first time on Windows Vista or even users who have just become used to Windows Vista may find it a bit frustrating since it doesn’t have any consistency with the Windows Vista shell. The way folders are navigated is different to Windows Explorer and many of the tools that users might depend on such as the built-in search capabilities are not present in the traditional file dialogs. The following image presents the same folder in Windows Explorer:
Now look at the new open dialog introduced with Windows Vista:
Notice how it looks almost exactly the same with the exception of the lower panel. This is the kind of consistency that makes working with Windows a pleasure. On that note, let’s look at some code to see what’s involved with adopting the new file dialogs in your own applications.
The Old Way
As a point of reference, let’s quickly recap what most Windows developers (using C++) have traditionally used to construct a file dialog. Most developers avoid using the GetOpenFileName and GetSaveFileName functions and instead used MFC or WTL’s CFileDialog class. Here is an example using WTL:
class OldSampleDialog : public CFileDialog
{
public:
OldSampleDialog() :
CFileDialog(true) // open dialog
{
// TODO: Customize dialog with m_ofn
}
};
OldSampleDialog dialog;
INT_PTR result = dialog.DoModal();
Neither MFC nor WTL support the new file dialogs at the time of writing but one of the goals of this article is to reach a comparable level of conciseness with a little help from C++. But first let’s examine the new API.
The New API
As I hinted at before, the new file dialogs are exposed through a set of COM interfaces. Here are the main interfaces that you should familiarize yourself with.
IFileOpenDialog – Implemented by the FileOpenDialog COM class and provides methods specific to open dialogs.
IFileSaveDialog – Implemented by the FileSaveDialog COM class and provides methods specific to save dialogs.
IFileDialog – Inherited by both IFileOpenDialog and IFileSaveDialog and provides most of the methods for customizing and interacting with a dialog.
IModalWindow – Inherited by IFileDialog and provides the Show method.
IFileDialogCustomize – Implemented by the FileOpenDialog and FileSaveDialog COM classes and provides methods to add controls to a dialog.
IFileDialogEvents – Implemented by an application to allow notification of events within a file dialog.
IFileDialogControlEvents – Implemented by an application to allow notification of events related to controls added by an application to a file dialog.
There are some not entirely new interfaces, such as IShellItem, that you may also need to use. I’ll talk about those a little later in this article.
You can use the CComPtr class template to create an open dialog as follows:
CComPtr<IFileOpenDialog> dialog;
HRESULT result = dialog.CoCreateInstance(__uuidof(FileOpenDialog));
Typically you will simply customize the dialog using the methods inherited from IFileDialog. We will explore this in the following sections. For further customization you can query for the IFileDialogCustomize interface as follows:
CComPtr<IFileDialogCustomize> customize;
HRESULT result = dialog.QueryInterface(&customize);
Once you’re ready to display the dialog you can do so using the Show method:
HRESULT result = dialog->Show(parentWindow);
The Show method will block until the dialog is dismissed.
File Types
You should be relieved to know that IFileDialog has not adopted the use of REG_MULTI_SZ strings from OPENFILENAME and instead uses the more approachable COMDLG_FILTERSPEC structure to declare the file types that a dialog can open or save:
COMDLG_FILTERSPEC fileTypes[] =
{
{ L"Text Documents", L"*.txt" },
{ L"All Files", L"*.*" }
};
HRESULT result = dialog->SetFileTypes(_countof(fileTypes),
fileTypes);
This model simplifies constructing the list of file types dynamically and also reduces the headaches involved with using a string table. The following example demonstrates how you might use a string table to simplify localization:
CString textName;
VERIFY(textName.LoadString(IDS_FILTER_TEXT_NAME));
CString textPattern;
VERIFY(textPattern.LoadString(IDS_FILTER_TEXT_PATTERN));
CString allName;
VERIFY(allName.LoadString(IDS_FILTER_ALL_NAME));
CString allPattern;
VERIFY(allPattern.LoadString(IDS_FILTER_ALL_PATTERN));
COMDLG_FILTERSPEC fileTypes[] =
{
{ textName, textPattern },
{ allName, allPattern }
};
The SetFileTypeIndex method allows you to indicate which file type appears selected in the dialog. Keep in mind that this is a one-based index rather than the usual zero-based index familiar to C and C++ developers.
HRESULT result = dialog->SetFileTypeIndex(2);
SetFileTypeIndex can be called before the dialog is displayed as well as while the dialog is open to change the selection programmatically. The GetFileTypeIndex method on the other hand can only be called while the dialog is open or after it has closed.
UINT index = 0;
HRESULT result = dialog->GetFileTypeIndex(&index);
Options
The file dialog offers a long list of options that you can control to affect the appearance and behavior of the dialog. The options are declared as flags packed into a DWORD. The options currently defined can be retrieved using the GetOptions method and changes can be made using the SetOptions method. Unless you know exactly which options you need and which you don’t, it’s generally a good idea to call GetOptions first and then modify the resulting DWORD before calling SetOptions again. Doing so will preserve any default options that may already be set depending on the type of dialog.
The following example shows how you can force the preview pane to be displayed:
DWORD options = 0;
HRESULT result = dialog->GetOptions(&options);
if (SUCCEEDED(result))
{
options |= FOS_FORCEPREVIEWPANEON;
result = dialog->SetOptions(options);
}
The user can of course manually show or hide the preview pane using the Organize drop-down menu from the toolbar.
The documentation for the SetOptions method provides a complete list of options that you can control.
Labels and Edit Controls
A few of the static text elements on the dialog can be changed from their defaults.
The SetTitle method sets the dialog’s title. The SetOkButtonLabel method sets the text for the dialog’s default button. The SetFileNameLabel method sets the text for the label appearing next to the file name edit control.
You can also get and set the text that appears in the file name edit control using the SetFileName and GetFileName methods.
Shell Items
Quite a few of the interface methods used for controlling the file dialogs use shell items to refer to folders instead of file system paths. The reason for this is so that the dialog can communicate information about not only file system folders but also other virtual folders that you find in the shell such as the control panel or the “Computer” folder. To get a good feel for all the well-known folders on your computer, both virtual and file system-based, check out my Known Folders Browser.
Shell items are very flexible and provide a great way to interact with many of the other shell APIs that use IShellItem to represent shell items. Of course if all you need is to specify a file system path then you’ll need a way to convert a path to a shell item. Fortunately Windows Vista introduces the extremely handy SHCreateItemFromParsingName function to do just this:
CComPtr<IShellItem> shellItem;
HRESULT result = ::SHCreateItemFromParsingName(L"D:\\SampleFolder",
0,
IID_IShellItem,
reinterpret_cast<void**>(&shellItem));
Similarly if you are handed a shell item and need to determine the file system path it represents you can use the GetDisplayName method as follows:
AutoTaskMemory<WCHAR> buffer;
HRESULT result = shellItem->GetDisplayName(SIGDN_FILESYSPATH,
&buffer.p);
AutoTaskMemory is just a simple class template I use. It calls the CoTaskMemFree function in its destructor to free the memory allocated by the GetDisplayName function. Keep in mind that a given shell item might not actually refer to a file system item. For example if you pass “::{ED228FDF-9EA8-4870-83b1-96b02CFE0D52}” to SHCreateItemFromParsingName you will get the shell item referring to “Games” virtual folder. Since this is not a file system folder, requesting its file system path with the GetDisplayName method will fail.
With that extremely light introduction to shell items out of the way let’s take a look at how shell items are used with file dialogs. The IFileDialog interface uses shell items to identify folders and selections. For example, you can set the folder that is initially displayed as follows:
CString path = // load path...
CComPtr<IShellItem> shellItem;
HRESULT result = ::SHCreateItemFromParsingName(path,
0,
IID_IShellItem,
reinterpret_cast<void**>(&shellItem));
if (SUCCEEDED(result))
{
result = m_dialog->SetFolder(shellItem);
}
The SetFolder method can also be called while the dialog is open, causing the dialog to navigate to the specified folder. The GetFolder method on the other hand can be used to determine the folder that will be initially selected when the dialog is opened or, if the dialog is already open, the folder that is currently displayed. A related method is GetCurrentSelection which specifically indicates the user’s current selection within the displayed folder. So if you need to determine the exact file that the user has selected while the dialog is open then GetCurrentSelection will give you the shell item describing it.
Another place (no pun intended) where shell items come in handy is to add links to the “Favorite Links” section. Consider the following example:
HRESULT result = m_dialog->AddPlace(shellItem,
FDAP_TOP);
Notice the “Window Clippings” link at the top of the “Favorite Links” list. This link was added because the shell item I provided to the AddPlace method referred to a folder on my computer where I store my window clippings.
Adding Controls
The developers that created the new dialogs realized that no matter how cool they make the new file dialog, software vendors are inevitably going to want to customize it. Microsoft has embraced this notion and added a very rich interface for extending the standard dialog with application-specific controls.
I’ve already described how you can get a reference to the IFileDialogCustomize interface by calling the QueryInterface method. The documentation for IFileDialogCustomize is straightforward so you shouldn’t have a problem making use of it. There are methods for adding buttons, combo boxes, check boxes, edit boxes and more. The interface is also used to update and query the controls while the dialog is open. The following example illustrates how you can add a text box to allow the user to specify the author of the document to be saved:
COM_VERIFY(customize->StartVisualGroup(100, L"Author:"));
COM_VERIFY(customize->AddEditBox(101, L""));
COM_VERIFY(customize->EndVisualGroup());
WCHAR buffer[256] = { 0 };
ULONG size = _countof(buffer);
if (::GetUserName(buffer,
&size))
{
COM_VERIFY(customize->SetEditBoxText(101,
buffer));
}
As you can see, although the IFileDialogCustomize interface allows you to add controls and even visually group them, it does not allow you full control over placement. This allows the dialog to provide the most appropriate layout even as it evolves in future releases.
Events
Two interfaces are defined for applications to implement in order to receive notifications from a dialog. The IFileDialogEvents interface can be implemented if you wish to be notified about navigation events and as well as folder and selection changes. The IFileDialogControlEvents interface should be implemented if you’ve added controls of your own to the dialog and wish to respond in some way when the user interacts with those controls.
To receive events you need to do a few things. First you need to implement the IFileDialogEvents interface and optionally the IFileDialogControlEvents interface. You then need to call the IFileDialog::Advise method with a pointer to your IFileDialogEvents implementation. The dialog will query the IFileDialogEvents interface pointer for IFileDialogControlEvents as needed.
CComPtr<IFileDialogEvents> events = // your implementation
DWORD cookie = 0;
HRESULT result = dialog->Advise(events,
&cookie);
The file dialog will store a reference to your implementation until the dialog is destroyed or sooner if you call the dialog’s Unadvise method.
HRESULT result = dialog->Unadvise(cookie);
Open Dialogs
So far we have discussed the file dialog in general. In this section we are taking a look at the open dialog specifically and in the next section we’ll take a look at what the save dialog offers.
Both the open and save dialogs inherit the GetResult method from IFileDialog. This method is useful in determining the choice that the user made. It can be called once the dialog has closed with a success code. It can also be called in your implementation of the IFileDialogEvents::OnFileOk method before the dialog is closed. You should however only call the GetResult method if the dialog is configured to accept a single selection. This is controlled with the FOS_ALLOWMULTISELECT option.
CComPtr<IShellItem> shellItem;
HRESULT result = dialog->GetResult(&shellItem);
If multiple selections are allowed you need to use the GetResults method provided by the IFileOpenDialog interface. It returns a pointer to the IShellItemArray interface that is new to Windows Vista. As its name implies, it provides access to an array of shell items. The following example illustrates how you can enumerate the results:
CComPtr<IShellItemArray> shellItemArray;
HRESULT result = dialog->GetResults(&shellItemArray);
if (SUCCEEDED(result))
{
DWORD count = 0;
result = shellItemArray->GetCount(&count);
if (SUCCEEDED(result))
{
for (DWORD index = 0; index < count; ++index)
{
CComPtr<IShellItem> shellItem;
if (SUCCEEDED(shellItemArray->GetItemAt(index,
&shellItem)))
{
AutoTaskMemory<WCHAR> name;
if (SUCCEEDED(shellItem->GetDisplayName(SIGDN_NORMALDISPLAY,
&name.p)))
{
TRACE(L"%s\n", name.p);
}
}
}
}
}
If you need to determine the current selection while the dialog is open then you can use the GetSelectedItems method, which also returns a shell item array.
Save Dialogs
The save dialog contains a few unique features of its own. The SetSaveAsItem method can be used to select an initial entry:
CComPtr<IShellItem> shellItem = // load shell item
HRESULT result = dialog->SetSaveAsItem(shellItem);
Methods are also provided to interface with a property store, however that is beyond the scope of this article. This may be covered in a future article in the series so stay tuned.
The FileDialog C++ Class Template
As nice as it is to have the file dialogs exposed through COM interfaces, providing a much richer programming model and more flexible extensibility, in many cases a simple solution is desired that does not involve writing a lot of code and implementing COM interfaces. To that end, I wrote the FileDialog class template. It implements both COM event interfaces used by the file dialogs and provides a very simple mechanism for adding the new file dialogs to your applications:
template <typename Interface, REFCLSID ClassId>
class FileDialog :
protected CWindow,
private IFileDialogEvents,
private IFileDialogControlEvents
{
public:
__checkReturn HRESULT Load();
HRESULT DoModal(HWND parent = ::GetActiveWindow());
_RestrictedFileDialogPointer<Interface>* operator->() const;
protected:
// ...
The following type definitions are also provided:
typedef FileDialog<IFileSaveDialog, __uuidof(FileSaveDialog)> FileSaveDialog;
typedef FileDialog<IFileOpenDialog, __uuidof(FileOpenDialog)> FileOpenDialog;
With only three public members it is very approachable but opens up tremendous power as needed. The Load method creates the underlying dialog object and notifies the dialog that it would like to receive event notifications. The overloaded operator allows direct access to the underlying dialog object through the appropriate interface. The traditional DoModal method makes the blocking call to the dialog’s Show method to display it. Here is an example:
Kerr::FileOpenDialog dialog;
HRESULT result = dialog.Load();
if (SUCCEEDED(result))
{
COMDLG_FILTERSPEC fileTypes[] =
{
{ L"Text Documents", L"*.txt" },
{ L"All Files", L"*.*" }
};
result = dialog->SetFileTypes(_countof(fileTypes),
fileTypes);
if (SUCCEEDED(result))
{
result = dialog.DoModal();
if (SUCCEEDED(result))
{
CComPtr<IShellItem> selection;
result = dialog->GetResult(&selection);
// use selection somehow
}
}
}
The FileDialog class template also provides the following protected virtual methods that derived classes can override to handle specific dialog events:
virtual bool OnFileOk(); // Return true to accept the result and close the dialog
virtual bool OnFolderChanging(IShellItem* shellItem); // Return true to allow the folder change
virtual void OnFolderChange(IShellItem* shellItem);
virtual void OnSelectionChange();
virtual FDE_SHAREVIOLATION_RESPONSE OnShareViolation(IShellItem* shellItem);
virtual void OnTypeChange(UINT index);
virtual FDE_OVERWRITE_RESPONSE OnOverwrite(IShellItem* shellItem);
FileDialog internally implements the IFileDialogEvents interface methods and forwards events to the methods listed above, simplifying the use of events considerably. Consider the following example:
class SampleDialog : public Kerr::FileOpenDialog
{
public:
SampleDialog()
{
COM_VERIFY(Load());
}
virtual void OnSelectionChange() override
{
CComPtr<IShellItem> selection;
HRESULT result = m_dialog->GetCurrentSelection(&selection);
if (SUCCEEDED(result))
{
AutoTaskMemory<WCHAR> name;
if (SUCCEEDED(selection->GetDisplayName(SIGDN_NORMALDISPLAY,
&name.p)))
{
TRACE(L"%s\n", name.p);
}
}
}
};
SampleDialog dialog;
dialog.DoModal();
The previous sample dialog will trace the name of the shell item every time the user changes the selection.
FileDialog also provides the following protected virtual methods for handling control-specific events:
virtual void OnItemSelected(DWORD controlId,
DWORD itemId);
virtual void OnButtonClicked(DWORD controlId);
virtual void OnCheckButtonToggled(DWORD controlId,
bool checked);
virtual void OnControlActivating(DWORD controlId);
FileDialog internally implements the IFileDialogControlEvents interface methods and forwards events to the methods listed above, again simplifying the use of these events considerably. Consider the following example:
class SampleDialog : public Kerr::FileOpenDialog
{
public:
SampleDialog()
{
COM_VERIFY(Load());
COM_VERIFY(m_customize->AddPushButton(100, L"I'm Feeling Lucky"));
}
virtual void OnButtonClicked(DWORD controlId) override
{
ASSERT(100 == controlId);
// Handle event...
}
};
FileDialog also automatically retrieves the dialog’s window handle through the IOleWindow implementation and makes that available through the inherited CWindow base class from ATL. Derived classes can use this to create a popup window or interact with the dialog window in some way that isn’t directly provided by the dialog’s COM interfaces.
Conclusion
There is even more that you can do with the new file dialogs in Windows Vista but hopefully this introduction will give you enough to get you going.
This article doesn’t include a sample application but you can download the FileDialog class discussed in the previous section for use in your own applications. You can then explore the FileDialog class as well as Windows Vista’s new file dialogs in more detail in your own time.
Stay tuned for part 7. -
Known Folders Browser 1.0 (for Vista and Beyond)
