=head1 NOM

Win32::Console - Console Win32 et fonctions en Mode Caractère

=head1 DESCRIPTION

Ce module implémente les consoles Win32 avec les fonctions en mode
caractère associées. Elles vous donnent le contrôle total sur
l'entrée et la sortie de la console, incluant :

=over

=item *

support des tampons de console hors écran (par exemple pages multi-écran),

=item *

lecture et écriture de caractères, attributs et portions entières
de l'écran,

=item *

traitement complet du clavier et des événements de la souris,

=item *

plus quelques fonctions supplémentaires très amusantes  :)

=back

Ces fonctions devraient aussi permettre un portage de la bibliothèque
Unix Curses; si quelqu'un est intéressé par (et/ou veut contribuer à)
ce projet, qu'il m'envoie un email. Merci.

=head1 RÉFÉRENCE

=head2 Méthodes

=over

=item Alloc

Alloue une nouvelle console au processus. Retourne C<undef> en
cas d'erreur, une valeur non nulle en cas de succès. Un processus
ne peut être associé à plus d'une console, aussi cette méthode échoue
s'il y a déjà une console allouée au processus. Utilisez Free pour
détacher le processus de la console et puis appelez Alloc pour créer
une nouvelle console. Voir aussi : C<Free>

Exemple:

    $CONSOLE->Alloc();

=item Attr [attr]

Obtient et fixe l'attribut courant de la console. Cet attribut est
utilisé par la méthode Write.

Exemple:

    $attr = $CONSOLE->Attr();
    $CONSOLE->Attr($FG_YELLOW | $BG_BLUE);

=item Cls ([attr])

Efface la console avec l'attribut I<attr> si celui-ci est donné, ou
avec ATTR_NORMAL sinon.

Exemple:

    $CONSOLE->Cls();
    $CONSOLE->Cls($FG_WHITE | $BG_GREEN);

=item Cursor ([x, y, taille, visible])

Obtient ou fixe la position et l'apparence du curseur. Retourne C<undef>
en cas d'erreur, ou une liste de 4 éléments contenant : I<x>, I<y>, I<taille>,
I<visible>. I<x> et I<y> représentent la position du curseur; ...

Exemple:

    ($x, $y, $taille, $visible) = $CONSOLE->Cursor();

    # Obtenir la position seulement
    ($x, $y) = $CONSOLE->Cursor();

    $CONSOLE->Cursor(40, 13, 50, 1);

    # Fixer la position seulement
    $CONSOLE->Cursor(40, 13);

    # Fixer la taille et la visibilité sans changer la position
    $CONSOLE->Cursor(-1, -1, 50, 1);

=item Display

Affiche la console spécifiée à l'écran. Retourne C<undef> en cas d'erreur,
une valeur non nulle en cas de succès.

Exemple:

    $CONSOLE->Display();

=item FillAttr ([attribut, nombre, col, lig])

Remplie le nombre spécifié d'attributs consécutifs, commençant à
I<col>, I<lig>, avec la valeur spécifiée dans I<attribut>. Retourne
le nombre d'attributs remplis, ou C<undef> en cas d'erreur.
Voir aussi : C<FillChar>.

Exemple:

    $CONSOLE->FillAttr($FG_BLACK | $BG_BLACK, 80*25, 0, 0);

=item FillChar (char, nombre, col, lig)

Remplie le nombre spécifié de caractères consécutifs, commençant à
I<col>, I<lig>, avec le caractère spécifié dans I<char>. Retourne
le nombre de caractères remplis, ou C<undef> en cas d'erreur.
Voir aussi : C<FillAttr>.

Exemple:

    $CONSOLE->FillChar("X", 80*25, 0, 0);

=item Flush

Vide le tampon d'entrée de la console. Tous les événements contenus dans
le tampon sont abandonnés. Retourne C<undef> en cas d'erreur, une valeur
non nulle en cas de succès.

Exemple:

    $CONSOLE->Flush();

=item Free

