Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

SecondaryTile class

Applies to Windows and Windows Phone

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

Syntax


public ref class SecondaryTile sealed 

Attributes

[Muse()]
[Version(0x06020000)]

Members

The SecondaryTile class has these types of members:

Constructors

The SecondaryTile class has these constructors.

ConstructorDescription
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) 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) Creates a SecondaryTile object as a medium tile.
SecondaryTile(String, String, String, String, TileOptions, Uri, Uri) Creates a SecondaryTile object as a wide tile.
SecondaryTile(String, String, String, Uri, TileSize) Creates a SecondaryTile object that includes all of the mandatory properties required to create a medium tile.

 

Events

The SecondaryTile class has these events.

EventDescription
VisualElementsRequested Fired when a call is made to RequestCreateAsync.

 

Methods

The SecondaryTile class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.

MethodDescription
Exists Checks whether a specific secondary tile exists for the calling app.
FindAllAsync() Retrieves a list of secondary tiles created for the calling app.
FindAllAsync(String) Retrieves a list of secondary tiles created for another app in the same package as the calling app.
FindAllForPackageAsync Retrieves a list of secondary tiles created for all of the apps in the package of the calling app.
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.
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.
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.
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.
RequestDeleteAsync() Displays the Unpin from Start flyout. This flyout lets the user confirm removal of the secondary tile.
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) Displays the Unpin from Start flyout above a specified area. This flyout lets the user confirm removal of the secondary tile.
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 Updates a secondary tile after that tile is pinned to the Start screen.

 

Properties

The SecondaryTile class has these properties.

PropertyAccess typeDescription

Arguments

Read/writeGets 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

Read/writeGets or sets the tile's background color.

DisplayName

Read/writeGets 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.

ForegroundText

Read/writeGets or sets whether the tile should use dark or light text.

LockScreenBadgeLogo

Read/writeGets 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.

LockScreenDisplayBadgeAndTileText

Read/writeGets or sets whether the secondary tile is eligible to display both a badge and a detailed tile on the lock screen.

Logo

Read/writeGets 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

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

RoamingEnabled

Read/writeGets 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.

ShortName

Read/writeGets or sets a short name to display directly on the tile. As of Windows 8.1, this property is ignored and the display name declared in the manifest is used in its place.

SmallLogo

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

TileId

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

TileOptions

Read/writeGets or sets options available to a secondary tile.

VisualElements

Read-onlyGets an object through which you can get or set a secondary tile's background color, foreground text, tile images, and app name display options.

WideLogo

Read/writeGets 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.

 

Examples

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



// 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.



// 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.



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.



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".



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

Requirements

Minimum supported client

Windows 8 [Windows Store apps only]

Minimum supported server

Windows Server 2012 [Windows Store apps only]

Minimum supported phone

Windows Phone 8.1 [Windows Phone Silverlight 8.1 and Windows Runtime apps]

Namespace

Windows.UI.StartScreen
Windows::UI::StartScreen [C++]

Metadata

Windows.winmd

See also

Secondary tiles sample

 

 

Show:
© 2014 Microsoft