CJumpList Class
The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.
The latest version of this topic can be found at CJumpList Class.
A CJumpList is the list of shortcuts revealed when you right click on an icon in the task bar.
Syntax
class CJumpList;
Members
Public Constructors
| Name | Description |
|---|---|
| CJumpList::CJumpList | Constructs a CJumpList object. |
| CJumpList::~CJumpList | Destroys a CJumpList object. |
| Name | Description |
|---|---|
| CJumpList::AbortList | Aborts a list-building transaction without committing. |
| CJumpList::AddDestination | Overloaded. Adds destination to the list. |
| CJumpList::AddKnownCategory | Appends a Known Category to the list. |
| CJumpList::AddTask | Overloaded. Adds items to the canonical Tasks category. |
| CJumpList::AddTasks | Adds items to the canonical Tasks category. |
| CJumpList::AddTaskSeparator | Adds a separator between tasks. |
| CJumpList::ClearAll | Removes all tasks and destinations that have been added to the current instance of CJumpList so far. |
| CJumpList::ClearAllDestinations | Removes all destinations that have been added to the current instance of CJumpList so far. |
| CJumpList::CommitList | Ends a list-building transaction and commits the reported list to the associated store (the registry in this case.) |
| CJumpList::GetDestinationList | Retrieves an interface pointer to destination list. |
| CJumpList::GetMaxSlots | Retrieves the maximum number of items, including category headers that can display in the calling application's destination menu. |
| CJumpList::GetRemovedItems | Returns array of items that represent removed destinations. |
| CJumpList::InitializeList | Begins a list-building transaction. |
| CJumpList::SetAppID | Sets the Application User Model ID for the list that will be built. |
Inheritance Hierarchy
Requirements
Header: afxadv.h
CJumpList::~CJumpList
Destroys a CJumpList object.
~CJumpList();
CJumpList::AbortList
Aborts a list-building transaction without committing.
void AbortList();
Remarks
Calling this method has the same effect as destroying CJumpList without calling CommitList.
CJumpList::AddDestination
Adds destination to the list.
BOOL AddDestination(
LPCTSTR lpcszCategoryName,
LPCTSTR strDestinationPath);
BOOL AddDestination(
LPCTSTR strCategoryName,
IShellItem* pShellItem);
BOOL AddDestination(
LPCTSTR strCategoryName,
IShellLink* pShellLink);
Parameters
lpcszCategoryName
Specifies a category name. If the specified category does not exist, it will be created.
strDestinationPath
Specifies a path to destination file.
strCategoryName
Specifies a category name. If the specified category does not exist, it will be created.
pShellItem
Specifies a Shell Item representing the destination being added.
pShellLink
Specifies a Shell Link representing the destination being added.
Return Value
Remarks
The instance of CJumpList internally accumulates added destinations and then commits them in CommitList.
CJumpList::AddKnownCategory
Appends a Known Category to the list.
BOOL AddKnownCategory(KNOWNDESTCATEGORY category);
Parameters
category
Specifies a known category type. Can be either KDC_RECENT, or KDC_KNOWN.
Return Value
Remarks
Known Categories are the Frequent and Recent categories that we will automatically calculate for every application that utilizes SHAddToRecentDocs (or indirectly uses it as the shell will call it on the application's behalf in some scenarios).
CJumpList::AddTask
Adds items to the canonical Tasks category.
BOOL AddTask(
LPCTSTR strTargetExecutablePath,
LPCTSTR strCommandLineArgs,
LPCTSTR strTitle,
LPCTSTR strIconLocation,
int iIconIndex);
BOOL AddTask(IShellLink* pShellLink);
Parameters
strTargetExecutablePath
Specifies the target task path.
strCommandLineArgs
Specifies command line arguments of the executable specified by strTargetExecutablePath.
strTitle
Task name that will be displayed in the Destination List.
strIconLocation
Location of icon that will be displayed in the Destination List along with the title.
iIconIndex
Icon index.
pShellLink
Shell Link that represents a task to be added.
Return Value
Remarks
The instance of CJumpList accumulates specified tasks and adds them to the Destination List during CommitList. Task items will appear in a category at the bottom of the application's destination menu. This category takes precedence over all other categories when it is filled in the UI.
CJumpList::AddTasks
Adds items to the canonical Tasks category.
BOOL AddTasks(IObjectArray* pObjectCollection);
Parameters
pObjectCollection
A collection of tasks to be added.
Return Value
Remarks
The instance of CJumpList accumulates specified tasks and adds them to the Destination List during CommitList. Task items will appear in a category at the bottom of the application's destination menu. This category takes precedence over all other categories when it is filled in the UI.
CJumpList::AddTaskSeparator
Adds a separator between tasks.
BOOL AddTaskSeparator();
Return Value
Nonzero if it is successful, 0 if it is not.
CJumpList::CJumpList
Constructs a CJumpList object.
CJumpList(BOOL bAutoCommit = TRUE);
Parameters
bAutoCommit
If this parameter is FALSE the list is not automatically committed in destructor.
CJumpList::ClearAll
Removes all tasks and destinations that have been added to the current instance of CJumpList so far.
void ClearAll();
Remarks
This method clears and releases all data and internal interfaces.
CJumpList::ClearAllDestinations
Removes all destinations that have been added to the current instance of CJumpList so far.
void ClearAllDestinations();
Remarks
Call this function if you need to remove all destinations that have been added so far in the current session of destination list building and add other destinations again. If the internal ICustomDestinationList has been initialized, it's left alive.
CJumpList::CommitList
Ends a list-building transaction and commits the reported list to the associated store (the registry in this case).
BOOL CommitList();
Return Value
Remarks
The commit is atomic. An error will be returned if the commit fails. When CommitList is called, the current list of removed items will be cleaned up. Calling this method resets the object so that it does not have an active list-building transaction. To update the list, BeginList needs to be called again.
CJumpList::GetDestinationList
Retrieves an interface pointer to destination list.
ICustomDestinationList* GetDestinationList();
Return Value
Remarks
If the jump list has not been initialized, or has been committed or aborted, the returned value will be NULL.
CJumpList::GetMaxSlots
Retrieves the maximum number of items, including category headers that can display in the calling application's destination menu.
UINT GetMaxSlots() const;
Return Value
Remarks
Applications may only report a number of items and category headers combined up to this value. If calls to AppendCategory, AppendKnownCategory, or AddUserTasks exceed this number, they will return failure.
CJumpList::GetRemovedItems
Returns array of items that represent removed destinations.
IObjectArray* GetRemovedItems();
Return Value
Remarks
The removed destinations are retrieved during initialization of jump list. When generating a new destination list, applications are expected to first process the removed destinations list, clearing their tracking data for any item returned by the removed list enumerator. If an application attempts to provide an item that was just removed in the transaction that the current call to BeginList started, the method call that re-added that item will fail, to ensure that applications are respecting the removed list.
CJumpList::InitializeList
Begins a list-building transaction.
BOOL InitializeList();
Return Value
Remarks
You don't need to call this method explicitly unless you wish to retrieve a pointer to ICustomDestinationList using GetDestinationList, the number of available slots using GetMaxSlots, or list of removed items using GetRemovedItems.
CJumpList::SetAppID
Sets the Application User Model ID for the list that will be built.
void SetAppID(LPCTSTR strAppID);
Parameters
strAppID
A string that specifies the Application User Model ID.