Win32::Shortcut Reference

## Reference Manual

### 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 = new Win32::Shortcut();

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=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

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=new Win32::Shortcut();
      $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=new Win32::Shortcut();
      $LINK->Load("test.lnk");

can be collapsed to:

      $LINK=new Win32::Shortcut("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 elsehow 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 = new Win32::Shortcut();

       $RegEdit = new Win32::Shortcut("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: `

- SW_SHOWNORMAL
- SW_SHOWMAXIMIZED
- SW_SHOWMINNOACTIVE

` Those constants are the allowed values for the ShowCmd property.

08 Apr 1997, Aldo Calpini <dada@divinf.it>