Working with custom icon overlays in pinned sites

Article
03/03/2016

In this task you learn how to create, set, and clear icon overlays to notify the user of activity within your Pinned site.

Note To view an icon overlay, the taskbar buttons must be in their default large icon mode. Small taskbar icons do not support icon overlays. In addition, icon overlays are visible only while the Pinned site window is running. The icon is removed from the taskbar button when the Pinned site window is closed.

Note For more information about notifications in Windows 8, see Pinned site notifications in Windows 8.

Methods used in this task
- msSiteModeSetIconOverlay(bstrIconUrl, bstrDescription)
- msSiteModeClearIconOverlay()
Creating icon overlays
Using icons to relay information
Setting the icon overlay
Clearing the icon overlay
Putting it all together
More examples
- Facebook notifications
Related topics

Methods used in this task

The following methods are introduced in this topic:

msSiteModeSetIconOverlay(bstrIconUrl, bstrDescription)

By using the window.external.msSiteModeSetIconOverlay method, you can add a 16x16 pixel icon overlay to the Pinned Site's taskbar button that you can use to communicate alerts, notifications, and application status to users.

msSiteModeClearIconOverlay()

The window.external.msSiteModeClearIconOverlay method removes the icon overlay from the taskbar button.

Creating icon overlays

An overlay icon is a small 16x16 pixel graphic that appears on top of the taskbar button icon. You are probably already familiar with icon overlays. Two common examples are the small arrow that distinguishes desktop shortcuts from files, and the shield on application icons for applications that require administrator privileges to run. On the taskbar, icon overlays take on a slightly different meaning. Here, you might think of them as "notification" icons, because they can notify the user of activity in your application.

You can create icons for icon overlays by using X-Icon Editor just as you did with the site icon in Customizing the Site Icon. X-Icon Editor is a free application (based on HTML5 Canvas) that allows you to create high resolution icons directly from within the browser. You can import a variety of images into the editor and quickly convert them to icons. For example, the following 16x16 pixel icon overlays were created from images.

All you need to begin is a square image—simple or whimsical—that suits the style of your website. After you import the image into X-Icon Editor, be sure to remove any background color. You can do this by using the Eraser tool to erase the background, or by using the Paint Can tool to fill the background area with a purely transparent color. For the best detail, edit the 64x64 pixel icon first, and then copy the image to 32x32, and so on. Before you export the icon, clear the icon sizes that you do not need to minimize the size of the resulting file.

Using icons to relay information

Consider how to make your icons as intuitive to your users as possible. Notification icons can relay information about the state of the application, such as the number of messages received, as shown in the following numeric icon overlays.

There are limits to what you can do with numeric icons, however. Although single digits work well, larger numbers can be hard to read. Also, each number requires its own icon resource, which can be difficult to create and manage, and which significantly increases the number of file requests made to the site. If you create numeric icon overlays, consider including a generic symbol for numbers outside the range you have provided, such as the yellow star in the previous image.

You can also create numeric icons in X-Icon Editor. First, start with a background image large enough to contain a wide number, like 5 or 8. Then, apply a number and export the icon. To create the next icon, just click the Undo arrow to remove the number before applying the next number in sequence.

Note Be creative. Try to add meaning to your application through your choice of icons.

Setting the icon overlay

You can display an overlay icon by using the msSiteModeSetIconOverlay method, as shown in the following code example.

function setOverlayIcon(iconUri, descText)
{
    try {
        if (window.external.msIsSiteMode()) {
            window.external.msSiteModeSetIconOverlay(iconUri, descText);
        }
    }
    catch (e) {
        // Fail silently.
    }
}

Note The bstrDescription parameter provides an accessible description of the information conveyed by the icon overlay. Choose text that can be read by screen readers.

This call replaces the previous icon overlay, if any existed. If the taskbar button is grouped with others, the stack displays only the most recent icon overlay.

Clearing the icon overlay

To remove the icon overlay, call the msSiteModeClearIconOverlay method, as shown in the following example.

function clearOverlayIcon()
{
    try {
        if (window.external.msIsSiteMode()) {
            window.external.msSiteModeClearIconOverlay();
        }
    }
    catch (e) {
        // Fail silently.
    }
}

Putting it all together

The TweetFeed sample application displays up to five recent tweets based on the specified search string, and it uses icon overlays to inform the user of current activity. For example, the magnifying glass appears when the application is searching for new tweets.

The following script, modified slightly from the original TweetFeed sample, shows one way to encapsulate the icon overlay code into a single function. This code relies on the functions defined earlier in this task.

var states = { CLEAR: 0, COMPLETE: 1, ERROR: 2, SEARCH: 3 };
var messages = [ "Waiting...",
                 "Searching tweets...",
                 "Found a tweet!",
                 "Oops! Twitter error." ];

function setStatus(status)
{
    switch (status) {
        case states.CLEAR:
            clearOverlayIcon();
            break;

        case states.COMPLETE:
            if (unreadTweetCounter == 0) {
                clearOverlayIcon();
            }
            else {
                setOverlayIcon('Images/num_' + unreadTweetCounter + '.ico',
                                messages[2]);
            }
            break;

        case states.ERROR:
            if (unreadTweetCounter == 0) {
                setOverlayIcon('Images/error.ico', messages[3]);
                setTimeout("setStatus(states.CLEAR)", 2000);
            }
            break;

        case states.SEARCH:
            setOverlayIcon('Images/search.ico', messages[1]);
            break;
    }
}

Sometimes, you need more than an icon overlay to attract attention. In the Flashing the Pinned Site Taskbar Button task, you learn how to flash the taskbar button to indicate a more urgent need.