Windows 8–Secondary Tiles

Continuing my series based on the presentations I’m giving on Europe, today I return to Tiles to look at creating Secondary tiles.

A secondary tile can be created by the user and pinned to the start menu to provide deep access into your program.  A classic example of a secondary tile would be to pin a tile for your home town in a weather application, or a specific stock in a portfolio program.

I’ve stripped down the Microsoft SDK sample to its essentials to make it a bit easier to see how to create a secondary tile.

To begin, create a new application, and as mentioned in the posting on Live Tiles add the NotificationsExtensions project that Microsoft ships with the SDK and with the Sample applications on tiles.

On the home page add this XAML:

   1: <Grid Background="{StaticResource ApplicationPageBackgroundThemeBrush}">

   2:     <StackPanel>

   3:         <TextBlock Name="xMessage"

   4:                    Text="Ready..."

   5:                    FontSize="42" />

   6:         <Button Name="xCreate"

   7:                 Content="Create"

   8:                 FontSize="20"

   9:                 Click="xCreate_Click_1" />

  10:     </StackPanel>

  11: </Grid>

This will create a TextBlock to provide an update message and a button to create the tile.

You will need to create two tile images (or download the source for this project) and place them in your assets folder.  One is for the wide tile, the other for the square.

We begin the event handler by getting the URL of the two images,

   1: private async void xCreate_Click_1(object sender, RoutedEventArgs e)

   2: {

   3:     Uri logo = new Uri("ms-appx:///Assets/squareTile-sdk.png");

   4:     Uri wideLogo = new Uri("ms-appx:///Assets/tile-sdk.png");

You can pass ActivationArguments to your tile, which you get back upon activation to tell you which tile was clicked and where in your program to go.  We’ll create a string for the ActivationArguments,

   1: string tileActivationArguments = dynamicTileId + 

   2:     " WasPinnedAt=" + DateTime.Now.ToLocalTime().ToString();

The constant dynamicTileID is declared at the top of the file, but could be retrieved from a database, etc.

We’re ready to create the Secondary tile,

   1: SecondaryTile secondaryTile = 

   2:     new SecondaryTile(dynamicTileId,

   3:             "A Live Secondary Tile (JL)",

   4:             "Secondary Tile Sample Live Secondary Tile(JL)",

   5:             tileActivationArguments,

   6:             TileOptions.ShowNameOnLogo | TileOptions.ShowNameOnWideLogo,

   7:             logo,

   8:             wideLogo);

The arguments are:

• A string representing the ID
• A string representing the short name
• A string representing the display name
• A string for the ActivationArguments
• TileOptions (an enumerated constant)
• The URI for the logo for the square tile
• The URI for the logo for the wide tile

You can now set properties on the secondary tile such as the foreground text color,

   1: secondaryTile.ForegroundText = ForegroundText.Light;

You are ready to instantiate the tile and pin it to the start menu.  You do so by calling RequestCreateForSelectionAsync on the secondary tile, passing in the location you want to place the flyout,

   1: bool isPinned = 

   2:     await secondaryTile.RequestCreateForSelectionAsync(

   3:         GetElementRect((FrameworkElement)sender), Windows.UI.Popups.Placement.Below);

Note that GetElementRect is a simple helper method that returns a rect given a Framework element.

Assuming the return value is true, you have successfully pinned your secondary tile,

   1: if (isPinned)

   2: {

   3:     xMessage.Text = "Secondary tile successfully pinned.";

   4: }

   5: else

   6: {

   7:     xMessage.Text = "Secondary tile not pinned.";

   8: }

Download the source code here