Table of Contents

Class JumpList

Namespace
Microsoft.WindowsAPICodePack.Taskbar
Assembly
Microsoft.WindowsAPICodePack.Shell.dll

Represents an instance of a Taskbar button jump list.

public class JumpList
Inheritance
JumpList
Inherited Members

Properties

ApplicationId

Gets or sets the application ID to use for this jump list.

public string ApplicationId { get; }

Property Value

string

KnownCategoryOrdinalPosition

Gets or sets the value for the known category location relative to the custom category collection.

public int KnownCategoryOrdinalPosition { get; set; }

Property Value

int

KnownCategoryToDisplay

Gets or sets the type of known categories to display.

public JumpListKnownCategoryType KnownCategoryToDisplay { get; set; }

Property Value

JumpListKnownCategoryType

MaxSlotsInList

Gets the recommended number of items to add to the jump list.

public uint MaxSlotsInList { get; }

Property Value

uint

Remarks

This number doesn’t imply or suggest how many items will appear on the jump list.
This number should only be used for reference purposes since the actual number of slots in the jump list can change after the last refresh due to items being pinned or removed and resolution changes. The jump list can increase in size accordingly.

RemovedDestinations

Retrieves the current list of destinations that have been removed from the existing jump list by the user. The removed destinations may become items on a custom jump list.

public IEnumerable RemovedDestinations { get; }

Property Value

IEnumerable

A collection of items (filenames) removed from the existing jump list by the user.

Methods

AddCustomCategories(params JumpListCustomCategory[])

Adds a collection of custom categories to the Taskbar jump list.

public void AddCustomCategories(params JumpListCustomCategory[] customCategories)

Parameters

customCategories JumpListCustomCategory[]

The catagories to add to the jump list.

AddToRecent(string)

Reports document usage to the shell.

public static void AddToRecent(string destination)

Parameters

destination string

The full path of the file to report usage.

AddUserTasks(params JumpListTask[])

Adds user tasks to the Taskbar JumpList. User tasks can only consist of JumpListTask or JumpListSeparator objects.

public void AddUserTasks(params JumpListTask[] tasks)

Parameters

tasks JumpListTask[]

The user tasks to add to the JumpList.

ClearAllUserTasks()

Removes all user tasks that have been added.

public void ClearAllUserTasks()

CreateJumpList()

Create a JumpList for the application's taskbar button.

public static JumpList CreateJumpList()

Returns

JumpList

A new JumpList that is associated with the app id of the main application window

Remarks

If there are any other child (top-level) windows for this application and they don't have a specific JumpList created for them, they all will share the same JumpList as the main application window. In order to have a individual JumpList for a top-level window, use the overloaded method CreateJumpListForIndividualWindow.

CreateJumpListForIndividualWindow(string, nint)

Create a JumpList for the application's taskbar button.

public static JumpList CreateJumpListForIndividualWindow(string appId, nint windowHandle)

Parameters

appId string

Application Id for the individual window. This must be unique for each top-level window in order to have a individual JumpList.

windowHandle nint

Handle of the window associated with the new JumpList

Returns

JumpList

A new JumpList that is associated with the specific window handle

CreateJumpListForIndividualWindow(string, Window)

Create a JumpList for the application's taskbar button.

public static JumpList CreateJumpListForIndividualWindow(string appId, Window window)

Parameters

appId string

Application Id for the individual window. This must be unique for each top-level window in order to have a individual JumpList.

window Window

WPF Window associated with the new JumpList

Returns

JumpList

A new JumpList that is associated with the specific WPF window

Refresh()

Commits the pending JumpList changes and refreshes the Taskbar.

public void Refresh()

Exceptions

InvalidOperationException

Will throw if the type of the file being added to the JumpList is not registered with the application.

UnauthorizedAccessException

Will throw if recent documents tracking is turned off by the user or via group policy.

COMException

Will throw if updating the JumpList fails for any other reason.

Events

JumpListItemsRemoved

Occurs when items are removed from the Taskbar's jump list since the last refresh.

public event EventHandler<UserRemovedJumpListItemsEventArgs> JumpListItemsRemoved

Event Type

EventHandler<UserRemovedJumpListItemsEventArgs>

Remarks

This event is not triggered immediately when a user removes an item from the jump list but rather when the application refreshes the task bar list directly.