Win32::Shortcut - Perl Module to deal with Windows Shortcuts

NAME

Win32::Shortcut - Perl Module to deal with Windows Shortcuts

SYNOPSIS

This module implements the Win32 IShellLink Interface to allow management of shortcut files from Perl.

  use Win32::Shortcut;
  $LINK = Win32::Shortcut->new();
  $LINK->{'Path'} = "C:\\Directory\\Target.exe";
  $LINK->{'Description'} = "Target executable";
  $LINK->Save("Target.lnk");
  $LINK->Close();

REFERENCE

General Usage

To use this module, first add the following line at the beginning of your script:

  use Win32::Shortcut;

Then, use this command to create a shortcut object:

  $LINK = Win32::Shortcut->new();

This function will create a $LINK object on which you can apply the Methods and Properties explained later.

The object is not yet a shortcut file; it is just the definition of a shortcut. Basically, you can do 2 things:

  1. Load a shortcut file into the object.
  2. Save the object into a shortcut file.

For the rest, the object can be accessed as it were a normal associative array reference. It has the following keys (here referred as properties):

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

Thus, assuming 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 = Win32::Shortcut->new();
  $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 = Win32::Shortcut->new();
  $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

and then you can save your changes to the shortcut file with this command:

  $LINK->Save();
  $LINK->Close();

or you can save it with another name, creating a new shortcut file:

  $LINK->Save("test2.lnk");
  $LINK->Close();

Finally, you can create a completely new shortcut:

  $LINK = Win32::Shortcut->new();
  $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->Save("Perl Version Info.lnk");
  $LINK->Close();

Note also that in the examples above the two lines:

  $LINK = Win32::Shortcut->new();
  $LINK->Load("test.lnk");

can be collapsed to:

  $LINK = Win32::Shortcut->new("test.lnk");

Methods

Close
Closes a shortcut object. Note that 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 somehow destroy such an object).

Note also 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.

Example:

  $LINK->Close();

Load file
Loads the content of the shortcut file named file in a shortcut object and fill the properties of the object with its values. Will return undef on errors, or a true value if everything was successful.

Example:

  $LINK->Load("test.lnk") or print "test.lnk not found!";
  print join("\n", $LINK->Path,
                   $LINK->ShortPath,
                   $LINK->Arguments,
                   $LINK->WorkingDirectory,
                   $LINK->Description,
                   $LINK->ShowCmd,
                   $LINK->Hotkey,
                   $LINK->IconLocation,
                   $LINK->IconNumber);
  }

new Win32::Shortcut [file]
Creates a new shortcut object. If a filename is passed in file, automatically Loads this file also. Returns the object created or undef on errors.

Example:

  $LINK = Win32::Shortcut->new();
  $RegEdit = Win32::Shortcut->new("Registry Editor.lnk");
  die "File not found" if not $RegEdit;

Resolve [flag]
Attempts to automatically resolve a shortcut and returns the resolved path, or undef on errors; in case no resolution was made, 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 (zero) in the flag parameter, it will eventually post a dialog box prompting the user for more information.

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 [file]
Saves the content of the shortcut object into the file named file. If file is omitted, it is taken from the File property of the object (which, if not changed, is the name of the last Loaded file).

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

Example:

 $LINK->Save();
 $LINK->Save("Copy of " . $LINK->{'File'});

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 those values changing the values of the properties.

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);
  # it is the same of...
  $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);

Properties

The properties of a shortcut object can be accessed as:

  $OBJECT->{'property'}

Eg., assuming that you have created a shortcut object with:

  $LINK=new Win32::Shortcut();

you can for example see its description with:

  print $LINK->{'Description'};

You can of course also set it:

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

From version 0.02, those properties have also a corresponding method (subroutine), so you can write the 2 lines above using this syntax too:

  print $LINK->Description;
  $LINK->Description("This is a description");

The properties of a shortcut reflect the content of the Shortcut Properties Dialog Box, which can be obtained by clicking the third mouse button on a shortcut file in the Windows 95 (or NT 4.0) Explorer and choosing ``Properties'' (well, I hope you already knew :).

The fields corresponding to the single properties are marked in bold in the following list.

Arguments
The arguments associated with the shell link object. They will be 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. Seems to be missing in the Shortcut Properties Dialog Box (not yet implemented?).

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 to the shortcut, in the form of a 2-byte number of which the first byte identifies the modifiers (Ctrl, Alt, Shift... but I didn't find out how it works) and the second is the ASCII code of the character key. Correspond to the ``Shortcut key'' field of a Shortcut Properties Dialog Box.

IconLocation
The file that contain the icon for the shortcut. Seems actually to always return nothing (YMMV, I hope...).

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 (I suppose this, documentation isn't so clear at this point).

Path
The target of the shortcut. This is (joined with Arguments) 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 characters 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). Correspond 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

Any other value (theoretically should) result in a Normal Window display.

WorkingDirectory
The directory in which the targeted program will be executed. Correspond to the ``Start in'' field of a Shortcut Properties Dialog Box.

Constants

The following constants are exported in the main namespace of your script using Win32::Shortcut:

Those constants are the allowed values for the ShowCmd property.

VERSION HISTORY

0.03 (07 Apr 1997)

0.02 (21 Jan 1997)

0.01 (15 Jan 1997)

0.01a (10 Jan 1997)

AUTHOR

Aldo Calpini dada@perl.it

Distributed under the terms of Larry Wall's Artistic License.

CREDITS

Thanks to: Jesse Dougherty, Dave Roth, ActiveWare, and the Perl-Win32-Users community.

DISCLAIMER

This program is FREE; you can redistribute, modify, disassemble, or even reverse engineer this software at your will. Keep in mind, however, that NOTHING IS GUARANTEED to work and everything you do is AT YOUR OWN RISK - I will not take responsibility for any damage, loss of money and/or health that may arise from the use of this program!

 Win32::Shortcut - Perl Module to deal with Windows Shortcuts