Introduction
Windows 7 provides many new features, the most visible of these features is the new TaskBar. Just as the TaskBar has a new look it also provides a significant increase in functionality over past versions. You may have noticed the area for each application icon provides new functionality. The icon background can act as a progress bar with multiple modes including indeterminate, normal, paused and error. In addition, the icon itself can be updated with overlays. While subtle, these two combined can provide the user with valuable status and/or progress information. The next time you download a file using Internet Explorer 8, take a look at the icon and you’ll see an example of the background progress bar. Another example of the significant improvements is the right-click menu, known as the Jump List. The Jump List provides applications the ability to list recent or favorite documents and include user tasks.
To get started with the TaskBar, first you need to download the Windows 7 API Code Pack from MSDN. The Code Pack provides managed code access to many of the enhancements within Windows 7, including TaskBar, Libraries, etc. For this article, we will focus on the TaskBar section of the code pack. After downloading and unpacking, open the Windows 7 API Code Pack solution in Visual Studio and compile it. We will need the dlls from the code pack in the examples below. The examples in the article are created using Windows Presentation Foundation (WPF); however, WPF is not a prerequisite for using the TaskBar and Jump List features. The functions described below can also be used in projects using WinForms.
Getting Started
To get started we will need to add references to the Windows 7 API Code Pack. The dlls we will need to reference for using the Toolbar are:
- Microsoft.WindowsAPICodePack
- Microsoft.WindowsAPICodePack.Shell
Next, we will need to use the following namespaces in the classes where we use the Taskbar:
- Microsoft.WindowsAPICodePack
- Microsoft.WindowsAPICodePack.Shell
- Microsoft.WindowsAPICodePack.Taskbar
TaskBar Progress Bar
The TaskBar Progress Bar capabilities are very easy to start using and they incorporate into your application. The Progress Bar functions can be accessed by using the class TaskbarManager. The TaskbarManager.Instance static member is an easy way to access the TaskBar methods as it will create or return an existing reference. With a reference to the TaskBarManager it is easy to set the Progress Bar value as shown below.
TaskbarManager.Instance.SetProgressValue(15, 100)
The SetProgressValue accepts 2 parameters, the value and the max value. In addition to setting the current value, you can also change the state using the method: TaskbarManager.Instance.SetProgressState. The SetProgressState accepts a single enum parameter. The TaskbarProgressBarState enum provides the following values: Normal, NoProgress, Error, Paused and Indeterminate. To set the ProgressBar in an indeterminate state you would use the following statement:
TaskbarManager.Instance.SetProgressState(TaskbarProgressBarState.Indeterminate);
This will produce the same affect as with a standard Progress Bar, it will provide a green bar slowly moving left to right and repeating. The Error mode will turn the progress bar red. Similarly, Paused will turn the progress bar yellow. The Normal state acts like a standard green progress bar and is turned on when you set the progress bar value. The NoProgress state hides the progress bar.
TaskBar Icon Overlays
Similar to the Progress Bar, you need to use the TaskbarManager.Instance to change overlays. You can change the overlay icon by using the following method:
TaskbarManager.Instance.SetOverlayIcon(Icon, “”);
The SetOverlayIcon method accepts two parameters, System.Drawing.Icon object and accessibility text. So you can create your own icon resources and use them as necessary; however, the Windows API Code Pack provides a handy method for pulling stock icons. The example below shows a simple use for the StockIcon class.
using (Microsoft.WindowsAPICodePack.Shell.StockIcon si =
new Microsoft.WindowsAPICodePack.Shell.StockIcon(StockIconIdentifier.Shield,
StockIconSizes.ShellSize,
false,
false))
{
TaskbarManager.Instance.SetOverlayIcon(si.Icon, “”);
}
The StockIcon constructor accepts 4 parameters, a StockIconIdentifier enum value, an icon size, an overlay icon boolean value and a selected icon boolean value. The SockIconIdentifier enum provides access to a large number of stock icons, making it a very handy tool to accompany the overlay icon feature. At some point in your application it will become necessary to hide the overlay icon. To hide it you need to pass null for icon into the SetOverlayIcon method as shown below.
TaskbarManager.Instance.SetOverlayIcon(null, “”);
BODY>
TaskBar Jump List
Unlike the TaskbarManager, the Jump List requires you to create an instance of the Jump List class. To create an instance, use the following method:
JumpList jump = JumpList.CreateJumpList();
It is a good idea to create an instance of this object and dispose of it upon closing. It is important to note that this method cannot be called in the constructor. The Window must be displayed, so in WPF you would want to use the Loaded event to create the object and Closing to dispose of it. Once we have a JumpList we can start adding tasks. The method to do this is shown below:
jump.AddUserTasks(new JumpListLink(Path, Name));
The AddUserTask accepts two parameters Path to the executable and the Name to be displayed. This will add an entry to the Jump List; however, the item added will have a generic icon. We can modify this statement to resolve this issue.
jump.AddUserTasks(new JumpListLink(txtPath.Text, txtName.Text)
{
IconReference = new IconReference(Path, 0)
});
Using the initializer, we can populate the IconReference parameter with a reference to the executable icon. The methods are simple enough to perform; however, they do not directly update the Jump List. In addition to adding user tasks, the Jump List supports the ability to add documents to Recent/Frequent and/or custom categories. The Recent and Frequent categories are mutually exclusive whereby only one of them can be displayed at once. To start adding documents to the Recent/Frequent list use the following method.
jump.AddToRecent(PathToDocument);
And to control which category Recent/Frequent is displayed use the following property:
jump.KnownCategoryToDisplay = JumpListKnownCategoryType.Frequent;
It is important to note that your application will still need to be registered for a specific document type to open your application when the user clicks on one of the them in the Jump List. The jump list methods above do not directly update the Jump List after call. So to commit the changes to the Jump List you need to make a call to the Refresh() method to commit the changes.
Creating a custom category is a fairly simple process as show below.
JumpListCustomCategory custom = new JumpListCustomCategory(“Custom”); jump.AddCustomCategories(custom);
This will create a new category called “Custom” and add it to the Jump List. To add items into the custom category, use the method AddJumpListItems as shown below.
custom.AddJumpListItems(new JumpListItem(DocumentPath));
Compatibility with Past Versions of Windows
The new Task Bar capability is currently only available in Windows 7, so this means we need to be sure we only access these capabilities while running on Windows 7. Luckily, the Windows 7 API Code Pack provides a simple method for checking compatibility. The TaskbarManager class provides a simple property, IsPlatformCompatible, to be used for this purpose. Here is a simple example of how to use this to ensure your application maintains backwards compatibility.
if (TaskbarManager.IsPlatformSupported) { //Task Bar Methods }
Conclusion
The new features provided by the Windows 7 Task Bar provides a great way of providing simple user feedback on your application. Using the Windows 7 API Code Pack, makes accessing these new features extremely easy from managed code. In addition, by using the IsPlatformSupport properties you can add these features to applications and not break compatibility with past versions of Windows.
Resources
Download the example source code by clicking here.
About the Author
Chris Bennett is with Crowe Horwath LLP in the Indianapolis office. He can be reached at chris .bennett@crowehorwath.com
