Introduction

Windows 7 includes a wealth of new features for developers to take advantage of.  This includes better rendering subsystems, new sensor and location API's, file libraries, federated search, and of course, the improved taskbar.  My last article discussed the taskbar's ability to show custom previews and toolbar icons.  This article focuses on Jump Lists - the replacement for notification area context menus.

To get started, download Visual Studio 2008 Express Edition or higher (C# or VB).  Or, just go for Visual Studio 2010 Beta 2 - it's available now and well worth the download.  All Express editions are free, and either 2008 or 2010 versions will work fine with this article's accompanying code.

What's a Jump List?

Jump Lists are a new concept in Windows 7 that allow developers to provide shortcuts for users right from their icon's context menu in the taskbar or Start menu.  The shortcuts could be simple links to the documents folder or a library for a given application, or links back to the same application with a parameter passed to cause something to happen.

You can use this method in Live Messenger to change online status, display the new message window, or open web pages relating to the application.  In the end, all of these are shortcuts.  Shortcuts to URL's, or shortcuts back to the executable with an argument that causes some change to occur.

Windows API Code Pack

The Windows API Code Pack lets you take advantage of specific features of Windows Vista and Windows 7 that aren't available across the general framework, as well as native features that don't make sense in the common CLR used across all the supported configurations. Much of it consists of interop wrappers.

With the Code Pack, you get access to the new taskbar, Direct2D, DirectWrite, shell properties, Jump Lists, and more. The download also includes numerous sample code projects to get you started, so there's no excuse for avoiding new features!

Adding a Jump List

Adding a Jump List is easy.  After you create the list itself, add items (shortcuts to files or folders, and tasks) to it.  Then, you can choose how a user's recent or frequently used documents show up.  Windows manages the user documents list, which relieves you of some work.

It's important to note that in order to make a change to the list, you have to recreate the entire thing.  In other words, you'll replace the old list with a new one, rather than updating it.

Here's how the process works:

First, add the two required references from the Windows API Code Pack.  You can either build a project and reference the DLL's, or directly add projects to your solution:

For convenience, you can add the namespaces to your using block to shorten typing later:

Visual Basic

Imports Microsoft.WindowsAPICodePack.Taskbar
Imports Microsoft.WindowsAPICodePack.Shell

Visual C#

using Microsoft.WindowsAPICodePack.Taskbar;
using Microsoft.WindowsAPICodePack.Shell;

The Microsoft.WindowsAPICodePack.Taskbar.JumpList class is where most of the action is.  There's a static factory method, CreateJumpList, to create the list.  Always start by calling this method, even if the application has created a Jump List in the past.

Visual Basic

Private Sub CreateJumpList()
    Dim jl As JumpList = JumpList.CreateJumpList()

Visual C#

private void CreateJumpList()
{
    JumpList jl = JumpList.CreateJumpList();

Next, you have several options, depending on what you need in the list.  The most basic group is the list of files.  You can choose to show Recent files, Frequent files, or neither-but you can't have both.  If you don't make a choice here, you'll get Recent files automatically, as long as you have a registered file type.

Visual Basic

' Show user files: Recent, Frequent, or None
jl.KnownCategoryToDisplay = JumpListKnownCategoryType.Recent

Visual C#

// Show user files: Recent, Frequent, or None
jl.KnownCategoryToDisplay = JumpListKnownCategoryType.Recent;

Now you can add one or more custom categories of items.  These are either folders or files.  There are two very important rules:

1. The files/folders must exist!  If necessary, check the path before adding the JumpListItem or you'll have a crash. 
2. The files you add have to be of a type registered for your application, or you'll crash. Even worse: the exception won't occur on the line where you add it, but rather when you're done setting it up and try to refresh the list.

I've commented out the last item here, but you would use a JumpListItem for actual file system files, and JumpListLink objects for non-filesystem references.  Again, don't add a JumpListItem unless you know that it exists and that you're registered to handle it.

Visual Basic

' Add my own links (nouns)
Dim catActions As New JumpListCustomCategory("Destinations")

catActions.AddJumpListItems(
    New JumpListLink(Environment.GetFolderPath(Environment.SpecialFolder.MyPictures), "My Pictures"), _
    New JumpListLink("http://blogs.msdn.com/coding4fun", "Visit Coding4Fun"), _
    New JumpListLink("http://code.msdn.microsoft.com/WindowsAPICodePack", "Windows API Code Pack"))
    'new JumpListItem(@"c:\Test1.c4f")

jl.AddCustomCategories(catActions)

Visual C#

// Add my own links (nouns)
JumpListCustomCategory catActions = new JumpListCustomCategory("Destinations");
catActions.AddJumpListItems(
    new JumpListLink(Environment.GetFolderPath(Environment.SpecialFolder.MyPictures), "My Pictures"),
    new JumpListLink("http://blogs.msdn.com/coding4fun", "Visit Coding4Fun"),
    new JumpListLink("http://code.msdn.microsoft.com/WindowsAPICodePack", "Windows API Code Pack")
    //new JumpListItem(@"c:\Test1.c4f")
    );

jl.AddCustomCategories( catActions);

You can add one or more tasks as  links to system executables by using the AddUserTasks method of the JumpList object.  Either create multiple objects and add them as a variable argument list, or add them one at a time, as I have here.

Visual Basic

' Add our user tasks (verbs)
jl.AddUserTasks(New JumpListLink(Path.Combine(systemFolder, "notepad.exe"), "Open Notepad") _
    With {.IconReference = New IconReference(Path.Combine(systemFolder, "notepad.exe"), 0)})

Visual C#

jl.AddUserTasks(new JumpListLink(Path.Combine(systemFolder, "notepad.exe"), "Open Notepad")
{
    IconReference = new IconReference(Path.Combine(systemFolder, "notepad.exe"), 0)
});

The IconReference property sets a pointer to the icon by referencing a DLL or EXE and then an index.  Specifying an EXE with "0" is a good way to get the default icon for an executable that you are linking to.

You can add a separator to the list whenever you need to.  The JumpListSeparator class represents a separator and can be added using the AddUserTasks call.

Visual Basic

jl.AddUserTasks(New JumpListSeparator())

Visual C#

jl.AddUserTasks(new JumpListSeparator());

The final links in our Jump List link back to our own executable. This is the most common use of Jump Lists.  Just having a Recent/Frequent list is nice, but being able to trigger actions on the program itself-even when it's not started-is really handy.  It's almost like a menu of command line options!

Commands in the list that invoke actions on the application itself involve calling the same application with different arguments.  Remember that this isn't a true menu; you won't receive a Click event.  Instead, you need to deal with an argument that's passed to you, even if you're already running.

Remember that the first argument on the command line is always the fully-qualified location to the running executable.  The Arguments property lets you specify command line arguments that users don't directly see.  For this sample application, I've defined three dummy arguments.  If one of these is passed in, the application changes the background color of a label and indicates which argument it was.

Visual Basic

jl.AddUserTasks(New JumpListLink(Assembly.GetEntryAssembly().Location, "Action 1 (Green)") _
    With {.Arguments = "-1", .IconReference = New IconReference(Assembly.GetEntryAssembly().Location, 0)})

Visual C#

jl.AddUserTasks(new JumpListLink(Assembly.GetEntryAssembly().Location, "Action 1 (Green)")
{
    IconReference = new IconReference(Assembly.GetEntryAssembly().Location, 0),
    Arguments = "-1"
});

Invoking Self Actions

Windows Live Messenger uses Jump List actions for setting its own available status, and Windows Media Player has Jump List actions for skipping tracks or stopping.  Likewise, you can add tasks that invoke actions on the same executable.  If the application isn't running (remember that the Jump List is still available), this will cause it to be launched with the right argument.  That's no problem.  What if it's already running though?

The key is to find a way to pass messages between running instances.  When the application starts up, check to see if another instance is running by using a Mutex (see Program.cs).  If not, just use the arguments directly.  If it is running, send the information about the parameter to the other instance and then quit.  You could use temporary files, shared registry keys, or memory-mapped files.  I find it easiest to use window messages.

You can find the code to create custom message ID's, to find the right window, and to send the message in my WindowsMessageHelper class.

From the main window code, override the WndProc method.  This is the message loop for everything: mouse events, key events, window closing, and much more.  Ensure that the message is something you need; otherwise pass it on to the underlying handler.

If the application is already running, post a message.  If not, start as usual and watch your message queue.  If you see a message of interest, take some action (in this case, just showing a message and changing a color). 

The only other tricky thing to remember, is that you might startup as the only instance, and also have a parameter.  For example, if the user clicked a task on the Jump List but the application isn't running.  I take the easy way out and check for parameters after fully starting up and then post to my own queue if needed!  That simplifies some of the logic anyway.

If you don't mind using the Microsoft.VisualBasic.ApplicationServices namespace from C#, then you can take advantage of the VB SingleInstance application mode.  This removes the need for any explicit mutex, interop, or message passing.  You can find some great information about this on Jocelyn Villaraza's excellent blog post.

Registering a File Type

Remember: unless you're registered as a file handler for the type, you can't show recent or frequent files or point to individual files.  Register to be a file handler by creating a registry write operation to a key under HKEY_CLASSES. 

The problem is, you can't write to the HKEY_CLASSES branch of the registry without proper permissions.  By default, permission is only granted to the Administrators group.  You really don't want to require that your application run under administrative privileges-that would be so Windows XP!

There are two alternatives: you could create a second application that can run elevated in order to perform the registration.  This is how the samples do it with the Windows API Code Pack. A better method is to create a custom installer for the project and perform the association there.  Installers always require administrative rights, and they only need to run once.

Creating the Installer

To create the installer, first add a setup project to your solution, following the usual steps. Then, from the Project types list, click Other Project Types | Setup and Deployment.  In the Templates list, click Setup Project. Give it a name, then add it.

From Solution Explorer, right-click the setup project, then click the View | File Types menu command.

From the File Types list, right-click File Types on Target Machine, and then click Add File Type.  Fill out the properties to name the file type and provide the extension.  For Command, be sure to set it to the Primary output of the main project. 

The file type should appear like the following in the File Types tab:

Now you have a registered file type.  You still need to modify your setup project to copy the primary output (the EXE) to Program Files and customize any other properties in the setup project, but these are the special steps for file types.  If in doubt, take a look at sample code to see how the Setup project is configured.

Conclusion

Working with the Windows API Code Pack makes it much easier to customize the taskbar and add Jump Lists, and gives you a great experience that really integrates well with the system.  Download Visual Studio Express, grab the Windows API Code Pack, and start digging in.

The new features won't work on machines prior to Windows 7, so be sure to check that they're supported.

A number of articles ago, a simple wallpaper utility was written. I thought it would be nice to put together some of the concepts that we've looked at recently and create a new, enhanced wallpaper changer. Specifically, this application is no longer based on a specific file. Instead, it expects a folder in which it will find images. Upon startup, it will change the wallpaper, and it will even modify the placement behavior based on the size of the image found.

You can read the article now, but for added benefit download a copy of Visual Studio 2005 Express Edition for C# or Visual Basic. These are free if downloaded during most of 2006, and provide all of the tools necessary to create great applications. After you install Visual Studio Express, download the code for this article from the links at the top. Choose from C# or Visual Basic, according to your personal preference—the applications are functionally identical.

As with most recent In the Box columns, this application will start with no visible interface beyond its notification icon in the system tray. The available options will be to display the settings, change the wallpaper on-demand, or exit. The "Show Settings" option is in bold. This is a visual cue that if you double-click the icon, this is the action that will take place. There is no built-in support for this feature. Simply set the menu item's Font.Bold property to "True" and create a MouseDoubleClick event handler for the NotifyIcon control.

Figure 1: The notification icon menu

Scanning folders

The heart of the application is its ability to scan a folder randomly to find an image to display as the desktop background. This is surprisingly easy using the System.IO.Directory class. Its static/shared GetFiles method returns a collection of all files in a given folder. You can optionally pass a wildcard pattern, and a recursive qualifier. It would have made sense to specify a wildcard pattern including extensions like .JPG and .GIF, but apparently only a single expression can be used. The third parameter takes an argument of type System.IO.SearchOption. This is where you can specify a top-level file listing (TopDirectoryOnly), or a recursive (AllDirectories) one.

Visual Basic

' Specify top-level or sub-folders
Dim opt As System.IO.SearchOption = _
     System.IO.SearchOption.TopDirectoryOnly

If subfoldersCheckbox.Checked Then
    opt = System.IO.SearchOption.AllDirectories

End If

' Grab complete list of files
Dim files As String() = System.IO.Directory.GetFiles( _
    picturesPathTextBox.Text, "*", opt)

Visual C#

// Specify top-level or sub-folders
System.IO.SearchOption opt = System.IO.SearchOption.TopDirectoryOnly;
if( FsubfoldersCheckbox.Checked ) opt = 
    System.IO.SearchOption.AllDirectories;

// Grab complete list of files
string[] files = System.IO.Directory.GetFiles(
picturesPathTextBox.Text, "*", opt);

At this point, the files object contains an array of strings. Each entry is a fully-qualified filename from within the supplied folder. It would be nice to just randomly select an entry from this collection, but recall that we were not able to filter based on file extension. This must be done now. Two other exclusions also apply. First, we don't want to select the file that was used last time (we save one time back). Second, we don't want to select the temporary image that we generate (discussed later). The following code demonstrates copying the array into a generic List collection, element by element, provided that each element meets our exacting criteria.

Visual Basic

' Filter list to remove non-images, last image shown,
' and the app-generated BMP file from a previous run.
Dim filteredFiles As New List(Of String)()

For Each file As String In files

    Dim ext As String = file.Substring(file.LastIndexOf("."))

    If ".jpg .bmp .gif".IndexOf(ext) > -1 AndAlso _
        file.EndsWith("coding4fun-desktop.bmp") = False AndAlso _
        Not file = My.Settings.LastImageShown Then

        filteredFiles.Add(file)
    End If
Next

Visual C#

// Filter list to remove non-images, last image shown,
// and the app-generated BMP file from a previous run.

List<String> filteredFiles = new List<string>();
foreach (string file in files)
{
    string ext = file.Substring(file.LastIndexOf("."));

    if (".jpg .bmp .gif".IndexOf(ext) > -1 &&

        !file.EndsWith("coding4fun-desktop.bmp") &&
        file != settings.LastImageShown)
    {
        filteredFiles.Add(file);
    }
}

After all of this processing, it is possible that no files remain in our collection. Perhaps the folder was empty initially, none of the files were images, or the only image found was used last time. Either nothing will be returned, or a random index will be generated to grab one element out of the collection. Recall that these elements are full pathnames. We will save that pathname as the LastImageShown setting, create a Bitmap object given the pathname, then return that object.

Visual Basic

' Make sure there are any files left
If filteredFiles.Count = 0 Then Return Nothing

' Randomly grab a file
Dim filename As String = filteredFiles(rnd.Next(filteredFiles.Count))


' Remember last image shown
My.Settings.LastImageShown = filename
My.Settings.Save()

' Return the bitmap object from this filename
Return New Bitmap(filename)

Visual C#

// Make sure there are any files left
if (filteredFiles.Count == 0) 
    return null;


// Randomly grab a file
string filename = filteredFiles[rnd.Next(filteredFiles.Count)];

// Remember last image shown
settings.LastImageShown = filename;
settings.Save();

// Return the bitmap object from this filename
return new Bitmap(filename);

Finally the image is saved as a BMP file in the My Pictures folder, and passed to the appropriate system API function, SystemParametersInfo, to effect the change. Most of this is the same as in the original In the Box column referenced above, but the original required an image to be in BMP format to begin with. As it turns out, once you have loaded an image into a Bitmap object, saving as a BMP file format is a single line of code:

Visual Basic

' Convert to BMP and save

img.Save(picturesPath, System.Drawing.Imaging.ImageFormat.Bmp)

Visual C#

// Convert to BMP and save)
img.Save(picturesPath, System.Drawing.Imaging.ImageFormat.Bmp);

Study the SetDesktopBackground static/shared method in WindowsAPI.vb/.cs to see the implementation details.

Settings

Because the image to display can vary wildly each time, the settings dialog includes a number of behavioral settings. The first checkbox allows you to specify if sub-folders should be scanned or not. If you are pointing at a collection of home photos divided into sub-folders for albums, this could be useful.

The three ComboBox controls allow some flexibility in how images are displayed depending on their size relative to the desktop size. By default, images larger than the desktop will be stretched to fit. Now the term "stretched" is taken from the Windows Display control panel. It's a bit of a misnomer, since what it really means is "stretched or shrunk" in either direction to exactly fill the screen. It's really ugly if you have a widescreen display and conventional (4:3) images.

Images smaller than the screen will be centered. The final category, Tiled, is a bit more flexible. If you have very small images, you may want to tile them for a repeating pattern. Just specify how small is small (128 pixels in both directions, by default), specify the action (it doesn't need to be Tiled), and watch it go. I personally like the defaults, but it made some sense to allow them to be preferences so anyone can change them easily.

Figure 2: Settings dialog

All of the settings directly correspond to project settings defined in Visual Studio. This nifty feature lets you define settings at the user or application level, set a datatype, and even a default value. Then, to complete the coolness, you can actually databind these settings to the controls. All you need to do is load and save when necessary. The mechanics of copying data between controls and settings are taken care of for you!

Figure 3: Databinding settings

Working with the Registry

The application must write to the registry in order to set the stretched/tiled/centered attributes. This is very easy using the Registry object. Just use a static property, such as CurrentUser to access the HKEY_CURRENT_USER key. You can dig deeper by using a method like OpenSubKey to open nested keys and access their values. The wallpaper cycler application also uses the registry to add itself to Windows startup. The auto-start CheckBox control calls some shared/static methods in the WindowsAPI class to add and remove itself:

Visual Basic

' Based on checkbox, call API functions to add or remove
' application path from registry Run section for current user.

If autostartCheckbox.Checked Then
    WindowsAPI.AddStartupItem("BackgroundCycler", _ 
    System.Reflection.Assembly.GetEntryAssembly().Location)
Else
    WindowsAPI.RemoveStartupItem("BackgroundCycler")

End If

Visual C#

// Based on checkbox, call API functions to add or remove
// application path from registry Run section for current user.
            if (autostartCheckbox.Checked)
            {
                WindowsAPI.AddStartupItem("BackgroundCycler",
                    System.Reflection.Assembly.GetEntryAssembly().Location);
            }
            else

            {
                WindowsAPI.RemoveStartupItem("BackgroundCycler");
            }

Notice the call to System.Reflection.Assembly class. The GetEntryAssembly method returns a reference to the assembly that contained the startup code for the current application. The Location property returns the assembly filename, in this case the path to the executable file. In the AddStartupItem method, the sub-key for the current user's Run entries is opened, and a new value is added. So simple, but so powerful:

Visual Basic

Dim key As RegistryKey = _
    Registry.CurrentUser.OpenSubKey( _
    "Software\Microsoft\Windows\CurrentVersion\Run", True)
key.SetValue(name, path)

Visual C#

RegistryKey key = Registry.CurrentUser.OpenSubKey(
                @"Software\Microsoft\Windows\CurrentVersion\Run", true);

            key.SetValue(name, path);

Potential Enhancements

The application is ready to use, and fun too! You can change wallpaper frequently, even if your images are not already in BMP format, and you don't need to go into Desktop properties to do it. It might also be fun to add an option to automatically change images on a timed interval. Another challenge would be to provide the ability to download images at random from URLs. You could provide a URL to an image gallery, scan the HTML for image links, then randomly select one to download, convert, and show as wallpaper. Lots of options!

Conclusion

I hope this got you thinking about things to do with the Bitmap object, the Registry object, and desktop interaction. Be sure to visit http://msdn.microsoft.com/vstudio/express/ to download your preferred version of Visual Studio 2005 Express Edition. Then, take a look at the source code for this project, learn, and do even more. Good luck, and best of all, have fun!