JumpListItem JumpListItem JumpListItem JumpListItem Class

Definition

Provides functionality for creating and defining jump list items for an app's jump list.

public : sealed class JumpListItem : IJumpListItempublic sealed class JumpListItem : IJumpListItemPublic NotInheritable Class JumpListItem Implements IJumpListItem// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10586.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v2)

Examples

The following example demonstrates how to create a task for a JumpList that launches the app with command line parameters and takes a desired action. Localization is not shown, but is possible for the DisplayName, description, and logo through the use of the ms-resource: and ms-appx: URI schemes.

private Windows.UI.StartScreen.JumpListItem CreateJumpListItemTask()
{
    var taskItem = JumpListItem.CreateWithArguments(
                            "/Argument", "DisplayName");

    // Set the description. (Optional.)
    taskItem.Description = "Compose a new message to " + friendName;

    // Set the logo for this jump list item. Must be ms-appx: or ms-appdata:.
    taskItem.Logo = new Uri("ms-appdata:///local/downloads/taskImage.png");

    // If the GroupName is left blank, then the item goes into the Tasks group by default.

    return taskItem;
}

partial class App
{
    protected override void OnLaunched(LaunchActivatedEventArgs e)
    {
        if (e.Kind == ActivationKind.Launch && e.Arguments == "/Argument")
        {
            // Run code relevant to the task that was selected.
        }
    }
}

Remarks

JumpListItem 's are created using the CreateWithArguments and CreateSeparator methods. After creation, they can be added to the app's jump list using the jump list's Items property and the SaveAsync method. Be aware that in the user interface, a user can right-click a jump list item that is in a custom group and select “Remove from this list”. When this action occurs, the system marks the item as removed by user and suppresses it from the UI. The next time an app loads the jump list, it should check the items to see if the item's RemovedByUser property is set to True. If RemovedByUser is True, then the app should update its internal state to be in sync with the user initiated change. It is the apps responsibility to make sure that a removed item is not added back to the jump list until such time as the conditions for its addition are again met, for example, by the user opening the associated document again.

When an app saves the JumpList using SaveAsync, the operating system organizes the items as follows.

  • Any items with RemovedByUser equal to True are removed.
  • Items with the same GroupName property are placed together, preserving their relative order.
  • Groups are ordered by the original position of the first item in the group, with the exception that system-managed groups are always at the top and the Tasks group is always at the bottom if they are present. That means that when an app loads it's JumpList using the LoadCurrentAsync method, the items are retrieved in their organized order, which might not agree with the order of the items in the jump list when it was originally saved.

Properties

Arguments Arguments Arguments Arguments

Gets the command line arguments for the jump list item.

public : PlatForm::String Arguments { get; }public string Arguments { get; }Public ReadOnly Property Arguments As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The jump list item command line arguments.

Description Description Description Description

Gets or sets the jump list item task description.

public : PlatForm::String Description { get; set; }public string Description { get; set; }Public ReadWrite Property Description As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The jump list item task description specified as a string. If localization is desired, this string must be a ms-resource: scheme specified URI.

DisplayName DisplayName DisplayName DisplayName

Gets or sets the jump list item display name. The display name can also be specified as a parameter using the CreateWithArguments method when the jump list item is created.

public : PlatForm::String DisplayName { get; set; }public string DisplayName { get; set; }Public ReadWrite Property DisplayName As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The display name of the jump list item in the app's jump list. If localization is desired, this string must be ams-resource: scheme specified URI.

GroupName GroupName GroupName GroupName

Gets or sets the jump list item custom group name. If no name is specified, the item will be added to the Tasks group by default.

public : PlatForm::String GroupName { get; set; }public string GroupName { get; set; }Public ReadWrite Property GroupName As string// You can use this property in JavaScript.
Value
PlatForm::String string string string

The custom group name for the jump list item specified as a string. If localization is desired, this string must be a ms-resource: scheme specified URI.

Remarks

If this string is not provided, then the item will be added to the Tasks group.

Kind Kind Kind Kind

Gets the JumpListItemKind of a jump list item.

public : JumpListItemKind Kind { get; }public JumpListItemKind Kind { get; }Public ReadOnly Property Kind As JumpListItemKind// You can use this property in JavaScript.
Value
JumpListItemKind JumpListItemKind JumpListItemKind JumpListItemKind

The JumpListItemKind enumeration indicating the kind of item represented by a jump list item.

Logo Logo Logo Logo

Gets or sets the jump list item's logo.

public : Uri Logo { get; set; }public Uri Logo { get; set; }Public ReadWrite Property Logo As Uri// You can use this property in JavaScript.
Value
Uri Uri Uri Uri

The Uri for the jump list item logo. This can be specified using one of these schemes:ms-appx:///A path within the deployed app package. This path is resolved for languages and DPI plateau supported by the app.ms-appdata:///local/A file found in the per-user app storage.

RemovedByUser RemovedByUser RemovedByUser RemovedByUser

Gets a boolean indicating whether the jump list item was removed from the app's jump list by the user.

public : PlatForm::Boolean RemovedByUser { get; }public bool RemovedByUser { get; }Public ReadOnly Property RemovedByUser As bool// You can use this property in JavaScript.
Value
PlatForm::Boolean bool bool bool

True when a user manually removed a jump list item from the app's jump list, otherwise False.

Remarks

If the RemovedByUser property is True, then the item will not be saved to the jump list when the SaveAsync method is called.

Methods

CreateSeparator() CreateSeparator() CreateSeparator() CreateSeparator()

Creates a jump list item that is an inert separator for a custom group within the app's jump list.

public : static JumpListItem CreateSeparator()public static JumpListItem CreateSeparator()Public Static Function CreateSeparator() As JumpListItem// You can use this method in JavaScript.
Returns

A jump list item that can be added to an app's jump list through the items property.

CreateWithArguments(String, String) CreateWithArguments(String, String) CreateWithArguments(String, String) CreateWithArguments(String, String)

Creates a new jump list item for an app's jump list.

public : static JumpListItem CreateWithArguments(PlatForm::String arguments, PlatForm::String displayName)public static JumpListItem CreateWithArguments(String arguments, String displayName)Public Static Function CreateWithArguments(arguments As String, displayName As String) As JumpListItem// You can use this method in JavaScript.
Parameters
arguments
PlatForm::String String String String

String that specifies any command line arguments that should be passed onto the app when the jump list item is selected by a user.

displayName
PlatForm::String String String String

String that specifies a display name for the jump list item. If localization is desired, this string must be a ms-resource: scheme specified URI.

Returns

A jump list item with the specified parameters that can be added to an app's jump list through the items property.