Making your app shine on Windows 7: Jumplist

This post is one in a series of posts covering the Windows API Code Pack. The code pack provides a managed code framework for using the new native Windows 7 features.

 

After thumbnail previews the next item you’ll be looking to implement for your application is a Jumplist. A Jumplist may provide shortcuts to recent documents, frequently use documents and application functionality.

Setting up a jumplist for your application is as simple as simple can be using the code pack managed API – but there are some gotchas worth noting.

First, you have to have a valid active window on the taskbar before you can create your jumplist. This isn’t obvious – except when you get the code pack’s error message on first run of your modified application. Remember, in working with the new Taskbar features, you are actually providing the Taskbar with details you want it to attribute to your application. If it doesn’t know about your application, it can’t take your details.

Second, the code pack API does a good job of proactive error detection. For example, it’ll test to make sure the file you want to list on your jumplist exists. If it doesn’t you get blown out before you get near the Taskbar. The same with file associations. The code pack tests for the file association relationship to your application. If it doesn’t you can’t list the file. For more details on this one, look at the code pack TaskBarDemo sample. You might wonder why this extreme protection. The answer lines in the third gotcha.

Third, the known category types (Recent, Frequent) are populated by the Taskbar for your application ‘automagically’. So you only have to choose to show one of these categories in your jumplist to get the information displayed. This is because Windows maintains a recent items history infrastructure when you use the current common file dialogs( or explicitly call the relevant API). If you don’t use them (why?), you can hand code this mechanism by using the shell API SHAddToRecentDocs or the code pack’s jumplist.AddToRecent method.

Fourth, the code pack’s jumplist does a lot of good stuff. This includes maintaining your jumplist against the removed items list created by the user. You may want to have all the items in the jumplist but the user can selectively remove file references from your list. It’s considered bad form to keep putting the item back when the user has removed it, jumplist ensures you don’t make this mistake. If you don’t use jumplist you have to check the removedDestinations property and modify the list yourself.

Now lets look at the code. Below is the specific parts of a C# Winforms application showing the creation of a jumplist:

Code Snippet

1. public partial class Form1 : Form
2. {
3.     private JumpList jumpList;
4.  
5.     private JumpListCustomCategory category1 = new JumpListCustomCategory("Custom Stuff");
6.     private JumpListCustomCategory category2 = new JumpListCustomCategory("Custom Stuff2");
7.  
8.     public Form1()
9.     {
10.         InitializeComponent();
11.         
12.     }
13.  
14.     private void Form1_Shown(object sender, EventArgs e)
15.     {
16.         // create a new taskbar jump list for the main window
17.         jumpList = JumpList.CreateJumpList();
18.  
19.         // Add custom categories
20.         jumpList.AddCustomCategories(category1, category2);
21.  
22.         AddTasks();
23.         jumpList.Refresh();
24.     }
25.  
26.     private void AddTasks()
27.     {
28.         // Path to Windows system folder
29.         string systemFolder = Environment.GetFolderPath(Environment.SpecialFolder.System);
30.  
31.         // Add our user tasks
32.         jumpList.AddUserTasks(new JumpListLink(Path.Combine(systemFolder, "notepad.exe"), "Open Notepad")
33.         {
34.             IconReference = new IconReference(Path.Combine(systemFolder, "notepad.exe"), 0)
35.         });
36.  
37.         jumpList.AddUserTasks(new JumpListLink(Path.Combine(systemFolder, "mspaint.exe"), "Open Paint")
38.         {
39.             IconReference = new IconReference(Path.Combine(systemFolder, "mspaint.exe"), 0)
40.         });
41.  
42.         jumpList.AddUserTasks(new JumpListSeparator());
43.  
44.         jumpList.AddUserTasks(new JumpListLink(Path.Combine(systemFolder, "calc.exe"), "Open Calculator")
45.         {
46.             IconReference = new IconReference(Path.Combine(systemFolder, "calc.exe"), 0)
47.         });
48.  
49.  
50.     }
51. }

All the work is kicked off in the form’s Shown event. With the creation of a jumplist. Two custom categories are added to it. Then some tasks are added that open other applications. The jumplist is ‘published’ by calling jumplist.refresh();

Remember the Jumplist is created by the Taskbar for your application. Unlike the Thumbnail preview toolbars there doesn’t appear to be a mechanism of capturing jumplist events into your application. The only event raised by jumplist is when items have been removed from the jumplist since the last jumplist refresh occurred. This means achieving something similar to Internet Explorer 8’s Open new tab jumplist task, requires an ‘external’ communication to occur with your application.