=head1 NOM

Win32::Shortcut - Gestion des raccourcis Win32 depuis Perl

=head1 SYNOPSIS

    use Win32::Shortcut;

    $LINK = new Win32::Shortcut();

=head1 DESCRIPTION

Ce module implémente l'interface Win32 IShellLink pour permettre la
gestion des raccourcis de fichiers depuis Perl.

=head2 Utilisation générale

Pour utiliser ce module, ajoutez d'abord la ligne suivante au début
de votre script :

    use Win32::Shortcut;

Puis, vous utilisez la commande suivante pour créer un objet raccourci :

    $LINK = new Win32::Shortcut();

Cette fonction créera un objet C<$LINK> sur lequel vous pourrez appliquer
les L<"Méthodes"> et L<"Propriétés"> expliquées plus bas.

L'objet n'est cependant pas un raccourci; c'est juste la définition d'un
raccourci. Fondamentalement, vous pouvez alors faire 2 choses:

=over 4

=item 1

L<Charger|Load> un fichier raccourci dans l'objet.

=item 2

L<Sauver|Save> l'objet dans un fichier raccourci.

=back

Pour le reste, l'objet peut être accédé comme si c'était une référence
à un tableau associatif normal. Il possède les clefs suivantes
(ici reportées comme L<propriétés|propriétés>):

    $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()

Donc, en supposant que vous avez un fichier raccourci nommé C<test.lnk>
dans votre répertoire courant, ce script simple vous dira où ce raccourci
pointe :

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

Mais vous pouvez aussi modifier ses valeurs :

    use Win32::Shortcut;
    $LINK=new Win32::Shortcut();
    $LINK->Load("test.lnk");
    $LINK->{'Path'}=~s/C:/D:/i;   # change la cible de C: en D:
    $LINK->{'ShowCmd'}=SW_NORMAL; # lancement dans une fenêtre normale

et alors vous pouvez sauver vos changements dans le fichier raccourci avec
cette commande :

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

ou alors vous pouvez le sauver sous un autre nom, en créant un nouveau
fichier raccourci :

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

Finalement, vous pouvez créer un raccourci complètement nouveau :

    $LINK=new Win32::Shortcut();
    $LINK->{'Path'}="C:\PERL5\BIN\PERL.EXE";
    $LINK->{'Arguments'}="-v";
    $LINK->{'WorkingDirectory'}="C:\PERL5\BIN";
    $LINK->{'Description'}="Affiche la version de Perl";
    $LINK->{'ShowCmd'}=SW_SHOWMAXIMIZED;
    $LINK->Save("Perl Version Info.lnk");
    $LINK->Close();

Notez aussi que, dans les exemples ci-dessus, les deux lignes :

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

peuvent être réduite à :

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

=head2 Méthodes

=over 4

=item Close

Ferme un objet raccourci. Notez qu'il n'est pas "strictement" requis de fermer
les objets que vous créez, puisque les objets Win32::Shortcut sont automatiquement
fermés quand le programme se termine (ou quand un tel objet est détruit).
Notez aussi qu'un raccourci n'est pas sauvé automatiquement quand il est fermé,
même si vous l'avez modifié. Vous devez appeler C<Save> pour appliquer les
modifications à un fichier raccourci.

Exemple:

      $LINK->Close();

=item Load (fichier)

Charge le contenu du fichier raccourci nommé I<fichier> dans un objet raccourci
et remplit les L<propriétés|propriétés> de l'objet avec ses valeurs.
Retourne C<undef> en cas d'erreur, ou une valeur VRAI si tout réussit.

Exemple:

      $LINK->Load("test.lnk") or print "test.lnk introuvable !";

      print join("\n", $LINK->Path,
                       $LINK->ShortPath,
                       $LINK->WorkingDirectory,
                       $LINK->Description,
                       $LINK->ShowCmd,
                       $LINK->Hotkey,
                       $LINK->IconLocation,
                       $LINK->IconNumber);
      }

=item new Win32::Shortcut ([fichier])

Crée un nouvel objet raccourci. Si un nom de fichier est passé dans I<fichier>,
ce fichier est automatiquement L<chargé|Load> aussi.
Retourne l'objet créé ou C<undef> en cas d'erreur.

Exemple:

      $LINK = new Win32::Shortcut();

      $RegEdit = new Win32::Shortcut("Registry Editor.lnk");
      die "Fichier introuvable" if not $RegEdit;

=item Resolve ([flag])

