Author: Bill Todd

A Component for Creating and Modifying Shortcuts

Answer:

Windows shortcuts provide a way to have as many links to a file as you need - in as 
many folders as you want. Shortcuts are also the tool for adding a file to the 
Windows Start menu. 

In Windows 3.x, creating shortcuts was easy. You had to learn a couple of simple 
DDE calls, and that was it. In 32-bit Windows, working with shortcuts is more 
complex, and requires the use of COM and interfaces. This article will look at 
working with shortcuts in detail, and show you how to build a custom component you 
can use to create and modify shortcuts in any folder. 

The Interfaces

Shortcuts, or links as they are sometimes called, are actually binary files stored 
on your hard disk with the .lnk extension. The Windows shell includes a COM object 
named ShellLink for working with shortcuts. The ShellLink object implements two 
interfaces, IShellLink and IPersistFile, that define the methods for working with 
shortcuts. Figure 1 shows the declaration of IShellLink from SHLOBJ.PAS, and Figure 
2 shows the declaration of IPersistFile from ACTIVEX.PAS. 

1   IShellLinkA = interface(IUnknown) { sl. }
2     [SID_IShellLinkA]
3     function GetPath(pszFile: PAnsiChar; cchMaxPath: Integer;
4       var pfd: TWin32FindData; fFlags: DWORD): HResult;
5       stdcall;
6     function GetIDList(var ppidl: PItemIDList): HResult;
7       stdcall;
8     function SetIDList(pidl: PItemIDList): HResult; stdcall;
9     function GetDescription(pszName: PAnsiChar;
10      cchMaxName: Integer): HResult; stdcall;
11    function SetDescription(pszName: PAnsiChar): HResult;
12      stdcall;
13    function GetWorkingDirectory(pszDir: PAnsiChar;
14      cchMaxPath: Integer): HResult; stdcall;
15    function SetWorkingDirectory(pszDir: PAnsiChar): HResult;
16      stdcall;
17    function GetArguments(pszArgs: PAnsiChar;
18      cchMaxPath: Integer): HResult; stdcall;
19    function SetArguments(pszArgs: PAnsiChar): HResult;
20      stdcall;
21    function GetHotkey(var pwHotkey: Word): HResult; stdcall;
22    function SetHotkey(wHotkey: Word): HResult; stdcall;
23    function GetShowCmd(out piShowCmd: Integer): HResult;
24      stdcall;
25    function SetShowCmd(iShowCmd: Integer): HResult; stdcall;
26    function GetIconLocation(pszIconPath: PAnsiChar;
27      cchIconPath: Integer; out piIcon: Integer): HResult;
28      stdcall;
29    function SetIconLocation(pszIconPath: PAnsiChar;
30      iIcon: Integer): HResult; stdcall;
31    function SetRelativePath(pszPathRel: PAnsiChar;
32      dwReserved: DWORD): HResult; stdcall;
33    function Resolve(Wnd: HWND; fFlags: DWORD): HResult;
34      stdcall;
35    function SetPath(pszFile: PAnsiChar): HResult; stdcall;
36  end;
37  //Figure 1: The IShellLink interface. 
38  
39  IPersistFile = interface(IPersist)
40    ['{ 0000010B-0000-0000-C000-000000000046 }']
41    function IsDirty: HResult; stdcall;
42    function Load(pszFileName: POleStr; dwMode: Longint):
43      HResult; stdcall;
44    function Save(pszFileName: POleStr; fRemember: BOOL):
45      HResult; stdcall;
46    function SaveCompleted(pszFileName: POleStr): HResult;
47      stdcall;
48    function GetCurFile(out pszFileName: POleStr): HResult;
49      stdcall;
50  end;
51  Figure 2: The IPersistFile interface. 


Into the TWinShortcut Component 

The shell of the TWinShortcut custom component was created with the Component 
Wizard in the Object Repository, using TComponent as its ancestor Listing One shows 
the finished component. To make things easier to find, the properties and their 
private member variables are in alphabetical order. In the implementation section, 
the methods are divided into three groups: constructor and destructor, property 
getter and setter, and custom methods. Within each of these groups, the methods are 
in alphabetical order. The constructor is overridden to automatically create an 
instance of the ShellLink object using the following code: 

FShellLink := CreateComObject(CLSID_ShellLink) as IShellLink;
FPersistFile := FShellLink as IPersistFile;

