diff options
Diffstat (limited to 'doc/fr/PerlQt.pod')
| -rw-r--r-- | doc/fr/PerlQt.pod | 1189 |
1 files changed, 1189 insertions, 0 deletions
diff --git a/doc/fr/PerlQt.pod b/doc/fr/PerlQt.pod new file mode 100644 index 0000000..5036239 --- /dev/null +++ b/doc/fr/PerlQt.pod @@ -0,0 +1,1189 @@ + +=head1 Programmer avec PerlQt + +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 Qt 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 + +PerlQt-3, cr�e par Ashley Winters, est une interface perl aux composants +graphiques (et non graphiques) fournis par Qt3. + +Le toolkit Qt 3.0 auquel PerlQt acc�de � �t� �crit en C++ par la soci�t� +Trolltech: L<Trolltech|"http://www.trolltech.com">. + +PerlQt3 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 Qt 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 PerlQt. +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 Qt|"http://doc.trolltech.com">. Ladite documentation est +la seule r�f�rence qui fasse autorit�. + +Si Qt est install� sur votre syst�me, sa documentation l'est +certainement aussi : voyez le programme $QTDIR/bin/assistant. + +=head1 Installation + +=head2 Conditions requises + +Pour compiler et utiliser PerlQt, 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<Qt E<gt>= +v3.0|"http://www.trolltech.com/developer/download/qt-x11.html"> + +=item * + +L<SmokeQt +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 +perlQt 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 Qt sont en dehors du sujet du pr�sent +document. Se r�f�rer aux documentations respectives de ces logiciels. + +=head2 Compilation de PerlQt + +Les instructions de cette section pr�supposent que le r�pertoire courant est +le r�pertoire racine de l'arborescence des sources de PerlQt. + +PerlQt 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<QTDIR> n'est pas d�finie, vous devrez +peut-�tre sp�cifier manuellement l'emplacement de Qt � l'aide de l'option : + + --with-qtdir=/emplacement/de/Qt + +Si la biblioth�que SMOKE est manquante, C<configure> g�n�rera ses sources dans +un sous-r�pertoire. + + make + + make install + +Cela installera PerlQt, 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 KDEDIR 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 PerlQt pour qu'il ne s'installe pas dans la hi�rarchie Perl ordinaire : + + cd PerlQt + 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 PerlQt + +=item * + +Lancez la compilation et l'installation + + make && make install + +Pour ex�cuter des programmes PerlQt, 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 PerlQt + +Un programme Qt 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<Qt::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. Qt g�rera les �v�nements et les dirigera vers les +routines appropri�es. + +Voyons un programme PerlQt minimal. + +=head2 Hello World + + 1: use Qt; + 2: my $a = Qt::Application(\@ARGV); + 3: my $hello = Qt::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 Qt [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<Qt::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 perlQt 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 PerlQt sont accessibles par le pr�fixe B<Qt::> au lieu du +B<Q> initial des classes Qt en C++. En consultant la L<documentation +Qt|"http://doc.trolltech.com">, vous devez donc mentalement changer le +nom d'une clasee B<QFoo> en B<Qt::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 Qt::Foo> ou C<Qt::Foo-E<gt>new()> +contrairement � l'usage commun en Perl. + +Dites simplement: + + my $object = Qt::<classname>(arg_1, ..., arg_n); + +Un constructeur sans argument s'�nonce encore plus bri�vement : + + my $object = Qt::<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 Qt (Par exemple: "C<QWidget* widget>"). + +=back + +=head2 L'h�ritage et les objets + +Avant d'expliquer comment les routines Perl peuvent �tre appel�es de Qt, +parlons du m�canisme d'h�ritage vu de PerlQt. + +PerlQt est con�u pour allier la simplicit� de Qt � la puissance et � la +flexibilit� de Perl. Pour ce faire, PerlQt �tend le paradigme objet de +Perl pour mimer Qt 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 Qt; + 5: use Qt::isa qw(Qt::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 Qt; + 18: use Button; + 19: + 20: my $a = Qt::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 Qt [l.4]. + +Nous utilisons le pragma C<Qt::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 PerlQt est appel� B<implicitement> I<comme ligne 21>. + +Note widget doit d'abord appeler le constructeur de sa classe de base +(ici: Qt::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, PerlQt 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, PerlQt 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 Qt::attributes>, suivi d'une liste des noms d'attributs souhait�s. +Ainsi: + + + 1: use strict; + 2: + 3: package Button; + 4: use Qt; + 5: use Qt::isa qw(Qt::PushButton); + 6: use Qt::attributes qw( + 7: itsTime + 8: pData + 9: ); + 10: + 11: sub NEW + 12: { + 13: shift->SUPER::NEW(@_[0..2]); + 14: itsTime = Qt::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<Qt::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 Qt, un package doit contenir un +pragma C<use Qt::isa>. + +Ainsi: + + use Qt::isa "Qt::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 Qt::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 Qt (ce sont les m�thodes pr�c�d�es du mot clef "virtual"). + +Vous pouvez visualiser les noms de m�thodes virtuelles que Qt tentera d'appeler +dans votre classe en pla�ant C<use Qt::debug qw|virtual|> en t�te de +votre programme. + +=back + +=head2 Signaux et Slots + +Voyons maintenant comment les objets Qt 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 Qt 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 Qt 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: + +Qt::Object::connect( envoyeur, SIGNAL 'mon_signal(types_d_arguments)', +recepteur, SLOT 'monslot(types_d_arguments)'); + +soit: + +unObjet->connect( envoyeur, 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 Qt::signals> et C<use Qt::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 Qt; + 5: use Qt::isa qw(Qt::PushButton); + 6: use Qt::attributes qw(itsTime); + 7: use Qt::slots + 8: aEteClicke => [], + 9: changement => ['int', 'int']; + 10: use Qt::signals + 11: changeLe => ['int', 'int']; + 12: + 13: sub NEW + 14: { + 15: shift->SUPER::NEW(@_[0..2]); + 16: itsTime = Qt::Time; + 17: itsTime->start; + 18: this->connect(this, SIGNAL 'clicked()', SLOT 'aEteClicke()'); + 19: this->connect(this, SIGNAL 'changeLe(int,int)', 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 Qt 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 PerlQt-3.008 : + + sub un_slot : SLOT(int, QString) + { + $int = shift; + $string = shift; + # faire quelque chose + } + +et + + sub un_signal : SIGNAL(QString); + +Cette syntaxe est parfaitement compatible avec la d�claration par le biais de +C<use Qt::signals> et C<use Qt::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 Qt::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 Qt Designer et Puic + + +=head2 Introduction + +=over 4 + +=item * N.B: + +Depuis la version 3.008, il existe un plugin sp�cifique � PerlQt pour Qt 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 Qt Designer I<sans> le plugin sp�cifique. + +=back + +Aussi puissant et intuitif que soit Qt, �crire une GUI compl�te reste un exercice +fastidieux. + +Heureusement, Qt est fourni avec un constructeur de GUI sophistiqu� +appel� Qt 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 Qt 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 PerlQt). + +Supposons que vous avez d�ja construit un fichier d'interface avec +Qt Designer, la transcription en un programme PerlQt 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 Qt 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 Qt 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 Qt 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 + +PerlQt comprend �galement deux programmes pouvant vous aider � ma�triser l'API de Qt : + +=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 PerlQt et de Qt + -h : afficher ce message d'aide + +ex: + + $>pqtapi -ir 'setpoint.* int' + void QCanvasLine::setPoints(int, int, int, int) + void QPointArray::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 PerlQt. +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: + QDictIterator ( const QDict<type> & dict ) + + +=head1 Cr�dits + +PerlQt-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 PerlQt une classe ou m�thode d�crite +dans la L<documentation|"http://doc.trolltech.com"> Qt (voyez aussi le programme +$QTDIR/bin/assistant livr� avec Qt), 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<Qt::> au lieu de B<Q> pour +�tre conforme � l'usage Perl. Ainsi: QComboBox est nomm� Qt::ComboBox +dans PerlQt. + +=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<QBar> +peut �tre acc�d�e de PerlQt par + + Qt::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 PerlQt 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, PerlQt 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: + QSize ( int w, int h ) + + +Vous �crirez : + + Qt::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 = Qt::keySequence( &Qt::CTRL + &Qt::F3 ); + $widget->setAccel( $keyseq ); + +ou + + $widget->setAccel(Qt::keySequence( &Qt::CTRL + &Qt::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 PerlQt, 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 Qt 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<QFruits>, vous +�crirez en PerlQt : + + $pomme_plus_orange = &Qt::Fruit::Pomme + &Qt::Fruit::Orange; + +=item Op�rateurs + +Dans PerlQt, la B<surcharge d'op�rateurs> fonctionne de mani�re transparente. +Si un op�rateur est surcharg� dans une classe Qt (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 PerlQt. + +ex-1: surcharge de '+=' + + $p1 = Qt::Point(10, 10) + $p2 = Qt::Point(30,40) + $p2 += $p1; # $p2 devient (40,50) + +ex-2: surcharge de '<<' + + $f = Qt::File("example"); + $f->open( IO_WriteOnly ); # voir l'entr�e 'Constantes' plus bas + $s = Qt::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 + +Qt 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<Qt::constants>, d'o� elles seront charg�es � la demande. + +Ainsi, pour importer l'ensemble des constantes d'E/S, on �crira : + + use Qt::constants; + +Et pour importer quelques symboles seulement : + + use Qt::constants qw( IO_ReadOnly IO_WriteOnly ); + +=item Fonctions globales + +Qt dispose de fonctions utilitaires, telles bitBlt, qCompress, etc. + +Ces fonctions ont �t� rassembl�es dans un espace de nom commun: +C<Qt::GlobalSpace>. + +Vous pourrez donc y acc�der soit par un appel pleinement qualifi� : + + Qt::GlobalSpace::qUncompress( $buffer ) + +Soit en important pr�alablement ces fonctions dans l'espace de nom courant : + + use Qt::GlobalSpace; + qUncompress( $buffer ) + +Bien entendu, vous pouvez aussi n'importer que les fonctions souhait�es : + + use Qt::GlobalSpace qw( qUncompress bitBlt ) + +B<N.B:> GlobalSpace renferme �galement des op�rateurs de port�e globale, tels +celui permettant d'aditionner deux Qt::Point(). Ces op�rateurs seront appel�s +automatiquement. + +ex: + + $p1 = Qt::Point(10, 10) + Qt::Point(20, 20) + +=back + +=head1 Annexe 2 : Internationalisation + +PerlQt r�sout les probl�mes d'internationalisation en convertissant syst�matiquement les B<QString> +de Qt en B<utf8> c�t� Perl. + +Les conversions en sens inverse, depuis Perl vers Qt 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 QString 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 QString 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 QString 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 Qt : + + $tr1=Qt::TextCodec::codecForLocale(); # ceci utilisera la locale en vigueur + $tr2=Qt::TextCodec::codecForName("KOI8-R"); # ceci force l'emploi d'une locale sp�cifique (Russe) + + print $tr1->fromUnicode(Qt::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 QString 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<Qt::debug> offre divers canaux de d�boguage permettant de filtrer +le flux cons�quent d'informations disponibles pour l'adapter � vos besoins. + + use Qt::debug; + + use Qt::debug qw|calls autoload verbose|; + +Avec le pragma C<use Qt::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 Qt; + use Qt::debug; + $a= Qt::Application(\@ARGV); + $a->libraryPath("chose"); + + --- No method to call for : + QApplication::libraryPath('chose') + Closer candidates are : + static void QApplication::addLibraryPath(const QString&) + static QStringList QApplication::libraryPaths() + static void QApplication::removeLibraryPath(const QString&) + static void QApplication::setLibraryPaths(const QStringList&) + +=item * calls + +Pour chaque appel de m�thode, vous dira quelle m�thode Qt 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 Qt. + +=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 Qt. + +=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 PerlQt, la plupart des objets Qt 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 Qt::StringList, qui serait d�licat � manipuler, +PerlQt 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 Qt::StringList. + + Liste des marshalleurs (PerlQt-3.008) + ----------------------------------------------------------------- + float, double <=> r�el Perl (NV) + char, uchar, int, uint, enum + long, ulong, short, ushort <=> entier Perl (IV) + QString, -&, -* => cha�ne Perl (utf8) + QString, -&, -* <= cha�ne Perl (utf8 ou iso-latin1 ou locale) + QCString, -&, -* <=> cha�ne Perl (utf8 ou octets, suivant contenu ou pragma "bytes") + QStringList, -&, -* => r�f�rence � une liste de cha�nes Perl (utf8) + QByteArray, -&, -* <=> 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) + QRgb* <= r�f�rence � une liste d'entiers Perl (IV) + QCOORD* <= r�f�rence � une liste d'entiers Perl (IV) + void* <=> r�f�rence � un entier Perl (IV) + QValueList<int>, - *, - & <=> r�f�rence � une liste d'entiers Perl (IV) + QCanvasItemList, - *, - & => r�ference � une liste de Qt::CanvasItem + QWidgetList, - *, - & <=> r�ference � une liste de Qt::Widget + QObjectList, - *, - & <=> r�ference � une liste de Qt::Object + QFileInfoList, - *, - & <=> r�ference � une liste de Qt::FileInfo + QPtrList<QTab>, - *, - & <=> r�ference � une liste de Qt::Tab + QPtrList<QToolBar>, - *, - & <=> r�ference � une liste de Qt::ToolBar + QPtrList<QNetworkOperation>, - *, - & <=> r�ference � une liste de Qt::NetworkOperation + QPtrList<QDockWindow>, - *, - & <=> r�ference � une liste de Qt::DockWindow + (QUObject*) + |