We covered the basics of the Windows 7 Taskbar in Developing for the Windows 7 Taskbar – Application ID, and how you can create a Jump List for your application in Developing for the Windows 7 Taskbar – Jump into Jump Lists – Part 1, Part 2, and Part 3). In this post, we will explore how you can leverage the cool Taskbar functionality of dynamic overlay icons and multi-state progress bars.

A central Windows 7 tenet is that the "User Is in Control"; that is, we empower users to take ownership of their desktop looks and functionality. From little things, like allowing users to arrange their Taskbar icons as they see fit, to enabling users to control the number of icons on the Taskbar. Windows 7 “removed” the System Tray Icon area. By default, almost all the tray icons are concealed. Consequently, it is safe to assume that large number of the notification balloons will also not be visible and most users will not see them. You can read more about the updates to the Notification Area here. To compensate for this lack of notification, Windows 7 Taskbar offers Overlay Icons and Progress Bars. By using overlay icons and progress bars, your application can provide contextual status information to the user in spite of the lack of a System Tray Icon area and even if the application’s window does not display. 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. This functionality is part of our commitment to provide users with easily accessible information about an application's status without any extra clicking.

Overlay Icons

The ITaskbarList4 interface, specifically its SetOverlayIcon function, exposes the native overlay functionality. The function takes a window handle, an icon handle, and optional description text, as you can see in the following code snippet.

HICON hIcon = NULL; // for IDM_OVERLAY_CLEAR
hIcon = LoadIcon(g_hInstance, MAKEINTRESOURCE(IDI_OVERLAY1));
// Set the window's overlay icon, possibly NULL value
g_pTaskbarList->SetOverlayIcon(hWnd, hIcon, NULL);
if (hIcon) {
// need to clean up the icon as we no longer need it
DestroyIcon(hIcon);
}

Make sure you obtain ITaskbarList3 *g_pTaskbarList = NULL;as we did before, and CoCreate it:

CoCreateInstance(
    CLSID_TaskbarList, 
    NULL, 
    CLSCTX_INPROC_SERVER, 
    IID_PPV_ARGS(&g_pTaskbarList));

The managed wrapper for this feature resides in the Taskbar class that is part of the Windows API Code Pack for the .NET Framework. All that you need to do is use the OverlayImage property (Taskbar.OverlayImage). Simply call:

Taskbar.OverlayImage = 
        new OverlayImage(TaskbarDemo.Properties.Resources.Red, "Red");

Doing so allows you to provide an OverlayImage for the taskbar button. The TaskbarDemo project is a WinForms demo, and you can find the above code in the TaskbarDemoMainForm.cs.

It’s equally easy to provide an extension method that does this to a WPF Window. Note that the only thing that you need to do is get the right icon, which is easy using .NET resources.

Progress Bars

If you already use a standard progress bar in your application’s top level window, the DMW will pick it up and, by default, display its progress as an overlay on top of your application. However, you can programmatically control the progress bar behavior on your application’s icon.

The native functionality is again found in the ITaskbarList3 interface, this time in the SetProgressState and SetProgressValue functions. The functions are quite self-explanatory. You can set the progress bar’s state (SetProgressState) to, for example, indeterminate or error, and use SetProgressValue to set the progress value. The following code snippet illustrates how to use these functions:

case WM_TIMER:
    g_nProgress++;
    if (g_nProgress == 1)
    {
        // First time through, so we'll set our progress state
        // to be indeterminate - this simulates a background 
        // computation to figure out how much progress we'll need.
        g_pTaskbarList->SetProgressState(hWnd, TBPF_INDETERMINATE);
    }
    else if (g_nProgress == MAX_PROGRESS_IND)
    {
        // Now set the progress state to indicate we have some 
        // normal progress to show.
        g_pTaskbarList->SetProgressValue(hWnd, 0, MAX_PROGRESS_NORMAL);
        g_pTaskbarList->SetProgressState(hWnd, TBPF_NORMAL);
    }
    else if (g_nProgress > MAX_PROGRESS_IND)
    {
        if (g_nProgress - MAX_PROGRESS_IND <= MAX_PROGRESS_NORMAL)
        {
            // Now show normal progress to simulate a background 
            // operation
            g_pTaskbarList->SetProgressValue(
                                hWnd, 
                                g_nProgress - MAX_PROGRESS_IND, 
                                MAX_PROGRESS_NORMAL);
        }
        else
        {
            // Progress is done, stop the timer and reset progress 
            // state
            KillTimer(hWnd, g_nTimerId);
            g_nTimerId = 0;
            g_pTaskbarList->SetProgressState(hWnd, TBPF_NOPROGRESS);
            MessageBox(hWnd, L"Done!", L"Progress Complete", MB_OK);
        }
    }
    break;

Note that on the first timer tick, we set the progress bar to TBPF_INDETERMINATE, and only after that did we set it to TBPF_NORMAL, which set the progress indicator to grow in size from left to right in proportion to the estimated amount of the operation completed.