The first statement creates the ShellLink object by calling CreateCOMObject and 
passing the ShellLink object's class ID as the parameter. The return value is cast 
to type IShellLink to provide a reference to the IShellLink interface and its 
methods. FShellLink is a protected member variable of type IShellLink. FPersistFile 
is also a protected member variable and is of type IPersistFile. Casting FShellLink 
to IPersistFile provides an interface reference to the IPersistFile methods 
implemented by the ShellLink object. TWinShortcut's destructor is overridden, and 
both FShellLink and FPersistFile are set to nil to destroy the ShellLink object. 
Because COM objects are reference counted, both variables must be set to nil before 
the ShellLink object will be destroyed. 

You must be able to specify the name and location of the shortcut file you want to 
work with, and that capability is provided by three properties: ShortcutFileName, 
ShortcutPath, and SpecialFolderLocation. One big problem in working with shortcuts 
is figuring out where to create them. For example, if you want to create a shortcut 
on the user's desktop, you have to know the path to the desktop folder, and that is 
different for different versions of Windows. 

The solution is a Windows API function named SHGetSpecialFolderLocation, which 
takes three parameters. The first is a window handle, which can be set to zero. The 
second is a constant that identifies the folder you want. To find a partial list of 
constants, click Start | Programs | Borland Delphi 5 | Help | MS SDK Help Files | 
Win32 Programmers Reference and search for SHGetSpecialFolderLocation. If you have 
the MSDN Library CD, search for SHGetSpecialFolderLocation and you'll find a list 
of over 40 folder constants. The Win32 Programmers Reference Help file also 
contains detailed information about IShellLink and IPersistFile and their methods. 
The third parameter is a variable of type PItemIdList. 

After calling SHGetSpecialFolderLocation, you will call SHGetPathFromIdList to 
extract the actual path from the PItemIdList parameter. The SpecialFolderLocation 
property of TWinShortcut is of type Word and corresponds to the second parameter, 
the folder number, of SHGetSpecialFolderLocation. This lets you specify the 
location of the shortcut by setting the value of the SpecialFolderLocation 
property, or by providing a path in the ShortcutPath property. 

TWinShortcut has a public OpenShortcut method that's used to open an existing 
shortcut. This method is only three statements long. The first statement is a call 
to the protected method GetFullShortcutPath. GetFullShortcutPath returns the full 
path and filename of the shortcut. The second statement, shown here, actually opens 
the file by calling the IPersistFile interface's Load method: 

OleCheck(FPersistFile.Load(PWideChar(WideString(FullPath)),
  STGM_READWRITE));

Load's two parameters are the name of the file and the mode. Because this function 
is Unicode-compatible, the path must be a null-terminated string of wide chars. 
Because the call to GetFullShortcutPath returns a Pascal ANSI string, the path 
variable FullPath is first cast to type WideString, and then cast to type PWideChar 
to match the type of the parameter. Note that Load is called as a parameter to the 
OleCheck procedure. OleCheck examines the value returned by 
SHGetSpecialFolderLocation, and if that value indicates an error, OleCheck raises 
an EOleSysError exception. This technique is used for all of the interface method 
calls in this example, so normal Delphi exception handling can be used to trap 
errors that occur when using this component. The last line of the LoadShortcut 
method calls the custom method GetPropertiesFromShortcut, which calls each of the 
get methods of the IShellLink interface and assigns the returned value to the 
corresponding property of TWinShortcut.

Before continuing, let's look at the GetFullShortcutPath and 
GetPropertiesFromShortcut methods used by OpenShortcut. If the ShortcutPath 
property is null, GetFullShortcutPath calls GetSpecialFolderPath. Otherwise, it 
assigns the value of the ShortcutPath property to Result. It then adds the 
ShortcutFileName property to the end of the string. This is safe because 
GetSpecialFolderPath always returns a path that ends with a backslash, and the 
write method for the ShortcutPath property ensures that the property value always 
ends with a backslash. The write method for the ShortcutFileName property ensures 
that the filename always includes the .lnk extension. 

GetSpecialFolderPath calls SHGetSpecialFolderLocation and passes the value of the 
SpecialFolderLocation property as the second parameter. This call loads the 
ItemIdList variable passed as the third parameter. Next, GetSpecialFolderPath calls 
SHGetPathFromIdList, passing two parameters. The first is the ItemIdList variable 
initialized by the call to SHGetSpecialFolderLocation, and the second is a char 
array, CharStr, into which the path will be placed. Finally, CharStr is assigned to 
the Result variable and a backslash is appended to the path. 

