Windows 7 Taskbar: Overlay Icons and Progress Bars

February 16, 2009

tags:
one comment

Let’s get the easy stuff out of the way before we start building jump lists and customizing live previews.  How do you leverage the cool functionality of having a dynamic overlay icon on your taskbar button or a multi-state progress bar?

For an overview of the fundamental features themselves and the managed wrapper library, you might want to read previous posts in this series.  This post assumes you’re up to speed on the above, and have a copy of the managed wrappers (Windows7.DesktopIntegration) from Code Gallery.

By using overlay icons and progress bars, your application can provide contextual status information to the user even if the application’s window is not shown.  The user doesn’t even have to look at the thumbnail or the live preview of your app – the taskbar button itself can reveal whether you have any interesting status updates.

Overlay Icons

image The native functionality is exposed by the ITaskbarList3 interface, specifically its SetOverlayIcon method.  The method takes a window handle, an icon handle, and an optional description text for accessibility purposes.

The managed wrapper for this feature lives in Windows7Taskbar.SetTaskbarOverlayIcon, which allows you do basically the same thing, but with an Icon class instance instead of an icon handle.  An extension method in the WindowsFormsExtensions.cs file allows you to use a Form instance instead of a window handle.  (It’s equally easy to provide an extension method that does this to a WPF Window.)

The only tricky thing could be that you can set the overlay icon only after the taskbar button for your window has already been created.  This does not happen before the WM_CREATE notification (or, if you’re writing managed code, your form/window’s constructor) – you need to wait for a special message letting you know that it happened.  There is currently no header-file definition for the value of this message, so you must obtain it manually by calling RegisterWindowMessage(L"TaskbarButtonCreated"), or use the Windows7Taskbar.TaskbarButtonCreatedMessage property.  (And handle it in your form/window’s window procedure.)

The IMClient sample shows how to set an overlay icon as a result of changing the selection in the status combo box.

The underlying code is trivial – it’s just a matter of getting the right icon:

private void cmbStatus_SelectedIndexChanged(

    object sender, EventArgs e)

{

    Icon icon = GetIconByStatus(

        (string)cmbStatus.SelectedItem);

    Windows7Taskbar.SetTaskbarOverlayIcon(

        Handle, icon, (string)cmbStatus.SelectedItem);

}

Progress Bars

image The native functionality is again in the ITaskbarList3 interface, this time in the SetProgressState and SetProgressValue methods.  The methods are quite self-explanatory, and allow setting the progress bar’s state (e.g. indetermine, error) and progress value.

The managed wrapper lives in Windows7Taskbar.SetProgressState and Windows7Taskbar.SetProgressValue – the API is simple so the wrapper is thin :-)   Again, there is an extension method in WindowsFormsExtensions.cs that allows you to specify a Form instance instead of a window handle.

Similarly to overlay icons, the taskbar progress bar can’t be manipulated if the window’s taskbar button has not been created yet.

The IMClient sample shows how to change the progress bar’s value and state in response to a “Send File” request that comes from the user.  The code is trivial:

private void sendFileToolStripMenuItem_Click(

    object sender, EventArgs e)

{

    sendFileTimer.Interval = 1000;

    sendFileTimer.Tick += delegate

    {

        _percentFileCompleted += 10;

        if (_percentFileCompleted == 100)

        {

            sendFileTimer.Stop();

            MessageBox.Show("File operation failed!");

            Windows7Taskbar.SetProgressState(

               Handle,

               Windows7Taskbar.ThumbnailProgressState.Error);

            _percentFileCompleted = 0;

        }

        else

        {

            Windows7Taskbar.SetProgressValue(

                Handle,

                (ulong)_percentFileCompleted,

                (ulong)100);

        }

    };

    sendFileTimer.Start();

}

As you see, the code emulates an “error” in order to demonstrate the error state of the progress bar.  As you might expect, the progress bar turns red but still retains the value.

The best part of taskbar progress bars is that you get this functionality FOR FREE if you use the standard progress dialog for file operations (as we advance in this series, you’ll see that you get lots of functionality for free if you follow the standard guidelines of Windows programming).  I.e., if you invoke a file operation using the SHFileOperation API or the new (shipped with Vista) IFileOperation interface, the progress information (including errors) of that operation will be automatically displayed as a progress bar in your taskbar button.  This is what Windows Explorer does, with great success.

Add comment
facebook linkedin twitter email

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

one comment

  1. OliverAugust 4, 2009 ב 11:24 AM

    i am having trouble using this api
    i have installed it but none of the code works

    Reply