path: root/doc/fr/PerlQt.pod

=head1 Programmer avec PerlTQt

B<Germain Garand> traduit par B<St�phane Payrard>, r�vis� et augment� par l'auteur.

Ce document d�crit l'interface Perl au toolkit TQt 3.x. Contacter
l'auteur � <[email protected]> ou le traducteur �
<[email protected]>.  Vous trouverez le document original sur le site
L<perlqt.sourceforge.net|"http://perlqt.sourceforge.net">

=head1 Introduction

PerlTQt-3, cr�e par Ashley Winters, est une interface perl aux composants
graphiques (et non graphiques) fournis par TQt3.

Le toolkit TQt 3.0 auquel PerlTQt acc�de � �t� �crit en C++ par la soci�t�
Trolltech: L<Trolltech|"http://www.trolltech.com">.

PerlTQt3 est fond� sur la librairie
L<SMOKE|"http://webcvs.kde.org/cgi-bin/cvsweb.cgi/kdebindings/smoke">,
une surcouche fine ind�pendante du langage. Cette couche a �t� g�n�r�e
� partir des fichiers d'en t�te de TQt par le
L<kalyptus|"http://webcvs.kde.org/cgi-bin/cvsweb.cgi/kdebindings/kalyptus">
de Richard Dale gr�ce au module de David Faure.

Le pr�sent document d�crit les principes de la programmation PerlTQt.
Vous devez avoir des notions de  programmation orient�e objet en Perl pour le
lire.  Une connaissance de C++ est recommand�e mais non requise.  Avec
celle de l'anglais, elle vous facilitera la consultation des L<manuels
en ligne de TQt|"http://doc.trolltech.com">. Ladite documentation est
la seule r�f�rence qui fasse autorit�.

Si TQt est install� sur votre syst�me, sa documentation l'est 
certainement aussi : voyez le programme $TQTDIR/bin/assistant.

=head1 Installation

=head2 Conditions requises

Pour compiler et utiliser PerlTQt, vous devez avoir:


=over 4

=item *

un syst�me conforme � la norme POSIX.

=item *

L<Perl E<gt>= v5.6.0|"http://www.perl.org">

=item *

L<TQt E<gt>=
v3.0|"http://www.trolltech.com/developer/download/qt-x11.html">

=item *

L<SmokeTQt
1.2.1|"http://webcvs.kde.org/cgi-bin/cvsweb.cgi/kdebindings/smoke"> La
librarie SMOKE  (Scripting Meta Object Kompiler) fait partie du module
L<KDE|"http://www.kde.org">'s B<kdebindings>.  Vous pouvez v�rifier si
une version pr�compil�e de ce module existe pour votre syst�me. Mais
perlTQt inclut une copie, donc la version pr�compil�e n'est pas
n�cessaire.

=item *

Les outils GNU : automake(>=1.5), autoconf (>=2.13), aclocal...

=back

L'installation de Perl et de TQt sont en dehors du sujet du pr�sent
document. Se r�f�rer aux documentations respectives de ces logiciels.

=head2 Compilation de PerlTQt

Les instructions de cette section pr�supposent que le r�pertoire courant est 
le r�pertoire racine de l'arborescence des sources de PerlTQt.

PerlTQt utilise le syst�me GNU Autoconf, mais il est pr�f�rable de le lancer via
le script standard C<Makefile.PL> :

 perl Makefile.PL

B<N.B :> Si la variable d'environnement B<TQTDIR> n'est pas d�finie, vous devrez
peut-�tre sp�cifier manuellement l'emplacement de TQt � l'aide de l'option :

 --with-qtdir=/emplacement/de/TQt

Si la biblioth�que SMOKE est manquante, C<configure> g�n�rera ses sources dans
un sous-r�pertoire.

 make

 make install

Cela installera PerlTQt, Puic et les utilitaires pqtsh et pqtapi.

Le lieu d'installation privil�gi� de SMOKE et de PUIC est le syst�me de
fichiers de KDE3. Si KDE3 n'est pas install� (ou que la variable TDEDIR n'est pas
d�finie), sp�cifier ce lieu avec l'option C<--prefix> de C<configure>'s. Ainsi :

 perl Makefile.PL --prefix=/usr

=head2 Installation avec les droits d'utilisateur

Pour r�aliser une installation locale, sans les droits de super-utilisateur,
suivez les instructions suivantes :

=over 4

=item *

R�alisez tout d'abord une configuration normale, en sp�cifiant le pr�fixe de la hi�rarchie de fichier 
dans laquelle la biblioth�que Smoke et l'ex�cutable 'puic' seront install�s :

 perl Makefile.PL --prefix=~

Ceci installera Smoke dans ~/lib et puic dans ~/bin

=item *

Reconfigurez le module PerlTQt pour qu'il ne s'installe pas dans la hi�rarchie Perl ordinaire :

 cd PerlTQt
 perl Makefile.PL PREFIX=~
 cd ..

Attention : il ne s'agit pas du Makefile.PL situ� � la racine de l'arborescence mais bien de celui
situ� dans le sous-r�pertoire PerlTQt

=item *

Lancez la compilation et l'installation

 make && make install

Pour ex�cuter des programmes PerlTQt, il vous faudra d�sormais indiquer � Perl l'emplacement de cette hi�rarchie externe,
� l'aide d'une ligne de la forme :

 perl -Mlib="~/local/lib/perl/5.x.x" programme.pl

o� 5.x.x repr�sente la version de Perl utilis�e, ligne qui peut �galement �tre plac�e en t�te de programme :

 use lib qw( ~/local/lib/perl/5.x.x );

=back

