CJumpList 类

项目
10/19/2023

CJumpList 是当你右键单击任务栏中的图标时显示的快捷方式列表。

语法

class CJumpList;

成员

公共构造函数

名称	描述
CJumpList::CJumpList	构造 `CJumpList` 对象。
CJumpList::~CJumpList	销毁 `CJumpList` 对象。

名称	描述
CJumpList::AbortList	在不提交的情况下中止列表生成事务。
CJumpList::AddDestination	已重载。将目标添加到列表中。
CJumpList::AddKnownCategory	将已知类别追加到列表中。
CJumpList::AddTask	已重载。将项添加到规范“任务”类别。
CJumpList::AddTasks	将项添加到规范“任务”类别。
CJumpList::AddTaskSeparator	在任务之间添加分隔符。
CJumpList::ClearAll	移除到目前为止已添加到 `CJumpList` 的当前实例的所有任务和目标。
CJumpList::ClearAllDestinations	移除到目前为止已添加到 `CJumpList` 的当前实例的所有目标。
CJumpList::CommitList	结束列表生成事务，并将报告的列表提交到关联的存储（这里是指注册表）。
CJumpList::GetDestinationList	检索指向目标列表的接口指针。
CJumpList::GetMaxSlots	检索最大项数，包括可在调用应用程序的目标菜单中显示的类别标头。
CJumpList::GetRemovedItems	返回表示已移除目标的项数组。
CJumpList::InitializeList	开始列表生成事务。
CJumpList::SetAppID	设置要生成的列表的应用程序用户模型 ID。

继承层次结构

CJumpList

要求

标头：afxadv.h

CJumpList::~CJumpList

销毁 CJumpList 对象。

~CJumpList();

CJumpList::AbortList

在不提交的情况下中止列表生成事务。

void AbortList();

备注

调用此方法的效果与在不调用 CommitList 的情况下销毁 CJumpList 的效果相同。

CJumpList::AddDestination

将目标添加到列表中。

BOOL AddDestination(
    LPCTSTR lpcszCategoryName,
    LPCTSTR strDestinationPath);

BOOL AddDestination(
    LPCTSTR strCategoryName,
    IShellItem* pShellItem);

BOOL AddDestination(
    LPCTSTR strCategoryName,
    IShellLink* pShellLink);

参数

lpcszCategoryName
指定类别名称。如果指定的类别不存在，将创建该类别。

strDestinationPath
指定目标文件的路径。

strCategoryName
指定类别名称。如果指定的类别不存在，将创建该类别。

pShellItem
指定表示要添加的目标的 shell 项。

pShellLink
指定表示要添加的目标的 shell 链接。

返回值

注解

CJumpList 的实例在内部累积添加的目标，然后在 CommitList 中提交它们。

CJumpList::AddKnownCategory

将已知类别追加到列表中。

BOOL AddKnownCategory(KNOWNDESTCATEGORY category);

参数

category
指定已知的类别类型。可以是 KDC_RECENT 或 KDC_KNOWN。

返回值

备注

已知类别有“频繁”和“最近”类别，我们将针对使用 SHAddToRecentDocs（或间接使用，因为 shell 会在某些情况下代表应用程序调用它）的每个应用程序自动计算这些类别。

CJumpList::AddTask

将项添加到规范“任务”类别。

BOOL AddTask(
    LPCTSTR strTargetExecutablePath,
    LPCTSTR strCommandLineArgs,
    LPCTSTR strTitle,
    LPCTSTR strIconLocation,
    int iIconIndex);

BOOL AddTask(IShellLink* pShellLink);

参数

strTargetExecutablePath
指定目标任务路径。

strCommandLineArgs
指定由 strTargetExecutablePath 指定的可执行文件的命令行自变量。

strTitle
将在目标列表中显示的任务名称。

strIconLocation
将在目标列表中以及标题中显示的图标的位置。

iIconIndex
图标索引。

pShellLink
表示要添加的任务的 shell 链接。

返回值

备注

CJumpList 的实例将累积指定的任务，并在 CommitList 期间将其添加到目标列表。任务项将显示在应用程序目标菜单底部的类别中。在 UI 中填充此类别时，此类别优先于所有其他类别。

CJumpList::AddTasks

将项添加到规范“任务”类别。

BOOL AddTasks(IObjectArray* pObjectCollection);

参数

pObjectCollection
要添加的任务的集合。

返回值

备注

CJumpList 的实例将累积指定的任务，并在 CommitList 期间将其添加到目标列表。任务项将显示在应用程序目标菜单底部的类别中。在 UI 中填充此类别时，此类别优先于所有其他类别。

CJumpList::AddTaskSeparator

在任务之间添加分隔符。

BOOL AddTaskSeparator();

返回值

如果成功，则为非零值，否则为 0。

CJumpList::CJumpList

构造 CJumpList 对象。

CJumpList(BOOL bAutoCommit = TRUE);

参数

bAutoCommit
如果此参数为 FALSE，则列表不会在析构函数中自动提交。

CJumpList::ClearAll

移除到目前为止已添加到 CJumpList 的当前实例的所有任务和目标。

void ClearAll();

备注

此方法将清除并释放所有数据和内部接口。

CJumpList::ClearAllDestinations

移除到目前为止已添加到 CJumpList 的当前实例的所有目标。

void ClearAllDestinations();

备注

如果需要移除到目前为止已在当前目标列表生成会话中添加的所有目标，并再次添加其他目标，请调用此函数。如果内部 ICustomDestinationList 已经过初始化，则保持它的活动状态。

CJumpList::CommitList

结束列表生成事务，并将报告的列表提交到关联的存储（这里是指注册表）。

BOOL CommitList();

返回值

备注

提交是原子性操作。如果提交失败，将返回错误。调用 CommitList 时，将清理已移除项的当前列表。调用此方法会重置对象，使其没有活动列表生成事务。若要更新列表，需要再次调用 BeginList。

CJumpList::GetDestinationList

检索指向目标列表的接口指针。

ICustomDestinationList* GetDestinationList();

返回值

备注

如果跳转列表尚未经过初始化，或者已被提交或中止，返回值将为 NULL。

CJumpList::GetMaxSlots

检索最大项数，包括可在调用应用程序的目标菜单中显示的类别标头。

UINT GetMaxSlots() const;

返回值

备注

应用程序只能报告上限为此值的项和类别标头的组合数量。如果对 AppendCategory、AppendKnownCategory 或 AddUserTasks 的调用次数超过此数字，它们将返回失败。

CJumpList::GetRemovedItems

返回表示已移除目标的项数组。

IObjectArray* GetRemovedItems();

返回值

备注

在跳转列表的初始化过程中会检索已移除的目标。在生成新的目标列表时，应用程序应首先处理已移除的目标列表，从而清除已移除列表枚举器返回的任何项的跟踪数据。如果应用程序尝试提供一个刚刚在当前的 BeginList 调用启动的事务中移除的项，重新添加该项的方法调用将失败，以确保应用程序遵循已移除的列表。

CJumpList::InitializeList

开始列表生成事务。

BOOL InitializeList();

返回值

备注

无需显式调用此方法，除非你希望使用 GetDestinationList 检索指向 ICustomDestinationList 的指针、使用 GetMaxSlots 检索可用槽数或使用 GetRemovedItems 检索已移除项的列表。

CJumpList::SetAppID

设置要生成的列表的应用程序用户模型 ID。

void SetAppID(LPCTSTR strAppID);

参数

strAppID
指定应用程序用户模型 ID 的字符串。

另请参阅

类

通过