Détache le processus de la console. Retourne C<undef> en cas d'erreur,
une valeur non nulle en cas de succès. Voir aussi C<Alloc>.

Exemple:

    $CONSOLE->Free();

=item GenerateCtrlEvent ([type, ProcessPid])

Envoie un signal d'arrêt du I<type> spécifié au I<ProcessPid> spécifié.
I<type> peut être l'une des constantes suivantes :

    CTRL_BREAK_EVENT
    CTRL_C_EVENT

qui indiquent respectivement l'appui sur les touches Control + Break et
Control + C; si I<type> n'est pas précisé, sa valeur par défaut est
CTRL_C_EVENT.
I<ProcessPid> est le pid d'un processus partageant la même console.
S'il n'est pas précisé, sa valeur par défaut est 0 (le processus courant),
qui est aussi la seule valeur significative que vous pouvez passer à
cette fonction. Retourne C<undef> en cas d'erreur,
une valeur non nulle en cas de succès.

Exemple:

    # arrêter ce script maintenant
    $CONSOLE->GenerateCtrlEvent();

=item GetEvents

Retourne le nombre d'événements en entrée non lus dans le tampon
d'entrée ou C<undef> en cas d'erreur.
Voir aussi C<Input>, C<InputChar>, C<PeekInput>, C<WriteInput>.

Exemple:

    $events = $CONSOLE->GetEvents();

=item Info

Retourne un tableau d'information à propos de la console (ou C<undef>
en cas d'erreur), qui contient :

=over

=item *

nombre de colonnes (taille X) du tampon de console.

=item *

nombre de lignes (taille Y) du tampon de console.

=item *

colonne courante (position X) du curseur.

=item *

ligne courante (position Y) du curseur.

=item *

attribut courant utilisé par C<Write>.

=item *

colonne de gauche (X du point de départ) de la fenêtre courante de la console.

=item *

ligne du haut (Y du point de départ) de la fenêtre courante de la console.

=item *

colonne de droite (X du point final) de la fenêtre courante de la console.

=item *

ligne du bas (Y du point final) de la fenêtre courante de la console.

=item *

nombre maximum de colonnes pour la fenêtre de la console, compte tenu de
la taille du tampon, de celle de la fonte et de la dimension de l'écran.

=item *

nombre maximum de lignes pour la fenêtre de la console, compte tenu de
la taille du tampon, de celle de la fonte et de la dimension de l'écran.

=back

Voir aussi : C<Attr>, C<Cursor>, C<Size>, C<Window>, C<MaxWindow>.

Exemple:

    @info = $CONSOLE->Info();
    print "Position du curseur : $info[3], $info[4].\n";

=item Input

Lit un événement depuis le tampon d'entrée. Retourne une liste de valeurs
qui, en fonction de la nature de l'événement, sont :

=over

=item événement du clavier

La liste contient :

=over

=item *

type d'événement : 1 pour le clavier

=item *

touche appuyée : VRAI si la touche est appuyée, FAUX si elle a été relâchée

=item *

nombre de répétitions : le nombre de fois que la touche a été appuyée

=item *

virtual keycode : le code virtuel de la touche

=item *

virtual scancode : code virtuel de balayage de la touche

=item *

char: le code ASCII du caractère (si la touche est une touche caractère, 0 autrement)

=item *

control key state : l'état des touches de contrôle (SHIFTs, CTRLs, ALTs, etc.)

=back

=item événement de la souris

La liste contient :

=over

=item *

type d'événement : 2 pour la souris

=item *

pos. X de la souris : coordonnée X (colonne) de la position de la souris

=item *

pos. Y de la souris : coordonnée Y (ligne) de la position de la souris

=item *

état des boutons : les boutons de la souris qui sont appuyés

=item *

control key state : l'état des touches de contrôle (SHIFTs, CTRLs, ALTs, etc.)

=item *

indicateurs d'événement : le type d'événement de la souris

=back

=back