The final step in the OpenShortcut method is the call to GetPropertiesFromShortcut. 
This method calls each of the get methods in the IShellLink interface and assigns 
the returned value to the corresponding property of TWinShortcut. For example, the 
first call is to the IShellLink GetPath method, which returns the path to the 
target file, i.e. the file to which the shortcut points. These calls are 
straightforward with two exceptions. If you create a shortcut manually in Windows, 
and the shortcut is to a program that requires command-line arguments, you type 
them in the Target edit box following the path to the EXE file. However, the 
command-line arguments are stored separately in the shortcut file and are retrieved 
with a separate call, GetArguments.

The call to GetHotkey returns the hotkey information in a single parameter of type 
Word. The virtual key code is stored in the low byte, and the modifier flags that 
indicate which shift keys were pressed are stored in the high-order byte. If you 
want to display the hotkey as text, or give users the ability to enter a hotkey, 
the easy way is to use the THotkey component from the Win32 page of the Component 
palette. The problem is that the THotkey component stores the virtual key code in 
its HotKey property, and the modifier flags in its Modifiers property. To make 
things worse, the values used to represent the [Ctrl], [Alt], [Shift], and extended 
keys in the high byte of the value returned by GetHotkey, aren't the same as the 
values used to represent the same keys in the Modifiers property of THotkey. 

(Note: The extended-key flag indicates whether the keystroke message originated 
from one of the additional keys on the enhanced keyboard. The extended keys consist 
of the [Alt] and [Ctrl] keys on the right-hand side of the keyboard; the [Ins], 
[Del], [Home], [End], [PageUp], [PageDown], and the arrow keys to the left of the 
numeric keypad; the [NumLock] key; the k key; the [PrintScreen] key; and the divide 
(/) and [Enter] keys in the numeric keypad. The extended-key flag is set if the key 
is an extended key.) 

To make life easier for anyone using TWinShortcut, it has two properties, Hotkey 
and HotkeyModifiers, that are assignment-compatible with the properties of THotkey. 
The code following the call to GetHotkey converts the modifier flags from the form 
used by GetHotkey to the form used by the HotkeyModifiers property and by the 
THotkey component. The modifier constants used with GetHotkey and SetHotkey 
(HOTKEYF_ALT, HOTKEYF_CONTROL, HOTKEYF_SHIFT and HOTKEYF_EXT) are declared in the 
CommCtrl.pas unit. The constants used with the THotkey component's Modifiers 
property (hkAlt, hkCtrl, hkShift, and hkExt) are declared in the ComCtrls.pas unit. 

Creating or saving a modified shortcut is handled by the TWinShortcut's public 
SaveShortcut method. SaveShortcut begins by calling PutPropertiesToShortcut. This 
method calls the IShellLink put method for each property to assign the current 
value of the TWinShortcut properties to the corresponding shortcut properties. The 
only part of this process that is complex is converting the HotkeyModifiers 
property to the form required by the SetHotkey method. The series of if statements 
set the appropriate bits in the byte variable HotKeyMods. SetHotkey is called with 
a single-word parameter that's constructed by shifting HotKeyMods left eight bits 
to place it in the high-order byte of the word and adding the value of the HotKey 
property. Next, a call to GetFullShortcutPath returns the path to the link file. 
Finally, the IPersistFile Save method is called with the full path to the link file 
as a parameter. Again, the path must be cast first to a WideString, and then to a 
PWideChar. 

Conclusion

You can create and modify any Windows shortcut using the methods of the IShellLink 
and IPersistFile interfaces implemented by the ShellLink object. Although this 
article doesn't cover every method in detail, it should give you everything you 
need for most shortcut operations. For more detailed information about the 
interfaces or any of their methods, consult the Win32 Programmers Reference online 
help file that's installed with Delphi 5. 

