Windows 7 Taskbar: Custom Destinations

February 24, 2009

tags:
one comment

We’ve already seen how to use the recent and frequent jump list categories in our Windows 7 taskbar jump list, and how to add user tasks to the jump list, enabling additional custom functionality.

However, most file-oriented applications will also benefit from the ability to add custom destinations grouped into categories to the taskbar jump list, providing additional destinations beyond the recent and frequent ones populated by the system.

A custom destination is a categorized entry in the application’s jump list, typically representing an item that the application can open and handle.  For example, Internet Explorer 8 populates a “History” category in the jump list which contains links to pages you have visited recently; an email application could have categories for “Inbox”, “Important”, “To Follow-Up” and whatnot.  There’s no limit on the number and variety of categories that you can create, other than the limits of the screen.

By their nature, custom destinations are nouns – they represent items (usually files) that the application can open and handle.  Therefore, most custom destinations are IShellItem objects, although IShellLink objects can be used as well.

When creating a new jump list and populating it with custom destinations, there are two important things to bear in mind before you start:

  1. There is a limited amount of screen estate for your categories and items.  You can retrieve the maximum number of items that can be placed in the jump list by querying the JumpListManager.MaximumSlotsInList property of the managed wrapper.
  2. The jump list belongs to the user and not to you, and therefore the user may choose to remove items from the jump list, using the right-click context menu on the item, as in the following screenshot.  When your application repopulates the jump list for whatever reason, it’s important that you bear the user’s choices in mind.  Specifically, if you attempt to add an item to the jump list that the user has removed earlier, you will encounter an exception.  For this scenario, the JumpListManager.UserRemovedItems event will help you find out that the user removed items from the list.  (Later in this post we discuss this in detail.)

image

First things first.  Let’s see how we can add a couple of items with different categories to the application’s jump list.  The following code is taken directly from the Windows7.DesktopIntegration.MainDemo project, and is used to initialize the jump list we’ve seen in the previous screenshot:

_jumpListManager.AddCustomDestination(new ShellLink

{

    Path = Path.Combine(_thisAppDataPath, "sonnet.txt"),

    Title = "Shall I compare thee…",

    Category = "My Category",

    IconLocation = shell32DllPath,

    IconIndex = 1

});

_jumpListManager.AddCustomDestination(new ShellLink

{

    Path = Path.Combine(_thisAppDataPath, "mary.txt"),

    Title = "Mary had a little…",

    Category = "My Category",

    IconLocation = shell32DllPath,

    IconIndex = 1

});

_jumpListManager.AddCustomDestination(new ShellLink

{

    Path = Path.Combine(_thisAppDataPath, "hello.html"),

    Title = "Hello World",

    Category = "My Other Category",

    IconLocation = shell32DllPath,

    IconIndex = 5

});

_jumpListManager.AddCustomDestination(new ShellItem

{

    Path = Path.Combine(_thisAppDataPath, "raven.txt"),

    Category = "My Other Category"

});

if (_jumpListManager.Refresh())

{

    statusLabel.Text = "Maximum slots in list: " +

        _jumpListManager.MaximumSlotsInList;

}

This code shows that ShellLink and ShellItem objects can be freely added to the jump list, and also demonstrates the use of the MaximumSlotsInList property that I’ve mentioned earlier.  Again, the jump list initialization statement is missing here, but we have already seen it in a previous post.

Now, what’s with all these items that could potentially be removed by the user?  Well, the jump list is designed to let the application know about removed items only when the jump list is being built.  The managed wrapper exposes this information using the UserRemovedItems event on the JumpListManager class, which your code must register to (or else the wrapper will throw an exception).  This ensures (at least in part) that you’re aware of the requirement to handle removed items.

The suggested flow for a well-behaved application that handles user-removed items is the following:

  1. Register to the UserRemovedItems event;
  2. Build the jump list and call the Refresh method to persist the changes;
  3. If the UserRemovedItems event is invoked, set the CancelCurrentOperation property of the UserRemovedItemsEventArgs object to true, indicating that the current jump list building transaction will be aborted; record the removed items from the RemovedItems property of the same object so that you’ll know not to add them in the next jump list building transaction;
  4. Check the return value of the Refresh method to determine whether the jump list building transaction completed successfully; if it hasn’t, build the jump list again, and this time do not add the items that you previously recorded as removed.

The above process occurs synchronously on the thread that invokes the Refresh operation, so there are nothing to worry about with regard to thread safety.

Now that we’re through with adding custom destinations to the jump list, we can safely say that the grounds of working with Windows 7 taskbar jump list are covered.  We’ve seen how to populate the jump list with recent/frequent items, how to add user tasks to the jump list, and finally how to add categorized custom destinations to the jump list.  In the next posts in this series, we will look at additional aspects of the Windows 7 taskbar, unrelated to jump lists.

Add comment
facebook linkedin twitter email

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

one comment

  1. ChadApril 2, 2009 ב 11:55 AM

    I was wondering how Windows knows what your frequent documents are? Is it a a counter in the registry of a log file somewhere?

    Reply