JumpList Class

Definition

Namespace:

System.Windows.Shell

Assembly:

PresentationFramework.dll

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

public ref class JumpList sealed : System::ComponentModel::ISupportInitialize

[System.Windows.Markup.ContentProperty("JumpItems")]
public sealed class JumpList : System.ComponentModel.ISupportInitialize

[<System.Windows.Markup.ContentProperty("JumpItems")>]
type JumpList = class
    interface ISupportInitialize

Public NotInheritable Class JumpList
Implements ISupportInitialize

Inheritance

Object

JumpList

Attributes

ContentPropertyAttribute

Implements

ISupportInitialize

Examples

The following example shows an application with a Jump List. The application has three buttons that enable you to add a task to the current Jump List, clear the contents of the Jump List, and apply a new Jump List to the application.

The following example shows how to declare a JumpList in markup. The JumpList contains two JumpTask links and one JumpPath. Applying the JumpPath to the shell will fail if the application is not registered to handle the .txt file name extension.

<Application x:Class="JumpListSample.App"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             StartupUri="MainWindow.xaml">
    <JumpList.JumpList>
        <JumpList ShowRecentCategory="True"
                  ShowFrequentCategory="True"
                  JumpItemsRejected="JumpList_JumpItemsRejected"
                  JumpItemsRemovedByUser="JumpList_JumpItemsRemovedByUser">
            <JumpTask Title="Notepad" 
                      Description="Open Notepad." 
                      ApplicationPath="C:\Windows\notepad.exe"
                      IconResourcePath="C:\Windows\notepad.exe"/>
            <JumpTask Title="Read Me" 
                      Description="Open readme.txt in Notepad." 
                      ApplicationPath="C:\Windows\notepad.exe"
                      IconResourcePath="C:\Windows\System32\imageres.dll"
                      IconResourceIndex="14"
                      WorkingDirectory="C:\Users\Public\Documents"
                      Arguments="readme.txt"/>
            <JumpPath Path="C:\Users\Public\Documents\readme.txt" />
        </JumpList>
    </JumpList.JumpList>
</Application>

The following example shows the code-behind page for App.xaml. This code handles the JumpItemsRejected and JumpItemsRemovedByUser events.

using System.Text;
using System.Windows;
using System.Windows.Shell;

namespace JumpListSample
{
    /// <summary>
    /// Interaction logic for App.xaml
    /// </summary>
    public partial class App : Application
    {
        private void JumpList_JumpItemsRejected(object sender, System.Windows.Shell.JumpItemsRejectedEventArgs e)
        {
            StringBuilder sb = new StringBuilder();
            sb.AppendFormat("{0} Jump Items Rejected:\n", e.RejectionReasons.Count);
            for (int i = 0; i < e.RejectionReasons.Count; ++i)
            {
                if (e.RejectedItems[i].GetType() == typeof(JumpPath))
                    sb.AppendFormat("Reason: {0}\tItem: {1}\n", e.RejectionReasons[i], ((JumpPath)e.RejectedItems[i]).Path);
                else
                    sb.AppendFormat("Reason: {0}\tItem: {1}\n", e.RejectionReasons[i], ((JumpTask)e.RejectedItems[i]).ApplicationPath);
            }

            MessageBox.Show(sb.ToString());
        }

        private void JumpList_JumpItemsRemovedByUser(object sender, System.Windows.Shell.JumpItemsRemovedEventArgs e)
        {
            StringBuilder sb = new StringBuilder();
            sb.AppendFormat("{0} Jump Items Removed by the user:\n", e.RemovedItems.Count);
            for (int i = 0; i < e.RemovedItems.Count; ++i)
            {
                sb.AppendFormat("{0}\n", e.RemovedItems[i]);
            }

            MessageBox.Show(sb.ToString());
        }
    }
}

The following example shows the markup used to create the application user interface.

<Window x:Class="JumpListSample.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        Title="Jump List Sample" Height="240" Width="500">
    <Window.Resources>
        <Style TargetType="Button">
            <Setter Property="Width" Value="200" />
            <Setter Property="Margin" Value="5" />
        </Style>
    </Window.Resources>
    <Grid>
        <StackPanel>
            <Button Content="Add Task to JumpList" Click="AddTask" />
            <Button Content="Clear Jump List" Click="ClearJumpList"/>
            <Button Content="Set New Jump List" Click="SetNewJumpList" />
        </StackPanel>
    </Grid>
</Window>

The following example shows the code-behind page for MainWindow.xaml. This code demonstrates how to modify, clear, and create a JumpList in procedural code. For the new Jump List, the static SetJumpList method is called to associate the JumpList with the current application and apply the JumpList to the Windows shell.

using System;
using System.IO;
using System.Windows;
using System.Windows.Shell;

namespace JumpListSample
{
    /// <summary>
    /// Interaction logic for MainWindow.xaml
    /// </summary>
    public partial class MainWindow : Window
    {
        public MainWindow()
        {
            InitializeComponent();
        }
        private void AddTask(object sender, RoutedEventArgs e)
        {
            // Configure a new JumpTask.
            JumpTask jumpTask1 = new JumpTask();
            // Get the path to Calculator and set the JumpTask properties.
            jumpTask1.ApplicationPath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.SystemX86), "calc.exe");
            jumpTask1.IconResourcePath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.SystemX86), "calc.exe");
            jumpTask1.Title = "Calculator";
            jumpTask1.Description = "Open Calculator.";
            jumpTask1.CustomCategory = "User Added Tasks";
            // Get the JumpList from the application and update it.
            JumpList jumpList1 = JumpList.GetJumpList(App.Current);
            jumpList1.JumpItems.Add(jumpTask1);
            JumpList.AddToRecentCategory(jumpTask1);
            jumpList1.Apply();
        }
        private void ClearJumpList(object sender, RoutedEventArgs e)
        {
            JumpList jumpList1 = JumpList.GetJumpList(App.Current);
            jumpList1.JumpItems.Clear();
            jumpList1.Apply();
        }
        private void SetNewJumpList(object sender, RoutedEventArgs e)
        {
            //Configure a new JumpTask
            JumpTask jumpTask1 = new JumpTask();
            // Get the path to WordPad and set the JumpTask properties.
            jumpTask1.ApplicationPath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.System), "write.exe");
            jumpTask1.IconResourcePath = Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.System), "write.exe");
            jumpTask1.Title = "WordPad";
            jumpTask1.Description = "Open WordPad.";
            jumpTask1.CustomCategory = "Jump List 2";
            // Create and set the new JumpList.
            JumpList jumpList2 = new JumpList();
            jumpList2.JumpItems.Add(jumpTask1);
            JumpList.SetJumpList(App.Current, jumpList2);
        }
    }
}

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.

Constructors

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.

Properties

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.

Methods

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.
AddToRecentCategory(String)	Adds the specified item path to the Recent category of the Jump List.
Apply()	Sends the JumpList to the Windows shell in its current state.
BeginInit()	Signals the start of the JumpList initialization.
EndInit()	Signals the end of the JumpList initialization.
Equals(Object)	Determines whether the specified object is equal to the current object. (Inherited from Object)
GetHashCode()	Serves as the default hash function. (Inherited from Object)
GetJumpList(Application)	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(Application, JumpList)	Sets the JumpList object associated with an application.
ToString()	Returns a string that represents the current object. (Inherited from Object)

Events

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.