Tente de résoudre un raccourci et retourne le chemin trouvé ou C<undef> en
cas d'erreur; si aucune solution n'est trouvée, le chemin est
retourné inchangé.
Notez que le chemin est mis à jour automatiquement dans la propriété C<Path>
du raccourci.
Par défaut, cette méthode agit discrètement, mais, si vous passez une valeur
de 0 (zéro) dans le paramètre I<flag>, elle affichera une boîte
de dialogue qui demandera à l'utilisateur plus d'information.

Exemple:

      # si la cible n'existe pas...
      if(! -f $LINK->Path) {

      # sauvegarder la cible actuelle pour comparaison
      $oldpath = $LINK->Path;

      # essayer de la résoudre (avec une boîte de dialogue)
      $newpath = $LINK->Resolve(0);

      die "Non résolu..." if $newpath == $oldpath;

      }

=item Save ([fichier])

Sauve le contenu de l'objet raccourci dans le fichier nommé I<fichier>.
Si I<fichier> est omis, il est pris dans la propriété C<File> de l'objet
(lequel, s'il n'a pas changé, est le nom du dernier fichier L<chargé|Load>).
Si aucun fichier n'a été chargé et si la propriété C<File> ne contient
pas de nom de fichier valide, la méthode renverra C<undef>, valeur qui sera
aussi renvoyée en cas d'erreur.
Une valeur VRAIE sera retournée si tout réussit.

Exemple:

      $LINK->Save();
      $LINK->Save("Copie de " . $LINK->{'File'});

=item Set (path, arguments, workingdirectory, description, showcmd,
          hotkey, iconlocation, iconnumber)

Fixe toutes les propriétés de l'objet raccourci en une seule commande.
Cette méthode est fournie seulement pour des raisons de commodité, vous
pouvez aussi fixer ces valeurs en changeant les valeurs des L<propriétés|propriétés>.

Exemple:

      $LINK->Set("C:\PERL5\BIN\PERL.EXE",
                 "-v",
                 "C:\PERL5\BIN",
                 "Affiche la version de Perl",
                 SW_SHOWMAXIMIZED,
                 hex('0x0337'),
                 "C:\WINDOWS\SYSTEM\COOL.DLL",
                 1);

      # ce qui est la même chose que ...
      $LINK->Path("C:\PERL5\BIN\PERL.EXE");
      $LINK->Arguments("-v");
      $LINK->WorkingDirectory("C:\PERL5\BIN");
      $LINK->Description("Affiche la version de Perl");
      $LINK->ShowCmd(SW_SHOWMAXIMIZED);
      $LINK->Hotkey(hex('0x0337'));
      $LINK->IconLocation("C:\WINDOWS\SYSTEM\COOL.DLL");
      $LINK->IconNumber(1);

=back

=head2 Propriétés

On a accès aux propriétés d'un objet raccourci par :

    $OBJECT->{'property'}

Par exemple, en supposant que vous avez créé un objet raccourci avec :

    $LINK=new Win32::Shortcut();

vous pouvez, par exemple, voir sa L<description|Description> avec :

    print $LINK->{'Description'};

Vous pouvez aussi bien la fixer :

    $LINK->{'Description'}="Ceci est une description";

Depuis la version 0.02, ces propriétés ont aussi une méthode correspondante
(routine), donc vous pouvez écrire les deux lignes ci-dessus en utilisant
cette syntaxe :

    print $LINK->Description;
    $LINK->Description("Ceci est une description");

Les propriétés d'un raccourci reflètent le contenu de la boîte de dialogue
des Propriétés du Raccourci qui peut être obtenue en cliquant le troisième
bouton de la souris sur un fichier raccourci dans l'Explorateur de Windows 95
(ou NT 4.0) et en choisissant "Propriétés" (bon, j'espère que vous le saviez
déjà :).
Les champs qui correspondent aux propriétés seules sont marqués en B<gras>
dans la liste suivante.

=over 4

=item Arguments

Les arguments associés avec l'objet lien du shell.
Ils seront passés au programme visé (voyez C<Path>) quand il sera exécuté.
En fait, concaténé avec C<Path>, ce paramètre forme le champ C<Cible>
de la boîte de Dialogue Propriété du raccourci.

=item Description

Une description optionnelle donnée au raccourci.
Semble manquer à la boîte de Dialogue Propriété du raccourci
(pas encore implémenté ?).

=item File