For managed code, we use the Windows Code Pack API. Much like the native progress bar, the managed code Taskbar class includes a progress bar property (it is in its own a class), which allows you to set current value, max value, and statethe progress bar state. The progress bar states (found in the TaskbarButtonProgressState class) are:

• NoProgress –equal to the TBPF_NOPROGRESS native state
• Indeterminate –equal to the TBPF_INDETERMINATE native state
• Normal –equal to the TBPF_NORMAL native state
• Error –equal to the TBPF_ERROR native state
• Paused –equal to the TBPF_PAUSED native state

You can find a WinForms demo in the TaskbarDemo project and in the TaskbarDemoMainForm.cs, you can find the UpdateProgressBar function that is called by a timer to update the progress bar.

Taskbar.ProgressBar.State = 
    (TaskbarButtonProgressState)Enum.Parse(
            typeof(TaskbarButtonProgressState), 
            (string)comboBoxProgressBarStates.SelectedItem);

if (Taskbar.ProgressBar.State != TaskbarButtonProgressState.Indeterminate)
    Taskbar.ProgressBar.CurrentValue = progressBar1.Value;

As you can see, the code enables you to choose the state of the progress bar. Changing it to the error state turns the color of the progress bar on the Taskbar Icon to red.

The icing on the Taskbar progress bar "cake" 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.) For example, if you invoke a file operation using the SHFileOperation API or IFileOperation interface, the Taskbar button progress bar automatically displays the progress information (including errors) of that operation. This is what Windows Explorer does with great success.

Original post from Sasha Goldstein

[June 19th - I added a code sample and new screenshots.]

In response to some of the comments I included a link to the download and new screenshots to show the effect of changing Application ID in run time. And Just to make sure we are all on the same page here are two images to illustrate the power of AppID. You can clearly see that the same application (with the same original application ID) can have two different Taskbar buttons. You can also download the code for this application.

Just a note as response to one of the comments. Yes you can place a different Taskbar button between to windows with different AppID!

download the code for this application

You can find the managed code Taskbar object in the Windows API Code pack project.

This is the first post in a new Windows 7 Taskbar series. One of the first Windows 7 changes that developers should pay attention to is the new Windows Taskbar. We all need to understand the functionality this feature introduces so that we can ensure that our applications work well with the Taskbar, resulting in an enhanced experience for our end users.

I assume that by now you are familiar with the basic functionality that Windows 7 Taskbar offers and the reasons behind the change we made from previous taskbar versions. If you are not familiar with and haven’t seen any demonstrations of the Windows 7 Taskbar, please watch the Windows 7 Taskbar Overview webcast on Channel 9. There are also great posts on the E7 blog like The Windows 7 Taskbar about some of the reasons we introduced the new Taskbar and desktop experience in Windows 7. I do encourage you to read these posts and watch the video so that you have some context for the technical material we are going to cover here.

The new Taskbar is probably the most noticeable change to Windows 7 when you first log on. The Windows 7 Taskbar is an application-launching and window-switching mechanism that consolidates the functions of previous Windows Desktop mechanisms, such as Quick Launch, Recent Documents, Notification Area icons, desktop shortcuts, and running application windows. Windows 7 Taskbar offers features like Jump Lists, Preview Handler, and Overlay Icons. But before we start diving into the various Windows 7 Taskbar features, let’s lay the basic foundation to our discussion and define some Windows 7 taskbar terminology.

The basic component is the Taskbar button. The Taskbar button is represented as an icon displayed on the Taskbar. As you can see in the following image, the Taskbar contains several buttons. You can tell what their status is by how they are displayed.

For example, the Media Player button has no frame or border, but simply sits directly on the Taskbar. This indicates that Media Player is not running. But it is pinned to the Taskbar, and will stay on the Taskbar unless we unpin it. A transparent frame that lets most of the color of the underlying Taskbar through the Windows Explorer button. This indicates that the app is running but is not the active application. The Visual Studio icon has a more opaque rectangular frame underlying its icon indicating that the user is actively using this app. You will also notice that Word has a “stack” of icons representing that multiple instances of Word or multiple Windows are grouped under the same Taskbar button. It is very important to understand the logic that underlies the creation, assignment, and grouping of Taskbar buttons.

A very large number of applications that run on Windows 7 (for example, Office Word 2007 and Visual Studio 2008), were not designed to work with the Windows 7 Taskbar, so how is it that they can play ball with the Taskbar, group multiple instances, and even take advantage of Word Jump Lists? Basically, a behind-the-scenes Application ID (AppID) is automatically computed and assigned to an application once you launch it. Every running application has an AppID assigned to it, either automatically computed for the app by Windows, or set by the app itself. Guess what? It is not a GUID; it is just a string (with a maximum of 128 characters), that either you provide or is being computed by the OS. All windows and applications, including Jump Lists, which have the same AppID are grouped under the same Taskbar button. Therefore, it is important to understand that every component (process, shortcut, window, Taskbar button, and document type – that is, registered file type handler) of your application has the AppID associated with it.

