19.16 Win32::Shortcut (Perl in a Nutshell)

19.16 Win32::Shortcut

This module allows you to create and manipulate Windows shortcut files ( .lnk files) through Perl. The methods and properties of this module apply to shortcut objects created by new :

use Win32::Shortcut;
$link = Win32::Shortcut->new();

This creates the shortcut object


$link

, on which you can set properties and save into a file. If you supply a filename as an argument to

new

, the file will be loaded into the shortcut object.

The object can also be accessed as if it were a normal hash reference. The following properties (hash keys) are available:

$link->{'File'}               
$link->{'Path'}
$link->{'ShortPath'}
$link->{'WorkingDirectory'}
$link->{'Arguments'}
$link->{'Description'}
$link->{'ShowCmd'}
$link->{'Hotkey'}
$link->{'IconLocation'}
$link->{'IconNumber'}

See the section on shortcut properties, below, for a description of each property.

The following example assumes you have a shortcut file named test.lnk in your current directory. This simple script will tell you where this shortcut points to:

use Win32::Shortcut;
$link=new Win32::Shortcut();
$link->Load("test.lnk");
print "Shortcut to: $link->{'Path'} $link->{'Arguments'} \n";
$link->Close();

But you can also modify its values:

use Win32::Shortcut;
$link=new Win32::Shortcut();
$link->Load("test.lnk");
$link->{'Path'}=~s/C:/D:/i; # move the target from C: to D:
$link->{'ShowCmd'}=SW_NORMAL; # runs in a normal window

The methods provided by Win32::Shortcut are as follows:

19.16.1 Shortcut properties

The properties of a shortcut object can be accessed as:

$link->{'
property
'}

For example, assuming that you have created a shortcut object with:

$link=new Win32::Shortcut();

you can see its description with:

print $link->{'Description'};

You can of course also set it like this:

$link->{'Description'}="This is a description";

The shortcut properties also have corresponding methods which can also set or read their values.

The properties of a shortcut reflect the content of the Shortcut Properties dialog box, which can be obtained by clicking the right mouse button on a shortcut file in the Windows 95 (or NT 4.0) Explorer and choosing "Properties." Shortcut properties are:

Arguments

The arguments associated with the shell link object. They are passed to the targeted program (see Path ) when it gets executed. In fact, joined with Path , this parameter forms the "Target" field of a Shortcut Properties dialog box.

Description

An optional description given to the shortcut. Not implemented in Shortcut Properties dialog box.

File

The filename of the shortcut file opened with Load , and/or the filename under which the shortcut will be saved with Save (if the file argument is not specified).

Hotkey

The hotkey associated with the shortcut, in the form of a 2-byte number, of which the first byte identifies the modifiers (Ctrl, Alt, Shift, etc.), and the second is the ASCII code of the character key. Corresponds to the "Shortcut key" field of a Shortcut Properties dialog box.

IconLocation

The file that contains the icon for the shortcut.

IconNumber

The number of the icon for the shortcut in the file pointed by IconLocation , in case more that one icon is contained in that file.

Path

The target of the shortcut. This (joined with Arguments ) is the content of the "Target" field in a Shortcut Properties dialog box.

ShortPath

Same as Path , but expressed in a DOS-readable format (8.3-character filenames). It is available as read-only (well, you can change it, but it has no effect on the shortcut; change Path instead) once you Load a shortcut file.

ShowCmd

The condition of the window in which the program will be executed (can be Normal, Minimized or Maximized). Corresponds to the "Run" field of a Shortcut Properties dialog box. Allowed values are:

Value	Meaning	Constant
1	Normal window	SW_SHOWNORMAL
3	Maximized	SW_SHOWMAXIMIZED
7	Minimized	SW_SHOWMINNOACTIVE

WorkingDirectory

The directory in which the targeted program will be executed. Corresponds to the "Start in" field of a Shortcut Properties dialog box.