start page | rating of books | rating of authors | reviews | copyrights
Book HomeJava and XSLTSearch this book
PreviousNext

22.18. 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 was 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 Section 22.18.1, "Shortcut Properties" 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.

new
new Win32::Shortcut [file]

Creates a new shortcut object. If a filename is passed in file, automatically Load s this file also. Returns the object created, or undef on error.

Close
$link->Close(  )

Closes a shortcut object. It is not strictly required to close the objects you created, since the Win32::Shortcut objects are automatically closed when the program ends (or when you otherwise destroy such an object).

Also note that a shortcut is not automatically saved when it is closed, even if you modified it. You have to call Save in order to apply modifications to a shortcut file.

Load
$link->Load(file)

Loads the content of the shortcut file named file in a shortcut object and fills the properties of the object with its values. Returns undef on error, or true if everything was successful.

Resolve
$link->Resolve([flag])

Attempts to automatically resolve a shortcut and returns the resolved path, or undef on error; if there is no resolution, the path is returned unchanged. Note that the path is automatically updated in the Path property of the shortcut.

By default, this method acts quietly, but if you pass a value of 0 in the flagparameter, it will eventually post a dialog box prompting the user for more information. For example: 

# If the target doesn't exist...
if(! -f $link->Path) {

    # Save the actual target for comparison
    $oldpath = $link->Path;

    # Try to resolve it (with dialog box)
    $newpath = $link->Resolve(0); 

    die "Not resolved..." if $newpath == $oldpath;
}
Save
$link->Save([file])

Saves the content of the shortcut object into the file named file. If file is omitted, the filename is taken from the File property of the object (which, if not changed, is the name of the last Load ed file).

If no file was loaded, and the File property doesn't contain a valid filename, the method returns undef, which is also returned on error. A true value is returned if everything was successful.

Set
$link->Set(path, arguments, workingdirectory, description, 
showcmd, hotkey, iconlocation, iconnumber)

Sets all the properties of the shortcut object with a single command. This method is supplied for convenience only; you can also set these values by changing the values of the properties. For example: 

$link->Set("C:\PERL5\BIN\PERL.EXE",
           "-v", 
           "C:\PERL5\BIN",
           "Prints out the version of Perl",
           SW_SHOWMAXIMIZED,
           hex('0x0337'),
           "C:\WINDOWS\SYSTEM\COOL.DLL",
           1);

This is the same as: 

$link->Path("C:\PERL5\BIN\PERL.EXE");
$link->Arguments("-v");
$link->WorkingDirectory("C:\PERL5\BIN");
$link->Description("Prints out the version of Perl");
$link->ShowCmd(SW_SHOWMAXIMIZED);
$link->Hotkey(hex('0x0337'));
$link->IconLocation("C:\WINDOWS\SYSTEM\COOL.DLL");
$link->IconNumber(1);</PRE>

22.18.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 that 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 right-clicking 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 fileargument is not specified).

Hotkey
The hotkey associated with the shortcut, in the form of a two-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 to 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.

PreviousHomeNext
22.17. Win32::ServiceBook Index22.19. Win32 Extensions
Library Navigation Links

Copyright © 2002 O'Reilly & Associates. All rights reserved.