<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN">
<HTML>
<HEAD>
<TITLE>Win32::Shortcut Reference</TITLE>
</HEAD>
<BODY BGCOLOR="white"
onLoad="window.defaultStatus=document.title; return true">
<FONT FACE=Arial><H2><A NAME=Reference>Reference Manual</H2></FONT>
<HR>
<FONT FACE=Arial><H3><A NAME=General>General Usage</H3></FONT>
<FONT FACE=Arial SIZE=2>
To use this module, first add the following line at the beginning of your script:
</FONT><PRE> use Win32::Shortcut;</PRE><FONT FACE=Arial SIZE=2>
Then, use this command to create a shortcut object:
</FONT><PRE> $LINK = new Win32::Shortcut();</PRE><FONT FACE=Arial SIZE=2>
This function will create a </FONT><TT>$LINK</TT><FONT FACE=Arial SIZE=2>
object on which you can apply the
<A HREF="#Methods">Methods</A> and <A HREF="#Properties">Properties</A> explained later.
<P>
The object is not yet a shortcut file; it is just the definition of a shortcut.
Basically, you can do 2 things:
<OL>
<LI><A HREF="#Load">Load</A> a shortcut file into the object.
<LI><A HREF="#Save">Save</A> the object into a shortcut file.
</OL>
For the rest, the object can be accessed as it were a normal associative array reference.
It has the following keys (here referred as <A HREF="#Properties">properties</A>):
</FONT><PRE>
$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()
</PRE><FONT FACE=Arial SIZE=2>
Thus, assuming you have a shortcut file named
</FONT><TT>test.lnk</TT><FONT FACE=Arial SIZE=2>
in your current directory, this simple script will tell you where this shortcut points to:
</FONT><PRE>
use Win32::Shortcut;
$LINK=new Win32::Shortcut();
$LINK->Load("test.lnk");
print "Shortcut to: $LINK->{'Path'} $LINK->{'Arguments'} \n";
$LINK->Close();
</PRE><FONT FACE=Arial SIZE=2>
But you can also modify its values:
</FONT><PRE>
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
</PRE><FONT FACE=Arial SIZE=2>
and then you can save your changes to the shortcut file with this command:
</FONT><PRE>
$LINK->Save();
$LINK->Close();
</PRE><FONT FACE=Arial SIZE=2>
or you can save it with another name, creating a new shortcut file:
</FONT><PRE>
$LINK->Save("test2.lnk");
$LINK->Close();
</PRE><FONT FACE=Arial SIZE=2>
Finally, you can create a completely new shortcut:
</FONT><PRE>
$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();
</PRE><FONT FACE=Arial SIZE=2>
Note also that in the examples above the two lines:
</FONT><PRE>
$LINK=new Win32::Shortcut();
$LINK->Load("test.lnk");
</PRE><FONT FACE=Arial SIZE=2>
can be collapsed to:
</FONT><PRE>
$LINK=new Win32::Shortcut("test.lnk");
</PRE><FONT FACE=Arial SIZE=2>
</FONT>
<P>
<HR>
<FONT FACE=Arial><H3><A NAME=Methods>Methods</H3></FONT>
<DL>
<DT><FONT FACE=Arial SIZE=2><A NAME=Close>
<B>Close</B>
<DD>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).
<BR>
Note also that a shortcut is not automatically saved when it is closed,
even if you modified it. You have to call <A HREF="#Save">Save</A> in order to
apply modifications to a shortcut file.
<BR>
Example:</FONT>
<PRE> $LINK->Close();</PRE>
<P>
<DT><FONT FACE=Arial SIZE=2><A NAME=Load>
<B>Load</B> <I>file</I>
<DD>Loads the content of the shortcut file named <I>file</I> in a shortcut object
and fill the <A HREF="#Properties">properties</A> of
the object with its values.
Will return <B>undef</B> on errors, or a true value
if everything was successful.
<BR>
Example:</FONT><PRE> $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);
}</PRE>
<P>
<DT><FONT FACE=Arial SIZE=2><A NAME=new>
<B>new Win32::Shortcut</B> <I>[file]</I>
<DD>Creates a new shortcut object. If a filename is passed in <I>file</I>,
automatically <A HREF="#Load">Load</A>s this file also.
Returns the object created or <B>undef</B> on errors.
<BR>
Example:</FONT>
<PRE> $LINK = new Win32::Shortcut();
$RegEdit = new Win32::Shortcut("Registry Editor.lnk");
die "File not found" if not $RegEdit;</PRE>
<P>
<DT><FONT FACE=Arial SIZE=2><A NAME=Resolve>
<B>Resolve</B> <I>[flag]</I>
<DD>Attempts to automatically resolve a shortcut and returns the resolved path,
or <B>undef</B> on errors;
in case no resolution was made, the path is returned unchanged.
Note that the path is automatically updated in the <A HREF="#Path">Path</A>
property of the shortcut.
<BR>
By default this method acts quietly, but if you pass a value of 0 (zero)
in the <I>flag</I> parameter, it will eventually
post a dialog box prompting the user for more information.
<BR>
Example:</FONT>
<PRE> # 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;
}</PRE>
<P>
<DT><FONT FACE=Arial SIZE=2><A NAME=Save>
<B>Save</B> <I>[file]</I>
<DD>Saves the content of the shortcut object into the file named <I>file</I>.
If <I>file</I> is omitted, it is taken from the <A HREF="#File">File</A> property
of the object (which, if not changed, is the name of the last <A HREF="#Load">Load</A>ed file).
<BR>
If no file was loaded and the <A HREF="#File">File</A> property doesn't contain a valid filename,
the method will return <B>undef</B>, which will also be returned on errors.
A true value will be returned if everything was successful.
<BR>
Example:</FONT><PRE> $LINK->Save();
$LINK->Save("Copy of " . $LINK->{'File'});</PRE>
<P>
<DT><FONT FACE=Arial SIZE=2><A NAME=Set>
<B>Set</B> <I>path, arguments, workingdirectory, description, showcmd, hotkey, iconlocation, iconnumber</I>
<DD>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 <A HREF="#Properties">properties</A>.
<BR>
Example:</FONT>
<PRE> $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);</PRE>
<P>
</DL>
<HR>
<FONT FACE=Arial><H3><A NAME=Properties>Properties</H3></FONT>
<FONT FACE=Arial SIZE=2>
The properties of a shortcut object can be accessed as:
</FONT><PRE> $<I>OBJECT</I>->{'<I>property</I>'}</PRE><FONT FACE=Arial SIZE=2>
Eg., assuming that you have created a shortcut object with:
</FONT><PRE> $LINK=new Win32::Shortcut();</PRE><FONT FACE=Arial SIZE=2>
you can for example see its <A HREF="#Description">description</A> with:
</FONT><PRE> print $LINK->{'Description'};</PRE><FONT FACE=Arial SIZE=2>
You can of course also set it:
</FONT><PRE> $LINK->{'Description'}="This is a description";</PRE><FONT FACE=Arial SIZE=2>
From version 0.02, those properties have also a corresponding method (subroutine), so
you can write the 2 lines above using this syntax too:
</FONT><PRE> print $LINK->Description;
$LINK->Description("This is a description");</PRE><FONT FACE=Arial SIZE=2>
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 :).
<BR>
The fields corresponding to
the single properties are marked in <B>bold</B> in the following list.
</FONT>
<DL>
<DT><FONT FACE=Arial SIZE=2><A NAME=Arguments>
<B>Arguments</B>
<DD>The arguments associated with the shell link object.
They will be passed to the targeted program (see <A HREF="#Path">Path</A>)
when it gets executed.
In fact, joined with <A HREF="#Path">Path</A>, this parameter forms the
"<B>Target</B>" field of a Shortcut Properties Dialog Box.
<P>
<DT><FONT FACE=Arial SIZE=2><A NAME=Description>
<B>Description</B>
<DD>An optional description given to the shortcut.
Seems to be missing in the Shortcut Properties Dialog Box (not yet implemented?).
<P>
<DT><FONT FACE=Arial SIZE=2><A NAME=File>
<B>File</B>
<DD>The filename of the shortcut file opened with <A HREF="#Load">Load</A>,
and/or the filename under which the shortcut will be saved with
<A HREF="#Save">Save</A> (if the <I>file</I> argument is not specified).
<P>
<DT><FONT FACE=Arial SIZE=2><A NAME=Hotkey>
<B>Hotkey</B>
<DD>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 "<B>Shortcut key</B>" field of a Shortcut Properties Dialog Box.
<P>
<DT><FONT FACE=Arial SIZE=2><A NAME=IconLocation>
<B>IconLocation</B>
<DD>The file that contain the icon for the shortcut.
Seems actually to always return nothing (YMMV, I hope...).
<P>
<DT><FONT FACE=Arial SIZE=2><A NAME=IconNumber>
<B>IconNumber</B>
<DD>The number of the icon for the shortcut in the file pointed by
<A HREF="#IconLocation">IconLocation</A>, in case more that one icon
is contained in that file (I suppose this, documentation isn't so clear at this point).
<P>
<DT><FONT FACE=Arial SIZE=2><A NAME=Path>
<B>Path</B>
<DD>The target of the shortcut.
This is (joined with <A HREF="#Arguments">Arguments</A>) the content
of the "<B>Target</B>" field in a Shortcut Properties Dialog Box.
<P>
<DT><FONT FACE=Arial SIZE=2><A NAME=ShortPath>
<B>ShortPath</B>
<DD>Same as <A HREF="#Path">Path</A>, 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 <A HREF="#Path">Path</A> instead)
once you <A HREF="#Load">Load</A> a shortcut file.
<P>
<DT><FONT FACE=Arial SIZE=2><A NAME=ShowCmd>
<B>ShowCmd</B>
<DD>The condition of the window in which the program will be executed
(can be Normal, Minimized or Maximized).
Correspond to the "<B>Run</B>" field of a Shortcut Properties Dialog Box.
<BR>
Allowed values are:
<TABLE>
<TD><FONT FACE=Arial SIZE=2><B>Value</TD>
<TD><FONT FACE=Arial SIZE=2><B>Meaning</TD>
<TD><FONT FACE=Arial SIZE=2><B>Constant</TD>
<TR VALIGN=top>
<TD><TT>1</TD>
<TD><FONT FACE=Arial SIZE=2>Normal Window</TD>
<TD><TT>SW_SHOWNORMAL</TD>
<TR VALIGN=top>
<TD><TT>3</TD>
<TD><FONT FACE=Arial SIZE=2>Maximized</TD>
<TD><TT>SW_SHOWMAXIMIZED</TD>
<TR VALIGN=top>
<TD><TT>7</TD>
<TD><FONT FACE=Arial SIZE=2>Minimized</TD>
<TD><TT>SW_SHOWMINNOACTIVE</TD>
</TABLE>
<P>
Any other value (theoretically should) result in a Normal Window display.
<P>
<DT><FONT FACE=Arial SIZE=2><A NAME=WorkingDirectory>
<B>WorkingDirectory</B>
<DD>The directory in which the targeted program will be executed.
Correspond to the "<B>Start in</B>" field of a Shortcut Properties Dialog Box.
<P>
</DL>
<HR>
<FONT FACE=Arial><H3><A NAME=Constants>Constants</H3></FONT>
The following constants are exported in the main namespace of your script using Win32::Shortcut:
</FONT><FONT SIZE=3 FACE=><TT>
<UL>
<LI>SW_SHOWNORMAL
<LI>SW_SHOWMAXIMIZED
<LI>SW_SHOWMINNOACTIVE
</UL>
</TT><FONT FACE=Arial SIZE=2>
Those constants are the allowed values for the <A HREF="#ShowCmd">ShowCmd</A> property.
<P>
<HR>
<FONT FACE=Arial SIZE=1>
08 Apr 1997, Aldo Calpini
<<A HREF="mailto:dada@perl.it">dada@perl.it</A>>
</FONT><P>
</BODY>
</HTML>