JumpListItem Class

Definition

Namespace:

Windows.UI.StartScreen

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

public ref class JumpListItem sealed

/// [Windows.Foundation.Metadata.ContractVersion(Windows.Foundation.UniversalApiContract, 131072)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
class JumpListItem final

[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Foundation.UniversalApiContract), 131072)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
public sealed class JumpListItem

Public NotInheritable Class JumpListItem

Inheritance

Object Platform::Object IInspectable JumpListItem

Attributes

ContractVersionAttribute MarshalingBehaviorAttribute

Windows requirements

Device family	Windows 10 (introduced in 10.0.10586.0)
API contract	Windows.Foundation.UniversalApiContract (introduced in v2.0)

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

A JumpListItem is 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 its 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	Gets the command line arguments for the jump list item.
Description	Gets or sets the jump list item task description.
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.
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.
Kind	Gets the JumpListItemKind of a jump list item.
Logo	Gets or sets the jump list item's logo.
RemovedByUser	Gets a boolean indicating whether the jump list item was removed from the app's jump list by the user.

Methods

CreateSeparator()	Creates a jump list item that is an inert separator for a custom group within the app's jump list.
CreateWithArguments(String, String)	Creates a new jump list item for an app's jump list.

See also

• Jump list customization sample