Edit

Share via

ICustomDestinationList interface (shobjidl_core.h)

  • Article

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.

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 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:

  1. SetAppID (required only if an application provides its own AppUserModelID)
  2. BeginList
  3. AppendCategory, AppendKnownCategory, AddUserTasks, or any combination of those three methods.
  4. 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)

See also

Taskbar Extensions