Listing One - TWinShortcut
52  unit WinShortcut;
53  
54  interface
55  
56  uses
57    Windows, Messages, SysUtils, Classes, Graphics, Controls,
58    Forms, Dialogs, ComObj, ShlObj, ShellAPI, ActiveX, Menus,
59    ComCtrls;
60  
61  type
62    TWinShortcut = class(TComponent)
63    private
64      { Private declarations. }
65      FArguments: string;
66      FDescription: string;
67      FHotkey: Word;
68      FHotKeyModifiers: THKModifiers;
69      FIconFile: string;
70      FIconIndex: Integer;
71      FShortcutFileName: string;
72      FShortcutPath: string;
73      FRunWindow: Integer;
74      FSpecialFolder: Integer;
75      FTarget: string;
76      FWorkingDirectory: string;
77    protected
78      { Protected declarations. }
79      FPersistFile: IPersistFile;
80      FShellLink: IShellLink;
81      function GetFullShortcutPath: string;
82      procedure GetPropertiesFromShortcut;
83      function GetSpecialFolderPath: string;
84      procedure PutPropertiesToShortcut;
85      procedure SetShortcutFileName(Value: string);
86      procedure SetShortcutPath(Value: string);
87      procedure SetSpecialFolder(Value: Integer);
88    public
89      { Public declarations. }
90      constructor Create(AOwner: TComponent); override;
91      destructor Destroy; override;
92      procedure OpenShortcut;
93      procedure SaveShortcut;
94    published
95      { Published declarations. }
96      property Arguments: string
97        read FArguments write FArguments;
98      property Description: string
99        read FDescription write FDescription;
100     property HotKey: Word read FHotkey write FHotkey;
101     property HotKeyModifiers: THKModifiers
102       read FHotKeyModifiers write FHotKeyModifiers;
103     property IconFile: string
104       read FIconFile write FIconFile;
105     property IconIndex: Integer
106       read FIconIndex write FIconIndex;
107     property RunWindow: Integer
108       read FRunWindow write FRunWindow;
109     property Target: string read FTarget write FTarget;
110     property ShortcutFileName: string
111       read FShortcutFileName write SetShortcutFileName;
112     property ShortcutPath: string
113       read FShortcutPath write SetShortcutPath;
114     property SpecialFolder: Integer
115       read FSpecialFolder write SetSpecialFolder;
116     property WorkingDirectory: string
117       read FWorkingDirectory write FWorkingDirectory;
118   end;
119 
120 procedure register;
121 
122 implementation
123 
124 uses CommCtrl;
125 
126 const
127   Backslash = '\';
128   LinkExtension = '.LNK';
129 
130   { ********* Constructor and Destructor ********** }
131 
132 constructor TWinShortcut.Create(AOwner: TComponent);
133 begin
134   { Create the ShellLink object and get an IShellLink and
135    an IPersistFile reference to it. }
136   inherited;
137   FShellLink :=
138     CreateComObject(CLSID_ShellLink) as IShellLink;
139   FPersistFile := FShellLink as IPersistFile;
140 end;
141 
142 destructor TWinShortcut.Destroy;
143 begin
144   { Free the ShellLink object. }
145   FShellLink := nil;
146   FPersistFile := nil;
147   inherited;
148 end;
149 
150 { ********* Property Getter and Setter Methods ********** }
151 
152 procedure TWinShortcut.SetShortcutFileName(Value: string);
153 begin
154   FShortcutFileName := Value;
155   { If the file name does not end with the .LNK extension,
156    add the extension. }
157   if CompareText(ExtractFileExt(FShortcutFileName),
158     LinkExtension) <> 0 then
159     FShortcutFileName := FShortcutFileName + LinkExtension;
160 end;
161 
162 procedure TWinShortcut.SetShortcutPath(Value: string);
163 begin
164   FShortcutPath := Value;
165   { Make sure the path ends with a backslash. }
166   if Copy(FShortcutPath,
167     Length(FShortcutPath), 1) <> Backslash then
168     FShortcutPath := FShortcutPath + Backslash;
169 end;
170 
171 procedure TWinShortcut.SetSpecialFolder(Value: Integer);
172 begin
173   FSpecialFolder := Value;
174   { Clear the ShortcutPath when a value is assinged to the
175    SpecialFolder property. The SpecialFolder property will
176    not be used to get the path to the link file if the
177    ShortcutPath property is not null. }
178   FShortcutPath := '';
179 end;
180 
181 { ********* Custom Methods ********** }
182 
183 function TWinShortcut.GetFullShortcutPath: string;
184 { Gets the path to the shortcut file. If the ShortcutPath
185   property is null, the path comes from the SpecialFolder
186   property. }
187 begin
188   if FShortcutPath = '' then
189     Result := GetSpecialFolderPath
190   else
191     Result := FShortcutPath;
192   Result := Result + FShortcutFileName;
193 end;
194 
195 procedure TWinShortcut.GetPropertiesFromShortcut;
196 { Calls the appropriate IShellLink method to get the value
197   of each property of the link and assign that value to the
198   corresponding property of this component. }
199 var
200   CharStr: array[0..MAX_PATH] of Char;
201   WinFindData: TWin32FindData;
202   RunWin: Integer;
203   HotKeyWord: Word;
204   HotKeyMod: Byte;
205 begin
206   OleCheck(FShellLink.GetPath(CharStr, MAX_PATH,
207     WinFindData, SLGP_UNCPRIORITY));
208   Target := CharStr;
209   OleCheck(FShellLink.GetArguments(CharStr, MAX_PATH));
210   Arguments := CharStr;
211   OleCheck(FShellLink.GetDescription(CharStr, MAX_PATH));
212   Description := CharStr;
213   OleCheck(
214     FShellLink.GetWorkingDirectory(CharStr, MAX_PATH));
215   WorkingDirectory := CharStr;
216   OleCheck(FShellLink.GetIconLocation(CharStr, MAX_PATH,
217     FIconIndex));
218   IconFile := CharStr;
219   OleCheck(FShellLink.GetShowCmd(RunWin));
220   RunWindow := RunWin;
221   OleCheck(FShellLink.GetHotkey(HotKeyWord));
222   { Extract the HotKey and Modifier properties. }
223   HotKey := HotKeyWord;
224   HotKeyMod := Hi(HotKeyWord);
225   if (HotKeyMod and HOTKEYF_ALT) = HOTKEYF_ALT then
226     Include(FHotKeyModifiers, hkAlt);
227   if (HotKeyMod and HOTKEYF_CONTROL) = HOTKEYF_CONTROL then
228     Include(FHotKeyModifiers, hkCtrl);
229   if (HotKeyMod and HOTKEYF_SHIFT) = HOTKEYF_SHIFT then
230     Include(FHotKeyModifiers, hkShift);
231   if (HotKeyMod and HOTKEYF_EXT) = HOTKEYF_EXT then
232     Include(FHotKeyModifiers, hkExt);
233 end;
234 
235 function TWinShortcut.GetSpecialFolderPath: string;
236 { Returns the full path to the special folder specified in
237   the SpecialFolder property. A backslash is appended to
238   the path. }
239 var
240   ItemIdList: PItemIdList;
241   CharStr: array[0..MAX_PATH] of Char;
242 begin
243   OleCheck(ShGetSpecialFolderLocation(0, FSpecialFolder,
244     ItemIdList));
245   if ShGetPathFromIdList(ItemIdList, CharStr) then
246   begin
247     Result := CharStr;
248     Result := Result + Backslash;
249   end; // if
250 end;
251 
252 procedure TWinShortcut.OpenShortcut;
253 { Opens the shortcut and loads its properties into the
254   component properties. }
255 var
256   FullPath: string;
257 begin
258   FullPath := GetFullShortcutPath;
259   OleCheck(FPersistFile.Load(PWideChar(WideString(
260     FullPath)), STGM_READWRITE));
261   GetPropertiesFromShortcut;
262 end;
263 
264 procedure TWinShortcut.PutPropertiesToShortcut;
265 { Calls the appropriate IShellLink method to assign the
266   value of each of the components properties to the
267   corresponding property of the shortcut. }
268 var
269   HotKeyMods: Byte;
270 begin
271   HotKeyMods := 0;
272   OleCheck(FShellLink.SetPath(PChar(FTarget)));
273   OleCheck(FShellLink.SetIconLocation(PChar(FIconFile),
274     FIconIndex));
275   OleCheck(FShellLink.SetDescription(PChar(FDescription)));
276   OleCheck(FShellLink.SetWorkingDirectory(PChar(
277     FWorkingDirectory)));
278   OleCheck(FShellLink.SetArguments(PChar(FArguments)));
279   OleCheck(FShellLink.SetShowCmd(FRunWindow));
280   if hkShift in FHotKeyModifiers then
281     HotKeyMods := HotKeyMods or HOTKEYF_SHIFT;
282   if hkAlt in FHotKeyModifiers then
283     HotKeyMods := HotKeyMods or HOTKEYF_ALT;
284   if hkCtrl in FHotKeyModifiers then
285     HotKeyMods := HotKeyMods or HOTKEYF_CONTROL;
286   if hkExt in FHotKeyModifiers then
287     HotKeyMods := HotKeyMods or HOTKEYF_EXT;
288   OleCheck(
289     FShellLink.SetHotkey((HotKeyMods shl 8) + HotKey));
290 end;
291 
292 procedure TWinShortcut.SaveShortcut;
293 { Copies the component properties to the shortcut
294   and saves it. }
295 var
296   FullPath: string;
297 begin
298   PutPropertiesToShortcut;
299   FullPath := GetFullShortcutPath;
300   OleCheck(FPersistFile.Save(PWideChar(
301     WideString(FullPath)), True));
302 end;
303 
304 procedure register;
305 begin
306   RegisterComponents('DI', [TWinShortcut]);
307 end;
308 
309 end.

End Listing One


Component Download: http://www.baltsoft.com/files/dkb/attachment/A_Quick_Way_to_Shortcuts.zip