Windows 7 Taskbar Dynamic Overlay Icons and Progress Bars

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 applications window does not display. The user doesnt 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)); When running the above code in the proper context (you can download the application) the result looks like the following pictures. On the left, you see the application without any overlay icons, and on the right you can see the application with a red icon overlay. 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. Its 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 applications 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 applications 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 bars 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, youll 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