Wednesday, September 28, 2011

Windows 8 Secondary Tiles

In the past couple posts I have showed various ways of manipulating the start menu tile for an application. Besides manipulating the main tile your app can also create secondary tiles when the user wants to see more information then can easily be displayed on a single tile. You can see an example of this in the Weather app. Open the app and add a second city, right click to bring up the app bar and click Pin City. Once you do this a second tile will appear on the start screen with the information for that city. Let’s look at how you create a secondary tile.
Before you can create a secondary tile you need, at a minimum, a 150x150 pixel image for the tile. Create the image and save it as a .PNG file in your applications Images directory then add it to the application in solution explorer. Set the Build Action property on the image to Content, and the Copy to Output Directory property to “Copy if Newer” or “Copy Always”. Once you have the image you can use the following code to display it:
Note: You will want to include the Windows.UI.StartScreen namespace in your file.

async public void ShowSecondayTile() 
  Uri logo = new Uri("ms-resource:images/SecondayLogo.png");
  SecondaryTile secondaryTile = new SecondaryTile("MySecondaryTile1",
    "Secondary Tile",
    "Hello World Secondary",
    "Tile 1 activated",
  bool isPinned = await secondaryTile.RequestCreateAsync();

First we need to create a Uri object to point to the tile image we added to the images folder. Next we create the secondary tile object. The parameters passed to the constructor mostly correspond to the properties you set in the manifest for the default startup tile.

  • - tileId: Since you can create more the one secondary tile the tileId uniquely identifies the tile to your application. If you add more then one tile with the tileId the later one will replace the earlier.

  • - shortName: A name that is displayed on the tile if you set the ShowName attribute.

  • - displayName: The name displayed when you hover over the tile.

  • - arguments: A string that you want passed back to your application when the tile is clicked. We will talk more about this later.

  • - displayAttributes: Any attributes you need to set on the tile, for example ShowName.

  • - logoRefernce: Uri of the image to use for the square tile.

Besides the properties you set in the constructor there are also properties on the object for setting things like the WideLogo, SmallLogo, ForegroundText, etc.

Once you have the SecondaryTile object setup the last line requests the creation of the tile. When that line is executed the user will see a popup that looks like this:


This shows an image of the tile, gives the user a chance to change the shortName and has a button to accept the request. If the user accepts, the function will return a true. If they click off the popup the request will be denied and the function will return a false.

One interesting thing to note in this line is the “await” keyword. Await, along with async in the function declaration are new keywords in C# that are used to handle asynchronous functions and you will see these used a lot in Windows 8 Metro applications. The details of how these work are beyond the scope of this article, but in short, execution will not continue to the next line until RequestCreateAsync is complete, but unlike in synchronous programming it won’t block the UI thread either. Essentially the ShowSecondayTile function is suspended until the async function completes.

Once the secondary tile is displayed the user can remove it from the start menu by right clicking it and selecting Remove from the app bar. We can also have our application request the removal of a secondary tile with this code:

async private void RemoveSecondaryTile() 
    var secondaryTile = new SecondaryTile(“MySecondaryTile1”);
    bool isDeleted = await secondaryTile.RequestDeleteAsync();

The first line creates a SecondaryTile object based on the tileId we set when we created the tile, and the second line requests the removal. The removal works just like the creation where the user will be prompted if they want to remove it and the functional will return true of false based on what the user chooses to do.

When the user clicks on a secondary tile, Windows will launch your application just as if they had clicked on the main tile. To determine which secondary tile launched the app you can use the Arguments property on SecondaryTile object. In your application’s App.xaml.cs file you will see the following default code:

protected override void OnLaunched(LaunchActivatedEventArgs args) 
    Window.Current.Content = new MainPage();

The LaunchActivatedEventArgs object contains a string property called Arguments that will contain the contents of the Arguments property we set on the secondary tile. One way to handle this would be to modify the MainPage contructor to accept a LaunchActivatedEventArgs object as a parameter and then modify the OnLaunched event to pass args to MainPage. In the MainPage constructor you can then get the Arguments property and handle it as needed.

While digging a little deeper into secondary tiles I noticed that both the TileUpdateManager and BadgeUpdateManager have methods to create updaters for secondary tile. For badges you call use a line like this to get a secondary tile updater:

var tileUpdater = TileUpdateManager.CreateTileUpdaterForSecondaryTile(“MySecondaryTile1”)

where the parameter passed is the tileId of the secondary tile. This updater would then allow us to show badges on the tile. We should be able to do something similar for notifications but I always got an exception when I called CreateTileUpdaterForSecondayTile(“MySecondaryTile1”) . Not sure if I am doing something wrong or if this is a bug.


galeyev said...

Hi, Dan!
Thx for this post, it is worth to be! But, do you know by chance, is there a way to manipulate whatever Live Tiles' items, for instance programmatically change the position of the IE tile?

Martina Fisher said...

Hey Dan!
Great Post, I liked it very much!I don't know I am new at windows 8. I had problems with the tiles too and found an article if it the same problem described here.