ICustomDestinationList interface (shobjidl_core.h)
Exposes methods that allow an application to provide a custom Jump List, including destinations and tasks, for display in the taskbar.
Inheritance
The ICustomDestinationList interface inherits from the IUnknown interface. ICustomDestinationList also has these types of members:
Methods
The ICustomDestinationList interface has these methods.
ICustomDestinationList::AbortList Discontinues a Jump List building session initiated by ICustomDestinationList::BeginList without committing any changes. |
ICustomDestinationList::AddUserTasks Specifies items to include in the Tasks category of a custom Jump List. |
ICustomDestinationList::AppendCategory Defines a custom category and the destinations that it contains, for inclusion in a custom Jump List. |
ICustomDestinationList::AppendKnownCategory Specifies that the Frequent or Recent category should be included in a custom Jump List. |
ICustomDestinationList::BeginList Initiates a building session for a custom Jump List. |
ICustomDestinationList::CommitList Declares that the Jump List initiated by a call to ICustomDestinationList::BeginList is complete and ready for display. |
ICustomDestinationList::DeleteList Deletes a custom Jump List for a specified application. |
ICustomDestinationList::GetRemovedDestinations Retrieves the current list of destinations that have been removed by the user from the existing Jump List that this custom Jump List is meant to replace. |
ICustomDestinationList::SetAppID Specifies a unique Application User Model ID (AppUserModelID) for the application whose taskbar button will hold the custom Jump List built through the methods of this interface. This method is optional. |
Remarks
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, websites, 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.
The application must call this object to provide a custom Jump List to the taskbar 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
Requirements
Requirement | Value |
---|---|
Minimum supported client | Windows 7 [desktop apps only] |
Minimum supported server | Windows Server 2008 R2 [desktop apps only] |
Target Platform | Windows |
Header | shobjidl_core.h (include Shobjidl.h) |