=head1 Anatomie de PerlTQt

Un programme TQt typique utilisant des composants GUI est fond� sur une
boucle �v�nementielle.

Il ne se comporte pas comme une suite s�quentielle
d'instructions o� vous devriez g�rer vous-m�me chaque �v�nement (tels
que le clic de la souris ou l'enfoncement d'une touche).

Au lieu de cela, vous cr�ez un objet B<TQt::Application> et les composants
du GUI qu'il utilise, puis vous  d�finissez les m�thodes d'objet � appeler
lors de l'occurrence d'un �v�nement, puis d�marrez la boucle �v�nementielle.

C'est tout. TQt g�rera les �v�nements et les dirigera vers les
routines appropri�es.

Voyons un programme PerlTQt minimal.

=head2 Hello World

 1: use TQt;
 2: my $a = TQt::Application(\@ARGV);
 3: my $hello = TQt::PushButton("Hello World!", undef);
 4: $hello->resize(160, 25);
 5: $a->setMainWidget($hello);
 6: $hello->show;
 7: exit $a->exec;

=for html
<br/>
<div class='image'><img src="../images/ex1.png"/></div>

Ce programme charge d'abord le module TQt [line 1] puis cr�e l'objet
application B<$a>  en lui passant une r�f�rence au tableau C<@ARGV>
contenant les arguments de la ligne de commande [l.2]. Cet objet
application est unique pour un interpr�teur Perl donn� et peut �tre
ensuite acc�d� par la fonction pure B<TQt::app()>.

La ligne 3, cr�e un PushButton orphelin (c.�.d sans parent: non
contenu dans un autre widget) dont nous passons la valeur B<undef>
comme argument pour le parent. B<undef> est l'�quivalent perlTQt d'un
pointeur null en C++.

Apr�s les instructions de "mise en page" [l.4], nous indiquons �
l'objet application que le widget principal est ce
PushButton... Ainsi, il saura que fermer la fen�tre associ�e � ce
widget signifie: I<sortir de l'application>.

Pour rendre ce widget visible (qui est par d�faut cach�), on
appelle la m�thode B<show> [l.6] et lance la boucle
�v�nementielle [l.7].

B<Sommaire de la syntaxe :>

=over 4

=item 1

Les classes PerlTQt sont accessibles par le pr�fixe B<TQt::> au lieu du
B<Q> initial des classes TQt en C++.  En consultant la L<documentation
TQt|"http://doc.trolltech.com">, vous devez donc mentalement changer le
nom d'une clasee B<TQFoo> en B<TQt::Foo>.

=item 2

De mani�re similaire � C++, un objet est cr�� par l'appel d'un
B<constructeur> de m�me nom que la classe dont il est une m�thode.

Vous ne devez donc pas dire C<new TQt::Foo> ou C<TQt::Foo-E<gt>new()>
contrairement � l'usage commun en Perl.

Dites simplement:

 my $object = TQt::<classname>(arg_1, ..., arg_n);

Un constructeur sans argument s'�nonce encore plus bri�vement :

 my $object = TQt::<classname>;


=item 3

Comme il a d�j� �t� dit, l'�quivalent Perl d'un pointeur C++ est le mot-cl�
Perl B<undef>.

Les pointeurs sont les arguments pr�c�d�s par le caract�re B<*> dans la
documentation TQt (Par exemple: "C<TQWidget* widget>").

=back

=head2 L'h�ritage et les objets

Avant d'expliquer comment les routines Perl peuvent �tre appel�es de TQt,
parlons du m�canisme d'h�ritage vu de PerlTQt.

PerlTQt est con�u pour allier la simplicit� de  TQt � la puissance et � la
flexibilit� de Perl. Pour ce faire, PerlTQt �tend le paradigme objet de
Perl pour mimer TQt et son m�canisme de B<m�taobjets>.

=head3 Un Widget personnalis�

R��crivons le programme "Hello World!" avec une version personnalis�e
de PushButton:

  1: use strict;
  2:
  3: package Button;
  4: use TQt;
  5: use TQt::isa qw(TQt::PushButton);
  6:
  7: sub NEW
  8: {
  9:   shift->SUPER::NEW(@_[0..2]);
 10:   resize(130, 40);
 11: }
 12:
 13: 1;
 14:
 15: package main;
 16:
 17: use TQt;
 18: use Button;
 19:
 20: my $a = TQt::Application(\@ARGV);
 21: my $w = Button("Hello World!", undef);
 22: $a->setMainWidget($w);
 23: $w->show;
 24: exit $a->exec;

Pour implanter notre propre version de PushButton, nous cr�ons un nouveau
package [l.3] et importons  TQt [l.4].

Nous utilisons le pragma C<TQt::isa> [l.5] pour d�clarer notre widget
comme sous-classe de PushButton. Ce pragma accepte une liste de une ou
plusieurs classes dont d�rive la classe � d�finir.

Cr�ons maintenant un constructeur pour notre nouveau widget
en �crivant une routine appel�e B<NEW> I<(notez les majuscules qui
marquent une m�thode diff�rente du constructeur "new" usuel)>.
Le constructeur PerlTQt est appel� B<implicitement> I<comme ligne 21>.

Note widget doit d'abord appeler le constructeur de sa classe de base
(ici: TQt::PushButton) � la ligne 9, avec tous les arguments que nous
avons re�us.

Nous cr�ons ainsi un objet instance de notre classe. Cette objet est
accessible par la fonction B<this> (Attention: ce n'est pas la
variable C<$this> mais simplement C<this>).

Chaque fois que nous invoquons une m�thode � partir de notre package
nous pouvons �crire indiff�remment C<method()> ou
C<this-E<gt>method()>;

