SecondaryTile SecondaryTile SecondaryTile SecondaryTile SecondaryTile Class

Definition

Creates, enumerates, and provides information about a secondary tile.

public : sealed class SecondaryTile : ISecondaryTile, ISecondaryTile2
struct winrt::Windows::UI::StartScreen::SecondaryTile : ISecondaryTile, ISecondaryTile2
public sealed class SecondaryTile : ISecondaryTile, ISecondaryTile2
Public NotInheritable Class SecondaryTile Implements ISecondaryTile, ISecondaryTile2
var secondaryTile = new secondaryTile();
Attributes

Windows 10 requirements

Device family
Windows 10 (introduced v10.0.10240.0 - for Xbox, see UWP features that aren't yet supported on Xbox)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Examples

The following example creates and pins a secondary tile to the Start screen.

using Windows.UI.StartScreen;

// Prepare package images for all four tile sizes in our tile to be pinned as well as for the square30x30 logo used in the Apps view.  
Uri square150x150Logo = new Uri("ms-appx:///Assets/square150x150Tile-sdk.png");
Uri wide310x150Logo = new Uri("ms-appx:///Assets/wide310x150Tile-sdk.png");
Uri square310x310Logo = new Uri("ms-appx:///Assets/square310x310Tile-sdk.png"); 
Uri square30x30Logo = new Uri("ms-appx:///Assets/square30x30Tile-sdk.png");

// During creation of secondary tile, an application may set additional arguments on the tile that will be passed in during activation.
// These arguments should be meaningful to the application. In this sample, we'll pass in the date and time the secondary tile was pinned.
string tileActivationArguments = MainPage.logoSecondaryTileId + " WasPinnedAt=" + DateTime.Now.ToLocalTime().ToString();

// Create a Secondary tile with all the required arguments.
// Note the last argument specifies what size the Secondary tile should show up as by default in the Pin to start fly out.
// It can be set to TileSize.Square150x150, TileSize.Wide310x150, or TileSize.Default.  
// If set to TileSize.Wide310x150, then the asset for the wide size must be supplied as well.
// TileSize.Default will default to the wide size if a wide size is provided, and to the medium size otherwise. 
SecondaryTile secondaryTile = new SecondaryTile(MainPage.logoSecondaryTileId,
                                                "Title text shown on the tile",
                                                tileActivationArguments,
                                                square150x150Logo,
                                                TileSize.Square150x150);

// Pin the tile
bool isPinned = await tile.RequestCreateAsync();
if (isPinned) {
    // Secondary tile successfully pinned.
} 
else {
    // Secondary tile not pinned.
}

// Prepare package images for use as the Tile Logo and Small Logo in our tile to be pinned.
var uriLogo = new Windows.Foundation.Uri("ms-appx:///images/SecondaryTileDefault-sdk.png");
var uriSmallLogo = new Windows.Foundation.Uri("ms-appx:///images/smallLogoSecondaryTile-sdk.png");

// Create a tile to be be pinned.

// During creation of secondary tiles, an application can set additional arguments on the tile 
// that will be passed in during activation. These arguments should be meaningful to the application. 
// In this example, we'll pass in the date and time that the Secondary Tile was pinned.
var currentTime = new Date();
var tileActivationArguments = "timeTileWasPinned=" + currentTime;

// Specify the short name to display on the tile, the display name, arguments to be passed in 
// during activation, attributes regarding how to display the tile by default, and the tile logo.
// Note that you should pick a unique ID that is descriptive and meaningful to your application. 
// In this case, we explicitly code a single ID to focus our attention on the pinning operation.

var tile = new Windows.UI.StartScreen.SecondaryTile("SecondaryTile.01", 
                                                    "A Secondary Tile", 
                                                    "Secondary Tile Sample Secondary Tile", 
                                                    tileActivationArguments, 
                                                    Windows.UI.StartScreen.TileOptions.showNameOnLogo, 
                                                    uriLogo);

// Specify a foreground text value.
// The secondary tile background color over which this text is shown is inherited from the 
// parent app unless a separate value is specified.
tile.foregroundText = Windows.UI.StartScreen.ForegroundText.dark;

// The small tile logo is inherited from the parent app unless overridden as we do here.
tile.smallLogo = uriSmallLogo;

// Attempt to pin the tile.
// Note that the status message is updated when the async operation to pin the tile completes.

tile.requestCreateAsync().then(function (isCreated) {
    if (isCreated) {
        // Secondary tile successfully pinned.
    } else {
        // Secondary tile not pinned.
    }
});

The following example demonstrates how to delete (unpin) a secondary tile by using the RequestDeleteAsync method. Note that this example assumes that the tile exists. To determine whether the tile is pinned before you call RequestDeleteAsync, see the Exists method.

// Check if the secondary tile is pinned
if (SecondaryTile.Exists(tileId)) {
    // Initialize a secondary tile with the same tile ID you want removed
    SecondaryTile toBeDeleted = new SecondaryTile(tileId);

    // And then unpin the tile
    bool isDeleted = await toBeDeleted.RequestDeleteAsync();
    if (isDeleted) {
        // Secondary tile successfully deleted.
    } else {
        // Secondary tile not deleted.
    }
}

// Specify the secondary tile to be deleted, using the ID that it was given when it was originally created.
var tileToBeDeleted = new Windows.UI.StartScreen.SecondaryTile("SecondaryTile.01");

// Make the delete request.
tileToBeDeleted.requestDeleteAsync().then(function (isDeleted) {
    if (isDeleted) {
        // Secondary tile successfully deleted.
    } else {
        // Secondary tile not deleted.
    }
});

The following example demonstrates how to use the FindAllForPackageAsync method to retrieve a list of IDs for all secondary tiles created for the calling app and any other app in the same package.

// Get all secondary tiles
var tiles = await SecondaryTile.FindAllAsync();

Windows.UI.StartScreen.SecondaryTile.findAllForPackageAsync().done(function (tiles) {
    tiles.forEach(function (tile) {
        var myTileId = tile.tileId;
        // Continue to process as necessary.
    });
});

The following example demonstrates how to use the TileUpdateManager.createTileUpdaterForSecondaryTile method to send a notification to a secondary tile with an ID of "SecondaryTile.Dynamic". Note that the example provides both a wide and square version of the notification because the user has control over which form of the tile is showing.

using NotificationsExtensions.TileContent;

// Define the notification context.
// Note: This sample contains an additional reference, NotificationsExtensions, which you can use in your apps
ITileWide310x150Text04 tileContent = TileContentFactory.CreateTileWide310x150Text04();
tileContent.TextBodyWrap.Text = "Sent to a secondary tile from NotificationsExtensions!";

// Provide a square version of the notification.
ITileSquare150x150Text04 squareContent = TileContentFactory.CreateTileSquare150x150Text04();
squareContent.TextBodyWrap.Text = "Sent to a secondary tile from NotificationExtensions!";
tileContent.Square150x150Content = squareContent;

// Send the notification to the secondary tile by creating a secondary tile updater
TileUpdateManager.CreateTileUpdaterForSecondaryTile(MainPage.dynamicTileId).Update(tileContent.CreateNotification());

var notifications = Windows.UI.Notifications;

// Define the notification content.
var tileXml = notifications.TileUpdateManager.getTemplateContent(notifications.TileTemplateType.tileWide310x150Text04);
var tileTextAttributes = tileXml.getElementsByTagName("text");
tileTextAttributes[0].appendChild(tileXml.createTextNode("Sent to a secondary tile!"));

// Provide a square version of the notification.
var squareTileXml = notifications.TileUpdateManager.getTemplateContent(notifications.TileTemplateType.tileSquare150x150Text04);
var squareTileTextAttributes = squareTileXml.getElementsByTagName("text");
squareTileTextAttributes[0].appendChild(squareTileXml.createTextNode("Sent to a secondary tile!"));

// Add the medium tile to the notification.
var node = tileXml.importNode(squareTileXml.getElementsByTagName("binding").item(0), true);
tileXml.getElementsByTagName("visual").item(0).appendChild(node);

// Create the notification based on the XML content.
var tileNotification = new notifications.TileNotification(tileXml);

// Create a secondary tile updater, passing it the ID of the tile.
var tileUpdater = notifications.TileUpdateManager.createTileUpdaterForSecondaryTile("SecondaryTile.Dynamic");

// Send the notification to the secondary tile.
tileUpdater.update(tileNotification);

The following example demonstrates how to use the BadgeUpdateManager.createBadgeUpdaterForSecondaryTile method to send a numeric badge notification to a secondary tile with an ID of "SecondaryTile.Dynamic".

using NotificationsExtensions.BadgeContent;

// Define the badge content
BadgeNumericNotificationContent badgeContent = new BadgeNumericNotificationContent(6);

// Send the notification to the secondary tile
BadgeUpdateManager.CreateBadgeUpdaterForSecondaryTile(MainPage.dynamicTileId).Update(badgeContent.CreateNotification());

var notifications = Windows.UI.Notifications;

// Define the badge content
var badgeNotification = notifications.BadgeUpdateManager.getTemplateContent(notifications.BadgeTemplateType.badgeNumber);
var badgeAttributes = badgeNotification.getElementsByTagName("badge");
badgeAttributes[0].setAttribute("value", "6");

// Create the notification based on the XML content.
var badge = new notifications.BadgeNotification(badgeNotification);

// Create a secondary tile updater, passing it the ID of the tile.
notifications.BadgeUpdateManager.createBadgeUpdaterForSecondaryTile("SecondaryTile.Dynamic");

// Send the notification to the secondary tile.
tileUpdater.update(tileNotification);

Constructors

SecondaryTile() SecondaryTile() SecondaryTile() SecondaryTile() SecondaryTile()

Creates a SecondaryTile object. The caller must then set any mandatory properties through the object before attempting to pin, update, or delete the tile.

SecondaryTile(String) SecondaryTile(String) SecondaryTile(String) SecondaryTile(String) SecondaryTile(String)

Creates a SecondaryTile object with a specific ID. This form of the constructor should be used to create a secondary tile object to perform a tile update or deletion.

SecondaryTile(String, String, String, String, TileOptions, Uri) SecondaryTile(String, String, String, String, TileOptions, Uri) SecondaryTile(String, String, String, String, TileOptions, Uri) SecondaryTile(String, String, String, String, TileOptions, Uri) SecondaryTile(String, String, String, String, TileOptions, Uri)

Note

This constructor may be altered or unavailable for releases after Windows 8.1. Instead, use SecondaryTile.SecondaryTile(String, String, String, Uri, TileSize).

Creates a SecondaryTile object as a medium tile.

SecondaryTile(String, String, String, String, TileOptions, Uri, Uri) SecondaryTile(String, String, String, String, TileOptions, Uri, Uri) SecondaryTile(String, String, String, String, TileOptions, Uri, Uri) SecondaryTile(String, String, String, String, TileOptions, Uri, Uri) SecondaryTile(String, String, String, String, TileOptions, Uri, Uri)

Note

This constructor may be altered or unavailable for releases after Windows 8.1. Instead, use SecondaryTile.SecondaryTile(String, String, String, Uri, TileSize) and supply other tile sizes and options through SecondaryTile.VisualElements method.

Creates a SecondaryTile object as a wide tile.

On Windows Phone 8.1, all tiles— including secondary tiles— are pinned at as medium tiles, after which they can be resized by the user. This constructor provides that option of resizing to a wide tile.

SecondaryTile(String, String, String, Uri, TileSize) SecondaryTile(String, String, String, Uri, TileSize) SecondaryTile(String, String, String, Uri, TileSize) SecondaryTile(String, String, String, Uri, TileSize) SecondaryTile(String, String, String, Uri, TileSize)

Creates a SecondaryTile object that includes all of the mandatory properties required to create a medium tile.

Properties

Arguments Arguments Arguments Arguments Arguments

Gets or sets an app-defined set of information that is passed from the secondary tile to the app on activation. This property is required when you create a tile.

BackgroundColor BackgroundColor BackgroundColor BackgroundColor BackgroundColor

Note

BackgroundColor may be altered or unavailable for releases after Windows 8.1. Instead, use SecondaryTileVisualElements.BackgroundColor.

Gets or sets the tile's background color.

DisplayName DisplayName DisplayName DisplayName DisplayName

Gets or sets a name that is associated with and displayed on the tile. This name is displayed on the tile in Start, in the tile's tooltip, next to the small tile representation in the Apps list, and in some Control Panel applications. This property is required when you create a tile. It is the equivalent of the display name declared in the manifest for the app's main tile.

On Windows Phone 8.1, the display name is shown only on the wide secondary tile.

ForegroundText ForegroundText ForegroundText ForegroundText ForegroundText

Note

ForegroundText may be altered or unavailable for releases after Windows 8.1. Instead, use SecondaryTileVisualElements.ForegroundText.

Gets or sets whether the tile should use dark or light text.

LockScreenBadgeLogo LockScreenBadgeLogo LockScreenBadgeLogo LockScreenBadgeLogo LockScreenBadgeLogo

Gets or sets the location of a badge logo image to represent the secondary tile on the lock screen. By supplying this image, you declare that the secondary tile is eligible to display a badge on the lock screen. If you also want the secondary tile to be eligible for the lock screen's detailed tile slot, you must also set the LockScreenDisplayBadgeAndTileText property to True.

Note

Stating that your secondary tile is eligible for a lock screen presence does not guarantee that it will have one. Only the user can add an app to one of the seven lock screen slots. For more information, see the Lock screen overview.

LockScreenDisplayBadgeAndTileText LockScreenDisplayBadgeAndTileText LockScreenDisplayBadgeAndTileText LockScreenDisplayBadgeAndTileText LockScreenDisplayBadgeAndTileText

Gets or sets whether the secondary tile is eligible to display both a badge and a detailed tile on the lock screen. If you set this property to True, you must also provide a badge image through the LockScreenBadgeLogo property. If you do not want to use the detailed tile capability, provide a badge image through the LockScreenBadgeLogo property and set LockScreenDisplayBadgeAndTileText to False.

Note

Stating that your secondary tile is eligible for a lock screen presence does not guarantee that it will have one. Only the user can add an app to one of the seven lock screen slots, as well as choosing which one of them can display detailed tile information. For more information, see the Lock screen overview.

Logo Logo Logo Logo Logo

Note

Logo may be altered or unavailable for releases after Windows 8.1. Instead, use SecondaryTileVisualElements.Square150x150Logo.

Gets or sets the logo image used in a medium tile. This property is required when you create either a square or a wide tile.

PhoneticName PhoneticName PhoneticName PhoneticName PhoneticName

Gets or sets a phonetic version of the secondary tile name. Used with character-based languages for UI sorting purposes.

RoamingEnabled RoamingEnabled RoamingEnabled RoamingEnabled RoamingEnabled

Gets or sets a value that determines whether the secondary tile will be reacquired through the cloud when the parent app is installed by the user, using their Microsoft account, on another computer. Note that as of Windows 8.1, roaming is the default behavior. This is the opposite of the default Windows 8 behavior, where roaming was opt-in.

This property always returns false on Windows Phone 8.1.

ShortName ShortName ShortName ShortName ShortName

Note

ShortName may be altered or unavailable for releases after Windows 8.1. Instead, use SecondaryTile.DisplayName.

Gets or sets a short name to display directly on the tile.

Note

As of Windows 8.1, this property is ignored and the display name declared in the manifest is used in its place.

SmallLogo SmallLogo SmallLogo SmallLogo SmallLogo

Note

SmallLogo may be altered or unavailable for releases after Windows 8.1. Instead, use SecondaryTileVisualElements.Square30x30Logo.

Gets or sets the small logo image, used in search results, the All Programs list, and other locations in the UI.

The small logo is not used with a Windows Phone 8.1 secondary tile.

TileId TileId TileId TileId TileId

Gets or sets a unique string to identify the tile within the package. This property is required when you create or delete a tile.

TileOptions TileOptions TileOptions TileOptions TileOptions

Note

TileOptions may be altered or unavailable for releases after Windows 8.1. Instead, use SecondaryTile.VisualElements.

Gets or sets options available to a secondary tile.

VisualElements VisualElements VisualElements VisualElements VisualElements

Gets an object through which you can get or set a secondary tile's background color, foreground text, tile images, and app name display options. As of Windows 8.1, the properties of this object replace these SecondaryTile properties:

WideLogo WideLogo WideLogo WideLogo WideLogo

Note

WideLogo may be altered or unavailable for releases after Windows 8.1. Instead, use SecondaryTileVisualElements.Wide310x150Logo.

Gets or sets the logo image used in a wide secondary tile. This property is required when you create a wide secondary tile and gives the user the option of a wide tile when they resize the tile.

Methods

Exists(String) Exists(String) Exists(String) Exists(String) Exists(String)

Checks whether a specific secondary tile exists for the calling app.

FindAllAsync() FindAllAsync() FindAllAsync() FindAllAsync() FindAllAsync()

Retrieves a list of secondary tiles created for the calling app.

FindAllAsync(String) FindAllAsync(String) FindAllAsync(String) FindAllAsync(String) FindAllAsync(String)

Retrieves a list of secondary tiles created for another app in the same package as the calling app.

FindAllForPackageAsync() FindAllForPackageAsync() FindAllForPackageAsync() FindAllForPackageAsync() FindAllForPackageAsync()

Retrieves a list of secondary tiles created for all of the apps in the package of the calling app.

When an app launches, it should always enumerate its secondary tiles through this method, in case there were any additions or deletions of which it was unaware. When a secondary tile is deleted through the Start screen app bar, Windows simply removes the tile. The app itself is responsible for releasing any resources that were used by the secondary tile. When secondary tiles are copied through the cloud, current tile or badge notifications on the secondary tile, scheduled notifications, push notification channels, and Uniform Resource Identifier (URI) used with periodic notifications are not copied with the secondary tile and must be reset up.

RequestCreateAsync() RequestCreateAsync() RequestCreateAsync() RequestCreateAsync() RequestCreateAsync()

Displays the Pin to Start flyout, through which the user can confirm that they want to create the secondary tile, which in turn creates the tile. Overloads of this method let you specify the on-screen location of the flyout.

Note

It is a best practice to display the Pin to Start flyout near the button that invoked the request to create the tile. Therefore, we recommend that you use the RequestCreateAsync(Point) form of this method overload.

On Windows Phone 8.1, the secondary tile is created through this call without showing the user a flyout, prompting them for confirmation, or allowing them to choose a tile size or title text. Note that when using the RequestCreateAsync method to pin a secondary tile in Windows Phone 8.x app, the app is suspended and the user is taken to the Start screen. This same API call on a PC does not suspend the program. Therefore, be aware that any code called after RequestCreateAsync is not guaranteed to be run before the app is suspended. To avoid this potential issue you should use the OnSuspended event of your app to run any code, such as updating the pinned tile, that should be run before the app suspends. To see an example of this pattern, download and run the Tile update on suspend sample.

RequestCreateAsync(Point) RequestCreateAsync(Point) RequestCreateAsync(Point) RequestCreateAsync(Point) RequestCreateAsync(Point)

Displays the Pin to Start flyout above a specified location, through which the user can confirm that they want to create the secondary tile, which in turn creates the tile.

On Windows Phone 8.1, the secondary tile is created through this call without showing the user a flyout, prompting them for confirmation, or allowing them to choose a tile size or title text. Note that when using the RequestCreateAsync method to pin a secondary tile in Windows Phone 8.x app, the app is suspended and the user is taken to the Start screen. This same API call on a PC does not suspend the program. Therefore, be aware that any code called after RequestCreateAsync is not guaranteed to be run before the app is suspended. To avoid this potential issue you should use the OnSuspended event of your app to run any code, such as updating the pinned tile, that should be run before the app suspends. To see an example of this pattern, download and run the Tile update on suspend sample.

RequestCreateForSelectionAsync(Rect) RequestCreateForSelectionAsync(Rect) RequestCreateForSelectionAsync(Rect) RequestCreateForSelectionAsync(Rect) RequestCreateForSelectionAsync(Rect)

Displays the Pin to Start flyout above a specified area. This flyout is used by the user to confirm that they want to create the secondary tile, which in turn creates the tile.

On Windows Phone 8.1, the secondary tile is created through this call without showing the user a flyout, prompting them for confirmation, or allowing them to choose a tile size or title text. Note that when using the RequestCreateAsync method to pin a secondary tile in Windows Phone 8.x app, the app is suspended and the user is taken to the Start screen. This same API call on a PC does not suspend the program. Therefore, be aware that any code called after RequestCreateAsync is not guaranteed to be run before the app is suspended. To avoid this potential issue you should use the OnSuspended event of your app to run any code, such as updating the pinned tile, that should be run before the app suspends. To see an example of this pattern, download and run the Tile update on suspend sample.

RequestCreateForSelectionAsync(Rect, Placement) RequestCreateForSelectionAsync(Rect, Placement) RequestCreateForSelectionAsync(Rect, Placement) RequestCreateForSelectionAsync(Rect, Placement) RequestCreateForSelectionAsync(Rect, Placement)

Displays the Pin to Start flyout at the specified side of a specified area. This flyout is used by the user to confirm that they want to create the secondary tile, which in turn creates the tile.

On Windows Phone 8.1, the secondary tile is created through this call without showing the user a flyout, prompting them for confirmation, or allowing them to choose a tile size or title text. Note that when using the RequestCreateAsync method to pin a secondary tile in Windows Phone 8.x app, the app is suspended and the user is taken to the Start screen. This same API call on a PC does not suspend the program. Therefore, be aware that any code called after RequestCreateAsync is not guaranteed to be run before the app is suspended. To avoid this potential issue you should use the OnSuspended event of your app to run any code, such as updating the pinned tile, that should be run before the app suspends. To see an example of this pattern, download and run the Tile update on suspend sample.

RequestDeleteAsync() RequestDeleteAsync() RequestDeleteAsync() RequestDeleteAsync() RequestDeleteAsync()

Displays the Unpin from Start flyout. This flyout lets the user confirm removal of the secondary tile.

RequestDeleteAsync(Point) RequestDeleteAsync(Point) RequestDeleteAsync(Point) RequestDeleteAsync(Point) RequestDeleteAsync(Point)

Displays the Unpin from Start flyout at a specified point. This flyout lets the user confirm removal of the secondary tile.

RequestDeleteForSelectionAsync(Rect) RequestDeleteForSelectionAsync(Rect) RequestDeleteForSelectionAsync(Rect) RequestDeleteForSelectionAsync(Rect) RequestDeleteForSelectionAsync(Rect)

Displays the Unpin from Start flyout above a specified area. This flyout lets the user confirm removal of the secondary tile.

RequestDeleteForSelectionAsync(Rect, Placement) RequestDeleteForSelectionAsync(Rect, Placement) RequestDeleteForSelectionAsync(Rect, Placement) RequestDeleteForSelectionAsync(Rect, Placement) RequestDeleteForSelectionAsync(Rect, Placement)

Displays the Unpin from Start flyout at the specified side of a specified area. This flyout lets the user confirm removal of the secondary tile.

UpdateAsync() UpdateAsync() UpdateAsync() UpdateAsync() UpdateAsync()

Updates a secondary tile after that tile is pinned to the Start screen.

On Windows Phone 8.1, your app is suspended and the user is taken to the Start screen when a secondary tile is pinned. Therefore, be aware that any code called after RequestCreateAsync is not guaranteed to be run before the app is suspended. To avoid this potential issue you should use the OnSuspended event of your app to run any code, such as updating the pinned tile, that should be run before the app suspends. To see an example of this pattern, download and run the Tile update on suspend sample.

Events

VisualElementsRequested VisualElementsRequested VisualElementsRequested VisualElementsRequested VisualElementsRequested

Fired when a call is made to RequestCreateAsync.

This event is not raised on Windows Phone 8.1.

See Also