When to Implement
An implementation of this interface is provided in Windows as CLSID_DestinationList. This interface is not implemented by third parties.
When to Use
Jump Lists contain both destination and task lists.
- Destinations are items that appear in the Recent, Frequent, or custom categories, based on an individual's usage. Destinations can be files, folders, Web sites, or other content-based items, but are not necessarily file-backed. Destinations can be thought of as things or nouns. Destinations can be pinned or removed from the Jump List by the user. They are generally represented by IShellItem objects but they can also be IShellLink objects.
- Tasks are common actions performed in an application that apply to all users of that application regardless of an individual's usage patterns. Tasks can be thought of as actions or verbs. Tasks cannot be pinned or removed. They are represented by IShellLink objects.
The taskbar provides each taskbar button with a Jump List. By default, a Jump List contains a Recent category, which is populated automatically for file-based applications through SHAddToRecentDocs or the common file dialog. To replace the Recent category with the Frequent category or define, add, and populate its own custom categories, an application must call the methods of this interface. The application can also supply its own tasks based on the application's architecture and intended use.
Note An application must be a registered handler for a file type for an item of that type to appear in its Jump List. It does not, however, need to be the default handler for that file type.
A custom Jump List is intended to present content that the application has deemed significant based on either previous usage of the application or through an action that has indicated that an item is of importance to the user, such as the user adding an item to a Favorites list.
The application must call this object to provide a custom Jump List to the taskbar user interface (UI). The system never queries the application for the information.
When an application provides a custom Jump List, it takes on certain responsibilities around that list. Custom categories must be populated in a manner consistent with the intended use of a Jump List. Items in the list must be checked for validity or fail gracefully if they have been deleted. If the user removes an item from the list, that removal must be honored.
A custom Jump List is never truly updated in the sense of changing elements in an existing list. Rather, the old list is replaced with a new list.
The basic sequence of ICustomDestinationList method calls to build and display a custom Jump List is as follows:
- SetAppID (required only if an application provides its own AppUserModelID)
- BeginList
- AppendCategory, AppendKnownCategory, AddUserTasks, or any combination of those three methods.
- CommitList