This is the PerlQt 1.00 README.

  PerlQt is an extensive interface between the Perl scripting language, and
the C++ Qt GUI programming toolkit. It allows Perl programs to not only
access and display Qt widgets (graphical components), but create new widgets
through inheritance, in much the same way as it is done in C++.

  The extent of the interface goes beyond merely inheritance. Qt has a
powerful call-back mechanism known as signals and slots. It allows the
programmer to avoid manual call-backs with function-pointers and the like,
and allows a cleaner programming style. Because C++ was incapable, on it's
own, of achieving this goal, a 'Meta-object compiler' program, called 'moc',
was created to automatically create the additional code needed to perform
call-backs with signals and slots. PerlQt has improved upon this system.

  The signals and slots mechanism, put to such good use in C++ Qt, could
not be left out of an extensive interface to Perl. It wasn't. Using
Perl's 'use' function, I made the declaration of signals and slots a
one-step process. No Meta-object compiler is needed, because Perl can call
functions from their names, and create functions at run-time.

  Admittedly, the interface to signals and slots in PerlQt is not as
flexible as in C++ Qt, but that will change soon enough. And what has been
interfaced so far is enough for most applications already.

  Creation of new Qt widgets just isn't complete without virtual functions.
With that in mind, I made sure that every virtual function in every
class could be overridden in PerlQt. This means that virtual function
overridding has no restrictions in PerlQt. Just create the function, and
it 'works'.

  Since Qt is written in C++, it was inevitable that it would have
overloaded functions (functions with more than one prototype). Since Perl
can determine the number and type of arguments to a function, I chose
to support all prototypes of all functions. The only drawback I can see
is with virtual functions. If you override a virtual function that has
another prototype (perhaps virtual, perhaps not), the programmer will
have to ensure that both prototypes are supported in the virtual function.

  One of the most notable features of Qt is its extensive documentation.
I have made great pains to ensure that the PerlQt interface matches the
C++ Qt interface as much as possible, thereby making the Qt documentation
as applicable to PerlQt as to C++ Qt.

  I admit that currently, there is not much PerlQt-specific documentation.
What documentation is provided is in the form of pod documentation, the
standard Perl documentation format, at the end of each module's .pm file.
When PerlQt is installed, the pod documentation should be translated into
the more digestable man format, and installed somewhere.

  Even better than documentation, in my opinion, is code. PerlQt comes
with over 5000 lines of code which actually runs in PerlQt. And all of
this code is directly ported from its C++ counterpart which is included
with Qt. Not only have *all* of the Qt tutorials been converted to PerlQt,
but most of the Qt examples have been as well. The most notable example
is the widgets example. Over a dozen widgets, some newly created, are used
in the same PerlQt program. Unfortunatly, I couldn't manage converting
tetris in time for this release. :)

  A line-by-line comparison of C++ Qt and PerlQt code yields interesting
insight into the directness of the interface between them. The Qt tutorial
documentation is a good place to start learning PerlQt, believe it or not.
It not only describes the actions of a function in detail, but the
differences between the C++ Qt and PerlQt interfaces can be clearly seen.

  Despite the attempted directness of the PerlQt interface, I could not
allow the constant/enumeration interface to remain as it was in C++.
While it was possible to convert everything exactly, doing so would
have been a really bad idea.

  I believe that I have cleaned up the enumeration/constant interface to
a great degree. Most constants have been stuffed into Perl hashes, where
in Qt they were just similarly named constants. Some were logical, like
Key_X being converted to $Key{X}, yet others were not so obviously logical.
I've tried to document the changes in the relevant places.

  PerlQt 1.00 requires Perl-5.004 and Qt-1.2. A late beta version of Perl,
>= 5.003_90, should be fine as well. Is should compile on most
POSIX-compatible Unix platforms, and probably on all Linux systems. It is
important that your version of Perl-5.004 is *NOT* binary-compatible with
Perl-5.003. There is a reason I chose not to use Perl-5.003 for PerlQt.

  Now that you know what PerlQt is, and some of what it does, I hope you'll
learn it, use it, live it, love it, and report all bugs to jql@accessone.com.


PerlQt is my baby,

Ashley Winters