ICustomDestinationList::AddUserTasks method (shobjidl_core.h)
Specifies items to include in the Tasks category of a custom Jump List.
Syntax
HRESULT AddUserTasks(
[in] IObjectArray *poa
);
Parameters
[in] poa
Type: IObjectArray*
A pointer to an IObjectArray that represents one or more IShellLink (or, more rarely, IShellItem) objects that represent the tasks.
Return value
Type: HRESULT
Returns S_OK if successful, or an error value otherwise.
Remarks
You must call ICustomDestinationList::BeginList before you call this method.
The Tasks category header is always shown in the list by default, unless the category is empty. This header text cannot be changed. It is displayed in the user's selected language.
The Tasks category, even though it always appears as the last category in a Jump List, takes priority over all other categories in the list. This list is filled, and then the remaining space is allocated to the other categories. Unlike other categories, items in the Tasks category cannot be removed or pinned by the user. Applications must balance the value to the user of the tasks in this category against the space needed for other categories.
Tasks should apply to the application as a whole; they are not meant to be specific to an individual window or document. For those more granular contextual tasks, an application can supply them through a thumbnail toolbar.
IShellLink instances provided through the IObjectArray pointed to by poa must provide the following:
- Either a pointer to an item identifier list (PIDL) (SetIDList) or the target path (SetPath or SetRelativePath)
- Command-line arguments (SetArguments)
- Icon location (SetIconLocation)
Optionally, the description field (SetDescription) can be set to provide a custom tooltip for the item in the Jump List.
A task list can also include separators. These are created by including a blank IShellLink (this is the single exception to the argument list requirement), and setting its System.AppUserModel.IsDestListSeparator property to TRUE through the IShellLink object's IPropertyStore interface. Any other values in the IShellLink will be ignored. Separators do not take up a full space in the list and are not counted in the number of items in the list. If two separators are provided with no items between them, one of the separators will not be shown. Separators at the beginning or end of the list are also ignored.
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) |
Library | Shell32.lib |
DLL | Shell32.dll (version 6.1 or later) |
See also
ICustomDestinationList::AppendCategory