From 10ee12b66a226f890b423ab711e17efd04bd2f70 Mon Sep 17 00:00:00 2001 From: Michele Calgaro Date: Thu, 18 Oct 2018 22:45:41 +0900 Subject: Moved to /usr folder instead of /opt/trinity. This relates to bug 266. Signed-off-by: Michele Calgaro --- doc/fr/PerlTQt.pod | 1189 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1189 insertions(+) create mode 100644 doc/fr/PerlTQt.pod (limited to 'doc/fr/PerlTQt.pod') diff --git a/doc/fr/PerlTQt.pod b/doc/fr/PerlTQt.pod new file mode 100644 index 0000000..70161fa --- /dev/null +++ b/doc/fr/PerlTQt.pod @@ -0,0 +1,1189 @@ + +=head1 Programmer avec PerlTQt + +B traduit par B, révisé et augmenté par l'auteur. + +Ce document décrit l'interface Perl au toolkit TQt 3.x. Contacter +l'auteur à ou le traducteur à +. Vous trouverez le document original sur le site +L + +=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. + +PerlTQt3 est fondé sur la librairie +L, +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 +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. 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= v5.6.0|"http://www.perl.org"> + +=item * + +L= +v3.0|"http://www.trolltech.com/developer/download/qt-x11.html"> + +=item * + +L La +librarie SMOKE (Scripting Meta Object Kompiler) fait partie du module +L's B. 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 : + + perl Makefile.PL + +B Si la variable d'environnement B 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 générera ses sources dans +un sous-répertoire. + + make + + make install + +Cela installera PerlTQt, Puic et les utilitaires ptqtsh et ptqtapi. + +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'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 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 +
+
+ +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. + +La ligne 3, crée un PushButton orphelin (c.à.d sans parent: non +contenu dans un autre widget) dont nous passons la valeur B +comme argument pour le parent. B 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. + +Pour rendre ce widget visible (qui est par défaut caché), on +appelle la méthode B [l.6] et lance la boucle +événementielle [l.7]. + +B + +=over 4 + +=item 1 + +Les classes PerlTQt sont accessibles par le préfixe B au lieu du +B initial des classes TQt en C++. En consultant la L, vous devez donc mentalement changer le +nom d'une clasee B en B. + +=item 2 + +De manière similaire à C++, un objet est créé par l'appel d'un +B de même nom que la classe dont il est une méthode. + +Vous ne devez donc pas dire C ou Cnew()> +contrairement à l'usage commun en Perl. + +Dites simplement: + + my $object = TQt::(arg_1, ..., arg_n); + +Un constructeur sans argument s'énonce encore plus brièvement : + + my $object = TQt::; + + +=item 3 + +Comme il a déjà été dit, l'équivalent Perl d'un pointeur C++ est le mot-clé +Perl B. + +Les pointeurs sont les arguments précédés par le caractère B<*> dans la +documentation TQt (Par exemple: "C"). + +=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. + +=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 [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 I<(notez les majuscules qui +marquent une méthode différente du constructeur "new" usuel)>. +Le constructeur PerlTQt est appelé B I. + +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 (Attention: ce n'est pas la +variable C<$this> mais simplement C). + +Chaque fois que nous invoquons une méthode à partir de notre package +nous pouvons écrire indifféremment C ou +Cmethod()>; + +=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) 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. + +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, 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 +
+
+ + +L'attribut itsTime est déclaré à la ligne 7 et initialisé par un objet C +à 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 + +=over 4 + +=item * + +Pour hériter d'une classe TQt, un package doit contenir un +pragma C. + +Ainsi: + + use TQt::isa "TQt::widget"; + +=item * + +Le constructeur d'objet est nommé B 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. + +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 : + + use TQt::attributes qw( + firstAttribute + ... + lastAttribute); + +Il sera alors disponible comme accesseur : + + firstAttribute = myContainedWidget( this ); + firstAttribute->resize( 100, 100 ); + +B 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, 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, créez simplement une +B 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 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. + +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 et des entrées ou +B. 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 et C +(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. + +B + + 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 ; nous le connectons donc à notre nouveau slot [ligne 18]. + +Nous connectons aussi notre signal C à notre slot +C. + +Ainsi, quand on appuie (clique) sur notre Button , le signal +C est émit et déclenche le slot C. +C émet à son tour le signal C[l.27], +appelant de ce fait le slot C, 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 et C. +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, 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 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 (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: + +=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 F + + +=item * Image Collection + +Cette stratégie est plus complexe, mais plus propre et plus puissante. + + puic -o F -embed F F ... F + +Ajoutez l'instruction C 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. Vous pouvez +alors générer la collection d'images par: + + puic -o F -embed F images/* + +Vous pouvez utiliser autant de collections d'images que vous voulez +dans un programme en ajoutant simplement une instruction B +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 dans l'explorateur +d'objets (B). 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, +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 BVotre ClasseE.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 prendra soin de le placer dans notre programme final. + +Ici, après l'exécution de B 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, 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 ptqtapi + +ptqtapi est un outil d'introspection en ligne de commande. + + utilisation: ptqtapi [-r ] [] + + options: + -r : chercher les méthodes correspondant à l'expression réguliè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: + + $>ptqtapi -ir 'setpoint.* int' + void TQCanvasLine::setPoints(int, int, int, int) + void TQPointArray::setPoint(uint, int, int) + +=head2 ptqtsh + +B est un shell graphique permettant de tester l'API de manière interactive. +Un exemple dynamique est accessible dans l'entrée de menu CExample>. + +=for html +
+
+ +=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 & 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 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 au lieu de B 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 sont accédées directement et non +à travers un objet. Ainsi la fonction statique Foo de la classe B +peut être accédée de PerlTQt par + + TQt::Bar::Foo( arg-1,...,arg-n); + +=item * + +Les fonctions décrites comme B ou B sont +accessibles à travers l'objet par l'opérateur + B<-E> . +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 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 qualifié par B (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 à 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 est le type (au sens de C++) de l'énumération, et +C, C et +C 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. + +Si nous rencontrons sa définition dans la classe C, vous +écrirez en PerlTQt : + + $pomme_plus_orange = &TQt::Fruit::Pomme + &TQt::Fruit::Orange; + +=item Opérateurs + +Dans PerlTQt, la B 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 : 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, 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. + +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 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 +de TQt en B 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 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. + +=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. + +=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 (C). + +=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 (et sa réciproque : B). + +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 est actif). + +Notez bien qu'il est préférable de I, 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 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, seuls les canaux B et B sont activés. +Si vous le faites suivre d'une liste précise de canaux, seuls ceux-ci seront affichés. + +B + +=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, 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 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, - *, - & <=> 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, - *, - & <=> réference à une liste de TQt::Tab + TQPtrList, - *, - & <=> réference à une liste de TQt::ToolBar + TQPtrList, - *, - & <=> réference à une liste de TQt::NetworkOperation + TQPtrList, - *, - & <=> réference à une liste de TQt::DockWindow + (TQUObject*) + -- cgit v1.2.3