We’ve all seen those programs that show progress on the Windows taskbar. WinRAR does it when creating or extracting RAR files. Firefox does it when downloading files. Windows Explorer does it when copying or moving files. Perhaps you’ve seen this and thought, “I wonder how I could do this in my own application.” It certainly adds polish. And as a user, being able to easily monitor a long running task while surfing the Interwebs has a lot of value. In this blog entry, I’m going to show you how to do it.
Prior to Windows 7, most applications would accomplish similar feats by manipulating window titles or system tray icons. It was kludgy. But it got the job done. Believe it or not, Windows 7 was the first version of Windows that gave us platform support for showing progress on the taskbar. It’s one of those silly little features we developers never knew we needed. After all, we thought we already had it figured out. But now that I know it’s there, I want to use it all of the time.
The key to showing taskbar progress is the ITaskbarList3 COM interface. It extends ITaskbarList and ITaskbarList2 interfaces, which are Windows 2000 and Windows XP era, respectively. As you can tell from the API docs, both ITaskbarList and ITaskbarList2 are pretty boring. It wasn’t until ITaskbarList3 showed up that things started getting interesting with the taskbar. It’s with ITaskbarList3 that we have the ability to manipulate things like overlay icons, thumbnail images, and progress, which is what we’re concerned with in this article.
(Note: If you’re a Windows developer and not experienced with COM, I strongly advise that you educate yourself on the topic. Much of the Windows platform is exposed through COM interfaces. There’s not much beyond the core Win32 API that you can do without dipping your toes into the world of COM. If you’re interested in learning more, I recommend picking up “Essential COM” by Don Box. It’s an older book (circa 1998). But it’s still the best introduction to COM and remains relevant after all of these years.)
I’m now going to demonstrate how to use ITaskbarList3 for showing progress by creating a simple wrapper class called TaskBarProgress. This is what the class declaration looks like.
class TaskBarProgress { public: //! Constructor. TaskBarProgress(HWND hWnd) : m_hWnd(hWnd), m_pTaskBarList3(NULL) {} //! Destructor. virtual ~TaskBarProgress() { _ASSERT(m_pTaskBarList3 == NULL); } //! Starts "progress mode". void startProgressMode(); //! Ends "progress mode". void endProgressMode(); //! Sets the current progress. void setProgress(ULONGLONG progressValue, ULONGLONG progressTotal); private: // We don't want the default implementations of the copy constructor // and assignment operator because we have a COM pointer involved. // Copying that without doing the appropriate AddRef'ing would be // hazardous to our health. Let's just leave these out unless we // find we need them at a later date. //! Copy constructor. NOT IMPLEMENTED. TaskBarProgress(const TaskBarProgress &); //! Assignment operator. NOT IMPLEMENTED. const TaskBarProgress & operator=(const TaskBarProgress &); //! The window for which we're showing progress. HWND m_hWnd; //! The ITaskbarList3 implementer. ITaskbarList3 *m_pTaskBarList3; }; |
TaskBarProgress is fairly simple. It has two member variables – m_hWnd and m_pTaskBarList3. Why do we need a window handle? When setting progress, ITaskbarList3 needs to know what window we’re setting progress on. So TaskBarProgress accepts the window handle as an argument to the constructor, which then gets stashed in m_hWnd.
The copy constructor and assignment operator are not implemented here. This is meant to keep us from shooting ourselves in the foot with COM reference count bookkeeping. For demo purposes (and probably for most practical purposes), we don’t need to support copies of this class.
The three methods startProgressMode(), endProgressMode(), and setProgress() are the interesting methods here. They do what their names suggest. When you want to begin displaying progress on the taskbar, you call startProgressMode(). As progress is made, you update the progress value by calling setProgress(). And when you’re all finished, tidy things up by calling endProgressMode().
Starting Progress
The implementation for startProgressMode() looks like so.
void TaskBarProgress::startProgressMode() { if (!m_hWnd) return; if (!m_pTaskBarList3) { HRESULT hr = ::CoCreateInstance(CLSID_TaskbarList, NULL, CLSCTX_INPROC_SERVER, IID_ITaskbarList3, (void **)&m_pTaskBarList3); if (hr != S_OK) return; // Not a supported platform. Nothing we can do. } // "Turning on" progress mode and setting the initial progress value to 0. m_pTaskBarList3->SetProgressState(m_hWnd, TBPF_NORMAL); m_pTaskBarList3->SetProgressValue(m_hWnd, 0, 100); } |
We first obtain a pointer to the ITaskbarList3 interface if we need to and verify that it was successful (this will fail on older platforms like Vista or XP). If it’s successful, we then enable the progress state with a call to ITaskbarList3::SetProgressState(). ITaskbarList3::SetProgressState() accepts two arguments – a window handle and the state flag. If you peruse the documentation for this method, you’ll find 5 different flags you can use for the state. These are described below.
| TBPF_NOPROGRESS | This is the normal taskbar mode. If a progress bar is present on the taskbar, setting this flag will dismiss it. You’ll notice we set this flag in our endProgressMode() method described later. |
| TBPF_INDETERMINATE | This is what it sounds like. It means you have something going on that you want to show progress for, but you have no idea how to track a progress value for it. For example, imagine calling a third party library function that takes a long time to finish. You may not be able to receive progress notifications from it, so you have no way of knowing when it’ll be finished until it’s actually done. This is when you might use this flag. |
| TBPF_NORMAL | Despite being called “normal”, this is actually the “in-progress” state. When you send this flag, the taskbar icon will begin showing progress. |
| TBPF_ERROR | Turns the icon red to indicate an error has occurred. |
| TBPF_PAUSED | Turns the icon yellow to indicate an action is needed before more progress can be made. |
For this article, we’re only concerned with TBPF_NORMAL and TBPF_NOPROGRESS.
After we set the progress mode in startProgressMode(), we initialize the progress value to 0 with a call to ITaskbarList3::SetProgressValue(). This isn’t absolutely necessary, but it’s a good practice.
Updating Progress
Updating the progress value occur in our setProgress method. This method has two parameters – progressValue and progressTotal. progressValue is whatever the current progress value is and progressTotal is the maximum value the progress value can be. Both of these parameters are passed straight through to ITaskbarList3::SetProgressValue()
void TaskBarProgress::setProgress(ULONGLONG progressValue, ULONGLONG progressTotal) { if (!m_pTaskBarList3 || !m_hWnd) return; m_pTaskBarList3->SetProgressValue(m_hWnd, progressValue, progressTotal); } |
Ending Progress Mode
Ending progress occurs in our endProgressMode() method. This method simply sets the state value to TBPF_NOPROGRESS as described above and then releases the ITaskbarList3 pointer.
void TaskBarProgress::endProgressMode() { if (!m_pTaskBarList3 || !m_hWnd) return; m_pTaskBarList3->SetProgressState(m_hWnd, TBPF_NOPROGRESS); m_pTaskBarList3->Release(); m_pTaskBarList3 = NULL; } |
Demo
And that’s all there is to it. We’ll demonstrate the use of this class with a simple console-based application (yes, consoles can have progress too!).
int _tmain(int argc, _TCHAR* argv[]) { CoInitialize(NULL); HWND hwnd = ::GetConsoleWindow(); TaskBarProgress progress(hwnd); progress.startProgressMode(); for (int i = 0; i < 20; ++i) { progress.setProgress(i, 20); Sleep(200); } progress.endProgressMode(); CoUninitialize(); return 0; } |
The first thing we do here is initialize COM with a call to CoInitialize(). You MUST do this before doing anything COM-related.
After initializing COM, we get a handle to the console window. We use that handle to construct an instance of TaskBarProgress. We then call the instance’s startProgressMode() and enter a loop that iterates 20 times. Each time through the loop, TaskBarProgress’s setProgress() method is called with the current progress value and then we sleep for 200 milliseconds. Once the the loop has finished, the TaskBarProgress’s endProgressMode() method is called.
Just before exiting, COM is uninitialized.
If you build this and run it from the console, you’ll see that the console window taskbar icon shows progress while the application is running and the icon returns to normal just before the application terminates.
Go Forth and Create Progress
The code for this article can be downloaded here. The sample was written and built using the Visual Studio 2012 Express edition. If you’re using an older platform SDK, you may need to update it in order to obtain definitions for ITaskbarList3. If you’ve included shobjidl.h and the compiler complains about missing definitions for ITaskbarList3, CLSID_TaskbarList, and/or IID_ITaskbarList3, that’s usually a good indication you need to update.
And that’s it! The ITaskbarList3 interface is pretty simple. You may not feel the need to wrap it in a class at all. That’s fine. Or you may have a better idea of how to wrap it (a scope-based progress class, perhaps?). That’s fine too. In any case, adding support for taskbar icon progress will definitely add some polish to whatever project you may be working on. Have fun with it!
-Shane
