OK, it is time we to dive into the gist of Windows 7 Libraries. This is the fourth post in a series of Windows 7 Libraries posts. So far, we discussed what Windows 7 Libraries are (Understanding Windows 7 Libraries) and we reviewed the internal structure of Libraries and how they integrate into the Windows Shell Libraries Under The Hood. In this post, we review the different programming models developers can use when integrating Libraries into their applications.
Libraries are the new entry points for user’s data In Windows 7. Libraries are an integral part of the Shell and are promoted across Windows in Windows Explorer, Start Menu, and Common File Dialog. Windows 7 Users will use Libraries in their day-to-day activities. As such, they will expect applications that are running on Windows 7 to work properly with their Libraries and provide the same user experience as Windows Explorer. It is therefore important that, as developers, we know how to work with libraries and make our applications Libraries-aware.
But before we start, I want to note that while most applications should just work fine with Windows 7 Libraries, there is an opportunity to tap into the Windows 7 Libraries environment to provide a richer user experiences.
Making an application Libraries-aware
One may wonder what would happen if “my application does not support Libraries.” Let’s imagine an application that, as part of its functionality, needs to save a file to the disk. The application prompts the user with the option to select a location for the file. The user may pick the Documents Library as his save "folder" since this is where the user usual goes when he needs to work on a document. However, if the application doesn’t recognize that the user selected the Documents Library and not a regular folder, the application may try to save to the Documents Library. This is a problem, since by now, as we already know, that Libraries are non –file system location and therefore can’t be address as regular folders.
A Library-aware application should include mechanisms for handling situations where users inadvertently try to pick libraries as if they are folder for either saving files to a Library or loading the contents of a Library. Furthermore, most applications allow users to interact with the file system as part of the application experience. An application should provide users with the same familiar entry points and UI offered by the Windows 7 Libraries. By including folders in a Library, users designate where their important data is stored, and thus applications should promote these locations by enabling Library browsing.
Developers have three integration points with Windows 7 that can help applications become Library-aware. You should review and become familiar with all three points and choose according to your needs.
- The most basic integration method is simply to use the new Common File Dialog (CFD) for picking files and folders while performing either save or load operations
- The second integration point offers applications the opportunity to Light Up on Windows 7 by enabling applications to select Libraries and consume Libraries contents.
- The last and most advanced integration point is to stay in sync with Library contents and directly manipulate Libraries by using the new IShellLibrary API that allows full control over libraries, including creating new libraries.
Let’s start by looking at the basic integration point, which can also be viewed as the bare minimum requirement for application compatibility when working with Windows 7 Libraries.
Using the Common File Dialog (CFD)
The good news is that Windows 7 Libraries are first class citizens in the CFD, allowing users to browse through Libraries, search Libraries, and even pick a specific Library as a save location, not an actual folder in the Library, but rather the Library itself!
But (there is always a but), we highly recommended that you use the new CFD interfaces that was introduced with Windows Vista, and not older or customized versions of the CFD. It is very important to note that the APIs for using the legacy CFD have not changed since Windows Vista, and XP to support application compatibility. However, the legacy version of the CFD (as is displayed in the next image) doesn’t directly support Libraries or the full new user experience offered in Windows 7.
Even if Libraries are presented in the right navigation pane, they require an extra click to save into one of the folders rather than just the Library. Also the legacy CFD doesn’t expose the search and arrangement views functionality that libraries offer. Finally, the legacy CFD doesn’t support the multiple selections of files across several folders, a basic functionality promoted in Libraries.
Therefore, it is important to use the proper APIs to show the correct CFD version. When using .NET, developers can use either the System.Windows.Forms.FileDialog or the Microsoft.Win32.FileDialog namespace. The latter uses the legacy version of the CFD; therefore, .NET developers should always use the WinForms namespace to show the new CFD. The following is a code snippet that prompts the user to choose a save location by showing the common save file dialog as shown in the next image.
System.Windows.Forms.SaveFileDialog _fd =
new System.Windows.Forms.SaveFileDialog();
_fd.Title = "Please choose a location to save your file";
_fd.FileName = "[Get Folder…]";
_fd.Filter = "Library|no.files";
if (_fd.ShowDialog() == System.Windows.Forms.DialogResult.OK)
{
string dir_path = System.IO.Path.GetDirectoryName(_fd.FileName);
if (dir_path != null && dir_path.Length > 0)
{
//this returns the path to the default save location
lblResult.Content = dir_path;
}
}
Native code developers should use the new family of IFileDialog native APIs (IFileDialog, IFileOpenDialog, IFileSaveDialog, IFileDialogCustomize, IFileDialogEvents, IFileDialogControlEvents) that are replacing the legacy GetOpenFileName and GetSaveFileName APIs from earlier Windows versions.
The Shell native APIs are COM-based; therefore, before using any COM object we must remember to initialize the COM object by calling CoCreateInstance. As an example, the following code snippet prompts the user to choose a Library or a folder to save the file to, by showing the common save file dialog.
*ppsi = NULL;
IFileSaveDialog *pfod;
hr = CoCreateInstance(
CLSID_FileSaveDialog,
NULL,
CLSCTX_INPROC,
IID_PPV_ARGS(&pfod));
if (SUCCEEDED(hr))
{
hr = pfod->SetOptions(FOS_PICKFOLDERS);
if (SUCCEEDED(hr))
{
hr = pfod->Show(hWndParent);
if (SUCCEEDED(hr))
{
hr = pfod->GetResult(ppsi);
}
}
pfod->Release();
}
After initializing the *pfod IFileSaveDialog variable, we set the dialog options to pick folders by passing the FOS_PICKFOLDERS flag to the IFileOpenDialog.SetOptions(). This code tells the Open dialog to enable the user to choose folders rather than files, and allows the user to choose a Library. If choosing a library, the CFD will then return the default save location folder that is associated with the chosen Library.
The two above code snippets are very simple and don’t show any new code; however, it is important to promote consistency among applications running on Windows 7 and supporting Windows 7 Libraries.
In the next post, we will (finally) show the new Windows 7 library API, as well as how to consume Library contents with the existing Shell APIs.