=head3 L'utilisation d'attributs

Lors de la construction d'un objet composite, vous pouvez simplement cr�er
ses diff�rents composants � l'int�rieur de variables de scope lexical
(c.�.d d�clar�es par B<my>) puisque les widgets sont seulement d�truits
par leur parent et non n�cessairement quand leur conteneur dispara�t
du scope.

En d'autres termes, PerlTQt utilise un syst�me de comptage de
r�f�rences pour g�rer la destruction des objets.

Souvent cependant, vous souhaiterez acc�der aux composants de votre objet depuis
un tout autre endroit que celui o� vous l'avez cr�� (par exemple pour modifier une
l�gende de bouton dynamiquement). Dans ce cas, la syntaxe traditionnelle de perl
propose de stocker une r�f�rence � ces composants dans la table associative (hash) de
l'objet lui-m�me. Mais cette syntaxe s'av�re peu pratique � l'usage et beaucoup
trop libre - il n'y a pas de v�rification � la compilation de sorte que vous pouvez
acc�der � des clefs non existantes sans d�clencher d'erreur.

En lieu et place de cette syntaxe, PerlTQt introduit le concept d'B<attributs>.

Les attributs sont de simples variables perl, �crites sans le signe dollar initial, et
pouvant contenir toute donn�e qui est une propri�t� de votre objet.
Leur principal avantage est de fournir une syntaxe tr�s rapide et v�rifiable � la compilation.

Pour d�finir et pouvoir utiliser de nouveaux attributs, il suffit d'utiliser
le pragma C<use TQt::attributes>, suivi d'une liste des noms d'attributs souhait�s.
Ainsi:


  1: use strict;
  2:
  3: package Button;
  4: use TQt;
  5: use TQt::isa qw(TQt::PushButton);
  6: use TQt::attributes qw(
  7:     itsTime
  8:     pData
  9: );
 10:
 11: sub NEW
 12: {
 13:   shift->SUPER::NEW(@_[0..2]);
 14:   itsTime = TQt::Time;
 15:   itsTime->start;
 16:   pData->{'key'} = " Foo ";
 17: }
 18:
 19: sub resizeEvent
 20: {
 21:    setText( "w: ". width() ." h: ". height() .
 22:             "\nt: ". itsTime->elapsed . pData->{'key'} );
 23: }
 24:
 25: 1;

=for html
<br/>
<div class='image'><img src="../images/ex2.png"/></div>


L'attribut itsTime est d�clar� � la ligne 7 et initialis� par un objet C<TQt::Time>
� la ligne 14.

Puisque nous r�impl�mentons la fonction virtuelle  "resizeEvent"
[l.19], chaque fois que le widget principal est redimensionn�, cette
fonction "resizeEvent" sera d�clench�e et le texte de notre Button mis
� jour avec les valeurs venant de l'objet [1.21] et les attributs que
nous avons d�finis [1.22].

B<R�capitulation>

=over 4

=item *

Pour h�riter d'une classe TQt, un package doit contenir un
pragma C<use TQt::isa>.

Ainsi:

 use TQt::isa "TQt::widget";

=item *

Le constructeur d'objet est nomm� B<NEW> et est appel� implicitement.
Vous ne devez donc pas dire:

 my $o = MyButton->NEW("Hello");

Mais bien :

 my $o = MyButton("Hello");

=item *

A l'int�rieur d'un package, on acc�de l'instance courante par la
fonction B<this>.

Quand une fonction membre est appel�e, les arguments sont accessibles
par le tableau B<@_>, mais le premier �l�ment de B<@_> n'est pas une
r�f�rence � l'objet contrairement � l'usage commun en Perl.

Vous ne pouvez donc pas dire :

 sub myMember
 {
   my $moi = shift;
   my $arg = shift;
   $arg->doThat($moi);
   $moi->doIt;
 }

�crivez plut�t :

 sub myMember
 {
   my $arg = shift;
   $arg->doThat(this);
   doIt();
 }

De plus, si vous voulez appeler une m�thode dans une classe de base �
partir d'une classe d�riv�e, utilisez l'attribut sp�cial SUPER :

 sub exemple
 {
   print "Appel de la m�thode 'exemple' dans la classe de base";
   SUPER->exemple(@_)
 }

Notez aussi que la construction :

 this->SUPER::Exemple(@_);

est possible, mais qu'elle passe l'objet comme premier argument.

=item *

Lorsque vous devez stocker dans votre package un objet contenu, vous
devez le d�finir comme B<attribut> :

 use TQt::attributes qw(
	firstAttribute
	...
	lastAttribute);

Il sera alors disponible comme accesseur :

 firstAttribute = myContainedWidget( this );
 firstAttribute->resize( 100, 100 );

