Libraries under the Hood

Now that we have a better understanding of what libraries represent and how users as well as developers can benefit from them, let’s examine how libraries work and how they integrate into the Windows Shell.

In some ways, a library is similar to a folder. From a user’s point of view, a library looks and behaves just like a regular folder. For example, when you open a library, one or more files are shown. However, unlike a folder, a library gathers files stored in several locations a subtle but important difference. Libraries monitor folders that contain files and enable users to access and arrange these files in different ways, but libraries don’t really store users’ files. A user can save an image directly to the Pictures library, but as we already mentioned, the Pictures library, or any other given library, is not a real folder so where will this picture be saved? The default save location is the user’s pictures folder, also known as My Pictures, which is part of the user profile. The user has full control over the default save location as well as the other locations that are part of a library.

Working with Libraries

As we’ve seen so far, libraries are the new entry points for user data in Windows 7. Libraries are also an integral part of the Windows Shell and are promoted across Windows 7 in Windows Explorer, the Start menu, and the Common File Dialog. Windows 7 users will use libraries in their day-to-day activities; they’ll expect applications running on Windows 7 to work properly with libraries and to have the same user experience. Therefore, as developers, you need to know how to work with libraries to make your applications library aware.

Make Your Application Library Aware

Let’s start by examining what happens if a given application doesn’t properly support Windows 7 libraries. Let’s assume an application needs to save a file to the local hard drive and prompts the user to select a location there. As part of her Windows 7 experience, the user can select the Documents library as her save destination because this is where she stores all her documents. But if the application fails to recognize that the Documents library is not a real folder and tries to perform a save operation to the Documents library location, the application will most likely fail to perform the task, because libraries are a non–file system location.

A library-aware application should be aware that users might choose a library as a save location and understand that a library is not a real folder, and it should act accordingly. Furthermore, most applications allow users to interact with the file system in their experience. An application should provide users with the same familiar entry points offered by libraries. By including folder locations in a library, a user designates where her important data lives, and thus applications should promote these locations by enabling library browsing. As developers, we have several integration points with Windows 7 that can help applications become library aware:

Use the Common File Dialog. The most basic integration option, and probably the easiest to implement, is the Common File Dialog (CFD) for picking files and folders when performing save or load operations. In the next section, “Using the Right Common File Dialog to Work with Libraries,” we describe in great detail which CFD is best to use and the specific API, but for now CFD will do. Suppose that in your application you are using the CFD to prompt the user to choose a location, pick a folder, and save the file, and the user selects the Documents library. The CFD returns the default save location, which is a valid file system path that you can work with and to which you can save the file. If you are using the CFD to open files, the user can choose a file from a library, and the system returns the fully qualified file system path to your application to work with.

Select and consume library content. The second integration option is to enable applications to select and consume library content. Imagine the case of a slideshow application that presents pictures. By using libraries, the user essentially tells the system that his important pictures are stored in the Pictures library. Therefore, the application can simply be pointed directly to the Pictures library to show the user’s entire pictures collection. From the development point of view, such an application will not need to maintain a separate configuration file or database of pictures, because it can rely on the Pictures library, which simplifies development efforts.

Manipulate Libraries. The last and most advanced integration option is the new IShellLibrary API, which you can use to stay in sync with the contents of a given library’s contents and to directly manipulate libraries. The IShellLibrary API gives you full control over libraries, including enabling you to create new libraries and control the different properties discussed earlier in this article. By integrating directly with libraries, applications can drive consistency with the Windows Explorer UI in Windows 7 and provide the best user experience.

Using the Right Common File Dialog to Work with Libraries

Windows always offered the CFD that developers use in their applications to prompt users to open and save files. The CFD displays a dialog box from which the user can select a file or folder by navigating through the local machine folder hierarchy as well as that of remote servers. The CFD is widely known and used by the majority of Microsoft software products as well as by a large number of third-party software applications. Windows 7 libraries are “firstclass citizens” in the CFD, a status that allows users to browse through libraries, search libraries, and even pick an actual library rather than a specific folder in the library as a save location.

This behavior is the out-of-the-box experience for users and applications using the new CFD. It’s highly recommended that you use the right version of Windows CFD rather than a custom proprietary dialog to stay consistent with Windows 7 Libraries.

There are two versions of the CFD, so even if a given application is using a CFD, it still needs to use the proper version. The most recent version was introduced in Windows Vista and updated in Windows 7 to support Libraries natively. Note that to support backward compatibility, the APIs for using the CFD have not changed since Windows Vista, and therefore applications that are already using the CFD will enjoy library integration in Windows 7. However, the legacy version of the CFD, shown in the next image, doesn’t support libraries.

Even if libraries are present, as indicated by the Libraries icon in the left navigation pane, a user can’t choose a library, such as the Documents library, as the location to save a file. Note that the Documents library is highlighted but the right bottom button caption is Open and not Save. The user will have to drill into the Documents library to choose a specific folder to save the file. The legacy CFD doesn’t expose the search and sort functionalities that libraries offer. The legacy CFD also doesn’t support selection across several folders, the basic functionality promoted in libraries.

It’s important to use the proper APIs to show the correct version of CFD. There is a great article on MSDN that explains in details the new API’s introduced in Windows Vista (http://msdn.microsoft.com/en-us/library/bb776913.aspx). You do this by using the family of IFileDialog native APIs that were introduced with Windows Vista and work perfectly in Windows7: IFileDialog, IFileOpenDialog, IFileSaveDialog, IFileDialogCustomize, IFileDialogEvents, and IFileDialogControlEvents. These APIs replace the legacy GetOpenFileName and GetSaveFileName APIs from earlier Windows versions and provide a more flexible mechanism for picking and interacting with items in the Shell namespace.

By using the new IFileDialog APIs, your application can work directly within the Shell namespace instead of using file system paths. This is crucial when interacting with libraries, which do not return a file system path. Native applications should use the IFileDialog COM interface, and Microsoft .NET Framework applications should use the System.Windows.Forms.FileDialog– derived classes System.Windows.Forms.OpenFileDialog and System.Windows.Forms.SaveFileDialog.

Using IFileDialog to select libraries The IFileDialog interface is the base interface for both IFileOpenDialog and IFileSaveDialog. The Shell native API is COM based; therefore, before using any COM object, you 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 folder by showing the common save file dialog.

IShellItem *ppsi = NULL;
   IFileSaveDialog *pfod;
   HRESULT 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);
   // use the returned IShellItem
   ppsi->Release();
   }
   }
   pfod->Release();
   }
 

Here you can see we’re using the IFileSaveDialog interface, but the details and principles shown here also apply to the rest of the IFileDialog family. 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 presents the Open dialog with the choice of folders rather than files and allows the user to choose a library. The CFD returns the default save location folder associated with the chosen library.

Important One of the flags that can be passed to the SetOptions function is FOS_FORCEFILESYSTEM, which ensures that returned items are only system items that are real file system locations. Libraries are not system items and therefore do not represent a real file system location. To make sure the CFD can choose libraries, developers must not set the FOS_FORCEFILESYSTEM flag.