How to Create a Custom Jumplist with Custom Events in Windows Forms

• Download demo project - 398.09 KB

Introduction

Windows 7 introduced a new set of features - one of them (and one of the most prominent features) is the Jumplist, so we are going to explore the Jumplist features and I will show you how to handle custom events that are fired from custom tasks in the Jumplist.

Jumplists

Simply, Jumplists can be called the context menu of the taskbar items in Windows 7 and they can contain different sets (categories) of items that can perform different tasks (you can check MSN messenger or Internet Explorer jumplists to make things clearer). Each application has its own jumplist by default, so even if your application is not doing anything, you will get the default Jumplist which contains these 3 tasks (Application name (JumplistDemo in our case), Pin this program to taskbar and Close window).

Any Jumplist consists of categories and each category has its own Jumptasks. There are two types of Jumptasks supported till now by WindowsAPICodePack; the JumplistLink (like Notepad link in the screen shot) and JumplistSeperator (like the separator between Paint and Calculator). A Jumptask represents an action to be performed by the user like openning a new instance of the application or launching another program. These Jumptasks are grouped in categories called JumplistCustomCategories (like the Action Category in the screen shot).

How to Build a Custom Jumplist for Your Application

In order to be able to deal with Jumplist classes in Windows Forms, you'd have to include these DLLs (Microsoft.WindowsAPICodePack.dll and Microsoft.WindowsAPICodePack.Shell.dll) in your project. You can get them from the attached project or you can download the Open source library from WindowsAPICodePack which includes the source code that can be used to access Windows 7 and Windows Vista features.

So let's explore how to build the Jumplist:

//declaration of our list, windowHandle is the handle of the window 
//you want the JumpList to be attached to
JumpList list = JumpList.CreateJumpListForIndividualWindow
		(TaskbarManager.Instance.ApplicationId, windowHandle);

//defining a new Custom Category called Actions
JumpListCustomCategory userActionsCategory = new JumpListCustomCategory("Actions");

//defining the JumpListLink "Clear History"
JumpListLink userActionLink = new JumpListLink
	(Assembly.GetEntryAssembly().Location, "Clear History");
userActionLink.Arguments = "-1";

//add this link to the Actions Category
userActionsCategory.AddJumpListItems(userActionLink);

//finally add the category to the JumpList
list.AddCustomCategories(userActionsCategory);

The above code will create a new Jumplist with a custom category called Actions and it has one JumpListLink called Clear History. This link will be used to send a message from the Jumplist to the application. We will see how to do this later, so let's complete the Jumplist implementation:

//get the notepad.exe path
string notepadPath = Path.Combine(Environment.SystemDirectory, "notepad.exe");

//attach it to the JumpListLink
JumpListLink jlNotepad = new JumpListLink(notepadPath, "Notepad");

//set its icon path
jlNotepad.IconReference = new IconReference(notepadPath, 0);

//add it to the list
list.AddUserTasks(jlNotepad);

we will do the same steps for the Calculator and Paint links. As long as we did not specify a custom category for these links, they will be grouped under the Tasks Category, so after finishing building the list, we have to call the Refresh() method in order to apply these settings. You will find a full implementation of the JumpList in MyJumplist class in the attached project source code.

list.Refresh();

You can run your application now and check the new modified JumpList.

Responding to Custom Events

The attached project is a very simple Windows application that has a single form that has some buttons, one of them is Clear History button which clears the listbox and changes the Recent action label to be "Clear History". This is very easy to be done from the Clear History button on the form, but what about doing the same thing from the Clear History JumplistLink? Actually, we will not be able to handle the click event of any link in your JumpList, but we want to be notified when the JumplistLink was clicked; after a very wide search on that issue (how to make jumplist call some methods written in your application and respond to custom events) I've found that the best way is sending messages between the Jumplist and the application in order to handle these custom events (thanks to this article: Windows 7: Jump Lists), so we are going to register a message that will be sent after clicking the Clear History link, this message will be caught by our application by overriding the WndProc method.

I've included in my solution the helper class WindowsMessageHelper which I got from the Windows 7: Jump Lists article. This class calls some APIs for sending and registering messages, so we have to do three steps in order to send messages between the Jumplist and the application.

First register the Message through the static method RegisterWindowMessage in the WindowsMessageHelper class:

//RegisterWindowMessage registers a window message and returns the message number
public static int ClearHistoryArg = 
	WindowsMessageHelper.RegisterWindowMessage("Jumplist.demo.ClearHistoryArg");

Second, override the WndProc method and apply your changes:

protected override void WndProc(ref Message m)
{
	//if the coming message has the same number as our registered message
	if (m.Msg == WindowsMessageHelper.ClearHistoryArg)
	{
		//clear history
		ClearHistory();

		//update recent action
		UpdateRecentAction(RecentActions.ClearHistory);
	}
	else
	{
		base.WndProc(ref m);
	}
}

Third, implement the method that will send messages to the application:

public static void HandleCmdLineArgs()
{
	if (Environment.GetCommandLineArgs().Length > 1)
	{
		switch (Environment.GetCommandLineArgs()[1])
		{
			case "-1":
                        WindowsMessageHelper.SendMessage
			("Jumplist.demo", WindowsMessageHelper.ClearHistoryArg);
                        break;
		}
	}
}

In the previous method, we are checking for additional command line arguments as the first element in that array is the name of the executing program, that's why we are checking the Length to be more than 1, remember that the value -1 in the switch-case clause stands for the Argument value we have set to the Clear History JumplistLink while creating the JumpList, so if you want to add more custom links you can set their arguments to whatever you want and catch them in this method with their value.

References

• Windows 7: Jump Lists
• WindowsAPICodePack
• WndProc

Final Word

I've attached a project that fully illustrates the steps mentioned above, and I hope you find it useful.

History

This article was written on 23^rd August 2010 by me (Ahmed Said).