B<NB:> Pour ceux qui souhaitent en savoir plus, les attributs sont impl�ment�s
� l'aide de sub lvalue, c'est � dire de fonctions assignables.
En interne, elles ne font que pointer sur la clef de hachage correspondante dans
l'objet B<this>, ce qui rend les tournures "unAttribut->fonction()" et
"this->{'unAttribut'}->fonction()" strictement �quivalentes
(si ce n'est que la premi�re est v�rifi�e au moment de la compilation).

=item *

Pour r�impl�menter une B<fonction virtuelle>, cr�ez simplement une
B<sub> de m�me nom que cette fonction.

Les fonctions virtuelles existantes sont marqu�es comme telles dans
la documentation de TQt (ce sont les m�thodes pr�c�d�es du mot clef "virtual").

Vous pouvez visualiser les noms de m�thodes virtuelles que TQt tentera d'appeler
dans votre classe en pla�ant C<use TQt::debug qw|virtual|> en t�te de 
votre programme.

=back

=head2 Signaux et Slots

Voyons maintenant comment les objets TQt peuvent communiquer entre eux
de mani�re � ce qu'un �v�nement concernant un objet puisse d�clencher
l'ex�cution d'une routine en un quelconque endroit de votre programme.

Dans d'autres toolkits, les callbacks (appels en retour) sont g�n�ralement
utilis�s � cet effet. Mais TQt dispose d'un m�canisme beaucoup plus puissant
et plus flexible : les B<Signaux et Slots>.

On peut se le repr�senter comme le cablage entre les composants d'une
cha�ne Hi-Fi. Un amplificateur, par exemple, �met des signaux de sortie
sans chercher � savoir si des enceintes lui sont connect�es ou non.
Un magn�tophone peut attendre un signal sur sa prise d'entr�e
pour commencer � enregistrer, et il ne cherchera pas � savoir s'il est
l'unique destinataire de ce signal ou si ce dernier est aussi re�u par un graveur de CD
ou �cout� au casque.

Un composant TQt se comporte comme notre amplificateur ou notre
magn�tophone. Il a des sorties ou B<Signaux> et des entr�es ou
B<Slots>. Chaque sortie (signal) est connectable � un nombre illimit�
d'entr�es (slots). La sortie d'un composant peut �tre potentiellement
branch�e � toute entr�e d'un composant (y compris lui-m�me),


La syntaxe de ce syst�me de connexion est soit:

TQt::Object::connect( envoyeur, TQT_SIGNAL 'mon_signal(types_d_arguments)',
recepteur, TQT_SLOT 'monslot(types_d_arguments)');

soit:

unObjet->connect( envoyeur, TQT_SIGNAL 'mon_signal(types_d_arguments)',
SLOT 'monslot(types_d_arguments)');

Dans le second cas, le r�cepteur est omis car c'est l'objet lui-m�me,

Ce m�canisme est extensible � volont� par la d�claration de nouveaux Signaux et
Slots par l'usage des pragma C<use TQt::signals> et C<use TQt::slots>
(voir aussi la deuxi�me syntaxe d�crite plus bas).

Chaque slot d�clar� appellera la routine correspondante de votre
objet. Chaque signal d�clar� peut �tre d�clench� via le mot-cl� B<emit>.

B<R��crivons encore notre exemple pour illustrer nos propos :>

  1: use strict;
  2:
  3: package Button;
  4: use TQt;
  5: use TQt::isa qw(TQt::PushButton);
  6: use TQt::attributes qw(itsTime);
  7: use TQt::slots
  8:     aEteClicke => [],
  9:     changement     => ['int', 'int'];
 10: use TQt::signals
 11:     changeLe   => ['int', 'int'];
 12:
 13: sub NEW
 14: {
 15:   shift->SUPER::NEW(@_[0..2]);
 16:   itsTime = TQt::Time;
 17:   itsTime->start;
 18:   this->connect(this, TQT_SIGNAL 'clicked()', TQT_SLOT 'aEteClicke()');
 19:   this->connect(this, TQT_SIGNAL 'changeLe(int,int)', TQT_SLOT 'changement(int,int)');
 20: }
 21:
 22: sub aEteClicke
 23: {
 24:    my $w = width();
 25:    my $h = height();
 26:    setText( "w: $w h: $h\nt: ". itsTime->elapsed );
 27:    emit changeLe($w, $h);
 28: }
 29:
 30: sub changement
 31: {
 32:    my ($w, $h) = @_;
 33:    print STDERR "w: $w h: $h \n";
 34: }
 35:
 36: 1;

Nous d�finissons dans ce package deux nouveaux slots et un nouveau signal.


La documentation TQt nous dit que tout PushButton click� �met un signal
C<clicked()> ; nous le connectons donc � notre nouveau slot [ligne 18].

Nous connectons aussi notre signal C<ChangeLe> � notre slot
C<changement>.

Ainsi, quand on appuie (clique) sur notre Button , le signal
C<clicked()> est �mit et d�clenche le slot  C<aEteClicke()>.
C<aEteClicke()> �met � son tour le signal C<changeLe(int,int)>[l.27],
appelant de ce fait le slot C<changement(int,int)>, avec deux arguments.

Enfin, il existe une syntaxe alternative introduite dans PerlTQt-3.008 :

 sub un_slot : TQT_SLOT(int, TQString)
 { 
	$int = shift;
	$string = shift;
	# faire quelque chose
 }

et

 sub un_signal : TQT_SIGNAL(TQString);

Cette syntaxe est parfaitement compatible avec la d�claration par le biais de
C<use TQt::signals> et C<use TQt::slots>. 
Il peut d'ailleurs d'av�rer tr�s profitable pour la clart� du programme de d�clarer tout d'abord 
les signaux/slots au moyen de C<use TQt::slots/signals>, puis de rappeler cette d�claration au niveau de 
l'impl�mentation � l'aide de la seconde syntaxe.
Les d�clarations seront alors v�rifi�es � la compilation, et le moindre conflit
g�n�rera un avertissement.

=head1 D�veloppement rapide (RAD) avec TQt Designer et Puic


=head2 Introduction

=over 4

=item * N.B:

Depuis la version 3.008, il existe un plugin sp�cifique � PerlTQt pour TQt Designer.
Ce plugin (disponible sur les pages internet du projet) apporte le confort d'une int�gration pouss�e,
la coloration  syntaxique Perl, la compl�tion automatique, et permet de lancer et d�boguer un projet
sans quitter l'interface du Designer. 
Ce qui suit reste n�anmoins parfaitement valable pour ce qui est de l'utilisation de puic en ligne de commande, 
et pour l'utilisation de TQt Designer I<sans> le plugin sp�cifique.

=back

Aussi puissant et intuitif que soit TQt, �crire une GUI compl�te reste un exercice 
fastidieux.

Heureusement, TQt est fourni avec un constructeur de GUI sophistiqu�
appel� TQt Designer qui est quasiment un environnement de d�veloppement
int�gr�. Il comporte la gestion de Projets, la cr�ation d'un GUI par
des actions de "drag and drop", un butineur d'objet complet,
l'interconnexion graphique de signaux et de slots, et plus encore.

L'information g�n�r�e par TQt Designer's est en format XML et peut donc
�tre pars�e par diff�rentes commandes comme dont B<puic> (le
compilateur d'interface utilisateur PerlTQt).

Supposons que vous avez d�ja construit un fichier d'interface avec
TQt Designer, la transcription en un programme PerlTQt se fait par
la simple ex�cution de la commande :

 puic -x -o program.pl program.ui

Cela g�n�rera le package d�fini dans votre fichier ui et un package
principal � fins de test,

Vous pouvez pr�f�rer :

 puic -o package.pm program.ui

Cela ne g�n�rera que le package qui pourra �tre utilis� par un programme s�par�.

=head2 Inclure des Images


Il y a deux mani�res d'inclure des B<images ou ic�nes>:

=over 4

=item * Inclusion Inline

A cette fin, nous devons s�lectionner "Edit->Form
Settings->Pixmaps->Save inline" dans TQt Designer et executer ensuite:

  puic -x -o F<program.pl> F<program.ui>


=item * Image Collection

Cette strat�gie est plus complexe, mais plus propre et plus puissante.

 puic -o F<Collection.pm> -embed F<unique_identifier> F<image-1> ... F<image-n>

Ajoutez l'instruction C<use Collection.pm> dans le package principal
de votre programme.

Si vous avez cr�� un fichier projet dans TQt Designer et ajout� toutes
les images dans un groupe (par "Project->Image Collection"), vous
disposez ensuite de ces images dans le r�pertoire o� votre fichier
projet (*.pro) est stock�, dans le sous-r�pertoire B<image>. Vous pouvez
alors g�n�rer la collection d'images par:

 puic -o F<Collection.pm> -embed F<identifier> images/*

Vous pouvez utiliser autant de collections d'images que vous voulez
dans un programme en ajoutant simplement une instruction B<use>
pour chaque collection.

=back

=head2  Travailler avec des fichiers B<.ui>

Souvent, vous voudrez reg�n�rez votre interface utilisateur �
� cause d'une modification ou extension  de votre design initial.
C'est donc une mauvais id�e d'�crire votre code dans le fichier Perl
autog�n�r� car vous risquerez d'�craser le code que vous avez �crit
manuellement ou vous devrez faire des copier-coller intensifs.

Voici une meilleure m�thode :

=over 4

=item * �crire l'impl�mentation de slots dans le Designer

Dans TQt Designer, selectionnez l'onglet I<Source> dans l'explorateur
d'objets (B<Object Explorer>).  Vous pouvez ainsi voir repr�sent�es
sous forme d'arbre les classes que vous avez g�n�r�es. Maintenant, si
vous cliquez deux fois sur l'entr�e I<Slots/public>,
un dialogue vous demande si vous voulez cr�er un nouveau slot pour
votre module. Une fois cela fait, le nouveau slot apparait �
l'int�rieur de l'arbre l'explorateur d'objet; cliquer dessus vous
am�nera � votre fichier B<E<lt>Votre ClasseE<gt>.ui.h> o� vous pouvez
�crire l'impl�mentation de votre slot.

Par d�faut, il devrait ressembler � ceci :

 void Form1::newSlot()
 {

 }


La d�claration du slot est r�ellement du code C++, mais ignorons cela
et �crivons du code Perl entre les deux accolades en faisant bien
attention d'indenter notre code avec au moins un espace.

 void Form1::newSlot()
 {
     print STDERR "Hello world from Form1::newSlot();
     if(this->foo())
     {
         # faire quelque chose
     }
 }

Notre code Perl ainsi �crit sera sauv� dans le fichier ui.h et
B<puic> prendra soin de le placer dans notre programme final.

Ici, apr�s l'ex�cution de B<puic> sur le ficier Form1.ui, vous
devriez avoir:

 sub newSlot
 {
     print STDERR "Hello world from Form1::newSlot();
     if(this->foo())
     {
         # faire quelque chose
     }
 }

=item * Sous-classez votre GUI

En utilisant l'option I<-subimpl> de B<puic>, vous pouvez g�n�rer un
module d�riv� qui h�rite l'interface utilisateur originelle.

Typiquement, vous g�n�rez le module d�riv� une fois, et �crivez votre
code dans ce module d�riv�. Ainsi, quand vous devez modifier votre
module GUI, reg�n�rez le module dont il d�rive et il h�ritera les
changements.

Pour g�n�rer le module de base  :

 puic -o Form1.pm form1.ui

(fa�tes cela aussi souvent que n�cessaire: n'�ditez jamais
manuellement form1.ui puisqu'il serait �cras�)


Pour g�n�rer le GUI d�riv�  :

 puic -o Form2.pm -subimpl Form2 form1.ui

ou

 puic -o program.pl -x -subimpl Form2 form1.ui

(faites cela une fois et travaillez avec le fichier r�sultant)

=back

=head1 Autres outils de d�veloppement

PerlTQt comprend �galement deux programmes pouvant vous aider � ma�triser l'API de TQt :

=head2 pqtapi

pqtapi est un outil d'introspection en ligne de commande.

 utilisation: pqtapi [-r <re>] [<class>]

 options:
        -r <re> : chercher les m�thodes correspondant � l'expression r�guli�re <re>
        -i : avec -r, effectue une recherche insensible � la casse
        -v : afficher les versions de PerlTQt et de TQt
        -h : afficher ce message d'aide

ex:

 $>pqtapi -ir 'setpoint.* int'
        void TQCanvasLine::setPoints(int, int, int, int)
        void TQPointArray::setPoint(uint, int, int)

=head2 pqtsh

B<pqtsh> est un shell graphique permettant de tester l'API de mani�re interactive.
Un exemple dynamique est accessible dans l'entr�e de menu C<Help-E<gt>Example>.

=for html
<br/>
<div class='image'><img src="../images/pqtsh.png"/></div>

=head1 Limitations

Les classes � mod�le (templates) ne sont pas encore accessibles par PerlTQt.
En revanche, les classes d�riv�es de classes � mod�le sont disponibles.

Vous pouvez reconna�tre ce type de classe en ce que leurs arguments comprennent un type g�n�rique plac� entre
les signes "<" et ">".

ex:
  TQDictIterator ( const TQDict<type> & dict )


=head1 Cr�dits

PerlTQt-3 est (c) 2002 Ashley Winters (et (c) 2003 Germain Garand)

Kalyptus et l'engin de g�n�ration  Smoke  sont (c) David Faure and Richard Dale

Puic is (c) TrollTech AS., Phil Thompson et Germain Garand,

Ledit logiciel est d�livr� sous la GNU Public Licence v.2 or later.


=head1 Appendice: Les conventions de C++ et leur traduction en Perl

Lorsque vous voulez utiliser depuis PerlTQt une classe ou m�thode d�crite
dans la L<documentation|"http://doc.trolltech.com"> TQt (voyez aussi le programme 
$TQTDIR/bin/assistant livr� avec TQt), vous devez suivre des r�gles de translation simples.

=over 4

=item Noms de classe

=over 4

=item *

Les noms de classes utilisent le pr�fixe B<TQt::> au lieu de B<Q> pour
�tre conforme � l'usage Perl.  Ainsi: TQComboBox est nomm� TQt::ComboBox
dans PerlTQt.

=back

=item Fonctions

=over 4

=item *

Les fonctions d�crites comme  B<static> sont acc�d�es directement et non
� travers un objet. Ainsi la fonction statique Foo de la classe B<TQBar>
peut �tre acc�d�e de PerlTQt par

 TQt::Bar::Foo( arg-1,...,arg-n);

=item *

Les fonctions d�crites comme  B<members> ou B<Signals> sont
accessibles � travers l'objet par l'op�rateur
 B<-E<gt>> .
Par exemple:

 $widget->show;

Il n'y a pas de diff�rence fondamentale entre les m�thodes et les
signaux, n�anmoins PerlTQt fournit le mot-cl� B<emit> comme une
mn�monique pratique pour rendre clair que vous �mettez un signal :

 emit $button->clicked;

=back

=item Arguments

=over 4

=item * Par valeur

Lorsqu'un argument n'est pas pr�c�d� par un des caract�res B<&> or
B<*>,  il est pass� par valeur. Pour tous les types basiques tels que
int, char, float and double, PerlTQt convertira automatiquement les
valeurs lit�rales et scalaires dans le type correspondants C++.

Ainsi pour le prototype d'un constructeur �crit dans la documentation
comme ceci:
 TQSize ( int w, int h )


Vous �crirez :

 TQt::Size(8, 12);

=item *  Par r�f�rence

Lorsqu'un argument est pr�c�d� par le caract�re B<&>, Il est une
r�f�rence � un objet ou � un type. Vous pouvez alors fournir un nom de
variable ou un objet temporaire :

 $keyseq = TQt::keySequence( &TQt::CTRL + &TQt::F3 );
 $widget->setAccel( $keyseq );

ou

 $widget->setAccel(TQt::keySequence( &TQt::CTRL + &TQt::F3 );

Si l'argument n'est I<pas> qualifi� par B<const> (constante), l'argument
est un objet qui peut �tre alt�r� par la m�thode, vous devez
donc passer une variable.

=item * Par pointeur

Lorsqu'un argument est pr�c�d� par le caract�re B<*>,
un pointeur vers un objet ou un type est attendu. En PerlTQt, vous
pouvez fournir un nom de  variable ou le mot cl� B<undef> � la place
du pointer Null.

De plus, si l'argument est const, l'objet pass� en argument est en
lecture seule: il ne peut pas �tre modifi�.

=back

=item �num�rations

Les �numerations sont une forme d'alias pour des valeurs num�riques
dont il serait autrement difficile de se souvenir:

Exemple C++:

 enum Strange { Apple, Orange, Lemon }

Ici, C<Strange> est le type (au sens de C++) de l'�num�ration, et
C<Apple>, C<Orange> et
C<Lemon> ses valeurs  possible , qui sont des aliases pour des
nombres (ici 0, 1 et 2)

L'acc�s aux valeurs d'�num�ration en Perl TQt est un appel
de fonction statique.

Donc, si vous voulez �viter des prbl�mes de lisibilit�, nous vous
recommandons l'usage d'une syntaxe alternative d'appel de fonction
pour marquer l'utilisation d'un alias d'�num�ration: C<&fonction>.


Revenons � notre exemple C<Strange>.

Si nous rencontrons sa  d�finition  dans la classe C<TQFruits>, vous
�crirez en PerlTQt :

 $pomme_plus_orange = &TQt::Fruit::Pomme + &TQt::Fruit::Orange;

=item Op�rateurs

Dans PerlTQt, la B<surcharge d'op�rateurs> fonctionne de mani�re transparente.
Si un op�rateur est surcharg� dans une classe TQt (ce qui signifie que son utilisation
d�clenchera un appel de m�thode, au lieu d'utiliser l'op�rateur g�n�rique)
il sera �galement surcharg� dans PerlTQt.

ex-1: surcharge de '+='

 $p1 = TQt::Point(10, 10)
 $p2 = TQt::Point(30,40)
 $p2 += $p1; # $p2 devient (40,50)

ex-2: surcharge de '<<'

 $f = TQt::File("example");
 $f->open( IO_WriteOnly ); # voir l'entr�e 'Constantes' plus bas
 $s = TQt::TextStream( $f );
 $s << "Que faire avec " << 12 << " pommes ?";


B<Exception notable> : le constructeur de copie (signe �gal, '=') n'est jamais surcharg�,
attendu qu'il ne pourrait fonctionner que partiellement et que le paradigme de
Perl est tr�s diff�rent de C++ en mati�re de copie d'objets.

=item Constantes

TQt n'utilise pas beaucoup de constantes, mais on en trouve cependant dans le module d'Entr�es/Sorties,
o� elles font office de drapeaux pour les modes d'ouverture de fichiers.

Pour �viter de polluer inutilement l'espace de nom, nous avons regroup� les constantes dans le module
B<TQt::constants>, d'o� elles seront charg�es � la demande.

Ainsi, pour importer l'ensemble des constantes d'E/S, on �crira :

 use TQt::constants;

Et pour importer quelques symboles seulement :

 use TQt::constants qw( IO_ReadOnly IO_WriteOnly );

=item Fonctions globales

TQt dispose de fonctions utilitaires, telles bitBlt, tqCompress, etc.

Ces fonctions ont �t� rassembl�es dans un espace de nom commun:
C<TQt::GlobalSpace>.

Vous pourrez donc y acc�der soit par un appel pleinement qualifi� :

 TQt::GlobalSpace::tqUncompress( $buffer )

Soit en important pr�alablement ces fonctions dans l'espace de nom courant :

 use TQt::GlobalSpace;
 tqUncompress( $buffer )

Bien entendu, vous pouvez aussi n'importer que les fonctions souhait�es :

 use TQt::GlobalSpace qw( tqUncompress bitBlt )

B<N.B:> GlobalSpace renferme �galement des op�rateurs de port�e globale, tels
celui permettant d'aditionner deux TQt::Point(). Ces op�rateurs seront appel�s 
automatiquement.

ex:

 $p1 = TQt::Point(10, 10) + TQt::Point(20, 20)

=back

=head1 Annexe 2 : Internationalisation

PerlTQt r�sout les probl�mes d'internationalisation en convertissant syst�matiquement les B<TQString>
de TQt en B<utf8> c�t� Perl.

Les conversions en sens inverse, depuis Perl vers TQt sont trait�es diff�remment suivant le contexte :

=over 4

=item * Si la cha�ne de caract�re est d�j� marqu�e comme �tant utf8

alors elle sera convertie en TQString directement.

C'est la mani�re privil�gi�e d'op�rer, et la plus simple :
Il vous suffit d'ins�rer un pragma B<use utf8> en t�te de vos programmes, puis d'utiliser un �diteur de
texte supportant l'utf8 (quasiment tous de nos jours) pour �laborer votre code source.
Les cha�nes seront marqu�es par Perl automatiquement.

=item * Si la cha�ne n'est pas marqu�e comme utf8, et le pragma 'use locale' n'est pas actif

alors la conversion en TQString se fera depuis l'B<ISO-Latin-1>.

=item * Si la cha�ne n'est pas marqu�e comme utf8, et le pragma 'use locale' est actif

alors la conversion en TQString se fera depuis votre B<locale>.

=back

Lorsque des cha�nes contiennent de l'utf8, Perl adapte automatiquement ses op�rateurs pour que
leur gestion soit enti�rement transparente (comprendre opaque, comme toujours...).
Cependant, vous pourrez avoir besoin � l'occasion de les transcrire en d'autres jeux d'encodage.
Ceci peut se faire soit avec TQt :

 $tr1=TQt::TextCodec::codecForLocale(); # ceci utilisera la locale en vigueur
 $tr2=TQt::TextCodec::codecForName("KOI8-R"); # ceci force l'emploi d'une locale sp�cifique (Russe)

 print $tr1->fromUnicode(TQt::DateTime::currentDateTime()->toString)."\n\n";
 print $tr2->fromUnicode($une_chaine_utf8);

Soit avec les outils de Perl (pour perl >= 5.8.0).
Se reporter � ce sujet � la documentation du module B<Encode> (C<perldoc Encode>).

=head3 d�sactiver l'encodage utf8

Les programmeurs souhaitant d�sactiver temporairement l'encodage utf8
(pour la gestion de programmes externes ou de modules anciens ne supportant pas cet encodage)
pourront utiliser le pragma B<use bytes> (et sa r�ciproque : B<no bytes>).

Dans la port�e de ce pragma, les conversions depuis TQString vers les cha�nes Perl se feront en ISO-Latin1
(par d�faut) ou suivant la locale en vigueur (si B<use locale> est actif).

Notez bien qu'il est pr�f�rable de I<ne pas utiliser ce pragma � la l�g�re>, en ce qu'il ruine totalement les
efforts de standardisations autour d'utf8 entrepris depuis plusieurs ann�es d�j�.
Il est tr�s pr�f�rable de corriger les programmes fautifs.

=head1 Annexe 3 : Canaux de d�boguage

Le module B<TQt::debug> offre divers canaux de d�boguage permettant de filtrer
le flux cons�quent d'informations disponibles pour l'adapter � vos besoins.

 use TQt::debug;

 use TQt::debug qw|calls autoload verbose|;

Avec le pragma C<use TQt::debug>, seuls les canaux B<verbose> et B<ambiguous> sont activ�s.
Si vous le faites suivre d'une liste pr�cise de canaux, seuls ceux-ci seront affich�s.

B<Liste et descriptif des canaux :>

=over 4

=item * ambiguous

V�rifier si les appels de m�thodes sont ambigus, et dire quelle m�thode, parmi le jeux
d'alternatives, � finalement �t� choisie.

=item * verbose

Donner davantage d'informations.

Utilis� avec B<ambiguous>, vous donnera les correspondances les plus proches lorsqu'un appel de m�thode �choue.

ex:

 use TQt;
 use TQt::debug;
 $a= TQt::Application(\@ARGV);
 $a->libraryPath("chose");

 --- No method to call for :
        TQApplication::libraryPath('chose')
 Closer candidates are :
        static void TQApplication::addLibraryPath(const TQString&)
        static TQStringList TQApplication::libraryPaths()
        static void TQApplication::removeLibraryPath(const TQString&)
        static void TQApplication::setLibraryPaths(const TQStringList&)

=item * calls

Pour chaque appel de m�thode, vous dira quelle m�thode TQt est finalement appel�e,
en pr�cisant les arguments si B<verbose> est actif.

=item * autoload

D�taille le passage dans le code interm�diaire faisant la jonction entre Perl et TQt.

=item * gc

Donne des informations sur la collection des d�chets, c'est � dire sur la destruction des objets,
qu'ils soient d�truits depuis Perl ou TQt.

=item * virtual

Vous averti chaque fois qu'une fonction virtuelle tente d'acc�der � sa r�impl�mentation en Perl
(que cette r�impl�mentation existe ou non).

=item * all

Activer tous les canaux.

=back

=head1 Annexe 4 : Marshalleurs

Un marshalleur est un convertisseur permettant de transcrire un type de donn�es en un autre.

Dans PerlTQt, la plupart des objets TQt gardent leurs propri�t�s d'objet, ce qui permet d'invoquer leurs m�thodes
et de changer leurs propri�t�s comme il se doit.
Cependant, il arrive que l'objet d'origine corresponde � ce point � un type natif de Perl qu'il serait mals�ant
d'utiliser l'interface C++ et beaucoup plus naturel de lui substituer son �quivalent.

Ici interviennent les marshalleurs.
Plut�t que de retourner un objet TQt::StringList, qui serait d�licat � manipuler,
PerlTQt le transformera en r�f�rence de liste Perl.
D�s lors, tous les op�rateurs de manipulation de liste pourront lui �tre appliqu� :
on gagne en densit�, en coh�rence et en simplicit�.

Cette transformation s'appliquera aussi en sens inverse, et n'importe quelle liste de cha�nes Perl
pourra �tre donn�e en argument � une m�thode attendant une TQt::StringList.

 Liste des marshalleurs (PerlTQt-3.008)
 -----------------------------------------------------------------
 float, double                         <=>       r�el Perl (NV)
 char, uchar, int, uint, enum
 long, ulong, short, ushort            <=>       entier Perl (IV)
 TQString, -&, -*                        =>       cha�ne Perl (utf8)
 TQString, -&, -*                       <=        cha�ne Perl (utf8 ou iso-latin1 ou locale)
 TQCString, -&, -*                      <=>       cha�ne Perl (utf8 ou octets, suivant contenu ou pragma "bytes")
 TQStringList, -&, -*                    =>       r�f�rence � une liste de cha�nes Perl (utf8)
 TQByteArray, -&, -*                    <=>       cha�ne Perl (octets)
 int&, -*                              <=>       entier Perl (IV)
 bool&, -*                             <=>       bool�en Perl
 char*                                 <=>       cha�ne Perl (octets)
 char**                                <=        r�f�rence � une liste de cha�nes Perl (octets)
 uchar*                                <=        cha�ne Perl(octets)
 TQRgb*                                 <=        r�f�rence � une liste d'entiers Perl (IV)
 TQCOORD*                               <=        r�f�rence � une liste d'entiers Perl (IV)
 void*                                 <=>       r�f�rence � un entier Perl (IV)
 TQValueList<int>, - *, - &             <=>       r�f�rence � une liste d'entiers Perl (IV)
 TQCanvasItemList, - *, - &              =>       r�ference � une liste de TQt::CanvasItem
 TQWidgetList, - *, - &                 <=>       r�ference � une liste de TQt::Widget
 TQObjectList, - *, - &                 <=>       r�ference � une liste de TQt::Object
 TQFileInfoList, - *, - &               <=>       r�ference � une liste de TQt::FileInfo
 TQPtrList<TQTab>, - *, - &              <=>       r�ference � une liste de TQt::Tab
 TQPtrList<TQToolBar>, - *, - &          <=>       r�ference � une liste de TQt::ToolBar
 TQPtrList<TQNetworkOperation>, - *, - & <=>       r�ference � une liste de TQt::NetworkOperation
 TQPtrList<TQDockWindow>, - *, - &       <=>       r�ference � une liste de TQt::DockWindow
 (TQUObject*)