Wednesday, May 25, 2011

Adding Windows 7 Jump List to a Delphi 2010 application

Recently I decided to update one of my Delphi applications and make it more shiny when running on Windows 7. I looked up in the list of the new Windows 7 features and selected the Windows 7 taskbar Jump List as a nice feature for my application. As of Windows 7, the taskbar has been extended with a possibility to create a list of destinations and common tasks associated with an application.This is the application's Jump List. The Jump List is available whether the taskbar button is in a launcher state (the application isn't running) or whether it represents one or more windows.


As a result of this work I made a Delphi 2010 library for easy manipulating of Windows 7 Jump List.
You can download the full source code here:
http://1drv.ms/1iWeIDJ


The Jump List class is similar to Microsoft .NET 4.0 JumpList class

TJumpList = class sealed
  ...
  public
    constructor Create;
    destructor Destroy; override;
    procedure Clear;
    procedure AddToRecentCategory(ItemPath: string); overload;
    procedure AddToRecentCategory(JumpPath: TJumpPath); overload;
    procedure AddToRecentCategory(JumpTask: TJumpTask); overload;
    function AddJumpPath : TJumpPath;
    function AddJumpTask : TJumpTask;
    function AddJumpSeparator : TJumpSeparator;
    function AddJumpItem<T : TJumpItem, constructor> : T;
    procedure Apply;
    procedure DeleteList;
    property ShowFrequentCategory : boolean read FShowFrequentCategory write FShowFrequentCategory;
    property ShowRecentCategory : boolean read FShowRecentCategory write FShowRecentCategory;
    property JumpItems : TList<TJumpItem> read FJumpItems;
    property ApplicationId : string read FApplicationId write SetApplicationId;
  end;

and can handle 3 types of items: Tasks, Paths and Separators. In case if you wish to add Path item to the list you have to register your application as a file type handler for the specific file extension you are going to use.
For more details see my previous post.

The library is simple enough. Here is a short sample how to use it in your application.

First step is to provide an application id

JumpList := TJumpList.Create;
  JumpList.ApplicationId := 'TaskbarDemo.Unique.Id';

Then you can add some items to the Jump List and apply your changes.

var
  Item : TJumpTask;
begin

  Item := TJumpTask.Create;
  Item.Title := 'Custom Task';
  Item.ApplicationPath := ParamStr(0);
  Item.Arguments := '/doit';
  Item.CustomCategory := 'Custom Category';

  JumpList.JumpItems.Add(Item);

  JumpList.Apply;
end;

That's all. Just download and use it. But if you want more details here is the advanced version of the story.

When I decided to add the Jump List to my application I checked VCL first hoping that the Jump List class or component is already available. Unfortunately I found only some interfaces and type definitions of Windows API ported to Delphi, but not a complete ready to use class. The second step was searching Google. I found some examples how to make a Jump List in Delphi, but most of them were quite incomplete.
There was almost no information how to handle ShellItem items or how to properly register the application as a file type handler. Finally I decided to create the Jump List class by myself.

The first important point was usage of the Application User Model Id. Application User Model IDs (AppIDs) are used extensively by the taskbar in Windows 7 and later systems to associate processes, files, and windows with a particular application.

An application must provide its AppID in the following form. It is limited to 128 characters.

CompanyName.ProductName.SubProduct.VersionInformation

Usually when describing the usage of the Jump List the authors pay not too much attention to it, but without providing an Application User Model Id not all features of the Jump List work properly.
Id must be provided at the start of the application and before to call any other methods of the Jump List class.

If you are planning to use the Recent or Frequent categories in your Jump List do not forget to associate the file extensions of the files which can be opened by your application with the application executable.
If this step is not done and you try to add a ShellItem item to the Jump List then it fails. The file registration helper class is also included in the library.

var
  F : TFileRegistrationHelper;
begin
  F := TFileRegistrationHelper.Create('Microsoft.Samples.TaskbarDemo', ParamStr(0),
  'TaskbarDemo Document', 'TaskbarDemo.AppID.1.0.0.0', '.w7c');
  F.RegisterToHandleFileType(True);
end;