Cette méthode retourne C<undef> en cas d'erreur. Notez que les
événements retournés dépendent du C<Mode> d'entrée de la console;
par exemple, les événements de la souris ne sont interceptés que si
ENABLE_MOUSE_INPUT est spécifié.
Voir aussi :  C<GetEvents>, C<InputChar>, C<Mode>,
C<PeekInput>, C<WriteInput>.

Exemple:

    @event = $CONSOLE->Input();

=item InputChar (nombre)

Lit et retourne I<nombre> de caractères depuis le tampon d'entrée de
la console, ou retourne C<undef> en cas d'erreur.
Voir aussi : C<Input>, C<Mode>.

Exemple:

    $key = $CONSOLE->InputChar(1);

=item InputCP ([codepage])

Obtient ou fixe la page de code utilisée en entrée par la console.
Notez que cela ne concerne pas un objet console, mais l'entrée de
la console standard. Cet attribut est utilisé par la méthode Write.
Voir aussi  : C<OutputCP>.

Exemple:

    $codepage = $CONSOLE->InputCP();
    $CONSOLE->InputCP(437);

    # vous pouvez utiliser la forme non instanciée pour éviter toute confusion :)
    $codepage = Win32::Console::InputCP();
    Win32::Console::InputCP(437);

=item MaxWindow

Retourne les dimensions de la fenêtre de console la plus grande possible,
compte tenu de la fonte courante et des dimensions de l'écran. Le résultat
est C<undef> en cas d'erreur, une liste de deux éléments (colonne, ligne)
autrement.

Exemple:

    ($maxCol, $maxRow) = $CONSOLE->MaxWindow();

=item Mode ([flags])

Obtient et fixe les modes d'entrée et de sortie de la console. I<flags>
peut être une combinaison des constantes suivantes :

    ENABLE_LINE_INPUT
    ENABLE_ECHO_INPUT
    ENABLE_PROCESSED_INPUT
    ENABLE_WINDOW_INPUT
    ENABLE_MOUSE_INPUT
    ENABLE_PROCESSED_OUTPUT
    ENABLE_WRAP_AT_EOL_OUTPUT

Pour plus de renseignements sur la signification de ses constantes,
référez-vous, s'il vous plaît, à la L<"Documentation Microsoft">.

Exemple:

    $mode = $CONSOLE->Mode();
    $CONSOLE->Mode(ENABLE_MOUSE_INPUT | ENABLE_PROCESSED_INPUT);

=item MouseButtons

Retourne le nombre de boutons de votre souris, ou C<undef> en cas d'erreur.

Exemple:

    print "Votre souris a ", $CONSOLE->MouseButtons(), " boutons.\n";

=item new Win32::Console (standard_handle)

=item new Win32::Console ([accessmode, sharemode])

Crée un nouvel objet console. La première forme crée un descripteur
vers un flux standard, I<standard_handle>, qui peut être une des
constantes suivantes :

    STD_OUTPUT_HANDLE
    STD_ERROR_HANDLE
    STD_INPUT_HANDLE

