Export (0) Print
Expand All

JumpList Class

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

System.Object
  System.Windows.Shell.JumpList

Namespace:  System.Windows.Shell
Assembly:  PresentationFramework (in PresentationFramework.dll)
XMLNS for XAML: Not mapped to an xmlns.

[ContentPropertyAttribute("JumpItems")]
[UIPermissionAttribute(SecurityAction.LinkDemand, Window = UIPermissionWindow.AllWindows)]
public sealed class JumpList : ISupportInitialize
<JumpList>
  JumpItems
</JumpList>

The JumpList type exposes the following members.

  NameDescription
Public methodJumpList()Initializes a new instance of the JumpList class.
Public methodJumpList(IEnumerable<JumpItem>, Boolean, Boolean)Initializes a new instance of the JumpList class with the specified parameters.
Top

  NameDescription
Public propertyJumpItemsGets the collection of JumpItem objects that are displayed in the Jump List.
Public propertyShowFrequentCategoryGets or sets a value that indicates whether frequently used items are displayed in the Jump List.
Public propertyShowRecentCategoryGets or sets a value that indicates whether recently used items are displayed in the Jump List.
Top

  NameDescription
Public methodStatic memberAddToRecentCategory(JumpPath)Adds the specified jump path to the Recent category of the Jump List.
Public methodStatic memberAddToRecentCategory(JumpTask)Adds the specified jump task to the Recent category of the Jump List.
Public methodStatic memberAddToRecentCategory(String)Adds the specified item path to the Recent category of the Jump List.
Public methodApplySends the JumpList to the Windows shell in its current state.
Public methodBeginInitInfrastructure. Signals the start of the JumpList initialization.
Public methodEndInitInfrastructure. Signals the end of the JumpList initialization.
Public methodEquals(Object)Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected methodFinalizeAllows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public methodGetHashCodeServes as a hash function for a particular type. (Inherited from Object.)
Public methodStatic memberGetJumpListReturns the JumpList object associated with an application.
Public methodGetTypeGets the Type of the current instance. (Inherited from Object.)
Protected methodMemberwiseCloneCreates a shallow copy of the current Object. (Inherited from Object.)
Public methodStatic memberSetJumpListSets the JumpList object associated with an application.
Public methodToStringReturns a string that represents the current object. (Inherited from Object.)
Top

  NameDescription
Public eventJumpItemsRejectedOccurs when jump items are not successfully added to the Jump List by the Windows shell.
Public eventJumpItemsRemovedByUserOccurs when jump items previously in the Jump List are removed from the list by the user.
Top

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

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.

NoteNote

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.

NoteNote

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.

NoteNote

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.

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);
        }
    }
}


.NET Framework

Supported in: 4

.NET Framework Client Profile

Supported in: 4

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.

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

Community Additions

ADD
Show:
© 2014 Microsoft