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
| 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.
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:
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.
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.
- 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.
A jump list item with the specified parameters that can be added to an app's jump list through the items property.