La deuxième forme crée un tampon en mémoire pour l'écran de la
console, auquel vous pouvez accéder pour lire et écrire comme dans une
console normale, et réachemine sur la sortie standard (l'écran) avec
C<Display>. Dans ce cas, vous pouvez spécifier une ou les deux valeurs
suivantes pour I<accessmode>:

    GENERIC_READ
    GENERIC_WRITE

qui sont les autorisations que vous aurez sur le tampon créé, et une ou
les deux valeurs suivantes pour I<sharemode> :

    FILE_SHARE_READ
    FILE_SHARE_WRITE

qui changent la manière dont la console peut être partagée.
Si vous ne spécifiez aucun de ces paramètres, tous les quatre
indicateurs seront utilisés.

Exemple:

    $STDOUT = new Win32::Console(STD_OUTPUT_HANDLE);
    $STDERR = new Win32::Console(STD_ERROR_HANDLE);
    $STDIN  = new Win32::Console(STD_INPUT_HANDLE);

    $BUFFER = new Win32::Console();
    $BUFFER = new Win32::Console(GENERIC_READ | GENERIC_WRITE);

=item OutputCP ([codepage])

Obtient ou fixe la page de code utilisée en sortie par la console.
Notez que cela ne concerne pas un objet console, mais la sortie de
la console standard.
Voir aussi  : C<InputCP>.

Exemple:

    $codepage = $CONSOLE->OutputCP();
    $CONSOLE->OutputCP(437);

    # vous pouvez utiliser la forme non instanciée pour éviter toute confusion :)
    $codepage = Win32::Console::OutputCP();
    Win32::Console::OutputCP(437);

=item PeekInput

Fait exactement la même chose que C<Input>, excepté que l'événement lu
n'est pas retiré du tampon d'entrée.
Voir aussi : C<GetEvents>, C<Input>, C<InputChar>, C<Mode>, C<WriteInput>.

Exemple:

    @event = $CONSOLE->PeekInput();

=item ReadAttr ([nombre, col, lig])

Lit le I<nombre> spécifié d'attributs consécutifs de la console, en
commençant à I<col>, I<lig>. Retourne les attributs lus (une variable
contenant un caractère pour chaque attribut), ou C<undef> en cas d'erreur.
Vous pouvez alors passer la variable obtenue à C<WriteAttr> pour
restaurer à l'écran les attributs sauvés.
Voir aussi : C<ReadChar>, C<ReadRect>.

Exemple:

    $colors = $CONSOLE->ReadAttr(80*25, 0, 0);

=item ReadChar ([nombre, col, lig])

Lit le I<nombre> spécifié de caractères consécutifs de la console en
commençant à I<col>, I<lig>.  Retourne une chaîne contenant les caractères
lus, ou C<undef> en cas d'erreur. Vous pouvez alors passer la variable
obtenue à C<WriteChar> pour restaurer à l'écran les caractères sauvés.
Voir aussi : C<ReadAttr>, C<ReadRect>.

Exemple:

    $chars = $CONSOLE->ReadChar(80*25, 0, 0);

=item ReadRect (gauche, haut, droit, bas)

Lit le contenu (caractères et attributs) du rectangle spécifié par
I<gauche>, I<haut>, I<droit>, I<bas> depuis la console.
Retourne une chaîne contenant le rectangle lu, ou C<undef> en cas
d'erreur. Vous pouvez passer la variable obtenue à C<WriteRect> pour
restaurer le rectangle à l'écran (ou sur une autre console).
Voir aussi : C<ReadAttr>, C<ReadChar>.

Exemple:

     $rect = $CONSOLE->ReadRect(0, 0, 80, 25);

=item Scroll (gauche, haut, droit, bas, col, lig, char, attr,
             [cgauche, chaut, cdroit, cbas])

Déplace un bloc de données dans le tampon de la console; le bloc est
identifié par I<gauche>, I<haut>, I<droit>, I<bas>, alors que
I<col>, I<lig> précise la nouvelle position du bloc. Les emplacements
laissés vides par le déplacement sont remplis par le caractère I<char>
avec l'attribut I<attr>.  Facultativement vous pouvez spécifier une région
de coupure [clipping region] avec I<cgauche>, I<chaut>, I<cdroit>, I<cbas>
afin que le contenu de la console à l'extérieur de ce rectangle reste
inchangé. Retourne I<undef> en cas d'erreur, une valeur non nulle en cas
de succès.

Exemple:

    # fait défiler l'écran 10 lignes vers le bas, avec remplissage d'espaces noirs
    $CONSOLE->Scroll(0, 0, 80, 25, 0, 10, " ", $FG_BLACK | $BG_BLACK);

=item Select (standard_handle)

Redirige un flux standard vers la console spécifiée.
I<standard_handle> peut prendre l'une des valeurs suivantes :

    STD_INPUT_HANDLE
    STD_OUTPUT_HANDLE
    STD_ERROR_HANDLE

Retourne I<undef> en cas d'erreur, une valeur non nulle en cas
de succès.

Exemple:

    $CONSOLE->Select(STD_OUTPUT_HANDLE);

=item Size ([col, lig])

Obtient ou fixe la taille du tampon de la console.

Exemple:

    ($x, $y) = $CONSOLE->Size();
    $CONSOLE->Size(80, 25);

=item Title ([titre])

Obtient ou fixe le titre de la barre supérieure de la fenêtre de la console.

Exemple:

    $title = $CONSOLE->Title();
    $CONSOLE->Title("Ceci est un titre");

=item Window ([flag, gauche, haut, droit, bas])

Obtient ou fixe les dimensions courantes de la fenêtre de la console.
Si elle est appelée sans argument, la méthode renvoie une liste de
quatre éléments comprenant les coordonnées de la fenêtre courante
sous la forme I<gauche>, I<haut>, I<droit>, I<bas>. Pour fixer les
dimensions de la fenêtre, vous devez spécifier un paramètre I<flag>
supplémentaire :
S'il est nul les coordonnées sont considérées comme relatives; s'il
est non nul, les coordonnées sont absolues.

Exemple:

    ($gauche, $haut, $droite, $bas) = $CONSOLE->Window();
    $CONSOLE->Window(1, 0, 0, 80, 50);

=item Write (string)

Écrit la chaîne I<string> sur la console, en utilisant l'attribut courant
que vous pouvez fixer avec C<Attr>, et fait avancer le curseur comme il
est nécessaire. Ce n'est pas si différent de l'instruction "print" de Perl.
Retourne le nombre de caractères écrits ou C<undef> en cas d'erreur.
Voir aussi : C<WriteAttr>, C<WriteChar>, C<WriteRect>.

Exemple:

    $CONSOLE->Write("Salut tout le monde !");

=item WriteAttr (attrs, col, lig)

Écrit les attributs contenus dans la chaîne I<attrs>, en commençant
à I<col>, I<lig>, sans affecter les caractères qui sont à l'écran.
La chaîne I<attrs> peut être le résultat d'une fonction C<ReadAttr>,
ou bien vous pouvez construire votre propre chaîne d'attributs; dans ce
cas, garder en mémoire que chaque attribut est traité comme un caractère
et non comme un nombre (voir exemple)
Retourne le nombre de caractères écrits ou C<undef> en cas d'erreur.
Voir aussi : C<Write>, C<WriteChar>, C<WriteRect>.

Exemple:

    $CONSOLE->WriteAttr($attrs, 0, 0);

    # notez l'utilisation de chr()...
    $attrs = chr($FG_BLACK | $BG_WHITE) x 80;
    $CONSOLE->WriteAttr($attrs, 0, 0);

=item WriteChar (chars, col, lig)

Écrit les caractères contenus dans la chaîne I<chars>, en commençant
à I<col>, I<lig>, sans affecter les caractères qui sont à l'écran.
La chaîne I<chars> peut être le résultat d'une fonction C<ReadChar>,
ou bien une chaîne normale.
Retourne le nombre de caractères écrits ou C<undef> en cas d'erreur.
Voir aussi : C<Write>, C<WriteAttr>, C<WriteRect>.

Exemple:

    $CONSOLE->WriteChar("Salut tout le monde !", 0, 0);

=item WriteInput (event)

Pousse les données dans le tampon d'entrée de la console. I<(event)>
est une liste de valeurs; pour plus d'information, voyez C<Input>.
La chaîne de caractères peut être le résultat d'une fonction
C<ReadChar> ou bien une chaîne normale.
Retourne le nombre de caractères écrits ou C<undef> en cas d'erreur.
Voir aussi : C<Write>, C<WriteAttr>, C<WriteRect>.

Exemple:

    $CONSOLE->WriteInput(@event);

=item WriteRect (rect, gauche, haut, droit, bas)

Écrit un rectangle de caractères et attributs (contenus dans I<rect>)
dans la console, aux coordonnées spécifiées par I<gauche>, I<haut>,
I<droit>, I<bas>. I<rect> peut être le résultat d'une fonction C<ReadRect>.
Retourne C<undef> en cas d'erreur, une liste de quatre éléments contenant
les coordonnées du rectangle spécifié dans l'ordre I<gauche>, I<haut>,
I<droit>, I<bas> dans le cas contraire.
Voir aussi : C<Write>, C<WriteAttr>, C<WriteChar>.

Exemple:

    $CONSOLE->WriteRect($rect, 0, 0, 80, 25);

=back


=head2 Constantes

Les constantes suivantes sont exportées dans l'espace de noms principal
de votre script comportant Win32::Console:

    BACKGROUND_BLUE
    BACKGROUND_GREEN
    BACKGROUND_INTENSITY
    BACKGROUND_RED
    CAPSLOCK_ON
    CONSOLE_TEXTMODE_BUFFER
    ENABLE_ECHO_INPUT
    ENABLE_LINE_INPUT
    ENABLE_MOUSE_INPUT
    ENABLE_PROCESSED_INPUT
    ENABLE_PROCESSED_OUTPUT
    ENABLE_WINDOW_INPUT
    ENABLE_WRAP_AT_EOL_OUTPUT
    ENHANCED_KEY
    FILE_SHARE_READ
    FILE_SHARE_WRITE
    FOREGROUND_BLUE
    FOREGROUND_GREEN
    FOREGROUND_INTENSITY
    FOREGROUND_RED
    LEFT_ALT_PRESSED
    LEFT_CTRL_PRESSED
    NUMLOCK_ON
    GENERIC_READ
    GENERIC_WRITE
    RIGHT_ALT_PRESSED
    RIGHT_CTRL_PRESSED
    SCROLLLOCK_ON
    SHIFT_PRESSED
    STD_INPUT_HANDLE
    STD_OUTPUT_HANDLE
    STD_ERROR_HANDLE

En complément, les variables suivantes peuvent être utilisées :

    $FG_BLACK
    $FG_BLUE
    $FG_LIGHTBLUE
    $FG_RED
    $FG_LIGHTRED
    $FG_GREEN
    $FG_LIGHTGREEN
    $FG_MAGENTA
    $FG_LIGHTMAGENTA
    $FG_CYAN
    $FG_LIGHTCYAN
    $FG_BROWN
    $FG_YELLOW
    $FG_GRAY
    $FG_WHITE

    $BG_BLACK
    $BG_BLUE
    $BG_LIGHTBLUE
    $BG_RED
    $BG_LIGHTRED
    $BG_GREEN
    $BG_LIGHTGREEN
    $BG_MAGENTA
    $BG_LIGHTMAGENTA
    $BG_CYAN
    $BG_LIGHTCYAN
    $BG_BROWN
    $BG_YELLOW
    $BG_GRAY
    $BG_WHITE

    $ATTR_NORMAL
    $ATTR_INVERSE

ATTR_NORMAL donne un premier plan gris sur un arrière-fond noir (couleurs
standard du DOS).

=head2 Documentation Microsoft

La documentation pour les Consoles Win32 et fonctions en Mode Caractère
peut être trouvée sur le site de Microsoft à l'URL :

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dllproc/base/using_the_console.asp

Une référence sur les fonctions disponibles se trouve à

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dllproc/base/console_functions.asp

=head1 HISTORIQUE DES VERSIONS

=over

=item * 0.031 (24 Sep 1999)

=over

=item *

Corrigé un typo dans GenerateCtrlEvent().

=item *

Converti et ajouté une documentation pod (de Jan Dubois <jand@activestate.com>).

=back

=item * 0.03 (07 Apr 1997)

=over

=item *

Ajouté la méthode "GenerateCtrlEvent".

=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.01 (09 Feb 1997)

=over

=item *

Première parution publique.

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