JumpList Class

Represents a list of items and tasks displayed as a menu on a Windows 7 taskbar button.

Inheritance Hierarchy

System.Object
  Microsoft.Windows.Shell.JumpList

Namespace:  Microsoft.Windows.Shell
Assembly:  Microsoft.Windows.Shell (in Microsoft.Windows.Shell.dll)

Syntax

'Declaration
<ContentPropertyAttribute("JumpItems")> _
Public NotInheritable Class JumpList _
    Implements ISupportInitialize

[ContentPropertyAttribute("JumpItems")]
public sealed class JumpList : ISupportInitialize

[ContentPropertyAttribute(L"JumpItems")]
public ref class JumpList sealed : ISupportInitialize

[<Sealed>]
[<ContentPropertyAttribute("JumpItems")>]
type JumpList =  
    class
        interface ISupportInitialize
    end

public final class JumpList implements ISupportInitialize

The JumpList type exposes the following members.

Constructors

	Name	Description
	JumpList()	Initializes a new instance of the JumpList class.
	JumpList(IEnumerable<JumpItem>, Boolean, Boolean)	Initializes a new instance of the JumpList class with the specified parameters.

Top

Properties

	Name	Description
	JumpItems	Gets the collection of JumpItem objects that are displayed in the Jump List.
	ShowFrequentCategory	Gets or sets a value that indicates whether frequently used items are displayed in the Jump List.
	ShowRecentCategory	Gets or sets a value that indicates whether recently used items are displayed in the Jump List.

Top

Methods

	Name	Description
	AddToRecentCategory(String)	Adds the specified item path to the Recent category of the Jump List.
	AddToRecentCategory(JumpPath)	Adds the specified jump path to the Recent category of the Jump List.
	AddToRecentCategory(JumpTask)	Adds the specified jump task to the Recent category of the Jump List.
	Apply	Sends the JumpList to the Windows shell in its current state.
	BeginInit	Infrastructure. Signals the start of the JumpList initialization.
	EndInit	Infrastructure. Signals the end of the JumpList initialization.
	Equals	Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
	Finalize	Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetJumpList	Returns the JumpList object associated with an application.
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	SetJumpList	Sets the JumpList object associated with an application.
	ToString	Returns a string that represents the current object. (Inherited from Object.)

Top

Events

	Name	Description
	JumpItemsRejected	Occurs when jump items are not successfully added to the Jump List by the Windows shell.
	JumpItemsRemovedByUser	Occurs when jump items previously in the Jump List are removed from the list by the user.

Top

Remarks

The Windows 7 taskbar provides enhanced functionality for starting programs directly from the taskbar button by using Jump Lists. Jump Lists are also used in the Windows 7 Start menu. You access a Jump List by right-clicking a taskbar button or by clicking the arrow next to a program in the Start menu. For more information about Jump Lists, see the Taskbar section of the Windows User Experience Interaction Guidelines.

The JumpList class provides a managed wrapper for the Jump List functionality in the Windows 7 taskbar and manages the data passed to the Windows shell. The functionality exposed by the JumpList class is not available in versions of Windows earlier than Windows 7. Applications that use the JumpList class will run in other versions of Windows, but the Jump List will not be available. For more information about the Windows shell and native Jump List APIs, see Taskbar Extensions.

The following illustration shows the Jump List for Windows Media Player, with items in the Tasks and Frequent categories.

Windows Media Player Jump List

Configuring a Jump List

Jump Lists can contain two types of items, a JumpTask and a JumpPath. A JumpTask is a link to a program and a JumpPath is a link to a file. You can visually separate items in a Jump List by creating a JumpTask that does not have a Title and CustomCategory specified. This empty JumpTask will be displayed as a horizontal line in the Jump List.

Note

If the type of the file specified in a JumpPath is not registered with your application, the file will not appear in the Jump List. For example, if you add a JumpPath that points to a .txt file, your application must be registered to handle .txt files. For more information, see Introduction to File Associations.

Jump items are placed into categories in the JumpList. By default, a JumpItem is displayed in the Tasks category. Alternatively, you can specify a CustomCategory for the JumpItem.

You can specify whether the standard Recent and Frequent categories are displayed in the JumpList by setting the ShowRecentCategory and ShowFrequentCategory properties. The contents of these categories are managed by the Windows shell. Because these categories might contain much of the same data, you typically display one or the other in your JumpList, but not both. Windows automatically manages recent items if they are opened through a common file dialog box or used to open an application through file type association. When an item is accessed through the Jump List, you can notify the Windows shell to add the item to the Recent category by calling the AddToRecentCategory method.

Applying a Jump List to the Windows Shell

You cannot access the shell’s Jump List directly or read its contents into the JumpList class. Instead, the JumpList class provides a representation of a Jump List that you can work with, and then apply to the Windows shell. You typically create a JumpList and set it one time when the application is first run. However, you can modify or replace the JumpList at run time.

When you have set the JumpList properties, you must apply the JumpList to the Windows shell before its contents appear in the taskbar Jump List. This is done automatically when the JumpList is first attached to an application, either in XAML or in a call to the SetJumpList method. If you modify the contents of the JumpList at run time, you must call the Apply method to apply its current contents to the Windows shell.

Setting a Jump List in XAML

A JumpList is not automatically attached to an Application object. You attach a JumpList to an Application object in XAML by using the attached property syntax. The JumpList class implements the ISupportInitialize interface to support XAML declaration of a JumpList. If the JumpList is declared in XAML and attached to the current Application, it is automatically applied to the Windows shell when the JumpList is initialized. 

Setting and Modifying a Jump List in Code

You attach a JumpList to an Application object in code by calling the static SetJumpList method. This also applies the JumpList to the Windows shell.

To modify a JumpList at run time, you call the GetJumpList method to get the JumpList that is currently attached to an Application. After you have modified the properties of the JumpList, you must call the Apply method to apply the changes to the Windows shell.

Note

You typically create one JumpList that is attached to the Application and applied to the Windows shell. However, you can create multiple JumpList objects. Only one JumpList at a time can be applied to the Windows shell, and only one JumpList at a time can be associated with an Application. The .NET Framework does not require that these be the same JumpList.

Note

This class contains a link demand at the class level that applies to all members. A SecurityException is thrown when the immediate caller does not have full-trust permission. For more information about security demands, see Link Demands and Inheritance Demands.

.NET Framework Security

• UIPermission 

  for full access to modify the Windows shell. Security action: LinkDemand. Associated enumeration: UIPermissionWindow.AllWindows

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See Also

Reference

Microsoft.Windows.Shell Namespace