Le nom de fichier du raccourci ouvert avec C<Load>, et/ou le nom de
fichier sous lequel le raccourci sera sauvé avec C<Save> (si l'argument
I<fichier> n'est pas spécifié).

=item Hotkey

La touche de raccourci associée au raccourci, dans la forme d'un nombre sur
deux octets dont le premier octet identifie les modificateurs (Ctrl, Alt, Shift...
mais je n'ai pas trouvé comme il marche) et le second octet est le code ASCII
de la touche de caractère.
Correspond au champ C<Touche de raccourci> de la boîte de Dialogue Propriétés
du raccourci.

=item IconLocation

Le fichier qui contient l'icone pour le raccourci.
Semble actuellement toujours ne renvoyer rien.

=item IconNumber

Le numéro de l'icone pour le raccourci dans le fichier pointé par
C<IconLocation> au cas ou plus d'une icone est contenue dans ce fichier.
(je suppose cela, la documentation n'est pas claire là-dessus).

=item Path

La cible du raccourci. Constitue (concaténé avec C<Arguments>) le contenu
du champ C<Cible> de la boîte de Dialogue Propriétés du raccourci.

=item ShortPath

Identique à C<Path>, mais exprimé dans le format compatible-DOS (nom
de fichiers 8.3). Disponible uniquement en lecture (bon, vous pouvez
le changer, mais cela n'a aucun effet sur le raccourci; changez C<Path>
à la place) une fois le fichier raccourci L<chargé|Load>.

=item ShowCmd

La condition de la fenêtre dans laquelle le programme sera exécuté (peut
être C<Normale>, C<Réduite> ou C<Agrandie>). Correspond au champ
C<Exécuter> de la boîte de Dialogue Propriétés du raccourci.
Les valeurs admises sont

    Valeur      Signification   Constante
    1           Normale         SW_SHOWNORMAL
    3           Agrandie        SW_SHOWMAXIMIZED
    7           Réduite         SW_SHOWMINNOACTIVE

Toute autre valeur doit (théoriquement) donner une fenêtre C<Normale>.

=item WorkingDirectory

Le répertoire dans lequel le programme cible doit s'exécuter.
Correspond au champ C<Démarrer dans> de la boîte de Dialogue Propriétés
du raccourci.

=back

=head2 Constantes

Les constantes suivantes sont exportées dans l'espace de noms principal
de votre script qui utilise Win32::Shortcut :

    SW_SHOWNORMAL
    SW_SHOWMAXIMIZED
    SW_SHOWMINNOACTIVE

Ces constantes sont les valeurs admises pour la propriété C<ShowCmd>.

=head1 HISTORIQUE DES VERSIONS

=over

=item * 0.03 (07 Apr 1997)

=over

=item *

Le fichier PPL est fourni en deux versions, une pour Perl version 5.001
(build 110) et l'autre pour Perl version 5.003 (build 300 ou plus,
EXCEPTÉ 304).

=item *

Ajouté un programme d'installation qui copie automatiquement la bonne
version à la bonne place.

=back

=item * 0.02 (21 Jan 1997)

=over

=item *

Ajouté des méthodes d'accession aux propriétés pour réduire la dactylographie
(par exemple,  Alt-123 et 125...).

=back

=item 0.01 (15 Jan 1997)

=over

=item *

Première parution publique.

=item *

Ajouté "Set" et "Resolve" et les propriétés "Hotkey", "IconLocation" et "IconNumber".

=back

=item * 0.01a (10 Jan 1997)

=over

=item *

Première implémentation de l'interface de IShellLink (wow, ça marche !)
Je peux charger, sauver et modifier les propriétés d'un raccourci.

=back

=back


=head1 AUTEUR

Aldo Calpini <a.calpini@romagiubileo.it>


=head1 CRÉDITS

Merci à : Jesse Dougherty, Dave Roth, ActiveWare, et à la communauté
des utilisateurs de Perl-Win32.


=head1 DÉCHARGE

Ce programme est LIBRE; vous pouvez le redistribuer, le modifier, le
désassembler, lui appliquer du "reverse engineering", comme vous le
voulez. Néanmoins, gardez présent à l'esprit que RIEN N'EST GARANTI
quant à son fonctionnement et que tout que vous faites l'est À VOS PROPRES
RISQUES - Je n'assume aucune responsabilité pour aucun dommage, perte
d'argent et/ou de santé qui pourraient résulter de l'utilisation de ce
programme !

This is distributed under the terms of Larry Wall's Artistic License.

=head1 VERSION FRANÇAISE

Cette traduction française correspond à la version anglaise distribuée avec perl 5.6.1.
Pour en savoir plus concernant ces traductions, consultez http://www.enstimac.fr/Perl/ .

=head1 TRADUCTION EN FRANÇAIS

Jean-Louis Morel <jl_morel@bribes.org>

=cut