Initial import of libqt-perl (not yet TQt compatible)

10 files changed, 4683 insertions, 0 deletions

diff --git a/doc/css/pod.css b/doc/css/pod.css
new file mode 100644
index 0000000..6f7bd52
--- /dev/null
+++ b/doc/css/pod.css
@@ -0,0 +1,132 @@
+/* standard elements */
+body
+    {
+    background: #FFFFFF;
+    font-family: Verdana, Arial, Helvetica, sans-serif;
+    font-weight: normal;
+    }	
+p
+    {
+    color: #000000;
+    font-family: Verdana, Arial, Helvetica, sans-serif;
+    font-weight: normal;
+    }
+blockquote
+    {
+    color: #000000;
+    font-family: Verdana, Arial, Helvetica, sans-serif;
+    font-weight: normal;
+    }
+ul
+    {
+    color: #000000;
+    font-family: Verdana, Arial, Helvetica, sans-serif;
+    font-weight: normal;
+    list-style-type: disc;
+    }
+ol
+    {
+    color: #000000;
+    font-family: Verdana, Arial, Helvetica, sans-serif;
+    font-weight: normal;
+    }
+h1
+    { 
+    font-family: Verdana, Arial, Helvetica, sans-serif;
+    font-size: 18px;
+    font-weight: bold;
+    color: #2660C9;
+    }
+h2 
+    {
+    font-family: Verdana, Arial, Helvetica, sans-serif;
+    font-size: 13px;
+    font-weight: bold;
+    color: #2660C9;
+    background-color: #EAE2BB;
+    }
+h3
+    { 
+    font-family: Verdana, Arial, Helvetica, sans-serif;
+    font-size: 12px;
+    font-weight: bold;
+    color: #000000;
+    }        
+h4
+    { 
+    font-family: Verdana, Arial, Helvetica, sans-serif;
+    font-size: 11px;
+    font-weight: bold;
+    color: #2660C9;
+    } 	
+
+pre
+    {
+    font-size: 120%;
+    padding-bottom: 5px;
+    }
+tt
+    {
+    font-size: 120%;
+    }
+code
+    {
+    font-size: 120%;
+    }
+kbd
+    {
+    font-size: 120%;
+    }
+   
+/* documentation link formatting */
+a:link 
+	{ 
+	color: #2660C9;
+        text-decoration: underline;
+	}
+a:visited 
+	{
+        color: #2660C9; 
+        text-decoration: underline;
+	}
+a:hover
+	{
+	color: #000000;
+    text-decoration: underline;
+	}
+a:active 
+	{ 
+        color: #2660C9;
+        text-decoration: underline;
+	}
+.docsubheading
+	{
+	font-family: Verdana, Arial, Helvetica, sans-serif;
+	font-size: 13px;
+	font-weight: bold;
+	color: #B82619;
+	background-color: #EAE2BB;
+	}
+.docsubheadinggrey
+	{
+	font-family: Verdana, Arial, Helvetica, sans-serif;
+	font-size: 13px;
+	font-weight: bold;
+	color: #B82619;
+	background-color: #cccccc;
+    }
+.error
+    {
+    color: #B82619;
+    }    
+.err
+    {
+    color: #B82619;
+    }    
+    
+/* unordered list without bullets */
+ul.sans 
+	{ 
+	list-style-type: none;
+	}
+        
diff --git a/doc/en/Makefile b/doc/en/Makefile
new file mode 100644
index 0000000..1d300c0
--- /dev/null
+++ b/doc/en/Makefile
@@ -0,0 +1,7 @@
+
+index.html: PerlQt.pod
+	pod2html --css ../css/pod.css PerlQt.pod > index.html
+	perl -pi -e 's/cgibin/cgi-bin/' index.html
+	perl -pi -e 's/#http/http/g' index.html
+	rm -f pod2*~~
+
diff --git a/doc/en/PerlQt.pod b/doc/en/PerlQt.pod
new file mode 100644
index 0000000..b05a0a9
--- /dev/null
+++ b/doc/en/PerlQt.pod
@@ -0,0 +1,1147 @@
+
+=head1 Programming PerlQt
+
+B<Germain Garand>
+
+This document describes a set of Perl bindings for the Qt toolkit. Contact
+the author at <germain@ebooksfrance.com>
+
+=head1 Introduction
+
+PerlQt-3 is Ashley Winters' full featured object oriented interface to
+L<Trolltech|"http://www.trolltech.com">'s C++ Qt toolkit v3.0.
+
+It is based on the
+L<SMOKE|"http://webcvs.kde.org/cgi-bin/cvsweb.cgi/kdebindings/smoke">
+library, a language independent low-level wrapper generated from Qt headers by
+Richard Dale's
+L<kalyptus|"http://webcvs.kde.org/cgi-bin/cvsweb.cgi/kdebindings/kalyptus">
+thanks to David Faure's module.
+
+This document describes the principles of PerlQt programming.
+It assumes you have some basic Perl Object Oriented programming knowledge.
+
+Some C++ knowledge is recommended but not required.
+It would mostly help you to find your way through L<Qt's
+excellent documentation|"http://doc.trolltech.com"> which is our
+ultimate and only reference.
+If Qt is installed on your system, then you most probably
+also have its documentation. Try the C<$QTDIR/bin/assistant> program.
+
+
+=head1 Installation
+
+=head2 Requirements
+
+To compile and use PerlQt, you'll need :
+
+=over 4
+
+=item *
+
+a POSIX system
+
+=item *
+
+GNU tools : automake(>=1.5), autoconf (>=2.13), aclocal...
+
+=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">
+The SMOKE library (Scripting Meta Object Kompiler) is part of L<KDE|"http://www.kde.org">'s B<kdebindings> module.
+You may want to check if a precompiled version of this module exists for your
+system.
+PerlQt is packaged with its own copy, so you don't need to check it out.
+
+=back
+
+Perl and Qt's installation is out of the scope of this document. Please refer
+to those projects' documentation.
+
+=head2 Compilation
+
+PerlQt uses GNU's Autoconf framework. However, the standard ./configure script is preferably driven
+by the Makefile.PL wrapper. All options are forwarded to ./configure :
+
+ perl Makefile.PL
+
+If SMOKE is missing, C<configure> will generate its sources.
+Then :
+
+ make
+
+ make install
+
+This will install PerlQt, Puic and Smoke (if needed), as well as the pqtsh and pqtapi utilities.
+
+The preferred install location for SMOKE and Puic is in the KDE3 file system.
+If you don't have KDE3 installed, specify a location with C<configure>'s
+C<--prefix> option. e.g:
+
+ perl Makefile.PL --prefix=/usr
+
+=head2 Troubleshooting and Configure Options
+
+If Smoke's linking fails or your Qt library was built with very specific
+options, run Makefile.PL again with:
+
+ perl Makefile.PL --with-threshold=0
+
+When building smoke, configure will check for OpenGL and try to compile
+support for it if it is properly installed and supported by Qt.
+
+You may disable this checking with:
+
+ --disable-GL
+
+Also, default behaviour is to prefer the Mesa GL library over a proprietary
+implementation.
+If your system features a proprietary OpenGL library, and you'd like to use
+it, specify:
+
+ --without-Mesa
+
+=head2 How to install PerlQt with user rights
+
+To install PerlQt without super-user rights, simply follow this procedure:
+
+=over 4
+
+=item *
+
+Perform a normal configuration, specifying as prefix a directory where you have write permissions :
+
+ perl Makefile.PL --prefix=~
+
+The above would install the Smoke library in ~/lib and the puic binary in ~/bin
+
+=item *
+
+Reconfigure the Perl module so that it doesn't target the standard perl hierarchy:
+
+ cd PerlQt
+ perl Makefile.PL PREFIX=~
+ cd ..
+
+Beware : this is not the same Makefile.PL as above, but the one located in the ./PerlQt
+subdirectory
+
+=item *
+
+Compile and Install
+
+ make && make install
+
+In order to use such an installation, you must tell to Perl where to find this extern hierarchy.
+This can be done either on the command line:
+
+ perl -Mlib="~/local/lib/perl/5.x.x" program.pl
+
+or at the top of your program:
+
+ use lib qw( ~/local/lib/perl/5.x.x );
+
+"5.x.x" should be changed to whatever Perl version your system is running.
+
+=back
+
+=head1 Anatomy of PerlQt
+
+A typical Qt program using GUI components is based on an event loop.
+
+This basically means that such a program is no more envisioned as a straight
+flow where you would need to handle yourself every single events (such as a
+mouse click or a key press).
+
+Instead, you just create an B<Application> object, create the GUI components it
+uses,
+define what objects methods need to be called when an event occurs,
+and then start the main event loop.
+
+That's all!
+Qt will handle all events and dispatch them to the correct subroutine.
+
+Lets see how this process is implemented in a minimal PerlQt program.
+
+=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>
+
+This program first loads the Qt interface [line 1] and creates the application
+object, passing it a reference to the command line arguments array C<@ARGV>
+[l.2].
+This application object is unique, and may later be accessed from
+anywhere through the B<Qt::app()> pointer.
+
+At line 3, we create a PushButton, which has no parent (i.e : it won't be
+contained nor owned by another widget).
+Therefore, we pass to the constructor an B<undef> value for the parent argument,
+which is PerlQt's way of passing a Null pointer.
+
+After some layouting at [l.4], we tell the application object that our main
+widget is this PushButton [l.5]... that way, it will know that closing the
+window associated with this widget means : I<quit the application>.
+
+Now the last steps are to make this widget visible (as opposed to
+hidden, which is the default) by calling the B<show> method on it [l.6] and
+to start the application loop [l.7].
+
+B<Syntax elements summary :>
+
+=over 4
+
+=item 1
+
+All Qt classes are accessed through the prefix B<Qt::>, which replaces the 
+initial B<Q> of Qt classes.
+When browsing the L<Qt
+documentation|"http://doc.trolltech.com>, you simply need to change the
+name of classes so that B<QFoo> reads B<Qt::Foo>.
+
+=item 2
+
+An object is created by calling the B<constructor> of the class. It has the 
+same name as the class itself.
+
+You don't need to say C<new Qt::Foo> or C<Qt::Foo-E<gt>new()> as most Perl
+programmers would have expected.
+
+Instead, you just say :
+
+ my $object = Qt::<classname>(arg_1, ..., arg_n);
+ 
+
+If you don't need to pass any argument to the constructor, simply say :
+
+ my $object = Qt::<classname>;
+ 
+
+=item 3
+
+Whenever you need to pass a Null pointer as an argument, use Perl's B<undef> 
+keyword. Do not pass zero.
+ Beware: this is by far the most common error in PerlQt programs.
+
+Pointers are arguments preceded by an B<*> 
+character in Qt's documentation (e.g: "C<QWidget * widget>").
+
+=back
+
+=head2 Inheritance and Objects
+
+Before we can discuss how Perl subroutines can be called back from Qt, we need
+to introduce PerlQt's inheritance mechanism.
+
+PerlQt was designed to couple as tightly as possible Qt's simplicity and Perl's 
+power and flexibility.
+
+In order to achieve that goal, the classical Object Oriented Perl paradigm had 
+to be extended, much in the same way than Qt itself
+had to extend C++'s paradigm with B<metaobjects>.
+
+=head3 A Custom Widget
+
+Lets rewrite the "Hello World!" program, this time using a custom version 
+of 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;
+
+Here, we want to create our own version of the PushButton widget.
+Therefore, we create a new package for it [l.3] and import Qt [l.4].
+
+We now want to declare our widget as subclassing PushButton.
+This is done through the use of the C<Qt::isa> pragma [l.5], which accepts a 
+list of one or more parent Qt classes.
+
+It is now time to create a B<constructor> for our new widget.
+This is done by creating a subroutine called B<NEW> I<(note the capitalized 
+form, which differentate it from the usual "new" constructor. PerlQt's NEW 
+constructor is called >B<implicitly>I< as can be seen on line 21)>.
+
+Since we want our widget to call its parent's constructor first, we call the 
+B<superclass's constructor> (here: Qt::PushButton) on line 9, passing it all 
+arguments we received.
+
+At this time, a class instance has been created and stored into a special 
+object holder named B<this> (not C<$this> but really just C<this>).
+
+Each time you invoke a method from within your package, you may now 
+indifferently say C<method()> or C<this-E<gt>method()>;
+
+=head3 Using Attributes
+
+When building a new composite widget, you may just create its different 
+parts inside B<my> variables, since widgets are only deleted by their parents 
+and not necessarily when their container goes out of scope.
+
+In other words, PerlQt performs clever reference counting to prevent 
+indesirable deletion of objects.
+
+Now, you'll often want to keep an access to those parts from anywhere inside 
+your package.
+For this purpose, you may use the B<this> object's blessed hash, as is usual in Perl,
+but that isn't really convenient and you don't have any compile time
+checking...
+
+Here come B<Attributes>. Attributes are data holders where you can 
+store any kind of properties for your object.
+
+Declaring new attributes is done through the C<use Qt::attributes> pragma, as is 
+demonstrated in the following package implementation :
+
+  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 = " Foo ";
+ 17: }
+ 18: 
+ 19: sub resizeEvent
+ 20: {
+ 21:    setText( "w: ". width() ." h: ". height() .
+ 22:             "\nt: ". itsTime->elapsed . pData );
+ 23: }
+ 24:
+ 25: 1;
+
+=for html
+<br/>
+<div class='image'><img src="../images/ex2.png"/></div>   
+
+
+An attribute itsTime is declared at line 7, and loaded with a C<Qt::Time> object 
+at line 14.
+
+Since we reimplement the virtual function "resizeEvent" [l.19].
+each time the main widget is resized, this function will be triggered and 
+our Button's text updated with values coming from the object [l.21] and from the 
+attributes we defined [l.22].
+
+B<Recapitulation>
+
+=over 4
+
+=item *
+
+In order to inherit a Qt class, a package must contain a 
+C<use Qt::isa> pragma.
+e.g:
+ 
+ use Qt::isa "Qt::widget";
+
+=item *
+
+The object constructor is named B<NEW> and is implicitly called.
+Thus you should not say : 
+
+ my $o = MyButton->NEW("Hello");
+
+But say :
+
+ my $o = MyButton("Hello"); 
+
+=item *
+
+Within a package, the current instance can be accessed through the B<this> 
+variable.
+
+When a member function is called, arguments are loaded as usual in the B<@_> 
+array, but B<without> the object pointer itself.
+
+Hence, you shouldn't say :
+
+ sub myMember
+ {
+   my $self = shift;
+   my $arg = shift;
+   $arg->doThat($self); 
+   $self->doIt;
+ }
+    
+But :
+
+ sub myMember
+ {
+   my $arg = shift;
+   $arg->doThat(this);
+   doIt;
+ }
+
+Furthermore, if you want to call a base class method from a derived class,
+you'd use the specal attribute SUPER :
+
+ sub example
+ {
+   print "Now calling the base class\n";
+   SUPER->example(@_)
+ }
+
+Note that the :
+
+ this->SUPER::Example(@_);
+
+construct is also available, but will pass the object as first argument.
+
+
+=item *
+
+Whenever you need to store a contained object in your package, you may define it 
+as an B<Attribute> :
+
+ use Qt::attributes qw(
+	firstAttribute
+	...
+	lastAttribute);
+
+and then use it as a convenient accessor :
+
+ firstAttribute = myContainedWidget( this );
+ firstAttribute->resize( 100, 100 );
+
+=item *
+
+To reimplement a B<virtual function>, simply create a B<sub> with the 
+same name in your object.
+
+Existing virtual functions are marked as such in Qt's documentation
+(they are prefixed with the "virtual" keyword).
+
+You can inspect what virtual function names are being called by Qt at runtime by
+putting a C<use Qt::debug qw( virtual )> statement at the top of your program.
+
+=back
+
+=head2 Signals and Slots
+
+We'll now learn how Qt objects can communicate with each other, 
+allowing an event occuring, for instance, in a given widget to trigger the 
+execution of one or several subroutines anywhere inside your program.
+
+Most other toolkits use callbacks for that purpose, but Qt has a much more 
+powerful and flexible mechanism called B<Signals and Slots>.
+
+Signals and slots are used for communication between objects.
+
+This can be thought off as something similar to the wiring between several Hi-fI 
+components : an amplificator, for instance, has a set of output signals, wich are 
+emitted wether a listening device is connected to them or not. Also, a tape 
+recorder deck can start to record when it receives a signal wired to it's input 
+slot, and it doesn't need to know that this signal is also received by a CD 
+recorder device, or listened through headphones.
+
+A Qt component behaves just like that. It has several output B<Signals> and 
+several input B<Slots> - and each signal can be connected to an unlimited number 
+of listening slots of the same type, wether they are inside or outside the 
+component.
+
+The general syntax of this connection process is either :
+
+Qt::Object::connect( sender, SIGNAL 'mysignal(arg_type)', 
+receiver, SLOT 'myslot(arg_type)');
+
+or
+
+myObject->connect( sender, SIGNAL 'mysignal(arg_type)', SLOT 
+'myslot(arg_type)');
+
+This mechanism can be extended at will by the declaration of custom Signals and 
+Slots, through the C<use Qt::signals> and C<use Qt::slots> pragma
+(see also the other syntax, later on).
+
+Each declared slot will call the corresponding subroutine in your object, 
+each declared signal can be raised through the B<emit> keyword.
+
+B<As an example, lets rewrite again our Button package :>
+
+  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:     wasClicked => [],
+  9:     change     => ['int', 'int'];
+ 10: use Qt::signals
+ 11:     changeIt   => ['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 'wasClicked()');
+ 19:   this->connect(this, SIGNAL 'changeIt(int,int)', SLOT 'change(int,int)');
+ 20: }
+ 21: 
+ 22: sub wasClicked
+ 23: {
+ 24:    my $w = width();
+ 25:    my $h = height();
+ 26:    setText( "w: $w h: $h\nt: ". itsTime->elapsed );
+ 27:    emit changeIt($w, $h);          
+ 28: }
+ 29:
+ 30: sub change
+ 31: {
+ 32:    my ($w, $h) = @_;
+ 33:    print STDERR "w: $w h: $h \n";
+ 34: }
+ 35:
+ 36: 1;
+
+In this package, we define two extra slots and one extra signal.
+
+We know from the Qt Documentation that a clicked PushButton emits a C<clicked()> 
+signal, so we connect it to our new slot at line 18.
+
+We also connect our signal C<changeIt> to our own C<change> slot- which is 
+quite stupid, but as an example.
+
+Now, whenever our Button is clicked, the C<clicked()> signal is raised and 
+triggers the C<wasClicked()> slot. C<wasClicked> then proceeds to emit 
+the C<changeIt(int,int)> signal [l.27], hence triggering the C<change(int,int)> 
+slot with two arguments.
+
+Finally, since PerlQt-3.008, an alternative syntax can be used to declare Signals and Slots:
+
+ sub a_slot : SLOT(int, QString)
+ { 
+	$int = shift;
+	$string = shift;
+	# do something
+ }
+
+and
+
+ sub a_signal : SIGNAL(QString);
+
+This syntax is perfectly compatible with the traditional
+C<use Qt::signals> and C<use Qt::slots> declarations.
+
+Eventually, it can prove good programming practice to mix both syntaxes, by first declaring  
+Signals/Slots with C<use Qt::slots/signals>, then repeat this declaration
+in the actual implementation with the second syntax.
+
+Declarations will be checked for consistency at compile time, and any mismatch
+in arguments would trigger a warning.
+
+=head1 RAD prototyping with Qt Designer and Puic
+
+=head2 Introduction
+
+=over 4
+
+=item * Note: 
+
+As of PerlQt-3.008, a separate PerlQt plugin for Qt Designer is available,
+bringing full integration, syntax highlighting, code completion and allowing to run/debug your PerlQt project
+entirely from the Designer GUI. 
+Nevertheless, the below is still accurate with regard to puic command line interaction 
+and with regard to using Qt Designer I<without> the specific plugin.
+
+=back
+
+As efficient and intuitive as Qt can be, building a complete GUI from scratch 
+is often a tedious task.
+
+Hopefully, Qt comes with a very sophisticated GUI Builder named Qt 
+Designer, which is close to a complete integrated development environment.
+It features Project management, drag'n drop GUI building, a complete object 
+browser, graphical interconnection of signals and slots, and much much more.
+
+Qt Designer's output is XML which can be parsed by several command line tools,
+among whose is B<puic> (the PerlQt User Interface Compiler).
+
+Assuming you have already built an interface file with the Designer, 
+translating it to a PerlQt program is simply a matter of issuing 
+one command :
+
+ puic -x -o program.pl program.ui
+
+This will generate the package defined in your ui file and a basic main package 
+for testing purposes.
+
+You may prefer :
+
+ puic -o package.pm program.ui
+
+This will only generate the package, which can then be used by a separate 
+program.
+
+=head2 Embedding Images
+
+If you need to B<embed images or icons>, it can be done in two ways
+:
+
+=over 4
+
+=item * Inline embedding
+
+For this, you need to check the "Edit->Form Settings->Pixmaps->Save inline" 
+checkbox inside Qt Designer.
+Then : puic -x -o F<program.pl> F<program.ui>
+
+=item * Image Collection
+
+This option is more complex but also far more powerful and clean.
+
+puic -o F<Collection.pm> -embed F<unique_identifier> F<image-1> ... F<image-n>
+
+Then add a C<use Collection.pm> statement to your program's main package.
+
+If you've created a project file in Qt Designer, and added all images 
+you want to group (through "Project->Image Collection"), you'll find all those 
+images inside the directory where your project file (*.pro) is stored, under 
+/images.
+You can then generate the corresponding image collection by issuing :
+
+puic -o F<Collection.pm> -embed F<identifier> ../images/*
+
+You can use as many image collections as you want in a program. Simply add a 
+B<use> statement for each collection.
+
+=back 
+
+=head2 Working With B<.ui> Files
+
+It will often happen that you need to regenerate your user interface -either
+because you changed your initial design, or you want to extend it.
+Thus writing your program's code straight in the auto-generated Perl file is
+quite a bad idea.
+You'd run constantly the risk of overwriting your handcrafted code, or end
+up doing lot of copy-paste.
+
+Instead, you may :
+
+=over 4
+
+=item * Write slots implementation in the Designer
+
+In Qt Designer, select the I<Source> tab of the B<Object Explorer>.
+There you can see a tree-like representation of your classes.
+Now if you double-click on the I<Slots/public> entry,
+you are prompted with a dialog where you can create a new custom slot for
+your module.
+Once this is done, the new slot appear inside the B<Object Explorer> tree and
+clicking on it will bring you to a B<E<lt>Your ClassE<gt>.ui.h> file where you can write
+the actual implementation of your slot.
+
+Keeping all the defaults, it should look like this :
+
+ void Form1::newSlot()
+ {
+ 
+ }
+
+The slot declaration is actually C++ code, but simply ignore it and write
+your Perl code straight between the two braces, paying special attention to
+indent it at least by one space.
+
+ void Form1::newSlot()
+ {
+     print STDERR "Hello world from Form1::newSlot();
+     if(this->foo())
+     {
+         # do something
+     }
+ }
+
+All Perl code written this way will be saved to the ui.h file, and B<puic> will take care of
+placing it back in the final program.
+
+Here, after running B<puic> on the Form1.ui file, you'd have:
+
+ sub newSlot
+ {
+     print STDERR "Hello world from Form1::newSlot();
+     if(this->foo())
+     {
+         # do something
+     }
+ }
+
+=item * Subclassing your GUI
+
+By using B<puic>'s I<-subimpl> option, you may generate a derived module
+inheriting your original user interface.
+
+You'd typically generate the derived module once, and write any handcrafted
+code in this child.
+Then, whenever you need to modify your GUI module, simply regenerate the
+parent module, and your child will inherit those changes.
+
+To generate the base module :
+
+ puic -o Form1.pm form1.ui 
+
+(do this as often as needed, never edit by hand)
+
+To generate the child :
+
+ puic -o Form2.pm -subimpl Form2 form1.ui
+
+or
+
+ puic -o program.pl -x -subimpl Form2 form1.ui 
+
+(do this once and work on the resulting file)
+
+=back
+
+=head1 More development tools
+
+PerlQt comes bundled with two simple programs that can help you to find your way through
+the Qt API:
+
+=head2 pqtapi
+
+pqtapi is a commandline driven introspection tool.
+
+ usage: pqtapi [-r <re>] [<class>]
+
+ options:
+        -r <re> : find all functions matching regular expression/keyword <re>
+        -i : together with -r, performs a case insensitive search
+        -v : print PerlQt and Qt versions
+        -h : print this help message
+
+e.g:
+
+ $>pqtapi -ir 'setpoint.* int'
+        void QCanvasLine::setPoints(int, int, int, int)
+        void QPointArray::setPoint(uint, int, int)
+
+=head2 pqtsh
+
+B<pqtsh> is a graphical shell that can be used to test the API interactively.
+It is fairly self explanatory and includes an interactive example (C<Help-E<gt>Example>)
+
+=for html
+<br/>
+<div class='image'><img src="../images/pqtsh.png"/></div>
+
+=head1 Known Limitations
+
+Templated classes aren't available yet (classes derived from templated classes are).
+
+=head1 Credits
+
+PerlQt-3 is (c) 2002 Ashley Winters (and (c) 2003 Germain Garand)
+
+Kalyptus and the Smoke generation engine are (c) David Faure and Richard Dale
+
+Puic is (c) TrollTech AS., Phil Thompson and Germain Garand, 
+
+The mentioned software is released under the GNU Public Licence v.2 or later.
+
+
+=head1 Appendix 1 : C++ conventions and their Perl counterpart
+
+Whenever you want to use a class/method described in Qt's
+L<documentation|"http://doc.trolltech.com"> (see also the 'assistant' program bundled with Qt)
+from PerlQt, you need to follow some simple translation rules.
+
+=over 4
+
+=item Classnames
+
+=over 4
+
+=item *
+
+All classnames are changed from a B<Q> prefix in Qt to a B<Qt::> prefix
+in Perl.
+e.g: QComboBox is named Qt::ComboBox within PerlQt.
+
+=back
+
+=item Functions
+
+=over 4
+
+=item *
+
+Functions referenced as B<static> are accessed directly, and not through
+an object. Thus the static function Foo in class QBar would be accessed from
+PerlQt as
+
+ Qt::Bar::Foo( arg-1,...,arg-n);
+
+The only notable exceptions are :
+
+ qApp()     will map to Qt::app()
+ qVersion() will map to Qt::version() # not really needed anymore: we have qVersion(). See Global Functions below.
+
+=item *
+
+Functions referenced as B<members> or B<Signals> are accessed through an object
+with the B<-E<gt>> operator.
+e.g:
+
+ $widget->show;
+
+There are no fundamental differences between methods and signals, however PerlQt 
+provides the B<emit> keyword as a convenient mnemonic, so that it is clear you 
+are emitting a signal :
+
+ emit $button->clicked;
+
+=back
+
+=item Arguments
+
+=over 4
+
+=item * By value
+
+When an argument isn't preceded by the B<&> or B<*> character, it is passed by 
+value. For all basic types such as int, char, float and double, PerlQt will 
+automatically convert litteral and scalar values to the corresponding C++ type.
+
+Thus for a constructor prototype written as follow in the documentation :
+
+ QSize ( int w, int h )
+ 
+
+You'd say :
+
+ Qt::Size(8, 12);
+ 
+
+=item * By reference
+
+When an argument is preceded by the B<&> character, it means a reference to an 
+object or to a type is expected. You may either provide a variable name or a 
+temporary object :
+
+ $keyseq = Qt::keySequence( &Qt::CTRL + &Qt::F3 );
+ $widget->setAccel( $keyseq );
+ 
+or
+
+ $widget->setAccel(Qt::keySequence( &Qt::CTRL + &Qt::F3 );
+
+If the argument isn't qualified as B<const> (constant), it means the passed
+object may be altered during the process - you must then provide a variable.
+
+=item * By pointer
+
+When an argument is preceded by the B<*> character, it means a 
+pointer to an object or to a type is expected. You may provide a variable 
+name or the Perl B<undef> keyword for a Null pointer.
+
+Similarly, if the argument isn't B<const>, the passed object may be altered by
+the method call.
+
+=back
+
+=item Enumerations
+
+Enumerations are sort of named aliases for numeric values that would be hard to
+remember otherwise.
+
+A C++ example would be :
+
+ enum Strange { Apple, Orange, Lemon }
+
+where C<Strange> is the generic enumeration name, and C<Apple>, C<Orange>,
+C<Lemon> its possible values, which are only aliases for numbers (here 0, 1
+and 2).
+
+Access to enumerations values in Perl Qt is very similar to a static function
+call. In fact, it B<is> a static function call.
+
+Therefore, since you probably want to avoid some readability problems, we
+recommend the use of the alternate function call syntax : C<&function>.
+
+Lets now go back to our C<Strange> example.
+
+If its definition was encountered in the class C<QFruits>, you'd write from
+PerlQt :
+
+ $apple_plus_orange = &Qt::Fruit::Apple + &Qt::Fruit::Orange;
+
+=item Operators
+
+Within PerlQt, B<operators overloading> works transparently.
+If a given operator is overloaded in a Qt class (which means using it triggers a custom method)
+it will behave identically in PerlQt.
+Beware though that due to limitations of the Smoke binding library, not all overloaded operators are
+available in PerlQt.
+You can check the availability of a given operator by using the pqtapi program.
+Also, due to outstanding differences between C++'s and Perl's object paradigm, the copy constructor operator (a.k.a '=')
+has been disabled.
+
+e.g-1: '+=' overload
+
+ $p1 = Qt::Point(10, 10)
+ $p2 = Qt::Point(30,40)
+ $p2 += $p1; # $p2 becomes (40,50)
+ 
+e.g-2: '<<' overload
+
+ $f = Qt::File("example");
+ $f->open( IO_WriteOnly ); # see 'Constants' below
+ $s = Qt::TextStream( $f );
+ $s << "What can I do with " << 12 << " apples?";
+
+=item Constants
+
+Qt doesn't use many constants, but there is at least one place where they are used : for setting 
+Input/Output flags on files.
+In order to avoid the namespace pollution induced by global constants, PerlQt group them in the B<Qt::constants> module.
+For instance, requesting the importation of all IO constants into the current namespace would be done with:
+
+ use Qt::constants;
+
+You may also import specific symbols:
+
+ use Qt::constants qw( IO_ReadOnly IO_WriteOnly );
+
+=item Global Functions
+
+
+Qt has also some utilitarian functions such as bitBlt, qCompress, etc.
+
+Those were global scope functions and have been grouped in a common namespace:
+C<Qt::GlobalSpace>.
+
+Hence, you shall access this namespace either with a fully qualified call:
+
+ Qt::GlobalSpace::qUncompress( $buffer )
+
+Or directly, after importation in the current namespace:
+
+ use Qt::GlobalSpace;
+ qUncompress( $buffer )
+
+Of course, you may selectively import a few functions:
+
+ use Qt::GlobalSpace qw( qUncompress bitBlt )
+
+B<Note:> GlobalSpace has also operators, such has the one performing an addition on two
+Qt::Point(). Those operators are called automatically.
+
+e.g:
+
+ $p1 = Qt::Point(10, 10) + Qt::Point(20, 20)
+
+=back
+
+
+=head1 Appendix 2 : Internationalization
+
+PerlQt handles internationalization by always converting B<QString> back to B<utf8> in Perl.
+
+Conversions from Perl strings to QStrings are made according to context :
+
+=over 4
+
+=item * If the Perl string is already utf8-encoded
+
+then the string will be converted straight to QString.
+
+This is the most convenient and seemless way of internationalizing your application. Typically, one would just enable
+the use of utf8 in source code with the C<use utf8> pragma and write its application with an utf8 aware editor.
+
+=item * If the string isn't tagged as utf8, and the B<use locale> pragma is not set
+
+then the string will be converted to QString's utf8 from B<ISO-Latin-1>.
+
+=item * If the string isn't tagged as utf8 and the B<use locale> pragma is set
+
+then the string will be converted to QString's utf8 according to the currently set B<locale>.
+
+=back
+
+Once a string contains utf8, you can convert it back to any locale by setting up B<converters> :
+
+ $tr1=Qt::TextCodec::codecForLocale(); # this one will use current locale
+ $tr2=Qt::TextCodec::codecForName("KOI8-R"); # that one forces a specific locale (Russian)
+
+ print $tr1->fromUnicode(Qt::DateTime::currentDateTime()->toString)."\n\n";
+ print $tr2->fromUnicode($my_utf8_string);
+
+Or, with Perl >= 5.8.0, you may use Perl's B<Encode> modules (see C<perldoc Encode>).
+
+=head3 disabling utf-8
+
+Developers who don't want to use UTF-8 or want to temporarily disable UTF-8 marshalling
+for handling legacy programs may use the B<use bytes> pragma (and the corresponding B<no bytes>).
+
+Within the scope of this pragma, QStrings are marshalled back to ISO-Latin1 (default) or to your locale
+(if B<use locale> has been set).
+
+Frivole use of this pragma is strongly discouraged as it ruins worldwide standardization efforts.
+
+=head1 Appendix 3 : Debugging Channels
+
+The B<Qt::debug> module offers various debugging channels/features.
+
+ use Qt::debug;
+
+ use Qt::debug qw|calls autoload verbose|;
+
+With the simple C<use Qt::debug> statement, the B<verbose> and B<ambiguous> channels are activated.
+If you specify a list of channels within the use statement, then only the specified channels will be enabled.
+
+B<Available channels :>
+
+=over 4
+
+=item * ambiguous
+
+Check if method and function calls are ambiguous, and tell which of the alternatives
+was finally elected.
+
+=item * verbose
+
+Enable more verbose debugging.
+
+Together with B<ambiguous>, tell you the nearest matches in case
+a method or function call fails.
+e.g:
+
+ use Qt;
+ use Qt::debug;
+ $a= Qt::Application(\@ARGV);
+ $a->libraryPath("foo");
+
+ --- No method to call for :
+        QApplication::libraryPath('foo')
+ 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
+
+For every call, tell what corresponding Qt method is called
+(detailing the arguments if B<verbose> is on).
+
+=item * autoload
+
+Track the intermediate code between a method invocation in Perl
+and its resolution to either a Qt or Perl call.
+
+=item * gc
+
+Give informations about garbage collection
+whenever a Qt object is deleted and/or a Perl object is destroyed
+
+=item * virtual
+
+Report whenever a virtual function tries to access its Perl
+reimplementation (wether it exists or not).
+
+=item * all
+
+Enable all channels
+
+=back
+
+
+=head1 Appendix 4 : Marshallers
+
+A marshaller is a piece of "glue code" translating a given datatype to another.
+
+Within PerlQt, most Qt objects keep their object nature, so that one may invoke methods on them.
+However, some classes and datatypes map so naturally to some Perl types that keeping their object nature would
+would feel unnatural and clumsy.
+
+For instance, instead of returning a Qt::StringList object, which would require an iterator to retrieve its content,
+PerlQt will translate it to an array reference containing all the object's strings.
+
+In the other way, instead of providing a Qt::StringList object as an argument of a method, one would simply
+provide the reference to an array of Perl strings.
+
+Here is the list of Marshallers as of PerlQt-3.008 :
+
+ -----------------------------------------------------------------
+ float, double                         <=>       Perl real (NV)
+ char, uchar, int, uint, enum
+ long, ulong, short, ushort            <=>       Perl integer (IV)
+ QString, -&, -*                        =>       Perl string (utf8)
+ QString, -&, -*                       <=        Perl string (utf8 or iso-latin1 or locale)
+ QCString, -&, -*                      <=>       Perl string (utf8 or bytes, according to content or "bytes" pragma)
+ QByteArray, -&, -*                    <=>       Perl string (bytes)
+ QStringList, -&, -*                    =>       Reference to an array of Perl strings (utf8)
+ QString, -&, -*                        =>       Perl string (utf8 or iso-latin1 or locale)
+ int&, -*                              <=>       Perl integer (IV)
+ bool&, -*                             <=>       Perl boolean
+ char*                                 <=>       Perl string (bytes)
+ char**                                <=        Reference to an array of Perl strings (bytes)
+ uchar*                                <=        Perl string (bytes)
+ QRgb*                                 <=        Reference to an array of Perl integers (IV)
+ QCOORD*                               <=        Reference to an array of Perl integers (IV)
+ void*                                 <=>       Reference to a Perl integer (IV)
+ QValueList<int>, - *, - &             <=>       Reference to an array of Perl integers (IV)
+ QCanvasItemList, - *, - &              =>       Reference to an array of Qt::CanvasItem
+ QWidgetList, - *, - &                 <=>       Reference to an array of Qt::Widget
+ QObjectList, - *, - &                 <=>       Reference to an array of Qt::Object
+ QFileInfoList, - *, - &               <=>       Reference to an array of Qt::FileInfo
+ QPtrList<QTab>, - *, - &              <=>       Reference to an array of Qt::Tab
+ QPtrList<QToolBar>, - *, - &          <=>       Reference to an array of Qt::ToolBar
+ QPtrList<QNetworkOperation>, - *, - & <=>       Reference to an array of Qt::NetworkOperation
+ QPtrList<QDockWindow>, - *, - &       <=>       Reference to an array of Qt::DockWindow
+ (QUObject*)
+
+
+
+
+
diff --git a/doc/en/index.html b/doc/en/index.html
new file mode 100644
index 0000000..6a4cc7b
--- /dev/null
+++ b/doc/en/index.html
@@ -0,0 +1,1081 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Programming PerlQt</title>
+<link rel="stylesheet" href="../css/pod.css" type="text/css" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body>
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+	<li><a href="#programming_perlqt">Programming PerlQt</a></li>
+	<li><a href="#introduction">Introduction</a></li>
+	<li><a href="#installation">Installation</a></li>
+	<ul>
+
+		<li><a href="#requirements">Requirements</a></li>
+		<li><a href="#compilation">Compilation</a></li>
+		<li><a href="#troubleshooting_and_configure_options">Troubleshooting and Configure Options</a></li>
+		<li><a href="#how_to_install_perlqt_with_user_rights">How to install PerlQt with user rights</a></li>
+	</ul>
+
+	<li><a href="#anatomy_of_perlqt">Anatomy of PerlQt</a></li>
+	<ul>
+
+		<li><a href="#hello_world">Hello World</a></li>
+		<li><a href="#inheritance_and_objects">Inheritance and Objects</a></li>
+		<ul>
+
+			<li><a href="#a_custom_widget">A Custom Widget</a></li>
+			<li><a href="#using_attributes">Using Attributes</a></li>
+		</ul>
+
+		<li><a href="#signals_and_slots">Signals and Slots</a></li>
+	</ul>
+
+	<li><a href="#rad_prototyping_with_qt_designer_and_puic">RAD prototyping with Qt Designer and Puic</a></li>
+	<ul>
+
+		<li><a href="#introduction">Introduction</a></li>
+		<li><a href="#embedding_images">Embedding Images</a></li>
+		<li><a href="#working_with_.ui_files">Working With <strong>.ui</strong> Files</a></li>
+	</ul>
+
+	<li><a href="#more_development_tools">More development tools</a></li>
+	<ul>
+
+		<li><a href="#pqtapi">pqtapi</a></li>
+		<li><a href="#pqtsh">pqtsh</a></li>
+	</ul>
+
+	<li><a href="#known_limitations">Known Limitations</a></li>
+	<li><a href="#credits">Credits</a></li>
+	<li><a href="#appendix_1_:_c++_conventions_and_their_perl_counterpart">Appendix 1 : C++ conventions and their Perl counterpart</a></li>
+	<li><a href="#appendix_2_:_internationalization">Appendix 2 : Internationalization</a></li>
+	<ul>
+
+		<ul>
+
+			<li><a href="#disabling_utf8">disabling utf-8</a></li>
+		</ul>
+
+	</ul>
+
+	<li><a href="#appendix_3_:_debugging_channels">Appendix 3 : Debugging Channels</a></li>
+	<li><a href="#appendix_4_:_marshallers">Appendix 4 : Marshallers</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="programming_perlqt">Programming PerlQt</a></h1>
+<p><strong>Germain Garand</strong></p>
+<p>This document describes a set of Perl bindings for the Qt toolkit. Contact
+the author at &lt;<a href="mailto:germain@ebooksfrance.com">germain@ebooksfrance.com</a>&gt;</p>
+<p>
+</p>
+<hr />
+<h1><a name="introduction">Introduction</a></h1>
+<p>PerlQt-3 is Ashley Winters' full featured object oriented interface to
+<a href="http://www.trolltech.com">Trolltech</a>'s C++ Qt toolkit v3.0.</p>
+<p>It is based on the
+<a href="http://webcvs.kde.org/cgi-bin/cvsweb.cgi/kdebindings/smoke">SMOKE</a>
+library, a language independent low-level wrapper generated from Qt headers by
+Richard Dale's
+<a href="http://webcvs.kde.org/cgi-bin/cvsweb.cgi/kdebindings/kalyptus">kalyptus</a>
+thanks to David Faure's module.</p>
+<p>This document describes the principles of PerlQt programming.
+It assumes you have some basic Perl Object Oriented programming knowledge.</p>
+<p>Some C++ knowledge is recommended but not required.
+It would mostly help you to find your way through <a href="http://doc.trolltech.com">Qt's excellent documentation</a> which is our
+ultimate and only reference.
+If Qt is installed on your system, then you most probably
+also have its documentation. Try the <code>$QTDIR/bin/assistant</code> program.</p>
+<p>
+</p>
+<hr />
+<h1><a name="installation">Installation</a></h1>
+<p>
+</p>
+<h2><a name="requirements">Requirements</a></h2>
+<p>To compile and use PerlQt, you'll need :</p>
+<ul>
+<li></li>
+a POSIX system
+<p></p>
+<li></li>
+GNU tools : automake(&gt;=1.5), autoconf (&gt;=2.13), aclocal...
+<p></p>
+<li></li>
+<a href="http://www.perl.org">Perl &gt;= v5.6.0</a>
+<p></p>
+<li></li>
+<a href="http://www.trolltech.com/developer/download/qtx11.html">Qt &gt;= v3.0</a>
+<p></p>
+<li></li>
+<a href="http://webcvs.kde.org/cgi-bin/cvsweb.cgi/kdebindings/smoke">SmokeQt 1.2.1</a>
+The SMOKE library (Scripting Meta Object Kompiler) is part of <a href="http://www.kde.org">KDE</a>'s <strong>kdebindings</strong> module.
+You may want to check if a precompiled version of this module exists for your
+system.
+PerlQt is packaged with its own copy, so you don't need to check it out.
+<p></p></ul>
+<p>Perl and Qt's installation is out of the scope of this document. Please refer
+to those projects' documentation.</p>
+<p>
+</p>
+<h2><a name="compilation">Compilation</a></h2>
+<p>PerlQt uses GNU's Autoconf framework. However, the standard ./configure script is preferably driven
+by the Makefile.PL wrapper. All options are forwarded to ./configure :</p>
+<pre>
+ perl Makefile.PL</pre>
+<p>If SMOKE is missing, <code>configure</code> will generate its sources.
+Then :</p>
+<pre>
+ make</pre>
+<pre>
+ make install</pre>
+<p>This will install PerlQt, Puic and Smoke (if needed), as well as the pqtsh and pqtapi utilities.</p>
+<p>The preferred install location for SMOKE and Puic is in the KDE3 file system.
+If you don't have KDE3 installed, specify a location with <code>configure</code>'s
+<code>--prefix</code> option. e.g:</p>
+<pre>
+ perl Makefile.PL --prefix=/usr</pre>
+<p>
+</p>
+<h2><a name="troubleshooting_and_configure_options">Troubleshooting and Configure Options</a></h2>
+<p>If Smoke's linking fails or your Qt library was built with very specific
+options, run Makefile.PL again with:</p>
+<pre>
+ perl Makefile.PL --with-threshold=0</pre>
+<p>When building smoke, configure will check for OpenGL and try to compile
+support for it if it is properly installed and supported by Qt.</p>
+<p>You may disable this checking with:</p>
+<pre>
+ --disable-GL</pre>
+<p>Also, default behaviour is to prefer the Mesa GL library over a proprietary
+implementation.
+If your system features a proprietary OpenGL library, and you'd like to use
+it, specify:</p>
+<pre>
+ --without-Mesa</pre>
+<p>
+</p>
+<h2><a name="how_to_install_perlqt_with_user_rights">How to install PerlQt with user rights</a></h2>
+<p>To install PerlQt without super-user rights, simply follow this procedure:</p>
+<ul>
+<li></li>
+Perform a normal configuration, specifying as prefix a directory where you have write permissions :
+<pre>
+ perl Makefile.PL --prefix=~</pre>
+<p>The above would install the Smoke library in ~/lib and the puic binary in ~/bin</p>
+<p></p>
+<li></li>
+Reconfigure the Perl module so that it doesn't target the standard perl hierarchy:
+<pre>
+ cd PerlQt
+ perl Makefile.PL PREFIX=~
+ cd ..</pre>
+<p>Beware : this is not the same Makefile.PL as above, but the one located in the ./PerlQt
+subdirectory</p>
+<p></p>
+<li></li>
+Compile and Install
+<pre>
+ make &amp;&amp; make install</pre>
+<p>In order to use such an installation, you must tell to Perl where to find this extern hierarchy.
+This can be done either on the command line:</p>
+<pre>
+ perl -Mlib=&quot;~/local/lib/perl/5.x.x&quot; program.pl</pre>
+<p>or at the top of your program:</p>
+<pre>
+ use lib qw( ~/local/lib/perl/5.x.x );</pre>
+<p>``5.x.x'' should be changed to whatever Perl version your system is running.</p>
+<p></p></ul>
+<p>
+</p>
+<hr />
+<h1><a name="anatomy_of_perlqt">Anatomy of PerlQt</a></h1>
+<p>A typical Qt program using GUI components is based on an event loop.</p>
+<p>This basically means that such a program is no more envisioned as a straight
+flow where you would need to handle yourself every single events (such as a
+mouse click or a key press).</p>
+<p>Instead, you just create an <strong>Application</strong> object, create the GUI components it
+uses,
+define what objects methods need to be called when an event occurs,
+and then start the main event loop.</p>
+<p>That's all!
+Qt will handle all events and dispatch them to the correct subroutine.</p>
+<p>Lets see how this process is implemented in a minimal PerlQt program.</p>
+<p>
+</p>
+<h2><a name="hello_world">Hello World</a></h2>
+<pre>
+ 1: use Qt;
+ 2: my $a = Qt::Application(\@ARGV);
+ 3: my $hello = Qt::PushButton(&quot;Hello World!&quot;, undef);
+ 4: $hello-&gt;resize(160, 25);
+ 5: $a-&gt;setMainWidget($hello);
+ 6: $hello-&gt;show;
+ 7: exit $a-&gt;exec;</pre>
+<br/>
+<div class='image'><img src="../images/ex1.png"/></div><p>This program first loads the Qt interface [line 1] and creates the application
+object, passing it a reference to the command line arguments array <code>@ARGV</code>
+[l.2].
+This application object is unique, and may later be accessed from
+anywhere through the <strong>Qt::app()</strong> pointer.</p>
+<p>At line 3, we create a PushButton, which has no parent (i.e : it won't be
+contained nor owned by another widget).
+Therefore, we pass to the constructor an <strong>undef</strong> value for the parent argument,
+which is PerlQt's way of passing a Null pointer.</p>
+<p>After some layouting at [l.4], we tell the application object that our main
+widget is this PushButton [l.5]... that way, it will know that closing the
+window associated with this widget means : <em>quit the application</em>.</p>
+<p>Now the last steps are to make this widget visible (as opposed to
+hidden, which is the default) by calling the <strong>show</strong> method on it [l.6] and
+to start the application loop [l.7].</p>
+<p><strong>Syntax elements summary :</strong></p>
+<ol>
+<li></li>
+All Qt classes are accessed through the prefix <strong>Qt::</strong>, which replaces the 
+initial <strong>Q</strong> of Qt classes.
+When browsing the <a href="http://doc.trolltech.com">Qt documentation</a>, you simply need to change the
+name of classes so that <strong>QFoo</strong> reads <strong>Qt::Foo</strong>.
+<p></p>
+<li></li>
+An object is created by calling the <strong>constructor</strong> of the class. It has the 
+same name as the class itself.
+<p>You don't need to say <code>new Qt::Foo</code> or <code>Qt::Foo-&gt;new()</code> as most Perl
+programmers would have expected.</p>
+<p>Instead, you just say :</p>
+<pre>
+ my $object = Qt::&lt;classname&gt;(arg_1, ..., arg_n);</pre>
+<p>If you don't need to pass any argument to the constructor, simply say :</p>
+<pre>
+ my $object = Qt::&lt;classname&gt;;</pre>
+<p></p>
+<li></li>
+Whenever you need to pass a Null pointer as an argument, use Perl's <strong>undef</strong> 
+keyword. Do not pass zero.
+ Beware: this is by far the most common error in PerlQt programs.
+<p>Pointers are arguments preceded by an <strong>*</strong> 
+character in Qt's documentation (e.g: ``<code>QWidget * widget</code>'').</p>
+<p></p></ol>
+<p>
+</p>
+<h2><a name="inheritance_and_objects">Inheritance and Objects</a></h2>
+<p>Before we can discuss how Perl subroutines can be called back from Qt, we need
+to introduce PerlQt's inheritance mechanism.</p>
+<p>PerlQt was designed to couple as tightly as possible Qt's simplicity and Perl's 
+power and flexibility.</p>
+<p>In order to achieve that goal, the classical Object Oriented Perl paradigm had 
+to be extended, much in the same way than Qt itself
+had to extend C++'s paradigm with <strong>metaobjects</strong>.</p>
+<p>
+</p>
+<h3><a name="a_custom_widget">A Custom Widget</a></h3>
+<p>Lets rewrite the ``Hello World!'' program, this time using a custom version 
+of PushButton:</p>
+<pre>
+  1: use strict;
+  2: 
+  3: package Button;
+  4: use Qt;
+  5: use Qt::isa qw(Qt::PushButton);
+  6: 
+  7: sub NEW
+  8: {
+  9:   shift-&gt;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(&quot;Hello World!&quot;, undef);
+ 22: $a-&gt;setMainWidget($w);
+ 23: $w-&gt;show;
+ 24: exit $a-&gt;exec;</pre>
+<p>Here, we want to create our own version of the PushButton widget.
+Therefore, we create a new package for it [l.3] and import Qt [l.4].</p>
+<p>We now want to declare our widget as subclassing PushButton.
+This is done through the use of the <code>Qt::isa</code> pragma [l.5], which accepts a 
+list of one or more parent Qt classes.</p>
+<p>It is now time to create a <strong>constructor</strong> for our new widget.
+This is done by creating a subroutine called <strong>NEW</strong> <em>(note the capitalized 
+form, which differentate it from the usual ``new'' constructor. PerlQt's NEW 
+constructor is called </em><strong>implicitly</strong><em> as can be seen on line 21)</em>.</p>
+<p>Since we want our widget to call its parent's constructor first, we call the 
+<strong>superclass's constructor</strong> (here: Qt::PushButton) on line 9, passing it all 
+arguments we received.</p>
+<p>At this time, a class instance has been created and stored into a special 
+object holder named <strong>this</strong> (not <code>$this</code> but really just <code>this</code>).</p>
+<p>Each time you invoke a method from within your package, you may now 
+indifferently say <code>method()</code> or <code>this-&gt;method()</code>;</p>
+<p>
+</p>
+<h3><a name="using_attributes">Using Attributes</a></h3>
+<p>When building a new composite widget, you may just create its different 
+parts inside <strong>my</strong> variables, since widgets are only deleted by their parents 
+and not necessarily when their container goes out of scope.</p>
+<p>In other words, PerlQt performs clever reference counting to prevent 
+indesirable deletion of objects.</p>
+<p>Now, you'll often want to keep an access to those parts from anywhere inside 
+your package.
+For this purpose, you may use the <strong>this</strong> object's blessed hash, as is usual in Perl,
+but that isn't really convenient and you don't have any compile time
+checking...</p>
+<p>Here come <strong>Attributes</strong>. Attributes are data holders where you can 
+store any kind of properties for your object.</p>
+<p>Declaring new attributes is done through the <code>use Qt::attributes</code> pragma, as is 
+demonstrated in the following package implementation :</p>
+<pre>
+  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-&gt;SUPER::NEW(@_[0..2]);
+ 14:   itsTime = Qt::Time;
+ 15:   itsTime-&gt;start;   
+ 16:   pData = &quot; Foo &quot;;
+ 17: }
+ 18: 
+ 19: sub resizeEvent
+ 20: {
+ 21:    setText( &quot;w: &quot;. width() .&quot; h: &quot;. height() .
+ 22:             &quot;\nt: &quot;. itsTime-&gt;elapsed . pData );
+ 23: }
+ 24:
+ 25: 1;</pre>
+<br/>
+<div class='image'><img src="../images/ex2.png"/></div><p>An attribute itsTime is declared at line 7, and loaded with a <code>Qt::Time</code> object 
+at line 14.</p>
+<p>Since we reimplement the virtual function ``resizeEvent'' [l.19].
+each time the main widget is resized, this function will be triggered and 
+our Button's text updated with values coming from the object [l.21] and from the 
+attributes we defined [l.22].</p>
+<p><strong>Recapitulation</strong></p>
+<ul>
+<li></li>
+In order to inherit a Qt class, a package must contain a 
+<code>use Qt::isa</code> pragma.
+e.g:
+
+<pre>
+
+ use Qt::isa &quot;Qt::widget&quot;;</pre>
+<p></p>
+<li></li>
+The object constructor is named <strong>NEW</strong> and is implicitly called.
+Thus you should not say :
+<pre>
+ my $o = MyButton-&gt;NEW(&quot;Hello&quot;);</pre>
+<p>But say :</p>
+<pre>
+ my $o = MyButton(&quot;Hello&quot;);</pre>
+<p></p>
+<li></li>
+Within a package, the current instance can be accessed through the <strong>this</strong> 
+variable.
+<p>When a member function is called, arguments are loaded as usual in the <strong>@_</strong> 
+array, but <strong>without</strong> the object pointer itself.</p>
+<p>Hence, you shouldn't say :</p>
+<pre>
+ sub myMember
+ {
+   my $self = shift;
+   my $arg = shift;
+   $arg-&gt;doThat($self); 
+   $self-&gt;doIt;
+ }
+    
+But :</pre>
+<pre>
+ sub myMember
+ {
+   my $arg = shift;
+   $arg-&gt;doThat(this);
+   doIt;
+ }</pre>
+<p>Furthermore, if you want to call a base class method from a derived class,
+you'd use the specal attribute SUPER :</p>
+<pre>
+ sub example
+ {
+   print &quot;Now calling the base class\n&quot;;
+   SUPER-&gt;example(@_)
+ }</pre>
+<p>Note that the :</p>
+<pre>
+ this-&gt;SUPER::Example(@_);</pre>
+<p>construct is also available, but will pass the object as first argument.</p>
+<p></p>
+<li></li>
+Whenever you need to store a contained object in your package, you may define it 
+as an <strong>Attribute</strong> :
+<pre>
+ use Qt::attributes qw(
+        firstAttribute
+        ...
+        lastAttribute);</pre>
+<p>and then use it as a convenient accessor :</p>
+<pre>
+ firstAttribute = myContainedWidget( this );
+ firstAttribute-&gt;resize( 100, 100 );</pre>
+<p></p>
+<li></li>
+To reimplement a <strong>virtual function</strong>, simply create a <strong>sub</strong> with the 
+same name in your object.
+<p>Existing virtual functions are marked as such in Qt's documentation
+(they are prefixed with the ``virtual'' keyword).</p>
+<p>You can inspect what virtual function names are being called by Qt at runtime by
+putting a <code>use Qt::debug qw( virtual )</code> statement at the top of your program.</p>
+<p></p></ul>
+<p>
+</p>
+<h2><a name="signals_and_slots">Signals and Slots</a></h2>
+<p>We'll now learn how Qt objects can communicate with each other, 
+allowing an event occuring, for instance, in a given widget to trigger the 
+execution of one or several subroutines anywhere inside your program.</p>
+<p>Most other toolkits use callbacks for that purpose, but Qt has a much more 
+powerful and flexible mechanism called <strong>Signals and Slots</strong>.</p>
+<p>Signals and slots are used for communication between objects.</p>
+<p>This can be thought off as something similar to the wiring between several Hi-fI 
+components : an amplificator, for instance, has a set of output signals, wich are 
+emitted wether a listening device is connected to them or not. Also, a tape 
+recorder deck can start to record when it receives a signal wired to it's input 
+slot, and it doesn't need to know that this signal is also received by a CD 
+recorder device, or listened through headphones.</p>
+<p>A Qt component behaves just like that. It has several output <strong>Signals</strong> and 
+several input <strong>Slots</strong> - and each signal can be connected to an unlimited number 
+of listening slots of the same type, wether they are inside or outside the 
+component.</p>
+<p>The general syntax of this connection process is either :</p>
+<p>Qt::Object::connect( sender, SIGNAL 'mysignal(arg_type)', 
+receiver, SLOT 'myslot(arg_type)');</p>
+<p>or</p>
+<p>myObject-&gt;connect( sender, SIGNAL 'mysignal(arg_type)', SLOT 
+'myslot(arg_type)');</p>
+<p>This mechanism can be extended at will by the declaration of custom Signals and 
+Slots, through the <code>use Qt::signals</code> and <code>use Qt::slots</code> pragma
+(see also the other syntax, later on).</p>
+<p>Each declared slot will call the corresponding subroutine in your object, 
+each declared signal can be raised through the <strong>emit</strong> keyword.</p>
+<p><strong>As an example, lets rewrite again our Button package :</strong></p>
+<pre>
+  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:     wasClicked =&gt; [],
+  9:     change     =&gt; ['int', 'int'];
+ 10: use Qt::signals
+ 11:     changeIt   =&gt; ['int', 'int'];
+ 12:
+ 13: sub NEW
+ 14: {
+ 15:   shift-&gt;SUPER::NEW(@_[0..2]);
+ 16:   itsTime = Qt::Time;
+ 17:   itsTime-&gt;start;   
+ 18:   this-&gt;connect(this, SIGNAL 'clicked()', SLOT 'wasClicked()');
+ 19:   this-&gt;connect(this, SIGNAL 'changeIt(int,int)', SLOT 'change(int,int)');
+ 20: }
+ 21: 
+ 22: sub wasClicked
+ 23: {
+ 24:    my $w = width();
+ 25:    my $h = height();
+ 26:    setText( &quot;w: $w h: $h\nt: &quot;. itsTime-&gt;elapsed );
+ 27:    emit changeIt($w, $h);          
+ 28: }
+ 29:
+ 30: sub change
+ 31: {
+ 32:    my ($w, $h) = @_;
+ 33:    print STDERR &quot;w: $w h: $h \n&quot;;
+ 34: }
+ 35:
+ 36: 1;</pre>
+<p>In this package, we define two extra slots and one extra signal.</p>
+<p>We know from the Qt Documentation that a clicked PushButton emits a <code>clicked()</code> 
+signal, so we connect it to our new slot at line 18.</p>
+<p>We also connect our signal <code>changeIt</code> to our own <code>change</code> slot- which is 
+quite stupid, but as an example.</p>
+<p>Now, whenever our Button is clicked, the <code>clicked()</code> signal is raised and 
+triggers the <code>wasClicked()</code> slot. <code>wasClicked</code> then proceeds to emit 
+the <code>changeIt(int,int)</code> signal [l.27], hence triggering the <code>change(int,int)</code> 
+slot with two arguments.</p>
+<p>Finally, since PerlQt-3.008, an alternative syntax can be used to declare Signals and Slots:</p>
+<pre>
+ sub a_slot : SLOT(int, QString)
+ { 
+        $int = shift;
+        $string = shift;
+        # do something
+ }</pre>
+<p>and</p>
+<pre>
+ sub a_signal : SIGNAL(QString);</pre>
+<p>This syntax is perfectly compatible with the traditional
+<code>use Qt::signals</code> and <code>use Qt::slots</code> declarations.</p>
+<p>Eventually, it can prove good programming practice to mix both syntaxes, by first declaring  
+Signals/Slots with <code>use Qt::slots/signals</code>, then repeat this declaration
+in the actual implementation with the second syntax.</p>
+<p>Declarations will be checked for consistency at compile time, and any mismatch
+in arguments would trigger a warning.</p>
+<p>
+</p>
+<hr />
+<h1><a name="rad_prototyping_with_qt_designer_and_puic">RAD prototyping with Qt Designer and Puic</a></h1>
+<p>
+</p>
+<h2><a name="introduction">Introduction</a></h2>
+<ul>
+<li><strong><a name="item_note%3a">Note:</a></strong><br />
+</li>
+As of PerlQt-3.008, a separate PerlQt plugin for Qt Designer is available,
+bringing full integration, syntax highlighting, code completion and allowing to run/debug your PerlQt project
+entirely from the Designer GUI. 
+Nevertheless, the below is still accurate with regard to puic command line interaction 
+and with regard to using Qt Designer <em>without</em> the specific plugin.
+<p></p></ul>
+<p>As efficient and intuitive as Qt can be, building a complete GUI from scratch 
+is often a tedious task.</p>
+<p>Hopefully, Qt comes with a very sophisticated GUI Builder named Qt 
+Designer, which is close to a complete integrated development environment.
+It features Project management, drag'n drop GUI building, a complete object 
+browser, graphical interconnection of signals and slots, and much much more.</p>
+<p>Qt Designer's output is XML which can be parsed by several command line tools,
+among whose is <strong>puic</strong> (the PerlQt User Interface Compiler).</p>
+<p>Assuming you have already built an interface file with the Designer, 
+translating it to a PerlQt program is simply a matter of issuing 
+one command :</p>
+<pre>
+ puic -x -o program.pl program.ui</pre>
+<p>This will generate the package defined in your ui file and a basic main package 
+for testing purposes.</p>
+<p>You may prefer :</p>
+<pre>
+ puic -o package.pm program.ui</pre>
+<p>This will only generate the package, which can then be used by a separate 
+program.</p>
+<p>
+</p>
+<h2><a name="embedding_images">Embedding Images</a></h2>
+<p>If you need to <strong>embed images or icons</strong>, it can be done in two ways
+:</p>
+<ul>
+<li><strong><a name="item_inline_embedding">Inline embedding</a></strong><br />
+</li>
+For this, you need to check the ``Edit-&gt;Form Settings-&gt;Pixmaps-&gt;Save inline'' 
+checkbox inside Qt Designer.
+Then : puic -x -o <em>program.pl</em> <em>program.ui</em>
+<p></p>
+<li><strong><a name="item_image_collection">Image Collection</a></strong><br />
+</li>
+This option is more complex but also far more powerful and clean.
+<p>puic -o <em>Collection.pm</em> -embed <em>unique_identifier</em> <em>image-1</em> ... <em>image-n</em></p>
+<p>Then add a <code>use Collection.pm</code> statement to your program's main package.</p>
+<p>If you've created a project file in Qt Designer, and added all images 
+you want to group (through ``Project-&gt;Image Collection''), you'll find all those 
+images inside the directory where your project file (*.pro) is stored, under 
+/images.
+You can then generate the corresponding image collection by issuing :</p>
+<p>puic -o <em>Collection.pm</em> -embed <em>identifier</em> ../images/*</p>
+<p>You can use as many image collections as you want in a program. Simply add a 
+<strong>use</strong> statement for each collection.</p>
+<p></p></ul>
+<p>
+</p>
+<h2><a name="working_with_.ui_files">Working With <strong>.ui</strong> Files</a></h2>
+<p>It will often happen that you need to regenerate your user interface -either
+because you changed your initial design, or you want to extend it.
+Thus writing your program's code straight in the auto-generated Perl file is
+quite a bad idea.
+You'd run constantly the risk of overwriting your handcrafted code, or end
+up doing lot of copy-paste.</p>
+<p>Instead, you may :</p>
+<ul>
+<li><strong><a name="item_write_slots_implementation_in_the_designer">Write slots implementation in the Designer</a></strong><br />
+</li>
+In Qt Designer, select the <em>Source</em> tab of the <strong>Object Explorer</strong>.
+There you can see a tree-like representation of your classes.
+Now if you double-click on the <em>Slots/public</em> entry,
+you are prompted with a dialog where you can create a new custom slot for
+your module.
+Once this is done, the new slot appear inside the <strong>Object Explorer</strong> tree and
+clicking on it will bring you to a <strong>&lt;Your Class&gt;.ui.h</strong> file where you can write
+the actual implementation of your slot.
+<p>Keeping all the defaults, it should look like this :</p>
+<pre>
+ void Form1::newSlot()
+ {
+ 
+ }</pre>
+<p>The slot declaration is actually C++ code, but simply ignore it and write
+your Perl code straight between the two braces, paying special attention to
+indent it at least by one space.</p>
+<pre>
+ void Form1::newSlot()
+ {
+     print STDERR &quot;Hello world from Form1::newSlot();
+     if(this-&gt;foo())
+     {
+         # do something
+     }
+ }</pre>
+<p>All Perl code written this way will be saved to the ui.h file, and <strong>puic</strong> will take care of
+placing it back in the final program.</p>
+<p>Here, after running <strong>puic</strong> on the Form1.ui file, you'd have:</p>
+<pre>
+ sub newSlot
+ {
+     print STDERR &quot;Hello world from Form1::newSlot();
+     if(this-&gt;foo())
+     {
+         # do something
+     }
+ }</pre>
+<p></p>
+<li><strong><a name="item_subclassing_your_gui">Subclassing your GUI</a></strong><br />
+</li>
+By using <strong>puic</strong>'s <em>-subimpl</em> option, you may generate a derived module
+inheriting your original user interface.
+<p>You'd typically generate the derived module once, and write any handcrafted
+code in this child.
+Then, whenever you need to modify your GUI module, simply regenerate the
+parent module, and your child will inherit those changes.</p>
+<p>To generate the base module :</p>
+<pre>
+ puic -o Form1.pm form1.ui</pre>
+<p>(do this as often as needed, never edit by hand)</p>
+<p>To generate the child :</p>
+<pre>
+ puic -o Form2.pm -subimpl Form2 form1.ui</pre>
+<p>or</p>
+<pre>
+ puic -o program.pl -x -subimpl Form2 form1.ui</pre>
+<p>(do this once and work on the resulting file)</p>
+<p></p></ul>
+<p>
+</p>
+<hr />
+<h1><a name="more_development_tools">More development tools</a></h1>
+<p>PerlQt comes bundled with two simple programs that can help you to find your way through
+the Qt API:</p>
+<p>
+</p>
+<h2><a name="pqtapi">pqtapi</a></h2>
+<p>pqtapi is a commandline driven introspection tool.</p>
+<pre>
+ usage: pqtapi [-r &lt;re&gt;] [&lt;class&gt;]</pre>
+<pre>
+ options:
+        -r &lt;re&gt; : find all functions matching regular expression/keyword &lt;re&gt;
+        -i : together with -r, performs a case insensitive search
+        -v : print PerlQt and Qt versions
+        -h : print this help message</pre>
+<p>e.g:</p>
+<pre>
+ $&gt;pqtapi -ir 'setpoint.* int'
+        void QCanvasLine::setPoints(int, int, int, int)
+        void QPointArray::setPoint(uint, int, int)</pre>
+<p>
+</p>
+<h2><a name="pqtsh">pqtsh</a></h2>
+<p><strong>pqtsh</strong> is a graphical shell that can be used to test the API interactively.
+It is fairly self explanatory and includes an interactive example (<code>Help-&gt;Example</code>)</p>
+<br/>
+<div class='image'><img src="../images/pqtsh.png"/></div><p>
+</p>
+<hr />
+<h1><a name="known_limitations">Known Limitations</a></h1>
+<p>Templated classes aren't available yet (classes derived from templated classes are).</p>
+<p>
+</p>
+<hr />
+<h1><a name="credits">Credits</a></h1>
+<p>PerlQt-3 is (c) 2002 Ashley Winters (and (c) 2003 Germain Garand)</p>
+<p>Kalyptus and the Smoke generation engine are (c) David Faure and Richard Dale</p>
+<p>Puic is (c) TrollTech AS., Phil Thompson and Germain Garand,</p>
+<p>The mentioned software is released under the GNU Public Licence v.2 or later.</p>
+<p>
+</p>
+<hr />
+<h1><a name="appendix_1_:_c++_conventions_and_their_perl_counterpart">Appendix 1 : C++ conventions and their Perl counterpart</a></h1>
+<p>Whenever you want to use a class/method described in Qt's
+<a href="http://doc.trolltech.com">documentation</a> (see also the 'assistant' program bundled with Qt)
+from PerlQt, you need to follow some simple translation rules.</p>
+<dl>
+<dt><strong><a name="item_classnames">Classnames</a></strong><br />
+</dt>
+<ul>
+<li></li>
+All classnames are changed from a <strong>Q</strong> prefix in Qt to a <strong>Qt::</strong> prefix
+in Perl.
+e.g: QComboBox is named Qt::ComboBox within PerlQt.
+<p></p></ul>
+<dt><strong><a name="item_functions">Functions</a></strong><br />
+</dt>
+<ul>
+<li></li>
+Functions referenced as <strong>static</strong> are accessed directly, and not through
+an object. Thus the static function Foo in class QBar would be accessed from
+PerlQt as
+<pre>
+ Qt::Bar::Foo( arg-1,...,arg-n);</pre>
+<p>The only notable exceptions are :</p>
+<pre>
+ qApp()     will map to Qt::app()
+ qVersion() will map to Qt::version() # not really needed anymore: we have qVersion(). See Global Functions below.</pre>
+<p></p>
+<li></li>
+Functions referenced as <strong>members</strong> or <strong>Signals</strong> are accessed through an object
+with the <strong>-&gt;</strong> operator.
+e.g:
+<pre>
+ $widget-&gt;show;</pre>
+<p>There are no fundamental differences between methods and signals, however PerlQt 
+provides the <strong>emit</strong> keyword as a convenient mnemonic, so that it is clear you 
+are emitting a signal :</p>
+<pre>
+ emit $button-&gt;clicked;</pre>
+<p></p></ul>
+<dt><strong><a name="item_arguments">Arguments</a></strong><br />
+</dt>
+<ul>
+<li><strong><a name="item_by_value">By value</a></strong><br />
+</li>
+When an argument isn't preceded by the <strong>&amp;</strong> or <strong>*</strong> character, it is passed by 
+value. For all basic types such as int, char, float and double, PerlQt will 
+automatically convert litteral and scalar values to the corresponding C++ type.
+<p>Thus for a constructor prototype written as follow in the documentation :</p>
+<pre>
+ QSize ( int w, int h )</pre>
+<p>You'd say :</p>
+<pre>
+ Qt::Size(8, 12);</pre>
+<p></p>
+<li><strong><a name="item_by_reference">By reference</a></strong><br />
+</li>
+When an argument is preceded by the <strong>&amp;</strong> character, it means a reference to an 
+object or to a type is expected. You may either provide a variable name or a 
+temporary object :
+<pre>
+ $keyseq = Qt::keySequence( &amp;Qt::CTRL + &amp;Qt::F3 );
+ $widget-&gt;setAccel( $keyseq );
+ 
+or</pre>
+<pre>
+ $widget-&gt;setAccel(Qt::keySequence( &amp;Qt::CTRL + &amp;Qt::F3 );</pre>
+<p>If the argument isn't qualified as <strong>const</strong> (constant), it means the passed
+object may be altered during the process - you must then provide a variable.</p>
+<p></p>
+<li><strong><a name="item_by_pointer">By pointer</a></strong><br />
+</li>
+When an argument is preceded by the <strong>*</strong> character, it means a 
+pointer to an object or to a type is expected. You may provide a variable 
+name or the Perl <strong>undef</strong> keyword for a Null pointer.
+<p>Similarly, if the argument isn't <strong>const</strong>, the passed object may be altered by
+the method call.</p>
+<p></p></ul>
+<dt><strong><a name="item_enumerations">Enumerations</a></strong><br />
+</dt>
+<dd>
+Enumerations are sort of named aliases for numeric values that would be hard to
+remember otherwise.
+</dd>
+<dd>
+<p>A C++ example would be :</p>
+</dd>
+<dd>
+<pre>
+ enum Strange { Apple, Orange, Lemon }</pre>
+</dd>
+<dd>
+<p>where <code>Strange</code> is the generic enumeration name, and <code>Apple</code>, <code>Orange</code>,
+<code>Lemon</code> its possible values, which are only aliases for numbers (here 0, 1
+and 2).</p>
+</dd>
+<dd>
+<p>Access to enumerations values in Perl Qt is very similar to a static function
+call. In fact, it <strong>is</strong> a static function call.</p>
+</dd>
+<dd>
+<p>Therefore, since you probably want to avoid some readability problems, we
+recommend the use of the alternate function call syntax : <code>&amp;function</code>.</p>
+</dd>
+<dd>
+<p>Lets now go back to our <code>Strange</code> example.</p>
+</dd>
+<dd>
+<p>If its definition was encountered in the class <code>QFruits</code>, you'd write from
+PerlQt :</p>
+</dd>
+<dd>
+<pre>
+ $apple_plus_orange = &amp;Qt::Fruit::Apple + &amp;Qt::Fruit::Orange;</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_operators">Operators</a></strong><br />
+</dt>
+<dd>
+Within PerlQt, <strong>operators overloading</strong> works transparently.
+If a given operator is overloaded in a Qt class (which means using it triggers a custom method)
+it will behave identically in PerlQt.
+Beware though that due to limitations of the Smoke binding library, not all overloaded operators are
+available in PerlQt.
+You can check the availability of a given operator by using the pqtapi program.
+Also, due to outstanding differences between C++'s and Perl's object paradigm, the copy constructor operator (a.k.a '=')
+has been disabled.
+</dd>
+<dd>
+<p>e.g-1: '+=' overload</p>
+</dd>
+<dd>
+<pre>
+ $p1 = Qt::Point(10, 10)
+ $p2 = Qt::Point(30,40)
+ $p2 += $p1; # $p2 becomes (40,50)
+ 
+e.g-2: '&lt;&lt;' overload</pre>
+</dd>
+<dd>
+<pre>
+ $f = Qt::File(&quot;example&quot;);
+ $f-&gt;open( IO_WriteOnly ); # see 'Constants' below
+ $s = Qt::TextStream( $f );
+ $s &lt;&lt; &quot;What can I do with &quot; &lt;&lt; 12 &lt;&lt; &quot; apples?&quot;;</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_constants">Constants</a></strong><br />
+</dt>
+<dd>
+Qt doesn't use many constants, but there is at least one place where they are used : for setting 
+Input/Output flags on files.
+In order to avoid the namespace pollution induced by global constants, PerlQt group them in the <strong>Qt::constants</strong> module.
+For instance, requesting the importation of all IO constants into the current namespace would be done with:
+</dd>
+<dd>
+<pre>
+ use Qt::constants;</pre>
+</dd>
+<dd>
+<p>You may also import specific symbols:</p>
+</dd>
+<dd>
+<pre>
+ use Qt::constants qw( IO_ReadOnly IO_WriteOnly );</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_global_functions">Global Functions</a></strong><br />
+</dt>
+<dd>
+Qt has also some utilitarian functions such as bitBlt, qCompress, etc.
+</dd>
+<dd>
+<p>Those were global scope functions and have been grouped in a common namespace:
+<code>Qt::GlobalSpace</code>.</p>
+</dd>
+<dd>
+<p>Hence, you shall access this namespace either with a fully qualified call:</p>
+</dd>
+<dd>
+<pre>
+ Qt::GlobalSpace::qUncompress( $buffer )</pre>
+</dd>
+<dd>
+<p>Or directly, after importation in the current namespace:</p>
+</dd>
+<dd>
+<pre>
+ use Qt::GlobalSpace;
+ qUncompress( $buffer )</pre>
+</dd>
+<dd>
+<p>Of course, you may selectively import a few functions:</p>
+</dd>
+<dd>
+<pre>
+ use Qt::GlobalSpace qw( qUncompress bitBlt )</pre>
+</dd>
+<dd>
+<p><strong>Note:</strong> GlobalSpace has also operators, such has the one performing an addition on two
+Qt::Point(). Those operators are called automatically.</p>
+</dd>
+<dd>
+<p>e.g:</p>
+</dd>
+<dd>
+<pre>
+ $p1 = Qt::Point(10, 10) + Qt::Point(20, 20)</pre>
+</dd>
+<p></p></dl>
+<p>
+</p>
+<hr />
+<h1><a name="appendix_2_:_internationalization">Appendix 2 : Internationalization</a></h1>
+<p>PerlQt handles internationalization by always converting <strong>QString</strong> back to <strong>utf8</strong> in Perl.</p>
+<p>Conversions from Perl strings to QStrings are made according to context :</p>
+<ul>
+<li><strong><a name="item_if_the_perl_string_is_already_utf8%2dencoded">If the Perl string is already utf8-encoded</a></strong><br />
+</li>
+then the string will be converted straight to QString.
+<p>This is the most convenient and seemless way of internationalizing your application. Typically, one would just enable
+the use of utf8 in source code with the <code>use utf8</code> pragma and write its application with an utf8 aware editor.</p>
+<p></p>
+<li><strong><a name="item_if_the_string_isn%27t_tagged_as_utf8%2c_and_the_us">If the string isn't tagged as utf8, and the <strong>use locale</strong> pragma is not set</a></strong><br />
+</li>
+then the string will be converted to QString's utf8 from <strong>ISO-Latin-1</strong>.
+<p></p>
+<li><strong><a name="item_if_the_string_isn%27t_tagged_as_utf8_and_the_use_l">If the string isn't tagged as utf8 and the <strong>use locale</strong> pragma is set</a></strong><br />
+</li>
+then the string will be converted to QString's utf8 according to the currently set <strong>locale</strong>.
+<p></p></ul>
+<p>Once a string contains utf8, you can convert it back to any locale by setting up <strong>converters</strong> :</p>
+<pre>
+ $tr1=Qt::TextCodec::codecForLocale(); # this one will use current locale
+ $tr2=Qt::TextCodec::codecForName(&quot;KOI8-R&quot;); # that one forces a specific locale (Russian)</pre>
+<pre>
+ print $tr1-&gt;fromUnicode(Qt::DateTime::currentDateTime()-&gt;toString).&quot;\n\n&quot;;
+ print $tr2-&gt;fromUnicode($my_utf8_string);</pre>
+<p>Or, with Perl &gt;= 5.8.0, you may use Perl's <strong>Encode</strong> modules (see <code>perldoc Encode</code>).</p>
+<p>
+</p>
+<h3><a name="disabling_utf8">disabling utf-8</a></h3>
+<p>Developers who don't want to use UTF-8 or want to temporarily disable UTF-8 marshalling
+for handling legacy programs may use the <strong>use bytes</strong> pragma (and the corresponding <strong>no bytes</strong>).</p>
+<p>Within the scope of this pragma, QStrings are marshalled back to ISO-Latin1 (default) or to your locale
+(if <strong>use locale</strong> has been set).</p>
+<p>Frivole use of this pragma is strongly discouraged as it ruins worldwide standardization efforts.</p>
+<p>
+</p>
+<hr />
+<h1><a name="appendix_3_:_debugging_channels">Appendix 3 : Debugging Channels</a></h1>
+<p>The <strong>Qt::debug</strong> module offers various debugging channels/features.</p>
+<pre>
+ use Qt::debug;</pre>
+<pre>
+ use Qt::debug qw|calls autoload verbose|;</pre>
+<p>With the simple <code>use Qt::debug</code> statement, the <strong>verbose</strong> and <strong>ambiguous</strong> channels are activated.
+If you specify a list of channels within the use statement, then only the specified channels will be enabled.</p>
+<p><strong>Available channels :</strong></p>
+<ul>
+<li><strong><a name="item_ambiguous">ambiguous</a></strong><br />
+</li>
+Check if method and function calls are ambiguous, and tell which of the alternatives
+was finally elected.
+<p></p>
+<li><strong><a name="item_verbose">verbose</a></strong><br />
+</li>
+Enable more verbose debugging.
+<p>Together with <strong>ambiguous</strong>, tell you the nearest matches in case
+a method or function call fails.
+e.g:</p>
+<pre>
+ use Qt;
+ use Qt::debug;
+ $a= Qt::Application(\@ARGV);
+ $a-&gt;libraryPath(&quot;foo&quot;);</pre>
+<pre>
+ --- No method to call for :
+        QApplication::libraryPath('foo')
+ Closer candidates are :
+        static void QApplication::addLibraryPath(const QString&amp;)
+        static QStringList QApplication::libraryPaths()
+        static void QApplication::removeLibraryPath(const QString&amp;)
+        static void QApplication::setLibraryPaths(const QStringList&amp;)</pre>
+<p></p>
+<li><strong><a name="item_calls">calls</a></strong><br />
+</li>
+For every call, tell what corresponding Qt method is called
+(detailing the arguments if <strong>verbose</strong> is on).
+<p></p>
+<li><strong><a name="item_autoload">autoload</a></strong><br />
+</li>
+Track the intermediate code between a method invocation in Perl
+and its resolution to either a Qt or Perl call.
+<p></p>
+<li><strong><a name="item_gc">gc</a></strong><br />
+</li>
+Give informations about garbage collection
+whenever a Qt object is deleted and/or a Perl object is destroyed
+<p></p>
+<li><strong><a name="item_virtual">virtual</a></strong><br />
+</li>
+Report whenever a virtual function tries to access its Perl
+reimplementation (wether it exists or not).
+<p></p>
+<li><strong><a name="item_all">all</a></strong><br />
+</li>
+Enable all channels
+<p></p></ul>
+<p>
+</p>
+<hr />
+<h1><a name="appendix_4_:_marshallers">Appendix 4 : Marshallers</a></h1>
+<p>A marshaller is a piece of ``glue code'' translating a given datatype to another.</p>
+<p>Within PerlQt, most Qt objects keep their object nature, so that one may invoke methods on them.
+However, some classes and datatypes map so naturally to some Perl types that keeping their object nature would
+would feel unnatural and clumsy.</p>
+<p>For instance, instead of returning a Qt::StringList object, which would require an iterator to retrieve its content,
+PerlQt will translate it to an array reference containing all the object's strings.</p>
+<p>In the other way, instead of providing a Qt::StringList object as an argument of a method, one would simply
+provide the reference to an array of Perl strings.</p>
+<p>Here is the list of Marshallers as of PerlQt-3.008 :</p>
+<pre>
+ -----------------------------------------------------------------
+ float, double                         &lt;=&gt;       Perl real (NV)
+ char, uchar, int, uint, enum
+ long, ulong, short, ushort            &lt;=&gt;       Perl integer (IV)
+ QString, -&amp;, -*                        =&gt;       Perl string (utf8)
+ QString, -&amp;, -*                       &lt;=        Perl string (utf8 or iso-latin1 or locale)
+ QCString, -&amp;, -*                      &lt;=&gt;       Perl string (utf8 or bytes, according to content or &quot;bytes&quot; pragma)
+ QByteArray, -&amp;, -*                    &lt;=&gt;       Perl string (bytes)
+ QStringList, -&amp;, -*                    =&gt;       Reference to an array of Perl strings (utf8)
+ QString, -&amp;, -*                        =&gt;       Perl string (utf8 or iso-latin1 or locale)
+ int&amp;, -*                              &lt;=&gt;       Perl integer (IV)
+ bool&amp;, -*                             &lt;=&gt;       Perl boolean
+ char*                                 &lt;=&gt;       Perl string (bytes)
+ char**                                &lt;=        Reference to an array of Perl strings (bytes)
+ uchar*                                &lt;=        Perl string (bytes)
+ QRgb*                                 &lt;=        Reference to an array of Perl integers (IV)
+ QCOORD*                               &lt;=        Reference to an array of Perl integers (IV)
+ void*                                 &lt;=&gt;       Reference to a Perl integer (IV)
+ QValueList&lt;int&gt;, - *, - &amp;             &lt;=&gt;       Reference to an array of Perl integers (IV)
+ QCanvasItemList, - *, - &amp;              =&gt;       Reference to an array of Qt::CanvasItem
+ QWidgetList, - *, - &amp;                 &lt;=&gt;       Reference to an array of Qt::Widget
+ QObjectList, - *, - &amp;                 &lt;=&gt;       Reference to an array of Qt::Object
+ QFileInfoList, - *, - &amp;               &lt;=&gt;       Reference to an array of Qt::FileInfo
+ QPtrList&lt;QTab&gt;, - *, - &amp;              &lt;=&gt;       Reference to an array of Qt::Tab
+ QPtrList&lt;QToolBar&gt;, - *, - &amp;          &lt;=&gt;       Reference to an array of Qt::ToolBar
+ QPtrList&lt;QNetworkOperation&gt;, - *, - &amp; &lt;=&gt;       Reference to an array of Qt::NetworkOperation
+ QPtrList&lt;QDockWindow&gt;, - *, - &amp;       &lt;=&gt;       Reference to an array of Qt::DockWindow
+ (QUObject*)
+
+</pre>
+
+</body>
+
+</html>
diff --git a/doc/fr/Makefile b/doc/fr/Makefile
new file mode 100644
index 0000000..1d300c0
--- /dev/null
+++ b/doc/fr/Makefile
@@ -0,0 +1,7 @@
+
+index.html: PerlQt.pod
+	pod2html --css ../css/pod.css PerlQt.pod > index.html
+	perl -pi -e 's/cgibin/cgi-bin/' index.html
+	perl -pi -e 's/#http/http/g' index.html
+	rm -f pod2*~~
+
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 à <germain@ebooksfrance.com> ou le traducteur à
+<stef@mongueurs.net>.  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*)
+
diff --git a/doc/fr/index.html b/doc/fr/index.html
new file mode 100644
index 0000000..2f5e788
--- /dev/null
+++ b/doc/fr/index.html
@@ -0,0 +1,1120 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>Programmer avec PerlQt</title>
+<link rel="stylesheet" href="../css/pod.css" type="text/css" />
+<link rev="made" href="mailto:root@localhost" />
+</head>
+
+<body>
+
+<p><a name="__index__"></a></p>
+<!-- INDEX BEGIN -->
+
+<ul>
+
+	<li><a href="#programmer_avec_perlqt">Programmer avec PerlQt</a></li>
+	<li><a href="#introduction">Introduction</a></li>
+	<li><a href="#installation">Installation</a></li>
+	<ul>
+
+		<li><a href="#conditions_requises">Conditions requises</a></li>
+		<li><a href="#compilation_de_perlqt">Compilation de PerlQt</a></li>
+		<li><a href="#installation_avec_les_droits_d'utilisateur">Installation avec les droits d'utilisateur</a></li>
+	</ul>
+
+	<li><a href="#anatomie_de_perlqt">Anatomie de PerlQt</a></li>
+	<ul>
+
+		<li><a href="#hello_world">Hello World</a></li>
+		<li><a href="#l'héritage_et_les_objets">L'héritage et les objets</a></li>
+		<ul>
+
+			<li><a href="#un_widget_personnalisé">Un Widget personnalisé</a></li>
+			<li><a href="#l'utilisation_d'attributs">L'utilisation d'attributs</a></li>
+		</ul>
+
+		<li><a href="#signaux_et_slots">Signaux et Slots</a></li>
+	</ul>
+
+	<li><a href="#développement_rapide_(rad)_avec_qt_designer_et_puic">Développement rapide (RAD) avec Qt Designer et Puic</a></li>
+	<ul>
+
+		<li><a href="#introduction">Introduction</a></li>
+		<li><a href="#inclure_des_images">Inclure des Images</a></li>
+		<li><a href="#travailler_avec_des_fichiers_.ui">Travailler avec des fichiers <strong>.ui</strong></a></li>
+	</ul>
+
+	<li><a href="#autres_outils_de_développement">Autres outils de développement</a></li>
+	<ul>
+
+		<li><a href="#pqtapi">pqtapi</a></li>
+		<li><a href="#pqtsh">pqtsh</a></li>
+	</ul>
+
+	<li><a href="#limitations">Limitations</a></li>
+	<li><a href="#crédits">Crédits</a></li>
+	<li><a href="#appendice:_les_conventions_de_c++_et_leur_traduction_en_perl">Appendice: Les conventions de C++ et leur traduction en Perl</a></li>
+	<li><a href="#annexe_2_:_internationalisation">Annexe 2 : Internationalisation</a></li>
+	<ul>
+
+		<ul>
+
+			<li><a href="#désactiver_l'encodage_utf8">désactiver l'encodage utf8</a></li>
+		</ul>
+
+	</ul>
+
+	<li><a href="#annexe_3_:_canaux_de_déboguage">Annexe 3 : Canaux de déboguage</a></li>
+	<li><a href="#annexe_4_:_marshalleurs">Annexe 4 : Marshalleurs</a></li>
+</ul>
+<!-- INDEX END -->
+
+<hr />
+<p>
+</p>
+<h1><a name="programmer_avec_perlqt">Programmer avec PerlQt</a></h1>
+<p><strong>Germain Garand</strong> traduit par <strong>Stéphane Payrard</strong>, révisé et augmenté par l'auteur.</p>
+<p>Ce document décrit l'interface Perl au toolkit Qt 3.x. Contacter
+l'auteur à &lt;<a href="mailto:germain@ebooksfrance.com">germain@ebooksfrance.com</a>&gt; ou le traducteur à
+&lt;<a href="mailto:stef@mongueurs.net">stef@mongueurs.net</a>&gt;.  Vous trouverez le document original sur le site
+<a href="http://perlqt.sourceforge.net">perlqt.sourceforge.net</a></p>
+<p>
+</p>
+<hr />
+<h1><a name="introduction">Introduction</a></h1>
+<p>PerlQt-3, crée par Ashley Winters, est une interface perl aux composants
+graphiques (et non graphiques) fournis par Qt3.</p>
+<p>Le toolkit Qt 3.0 auquel PerlQt accède à été écrit en C++ par la société
+Trolltech: <a href="http://www.trolltech.com">Trolltech</a>.</p>
+<p>PerlQt3 est fondé sur la librairie
+<a href="http://webcvs.kde.org/cgi-bin/cvsweb.cgi/kdebindings/smoke">SMOKE</a>,
+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
+<a href="http://webcvs.kde.org/cgi-bin/cvsweb.cgi/kdebindings/kalyptus">kalyptus</a>
+de Richard Dale grâce au module de David Faure.</p>
+<p>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 <a href="http://doc.trolltech.com">manuels en ligne de Qt</a>. Ladite documentation est
+la seule référence qui fasse autorité.</p>
+<p>Si Qt est installé sur votre système, sa documentation l'est 
+certainement aussi : voyez le programme $QTDIR/bin/assistant.</p>
+<p>
+</p>
+<hr />
+<h1><a name="installation">Installation</a></h1>
+<p>
+</p>
+<h2><a name="conditions_requises">Conditions requises</a></h2>
+<p>Pour compiler et utiliser PerlQt, vous devez avoir:</p>
+<ul>
+<li></li>
+un système conforme à la norme POSIX.
+<p></p>
+<li></li>
+<a href="http://www.perl.org">Perl &gt;= v5.6.0</a>
+<p></p>
+<li></li>
+<a href="http://www.trolltech.com/developer/download/qtx11.html">Qt &gt;= v3.0</a>
+<p></p>
+<li></li>
+<a href="http://webcvs.kde.org/cgi-bin/cvsweb.cgi/kdebindings/smoke">SmokeQt 1.2.1</a> La
+librarie SMOKE  (Scripting Meta Object Kompiler) fait partie du module
+<a href="http://www.kde.org">KDE</a>'s <strong>kdebindings</strong>.  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.
+<p></p>
+<li></li>
+Les outils GNU : automake(&gt;=1.5), autoconf (&gt;=2.13), aclocal...
+<p></p></ul>
+<p>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.</p>
+<p>
+</p>
+<h2><a name="compilation_de_perlqt">Compilation de PerlQt</a></h2>
+<p>Les instructions de cette section présupposent que le répertoire courant est 
+le répertoire racine de l'arborescence des sources de PerlQt.</p>
+<p>PerlQt utilise le système GNU Autoconf, mais il est préférable de le lancer via
+le script standard <code>Makefile.PL</code> :</p>
+<pre>
+ perl Makefile.PL</pre>
+<p><strong>N.B :</strong> Si la variable d'environnement <strong>QTDIR</strong> n'est pas définie, vous devrez
+peut-être spécifier manuellement l'emplacement de Qt à l'aide de l'option :</p>
+<pre>
+ --with-qtdir=/emplacement/de/Qt</pre>
+<p>Si la bibliothèque SMOKE est manquante, <code>configure</code> générera ses sources dans
+un sous-répertoire.</p>
+<pre>
+ make</pre>
+<pre>
+ make install</pre>
+<p>Cela installera PerlQt, Puic et les utilitaires pqtsh et pqtapi.</p>
+<p>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 <code>--prefix</code> de <code>configure</code>'s. Ainsi :</p>
+<pre>
+ perl Makefile.PL --prefix=/usr</pre>
+<p>
+</p>
+<h2><a name="installation_avec_les_droits_d'utilisateur">Installation avec les droits d'utilisateur</a></h2>
+<p>Pour réaliser une installation locale, sans les droits de super-utilisateur,
+suivez les instructions suivantes :</p>
+<ul>
+<li></li>
+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 :
+<pre>
+ perl Makefile.PL --prefix=~</pre>
+<p>Ceci installera Smoke dans ~/lib et puic dans ~/bin</p>
+<p></p>
+<li></li>
+Reconfigurez le module PerlQt pour qu'il ne s'installe pas dans la hiérarchie Perl ordinaire :
+<pre>
+ cd PerlQt
+ perl Makefile.PL PREFIX=~
+ cd ..</pre>
+<p>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</p>
+<p></p>
+<li></li>
+Lancez la compilation et l'installation
+<pre>
+ make &amp;&amp; make install</pre>
+<p>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 :</p>
+<pre>
+ perl -Mlib=&quot;~/local/lib/perl/5.x.x&quot; programme.pl</pre>
+<p>où 5.x.x représente la version de Perl utilisée, ligne qui peut également être placée en tête de programme :</p>
+<pre>
+ use lib qw( ~/local/lib/perl/5.x.x );</pre>
+<p></p></ul>
+<p>
+</p>
+<hr />
+<h1><a name="anatomie_de_perlqt">Anatomie de PerlQt</a></h1>
+<p>Un programme Qt typique utilisant des composants GUI est fondé sur une
+boucle événementielle.</p>
+<p>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).</p>
+<p>Au lieu de cela, vous créez un objet <strong>Qt::Application</strong> 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.</p>
+<p>C'est tout. Qt gérera les événements et les dirigera vers les
+routines appropriées.</p>
+<p>Voyons un programme PerlQt minimal.</p>
+<p>
+</p>
+<h2><a name="hello_world">Hello World</a></h2>
+<pre>
+ 1: use Qt;
+ 2: my $a = Qt::Application(\@ARGV);
+ 3: my $hello = Qt::PushButton(&quot;Hello World!&quot;, undef);
+ 4: $hello-&gt;resize(160, 25);
+ 5: $a-&gt;setMainWidget($hello);
+ 6: $hello-&gt;show;
+ 7: exit $a-&gt;exec;</pre>
+<br/>
+<div class='image'><img src="../images/ex1.png"/></div><p>Ce programme charge d'abord le module Qt [line 1] puis crée l'objet
+application <strong>$a</strong>  en lui passant une référence au tableau <code>@ARGV</code>
+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 <strong>Qt::app()</strong>.</p>
+<p>La ligne 3, crée un PushButton orphelin (c.à.d sans parent: non
+contenu dans un autre widget) dont nous passons la valeur <strong>undef</strong>
+comme argument pour le parent. <strong>undef</strong> est l'équivalent perlQt d'un
+pointeur null en C++.</p>
+<p>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: <em>sortir de l'application</em>.</p>
+<p>Pour rendre ce widget visible (qui est par défaut caché), on
+appelle la méthode <strong>show</strong> [l.6] et lance la boucle
+événementielle [l.7].</p>
+<p><strong>Sommaire de la syntaxe :</strong></p>
+<ol>
+<li></li>
+Les classes PerlQt sont accessibles par le préfixe <strong>Qt::</strong> au lieu du
+<strong>Q</strong> initial des classes Qt en C++.  En consultant la <a href="http://doc.trolltech.com">documentation Qt</a>, vous devez donc mentalement changer le
+nom d'une clasee <strong>QFoo</strong> en <strong>Qt::Foo</strong>.
+<p></p>
+<li></li>
+De manière similaire à C++, un objet est créé par l'appel d'un
+<strong>constructeur</strong> de même nom que la classe dont il est une méthode.
+<p>Vous ne devez donc pas dire <code>new Qt::Foo</code> ou <code>Qt::Foo-&gt;new()</code>
+contrairement à l'usage commun en Perl.</p>
+<p>Dites simplement:</p>
+<pre>
+ my $object = Qt::&lt;classname&gt;(arg_1, ..., arg_n);</pre>
+<p>Un constructeur sans argument s'énonce encore plus brièvement :</p>
+<pre>
+ my $object = Qt::&lt;classname&gt;;</pre>
+<p></p>
+<li></li>
+Comme il a déjà été dit, l'équivalent Perl d'un pointeur C++ est le mot-clé
+Perl <strong>undef</strong>.
+<p>Les pointeurs sont les arguments précédés par le caractère <strong>*</strong> dans la
+documentation Qt (Par exemple: ``<code>QWidget* widget</code>'').</p>
+<p></p></ol>
+<p>
+</p>
+<h2><a name="l'héritage_et_les_objets">L'héritage et les objets</a></h2>
+<p>Avant d'expliquer comment les routines Perl peuvent être appelées de Qt,
+parlons du mécanisme d'héritage vu de PerlQt.</p>
+<p>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 <strong>métaobjets</strong>.</p>
+<p>
+</p>
+<h3><a name="un_widget_personnalisé">Un Widget personnalisé</a></h3>
+<p>Réécrivons le programme ``Hello World!'' avec une version personnalisée
+de PushButton:</p>
+<pre>
+  1: use strict;
+  2:
+  3: package Button;
+  4: use Qt;
+  5: use Qt::isa qw(Qt::PushButton);
+  6:
+  7: sub NEW
+  8: {
+  9:   shift-&gt;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(&quot;Hello World!&quot;, undef);
+ 22: $a-&gt;setMainWidget($w);
+ 23: $w-&gt;show;
+ 24: exit $a-&gt;exec;</pre>
+<p>Pour implanter notre propre version de PushButton, nous créons un nouveau
+package [l.3] et importons  Qt [l.4].</p>
+<p>Nous utilisons le pragma <code>Qt::isa</code> [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.</p>
+<p>Créons maintenant un constructeur pour notre nouveau widget
+en écrivant une routine appelée <strong>NEW</strong> <em>(notez les majuscules qui
+marquent une méthode différente du constructeur ``new'' usuel)</em>.
+Le constructeur PerlQt est appelé <strong>implicitement</strong> <em>comme ligne 21</em>.</p>
+<p>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.</p>
+<p>Nous créons ainsi un objet instance de notre classe. Cette objet est
+accessible par la fonction <strong>this</strong> (Attention: ce n'est pas la
+variable <code>$this</code> mais simplement <code>this</code>).</p>
+<p>Chaque fois que nous invoquons une méthode à partir de notre package
+nous pouvons écrire indifféremment <code>method()</code> ou
+<code>this-&gt;method()</code>;</p>
+<p>
+</p>
+<h3><a name="l'utilisation_d'attributs">L'utilisation d'attributs</a></h3>
+<p>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 <strong>my</strong>) puisque les widgets sont seulement détruits
+par leur parent et non nécessairement quand leur conteneur disparaît
+du scope.</p>
+<p>En d'autres termes, PerlQt utilise un système de comptage de
+références pour gérer la destruction des objets.</p>
+<p>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.</p>
+<p>En lieu et place de cette syntaxe, PerlQt introduit le concept d'<strong>attributs</strong>.</p>
+<p>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.</p>
+<p>Pour définir et pouvoir utiliser de nouveaux attributs, il suffit d'utiliser
+le pragma <code>use Qt::attributes</code>, suivi d'une liste des noms d'attributs souhaités.
+Ainsi:</p>
+<pre>
+  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-&gt;SUPER::NEW(@_[0..2]);
+ 14:   itsTime = Qt::Time;
+ 15:   itsTime-&gt;start;
+ 16:   pData-&gt;{'key'} = &quot; Foo &quot;;
+ 17: }
+ 18:
+ 19: sub resizeEvent
+ 20: {
+ 21:    setText( &quot;w: &quot;. width() .&quot; h: &quot;. height() .
+ 22:             &quot;\nt: &quot;. itsTime-&gt;elapsed . pData-&gt;{'key'} );
+ 23: }
+ 24:
+ 25: 1;</pre>
+<br/>
+<div class='image'><img src="../images/ex2.png"/></div><p>L'attribut itsTime est déclaré à la ligne 7 et initialisé par un objet <code>Qt::Time</code>
+à la ligne 14.</p>
+<p>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].</p>
+<p><strong>Récapitulation</strong></p>
+<ul>
+<li></li>
+Pour hériter d'une classe Qt, un package doit contenir un
+pragma <code>use Qt::isa</code>.
+<p>Ainsi:</p>
+<pre>
+ use Qt::isa &quot;Qt::widget&quot;;</pre>
+<p></p>
+<li></li>
+Le constructeur d'objet est nommé <strong>NEW</strong> et est appelé implicitement.
+Vous ne devez donc pas dire:
+<pre>
+ my $o = MyButton-&gt;NEW(&quot;Hello&quot;);</pre>
+<p>Mais bien :</p>
+<pre>
+ my $o = MyButton(&quot;Hello&quot;);</pre>
+<p></p>
+<li></li>
+A l'intérieur d'un package, on accéde l'instance courante par la
+fonction <strong>this</strong>.
+<p>Quand une fonction membre est appelée, les arguments sont accessibles
+par le tableau <strong>@_</strong>, mais le premier élément de <strong>@_</strong> n'est pas une
+référence à l'objet contrairement à l'usage commun en Perl.</p>
+<p>Vous ne pouvez donc pas dire :</p>
+<pre>
+ sub myMember
+ {
+   my $moi = shift;
+   my $arg = shift;
+   $arg-&gt;doThat($moi);
+   $moi-&gt;doIt;
+ }</pre>
+<p>Écrivez plutôt :</p>
+<pre>
+ sub myMember
+ {
+   my $arg = shift;
+   $arg-&gt;doThat(this);
+   doIt();
+ }</pre>
+<p>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 :</p>
+<pre>
+ sub exemple
+ {
+   print &quot;Appel de la méthode 'exemple' dans la classe de base&quot;;
+   SUPER-&gt;exemple(@_)
+ }</pre>
+<p>Notez aussi que la construction :</p>
+<pre>
+ this-&gt;SUPER::Exemple(@_);</pre>
+<p>est possible, mais qu'elle passe l'objet comme premier argument.</p>
+<p></p>
+<li></li>
+Lorsque vous devez stocker dans votre package un objet contenu, vous
+devez le définir comme <strong>attribut</strong> :
+<pre>
+ use Qt::attributes qw(
+        firstAttribute
+        ...
+        lastAttribute);</pre>
+<p>Il sera alors disponible comme accesseur :</p>
+<pre>
+ firstAttribute = myContainedWidget( this );
+ firstAttribute-&gt;resize( 100, 100 );</pre>
+<p><strong>NB:</strong> 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 <strong>this</strong>, ce qui rend les tournures ``unAttribut-&gt;fonction()'' et
+``this-&gt;{'unAttribut'}-&gt;fonction()'' strictement équivalentes
+(si ce n'est que la première est vérifiée au moment de la compilation).</p>
+<p></p>
+<li></li>
+Pour réimplémenter une <strong>fonction virtuelle</strong>, créez simplement une
+<strong>sub</strong> de même nom que cette fonction.
+<p>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'').</p>
+<p>Vous pouvez visualiser les noms de méthodes virtuelles que Qt tentera d'appeler
+dans votre classe en plaçant <code>use Qt::debug qw|virtual|</code> en tête de 
+votre programme.</p>
+<p></p></ul>
+<p>
+</p>
+<h2><a name="signaux_et_slots">Signaux et Slots</a></h2>
+<p>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.</p>
+<p>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 <strong>Signaux et Slots</strong>.</p>
+<p>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.</p>
+<p>Un composant Qt se comporte comme notre amplificateur ou notre
+magnétophone. Il a des sorties ou <strong>Signaux</strong> et des entrées ou
+<strong>Slots</strong>. 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),</p>
+<p>La syntaxe de ce système de connexion est soit:</p>
+<p>Qt::Object::connect( envoyeur, SIGNAL 'mon_signal(types_d_arguments)',
+recepteur, SLOT 'monslot(types_d_arguments)');</p>
+<p>soit:</p>
+<p>unObjet-&gt;connect( envoyeur, SIGNAL 'mon_signal(types_d_arguments)',
+SLOT 'monslot(types_d_arguments)');</p>
+<p>Dans le second cas, le récepteur est omis car c'est l'objet lui-même,</p>
+<p>Ce mécanisme est extensible à volonté par la déclaration de nouveaux Signaux et
+Slots par l'usage des pragma <code>use Qt::signals</code> et <code>use Qt::slots</code>
+(voir aussi la deuxième syntaxe décrite plus bas).</p>
+<p>Chaque slot déclaré appellera la routine correspondante de votre
+objet. Chaque signal déclaré peut être déclenché via le mot-clé <strong>emit</strong>.</p>
+<p><strong>Réécrivons encore notre exemple pour illustrer nos propos :</strong></p>
+<pre>
+  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 =&gt; [],
+  9:     changement     =&gt; ['int', 'int'];
+ 10: use Qt::signals
+ 11:     changeLe   =&gt; ['int', 'int'];
+ 12:
+ 13: sub NEW
+ 14: {
+ 15:   shift-&gt;SUPER::NEW(@_[0..2]);
+ 16:   itsTime = Qt::Time;
+ 17:   itsTime-&gt;start;
+ 18:   this-&gt;connect(this, SIGNAL 'clicked()', SLOT 'aEteClicke()');
+ 19:   this-&gt;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( &quot;w: $w h: $h\nt: &quot;. itsTime-&gt;elapsed );
+ 27:    emit changeLe($w, $h);
+ 28: }
+ 29:
+ 30: sub changement
+ 31: {
+ 32:    my ($w, $h) = @_;
+ 33:    print STDERR &quot;w: $w h: $h \n&quot;;
+ 34: }
+ 35:
+ 36: 1;</pre>
+<p>Nous définissons dans ce package deux nouveaux slots et un nouveau signal.</p>
+<p>La documentation Qt nous dit que tout PushButton clické émet un signal
+<code>clicked()</code> ; nous le connectons donc à notre nouveau slot [ligne 18].</p>
+<p>Nous connectons aussi notre signal <code>ChangeLe</code> à notre slot
+<code>changement</code>.</p>
+<p>Ainsi, quand on appuie (clique) sur notre Button , le signal
+<code>clicked()</code> est émit et déclenche le slot  <code>aEteClicke()</code>.
+<code>aEteClicke()</code> émet à son tour le signal <code>changeLe(int,int)</code>[l.27],
+appelant de ce fait le slot <code>changement(int,int)</code>, avec deux arguments.</p>
+<p>Enfin, il existe une syntaxe alternative introduite dans PerlQt-3.008 :</p>
+<pre>
+ sub un_slot : SLOT(int, QString)
+ { 
+        $int = shift;
+        $string = shift;
+        # faire quelque chose
+ }</pre>
+<p>et</p>
+<pre>
+ sub un_signal : SIGNAL(QString);</pre>
+<p>Cette syntaxe est parfaitement compatible avec la déclaration par le biais de
+<code>use Qt::signals</code> et <code>use Qt::slots</code>. 
+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 <code>use Qt::slots/signals</code>, 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.</p>
+<p>
+</p>
+<hr />
+<h1><a name="développement_rapide_(rad)_avec_qt_designer_et_puic">Développement rapide (RAD) avec Qt Designer et Puic</a></h1>
+<p>
+</p>
+<h2><a name="introduction">Introduction</a></h2>
+<ul>
+<li><strong><a name="item_n%2eb%3a">N.B:</a></strong><br />
+</li>
+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 <em>sans</em> le plugin spécifique.
+<p></p></ul>
+<p>Aussi puissant et intuitif que soit Qt, écrire une GUI complète reste un exercice 
+fastidieux.</p>
+<p>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.</p>
+<p>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 <strong>puic</strong> (le
+compilateur d'interface utilisateur PerlQt).</p>
+<p>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 :</p>
+<pre>
+ puic -x -o program.pl program.ui</pre>
+<p>Cela génèrera le package défini dans votre fichier ui et un package
+principal à fins de test,</p>
+<p>Vous pouvez préférer :</p>
+<pre>
+ puic -o package.pm program.ui</pre>
+<p>Cela ne générera que le package qui pourra être utilisé par un programme séparé.</p>
+<p>
+</p>
+<h2><a name="inclure_des_images">Inclure des Images</a></h2>
+<p>Il y a deux manières d'inclure des <strong>images ou icônes</strong>:</p>
+<ul>
+<li><strong><a name="item_inclusion_inline">Inclusion Inline</a></strong><br />
+</li>
+A cette fin, nous devons sélectionner ``Edit-&gt;Form
+Settings-&gt;Pixmaps-&gt;Save inline'' dans Qt Designer et executer ensuite:
+<pre>
+  puic -x -o F&lt;program.pl&gt; F&lt;program.ui&gt;</pre>
+<p></p>
+<li><strong><a name="item_image_collection">Image Collection</a></strong><br />
+</li>
+Cette stratégie est plus complexe, mais plus propre et plus puissante.
+<pre>
+ puic -o F&lt;Collection.pm&gt; -embed F&lt;unique_identifier&gt; F&lt;image-1&gt; ... F&lt;image-n&gt;</pre>
+<p>Ajoutez l'instruction <code>use Collection.pm</code> dans le package principal
+de votre programme.</p>
+<p>Si vous avez créé un fichier projet dans Qt Designer et ajouté toutes
+les images dans un groupe (par ``Project-&gt;Image Collection''), vous
+disposez ensuite de ces images dans le répertoire où votre fichier
+projet (*.pro) est stocké, dans le sous-répertoire <strong>image</strong>. Vous pouvez
+alors générer la collection d'images par:</p>
+<pre>
+ puic -o F&lt;Collection.pm&gt; -embed F&lt;identifier&gt; images/*</pre>
+<p>Vous pouvez utiliser autant de collections d'images que vous voulez
+dans un programme en ajoutant simplement une instruction <strong>use</strong>
+pour chaque collection.</p>
+<p></p></ul>
+<p>
+</p>
+<h2><a name="travailler_avec_des_fichiers_.ui">Travailler avec des fichiers <strong>.ui</strong></a></h2>
+<p>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.</p>
+<p>Voici une meilleure méthode :</p>
+<ul>
+<li><strong><a name="item_écrire_l%27implémentation_de_slots_dans_le_designe">Écrire l'implémentation de slots dans le Designer</a></strong><br />
+</li>
+Dans Qt Designer, selectionnez l'onglet <em>Source</em> dans l'explorateur
+d'objets (<strong>Object Explorer</strong>).  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 <em>Slots/public</em>,
+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 <strong>&lt;Votre Classe&gt;.ui.h</strong> où vous pouvez
+écrire l'implémentation de votre slot.
+<p>Par défaut, il devrait ressembler à ceci :</p>
+<pre>
+ void Form1::newSlot()
+ {</pre>
+<pre>
+ }</pre>
+<p>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.</p>
+<pre>
+ void Form1::newSlot()
+ {
+     print STDERR &quot;Hello world from Form1::newSlot();
+     if(this-&gt;foo())
+     {
+         # faire quelque chose
+     }
+ }</pre>
+<p>Notre code Perl ainsi écrit sera sauvé dans le fichier ui.h et
+<strong>puic</strong> prendra soin de le placer dans notre programme final.</p>
+<p>Ici, après l'exécution de <strong>puic</strong> sur le ficier Form1.ui, vous
+devriez avoir:</p>
+<pre>
+ sub newSlot
+ {
+     print STDERR &quot;Hello world from Form1::newSlot();
+     if(this-&gt;foo())
+     {
+         # faire quelque chose
+     }
+ }</pre>
+<p></p>
+<li><strong><a name="item_sous%2dclassez_votre_gui">Sous-classez votre GUI</a></strong><br />
+</li>
+En utilisant l'option <em>-subimpl</em> de <strong>puic</strong>, vous pouvez générer un
+module dérivé qui hérite l'interface utilisateur originelle.
+<p>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.</p>
+<p>Pour générer le module de base  :</p>
+<pre>
+ puic -o Form1.pm form1.ui</pre>
+<p>(faîtes cela aussi souvent que nécessaire: n'éditez jamais
+manuellement form1.ui puisqu'il serait écrasé)</p>
+<p>Pour générer le GUI dérivé  :</p>
+<pre>
+ puic -o Form2.pm -subimpl Form2 form1.ui</pre>
+<p>ou</p>
+<pre>
+ puic -o program.pl -x -subimpl Form2 form1.ui</pre>
+<p>(faites cela une fois et travaillez avec le fichier résultant)</p>
+<p></p></ul>
+<p>
+</p>
+<hr />
+<h1><a name="autres_outils_de_développement">Autres outils de développement</a></h1>
+<p>PerlQt comprend également deux programmes pouvant vous aider à maîtriser l'API de Qt :</p>
+<p>
+</p>
+<h2><a name="pqtapi">pqtapi</a></h2>
+<p>pqtapi est un outil d'introspection en ligne de commande.</p>
+<pre>
+ utilisation: pqtapi [-r &lt;re&gt;] [&lt;class&gt;]</pre>
+<pre>
+ options:
+        -r &lt;re&gt; : chercher les méthodes correspondant à l'expression régulière &lt;re&gt;
+        -i : avec -r, effectue une recherche insensible à la casse
+        -v : afficher les versions de PerlQt et de Qt
+        -h : afficher ce message d'aide</pre>
+<p>ex:</p>
+<pre>
+ $&gt;pqtapi -ir 'setpoint.* int'
+        void QCanvasLine::setPoints(int, int, int, int)
+        void QPointArray::setPoint(uint, int, int)</pre>
+<p>
+</p>
+<h2><a name="pqtsh">pqtsh</a></h2>
+<p><strong>pqtsh</strong> est un shell graphique permettant de tester l'API de manière interactive.
+Un exemple dynamique est accessible dans l'entrée de menu <code>Help-&gt;Example</code>.</p>
+<br/>
+<div class='image'><img src="../images/pqtsh.png"/></div><p>
+</p>
+<hr />
+<h1><a name="limitations">Limitations</a></h1>
+<p>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.</p>
+<p>Vous pouvez reconnaître ce type de classe en ce que leurs arguments comprennent un type générique placé entre
+les signes ``&lt;'' et ``&gt;''.</p>
+<p>ex:
+  QDictIterator ( const QDict&lt;type&gt; &amp; dict )</p>
+<p>
+</p>
+<hr />
+<h1><a name="crédits">Crédits</a></h1>
+<p>PerlQt-3 est (c) 2002 Ashley Winters (et (c) 2003 Germain Garand)</p>
+<p>Kalyptus et l'engin de génération  Smoke  sont (c) David Faure and Richard Dale</p>
+<p>Puic is (c) TrollTech AS., Phil Thompson et Germain Garand,</p>
+<p>Ledit logiciel est délivré sous la GNU Public Licence v.2 or later.</p>
+<p>
+</p>
+<hr />
+<h1><a name="appendice:_les_conventions_de_c++_et_leur_traduction_en_perl">Appendice: Les conventions de C++ et leur traduction en Perl</a></h1>
+<p>Lorsque vous voulez utiliser depuis PerlQt une classe ou méthode décrite
+dans la <a href="http://doc.trolltech.com">documentation</a> Qt (voyez aussi le programme 
+$QTDIR/bin/assistant livré avec Qt), vous devez suivre des règles de translation simples.</p>
+<dl>
+<dt><strong><a name="item_noms_de_classe">Noms de classe</a></strong><br />
+</dt>
+<ul>
+<li></li>
+Les noms de classes utilisent le préfixe <strong>Qt::</strong> au lieu de <strong>Q</strong> pour
+être conforme à l'usage Perl.  Ainsi: QComboBox est nommé Qt::ComboBox
+dans PerlQt.
+<p></p></ul>
+<dt><strong><a name="item_fonctions">Fonctions</a></strong><br />
+</dt>
+<ul>
+<li></li>
+Les fonctions décrites comme  <strong>static</strong> sont accédées directement et non
+à travers un objet. Ainsi la fonction statique Foo de la classe <strong>QBar</strong>
+peut être accédée de PerlQt par
+<pre>
+ Qt::Bar::Foo( arg-1,...,arg-n);</pre>
+<p></p>
+<li></li>
+Les fonctions décrites comme  <strong>members</strong> ou <strong>Signals</strong> sont
+accessibles à travers l'objet par l'opérateur
+ <strong>-&gt;</strong> .
+Par exemple:
+<pre>
+ $widget-&gt;show;</pre>
+<p>Il n'y a pas de différence fondamentale entre les méthodes et les
+signaux, néanmoins PerlQt fournit le mot-clé <strong>emit</strong> comme une
+mnémonique pratique pour rendre clair que vous émettez un signal :</p>
+<pre>
+ emit $button-&gt;clicked;</pre>
+<p></p></ul>
+<dt><strong><a name="item_arguments">Arguments</a></strong><br />
+</dt>
+<ul>
+<li><strong><a name="item_par_valeur">Par valeur</a></strong><br />
+</li>
+Lorsqu'un argument n'est pas précédé par un des caractères <strong>&amp;</strong> or
+<strong>*</strong>,  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++.
+<p>Ainsi pour le prototype d'un constructeur écrit dans la documentation
+comme ceci:
+ QSize ( int w, int h )</p>
+<p>Vous écrirez :</p>
+<pre>
+ Qt::Size(8, 12);</pre>
+<p></p>
+<li><strong><a name="item_par_référence">Par référence</a></strong><br />
+</li>
+Lorsqu'un argument est précédé par le caractère <strong>&amp;</strong>, Il est une
+référence à un objet ou à un type. Vous pouvez alors fournir un nom de
+variable ou un objet temporaire :
+<pre>
+ $keyseq = Qt::keySequence( &amp;Qt::CTRL + &amp;Qt::F3 );
+ $widget-&gt;setAccel( $keyseq );</pre>
+<p>ou</p>
+<pre>
+ $widget-&gt;setAccel(Qt::keySequence( &amp;Qt::CTRL + &amp;Qt::F3 );</pre>
+<p>Si l'argument n'est <em>pas</em> qualifié par <strong>const</strong> (constante), l'argument
+est un objet qui peut être altéré par la méthode, vous devez
+donc passer une variable.</p>
+<p></p>
+<li><strong><a name="item_par_pointeur">Par pointeur</a></strong><br />
+</li>
+Lorsqu'un argument est précédé par le caractère <strong>*</strong>,
+un pointeur vers un objet ou un type est attendu. En PerlQt, vous
+pouvez fournir un nom de  variable ou le mot clé <strong>undef</strong> à la place
+du pointer Null.
+<p>De plus, si l'argument est const, l'objet passé en argument est en
+lecture seule: il ne peut pas être modifié.</p>
+<p></p></ul>
+<dt><strong><a name="item_énumérations">Énumérations</a></strong><br />
+</dt>
+<dd>
+Les Énumerations sont une forme d'alias pour des valeurs numériques
+dont il serait autrement difficile de se souvenir:
+</dd>
+<dd>
+<p>Exemple C++:</p>
+</dd>
+<dd>
+<pre>
+ enum Strange { Apple, Orange, Lemon }</pre>
+</dd>
+<dd>
+<p>Ici, <code>Strange</code> est le type (au sens de C++) de l'énumération, et
+<code>Apple</code>, <code>Orange</code> et
+<code>Lemon</code> ses valeurs  possible , qui sont des aliases pour des
+nombres (ici 0, 1 et 2)</p>
+</dd>
+<dd>
+<p>L'accès aux valeurs d'énumération en Perl Qt est un appel
+de fonction statique.</p>
+</dd>
+<dd>
+<p>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: <code>&amp;fonction</code>.</p>
+</dd>
+<dd>
+<p>Revenons à notre exemple <code>Strange</code>.</p>
+</dd>
+<dd>
+<p>Si nous rencontrons sa  définition  dans la classe <code>QFruits</code>, vous
+écrirez en PerlQt :</p>
+</dd>
+<dd>
+<pre>
+ $pomme_plus_orange = &amp;Qt::Fruit::Pomme + &amp;Qt::Fruit::Orange;</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_opérateurs">Opérateurs</a></strong><br />
+</dt>
+<dd>
+Dans PerlQt, la <strong>surcharge d'opérateurs</strong> 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.
+</dd>
+<dd>
+<p>ex-1: surcharge de '+='</p>
+</dd>
+<dd>
+<pre>
+ $p1 = Qt::Point(10, 10)
+ $p2 = Qt::Point(30,40)
+ $p2 += $p1; # $p2 devient (40,50)</pre>
+</dd>
+<dd>
+<p>ex-2: surcharge de '&lt;&lt;'</p>
+</dd>
+<dd>
+<pre>
+ $f = Qt::File(&quot;example&quot;);
+ $f-&gt;open( IO_WriteOnly ); # voir l'entrée 'Constantes' plus bas
+ $s = Qt::TextStream( $f );
+ $s &lt;&lt; &quot;Que faire avec &quot; &lt;&lt; 12 &lt;&lt; &quot; pommes ?&quot;;</pre>
+</dd>
+<dd>
+<p><strong>Exception notable</strong> : 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.</p>
+</dd>
+<p></p>
+<dt><strong><a name="item_constantes">Constantes</a></strong><br />
+</dt>
+<dd>
+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.
+</dd>
+<dd>
+<p>Pour éviter de polluer inutilement l'espace de nom, nous avons regroupé les constantes dans le module
+<strong>Qt::constants</strong>, d'où elles seront chargées à la demande.</p>
+</dd>
+<dd>
+<p>Ainsi, pour importer l'ensemble des constantes d'E/S, on écrira :</p>
+</dd>
+<dd>
+<pre>
+ use Qt::constants;</pre>
+</dd>
+<dd>
+<p>Et pour importer quelques symboles seulement :</p>
+</dd>
+<dd>
+<pre>
+ use Qt::constants qw( IO_ReadOnly IO_WriteOnly );</pre>
+</dd>
+<p></p>
+<dt><strong><a name="item_fonctions_globales">Fonctions globales</a></strong><br />
+</dt>
+<dd>
+Qt dispose de fonctions utilitaires, telles bitBlt, qCompress, etc.
+</dd>
+<dd>
+<p>Ces fonctions ont été rassemblées dans un espace de nom commun:
+<code>Qt::GlobalSpace</code>.</p>
+</dd>
+<dd>
+<p>Vous pourrez donc y accéder soit par un appel pleinement qualifié :</p>
+</dd>
+<dd>
+<pre>
+ Qt::GlobalSpace::qUncompress( $buffer )</pre>
+</dd>
+<dd>
+<p>Soit en important préalablement ces fonctions dans l'espace de nom courant :</p>
+</dd>
+<dd>
+<pre>
+ use Qt::GlobalSpace;
+ qUncompress( $buffer )</pre>
+</dd>
+<dd>
+<p>Bien entendu, vous pouvez aussi n'importer que les fonctions souhaitées :</p>
+</dd>
+<dd>
+<pre>
+ use Qt::GlobalSpace qw( qUncompress bitBlt )</pre>
+</dd>
+<dd>
+<p><strong>N.B:</strong> 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.</p>
+</dd>
+<dd>
+<p>ex:</p>
+</dd>
+<dd>
+<pre>
+ $p1 = Qt::Point(10, 10) + Qt::Point(20, 20)</pre>
+</dd>
+<p></p></dl>
+<p>
+</p>
+<hr />
+<h1><a name="annexe_2_:_internationalisation">Annexe 2 : Internationalisation</a></h1>
+<p>PerlQt résout les problèmes d'internationalisation en convertissant systématiquement les <strong>QString</strong>
+de Qt en <strong>utf8</strong> côté Perl.</p>
+<p>Les conversions en sens inverse, depuis Perl vers Qt sont traitées différemment suivant le contexte :</p>
+<ul>
+<li><strong><a name="item_si_la_chaîne_de_caractère_est_déjà_marquée_comme_é">Si la chaîne de caractère est déjà marquée comme étant utf8</a></strong><br />
+</li>
+alors elle sera convertie en QString directement.
+<p>C'est la manière privilégiée d'opérer, et la plus simple :
+Il vous suffit d'insérer un pragma <strong>use utf8</strong> 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.</p>
+<p></p>
+<li><strong><a name="item_si_la_chaîne_n%27est_pas_marquée_comme_utf8%2c_et_">Si la chaîne n'est pas marquée comme utf8, et le pragma 'use locale' n'est pas actif</a></strong><br />
+</li>
+alors la conversion en QString se fera depuis l'<strong>ISO-Latin-1</strong>.
+<p></p>
+<li><strong>Si la chaîne n'est pas marquée comme utf8, et le pragma 'use locale' est actif</strong><br />
+</li>
+alors la conversion en QString se fera depuis votre <strong>locale</strong>.
+<p></p></ul>
+<p>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 :</p>
+<pre>
+ $tr1=Qt::TextCodec::codecForLocale(); # ceci utilisera la locale en vigueur
+ $tr2=Qt::TextCodec::codecForName(&quot;KOI8-R&quot;); # ceci force l'emploi d'une locale spécifique (Russe)</pre>
+<pre>
+ print $tr1-&gt;fromUnicode(Qt::DateTime::currentDateTime()-&gt;toString).&quot;\n\n&quot;;
+ print $tr2-&gt;fromUnicode($une_chaine_utf8);</pre>
+<p>Soit avec les outils de Perl (pour perl &gt;= 5.8.0).
+Se reporter à ce sujet à la documentation du module <strong>Encode</strong> (<code>perldoc Encode</code>).</p>
+<p>
+</p>
+<h3><a name="désactiver_l'encodage_utf8">désactiver l'encodage utf8</a></h3>
+<p>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 <strong>use bytes</strong> (et sa réciproque : <strong>no bytes</strong>).</p>
+<p>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 <strong>use locale</strong> est actif).</p>
+<p>Notez bien qu'il est préférable de <em>ne pas utiliser ce pragma à la légère</em>, 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.</p>
+<p>
+</p>
+<hr />
+<h1><a name="annexe_3_:_canaux_de_déboguage">Annexe 3 : Canaux de déboguage</a></h1>
+<p>Le module <strong>Qt::debug</strong> offre divers canaux de déboguage permettant de filtrer
+le flux conséquent d'informations disponibles pour l'adapter à vos besoins.</p>
+<pre>
+ use Qt::debug;</pre>
+<pre>
+ use Qt::debug qw|calls autoload verbose|;</pre>
+<p>Avec le pragma <code>use Qt::debug</code>, seuls les canaux <strong>verbose</strong> et <strong>ambiguous</strong> sont activés.
+Si vous le faites suivre d'une liste précise de canaux, seuls ceux-ci seront affichés.</p>
+<p><strong>Liste et descriptif des canaux :</strong></p>
+<ul>
+<li><strong><a name="item_ambiguous">ambiguous</a></strong><br />
+</li>
+Vérifier si les appels de méthodes sont ambigus, et dire quelle méthode, parmi le jeux
+d'alternatives, à finalement été choisie.
+<p></p>
+<li><strong><a name="item_verbose">verbose</a></strong><br />
+</li>
+Donner davantage d'informations.
+<p>Utilisé avec <strong>ambiguous</strong>, vous donnera les correspondances les plus proches lorsqu'un appel de méthode échoue.</p>
+<p>ex:</p>
+<pre>
+ use Qt;
+ use Qt::debug;
+ $a= Qt::Application(\@ARGV);
+ $a-&gt;libraryPath(&quot;chose&quot;);</pre>
+<pre>
+ --- No method to call for :
+        QApplication::libraryPath('chose')
+ Closer candidates are :
+        static void QApplication::addLibraryPath(const QString&amp;)
+        static QStringList QApplication::libraryPaths()
+        static void QApplication::removeLibraryPath(const QString&amp;)
+        static void QApplication::setLibraryPaths(const QStringList&amp;)</pre>
+<p></p>
+<li><strong><a name="item_calls">calls</a></strong><br />
+</li>
+Pour chaque appel de méthode, vous dira quelle méthode Qt est finalement appelée,
+en précisant les arguments si <strong>verbose</strong> est actif.
+<p></p>
+<li><strong><a name="item_autoload">autoload</a></strong><br />
+</li>
+Détaille le passage dans le code intermédiaire faisant la jonction entre Perl et Qt.
+<p></p>
+<li><strong><a name="item_gc">gc</a></strong><br />
+</li>
+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.
+<p></p>
+<li><strong><a name="item_virtual">virtual</a></strong><br />
+</li>
+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).
+<p></p>
+<li><strong><a name="item_all">all</a></strong><br />
+</li>
+Activer tous les canaux.
+<p></p></ul>
+<p>
+</p>
+<hr />
+<h1><a name="annexe_4_:_marshalleurs">Annexe 4 : Marshalleurs</a></h1>
+<p>Un marshalleur est un convertisseur permettant de transcrire un type de données en un autre.</p>
+<p>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.</p>
+<p>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é.</p>
+<p>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.</p>
+<pre>
+ Liste des marshalleurs (PerlQt-3.008)
+ -----------------------------------------------------------------
+ float, double                         &lt;=&gt;       réel Perl (NV)
+ char, uchar, int, uint, enum
+ long, ulong, short, ushort            &lt;=&gt;       entier Perl (IV)
+ QString, -&amp;, -*                        =&gt;       chaîne Perl (utf8)
+ QString, -&amp;, -*                       &lt;=        chaîne Perl (utf8 ou iso-latin1 ou locale)
+ QCString, -&amp;, -*                      &lt;=&gt;       chaîne Perl (utf8 ou octets, suivant contenu ou pragma &quot;bytes&quot;)
+ QStringList, -&amp;, -*                    =&gt;       référence à une liste de chaînes Perl (utf8)
+ QByteArray, -&amp;, -*                    &lt;=&gt;       chaîne Perl (octets)
+ int&amp;, -*                              &lt;=&gt;       entier Perl (IV)
+ bool&amp;, -*                             &lt;=&gt;       booléen Perl
+ char*                                 &lt;=&gt;       chaîne Perl (octets)
+ char**                                &lt;=        référence à une liste de chaînes Perl (octets)
+ uchar*                                &lt;=        chaîne Perl(octets)
+ QRgb*                                 &lt;=        référence à une liste d'entiers Perl (IV)
+ QCOORD*                               &lt;=        référence à une liste d'entiers Perl (IV)
+ void*                                 &lt;=&gt;       référence à un entier Perl (IV)
+ QValueList&lt;int&gt;, - *, - &amp;             &lt;=&gt;       référence à une liste d'entiers Perl (IV)
+ QCanvasItemList, - *, - &amp;              =&gt;       réference à une liste de Qt::CanvasItem
+ QWidgetList, - *, - &amp;                 &lt;=&gt;       réference à une liste de Qt::Widget
+ QObjectList, - *, - &amp;                 &lt;=&gt;       réference à une liste de Qt::Object
+ QFileInfoList, - *, - &amp;               &lt;=&gt;       réference à une liste de Qt::FileInfo
+ QPtrList&lt;QTab&gt;, - *, - &amp;              &lt;=&gt;       réference à une liste de Qt::Tab
+ QPtrList&lt;QToolBar&gt;, - *, - &amp;          &lt;=&gt;       réference à une liste de Qt::ToolBar
+ QPtrList&lt;QNetworkOperation&gt;, - *, - &amp; &lt;=&gt;       réference à une liste de Qt::NetworkOperation
+ QPtrList&lt;QDockWindow&gt;, - *, - &amp;       &lt;=&gt;       réference à une liste de Qt::DockWindow
+ (QUObject*)</pre>
+
+</body>
+
+</html>
diff --git a/doc/images/ex1.png b/doc/images/ex1.png
new file mode 100644
index 0000000..140b380
--- /dev/null
+++ b/doc/images/ex1.png
diff --git a/doc/images/ex2.png b/doc/images/ex2.png
new file mode 100644
index 0000000..5e44a51
--- /dev/null
+++ b/doc/images/ex2.png
diff --git a/doc/images/pqtsh.png b/doc/images/pqtsh.png
new file mode 100644
index 0000000..f5929b3
--- /dev/null
+++ b/doc/images/pqtsh.png