You may ask, "Where do AppIDs come from?" As mentioned before, the OS generates Application IDs for your application using a very simple, yet important to understand heuristic. Since in Windows 7 you can assign AppIDs to individual windows, the OS tries to extrapolate the AppID from a window. Applications usually display at least one window that the OS can query for its AppID. However, most existing apps do not have an AppID attached to each window (or, for that matter, any AppID at all), and therefore the OS falls back to the process to which the window belongs for the AppID. Each process has several properties that the OS can check, like the executable of the process. But even then, the process may not provide a granular enough separation. Different shortcuts may provide different start up command line parameters to the same executable and launch different applications (imagine a “launcher” application) that will be grouped under the same Taskbar button. In such cases, the OS has the ability to look into the specific shortcut that launched the application, to find the executable, the command line parameters, and so on. Note that if you have a register file, this registration points to an application that gets launched once you double click that file. Again, this is another way to calculate the AppID. The following image illustrates this automatic computation process.

If you are interested in really understanding the internals of the Windows 7 taskbar, a great Channel 9 video describes its underlying architecture. Watch the Rob Jarrett and Ben Bets Windows 7 Taskbar - Behind the Scenes video and, specifically for the Application ID overview, watch Jump into the Windows 7 Taskbar Jump Lists (between 29:30 and 34:40).

While the OS can compute AppIDs for you, you may want to have greater control over the AppID for a given application or even an individual window in your application. Assume that you have an application that hosts (runs) another application (like what happens when you debug an application using Visual Studio). Or you have several different applications or processes that you wish to group under the same Taskbar button. The Taskbar API offers you ways to control the Application ID per application or per window. IN ANY CASE, if you are writing a new application that targets Windows 7, we highly recommend that you provide your own application ID, as we will describe below.

OK, let’s examine the API that allows you to control the AppID associations of your application.

If you want to have a separate Taskbar button for each process (including all windows owned by that process), you can set an explicit AppID for the entire process that affects all windows within the process that do not have their own explicit AppID. Setting the explicit process AppID is very easy. All it takes is a single call to the SetCurrentProcessExplicitAppUserModelID function as shown in the following code snippet:

SetCurrentProcessExplicitAppUserModelID(c_rgszAppID[0]);

In managed code, from the latest Windows API Code Pack Library, you can use the AppID property that is part of the Taskbar object, which you can find in the Microsoft.WindowsAPICodePack.Shell.Taskbar namespace. Using that property you can set and get the application ID of a given application.

Setting the AppID for a window is a bit more complicated (but only a bit). It requires calling the SHGetPropertyStoreForWindow function and then manipulating the resulting IPropertyStore object to retrieve the requested property as shown in the following code snippet:

void SetAppID(HWND hWnd, int iAppID)
{
    IPropertyStore *pps;
    HRESULT hr = SHGetPropertyStoreForWindow(hWnd, IID_PPV_ARGS(&pps));
    if (SUCCEEDED(hr))
    {
        PROPVARIANT pv;
        if (iAppID >= 0)
        {
            hr = InitPropVariantFromString(c_rgszAppID[iAppID], &pv);
        }
        else
        {
            PropVariantInit(&pv);
        }
        if (SUCCEEDED(hr))
        {
            hr = pps->SetValue(PKEY_AppUserModel_ID, pv);
            PropVariantClear(&pv);
        }
        pps->Release();
    }
}

Here you can see how we extract the current windows property store by calling SHGetPropertyStoreForWindow, passing hWnd as refrence to the window. Next we initiate, InitPropVariantFromString(c_rgszAppID[iAppID], &pv), a property variant with a string that represents the AppID for that window. Finally, we set the value of the new property store to the window.

Unfortunately, the current Windows API Code pack doesn’t support setting specific application IDs per window, although all you need to do is add the following function to the Taskbar.cs file:

private static void SetWindowAppId(string appId)
{
    Microsoft.WindowsAPICodePack.Shell.ShellNativeMethods.SetWindowAppId
        (OwnerHandle, "name here");
}

Since the Windows API Code Pack provides the source code, you can actually check the specific implementation of SetWindowAppId function and see for yourself that it is very similar to the SetAppID example above. Note you don’t have to use the full qualified assembly name “Microsoft.WindowsAPICodePack.Shell’, but I did to help you navigate the Windows API Code Pack hierarchy.

By the way, the window AppID is dynamic, so it’s entirely possible for a window to show up as part of one Taskbar button and then change its AppID so that it appears on an entirely different Taskbar button. This has interesting effects. For example, the Jump List is attached to a Taskbar button (with a specific AppID), so the same window might show a different Jump List when it is reattached to an entirely different Taskbar button. This potentially can confuse users, so the recommended practice is to set the window AppID and stick to it, using the same process for determining the AppID every time the window displays.

You can find the managed code Taskbar object in the Windows API Code pack project.

[Sasha Goldshtein helped write this post, and you can find his original posting here].