Help language development. Donate to The Perl Foundation
A Raku module and native wrapper providing an interface to the Qt5 GUI.
This module defines Raku classes trying to mimic the Qt GUI C++ classes. Qt objects are created and used through the Raku classes with native calls.
This is a work in progress and, currently, only a few classes and methods are defined. Nevertheless, this module is already usable (see paragraph 5 EXAMPLES below).
Currently, this module is only working with Linux.
Although already usable, this interface is still limited to a few of the most basic objects of the Qt GUI.
The list of Qt classes and methods already ported is given in the file doc/Qt/QtWidgets/Classes.html included in the distribution.
The Raku API aims to be as close as possible to the C++ one.
Classes defined by the Raku API implement the Qt C++ classes and the Raku methods have the same arguments as their related C++ methods.
Therefore the Qt C++ documentation should apply to its Raku interface.
This documentation is available here: https://doc.qt.io/qt-5.
The Raku API hides the C++ passing mode of the parameters.
Each class resides in its own compunit. So, before using a class, an use instruction have to be provided for the related module.
For example, the following line:
use Qt::QtWidgets::QPushButton;
has to be issued before using any instruction related to a QPushButton.
The script guessuse is provided to help writing the needed use
instructions.
See the paragraph 6 TOOL below.
To instantiate a Qt class object from Raku, just use new with the same arguments than the C++ constructor.
For example the C++ call of a QPushButton constructor is :
QPushButton * button = new QPushButton("some text");
the raku equivalent is:
my $button = QPushButton.new("some text");
Raku methods are called exactly as the original C++ method.
The C++ code :
button->setDisable(true);
is translated to Raku as :
$button.setDisable(True);
Similarly the C++ enums have their Raku equivalent :
the C++ code :
QPen * pen = new QPen(Qt::DashLine);
is translated to Raku as :
my $pen = QPen.new(Qt::DashLine);
The signals and slots mechanism used by Qt allows unrelated objects to communicate.
A C++ Qt object can have slots and/or signals if it inherits from the C++ class QObject.
Similarly, a Raku object can have QtSlots and/or QtSignals if it inherits from the Raku class QtObject.
The class QtObject and the related subroutines connect and disconnect are exported from the compunit Qt::QtWidgets and have to be imported with:
use Qt::QtWidgets;
A Raku Qt::QtWidgets Qtslot is an ordinary method defined with the trait is QtSlot.
class MyClass is Qt::QtWidgetsObject {
... # Some code
method mySlot(...) is QtSlot {
... # Some code
}
... # Some code
}
As well, a Raku Qt::QtWidgets Qtsignal is a method defined with the trait
is QtSignal.
Its associated code will never be executed. So a stub should be used when
defining the method.
class MyClass2 is Qt::QtWidgetsObject {
... # Some code
method mySignal(...) is QtSignal { ... }
... # Some code
}
The subroutine connect connects a QtSignal to a QtSlot (or to another QtSignal).
sub connect(QtObject $src, Str $signal, QtObject $dst, Str $slot)
The names of signal and slot are passed to connect in strings.
The signal and slot must have compatible signatures.
TODO: explanations needed
Example:
my $src = MyClass2.new; my $dst = MyClass.new; connect $src, "mySignal", $dst, "mySlot";
The subroutine disconnect does the opposite of connect.
sub disconnect(QtObject $src, Str $signal, QtObject $dst, Str $slot)
Example:
disconnect $src, "mySignal", $dst, "mySlot";
In C++ Qt, the keyword emit is used to emit a signal.
emit mySignal(some_arg);
In Raku Qt::QtWidgets, you only have to execute the method to emit the associated QtSignal.
self.mySignal(some_arg);
When programming with Qt and C++, some features can only be accessed by overriding a Qt C++ virtual method.
A parallel mechanism is implemented in the Qt::QtWidgets module.
Subclassing a Qt object needs three steps:
Define a Raku class inheriting the Qt class
Call the subClass method of the parent class from the BUILD or TWEAK submethod of the new class.
Override the virtual methods. The overriding method must have the same name and signature that the overrided method and doesn't need any specific syntax.
The first and third steps are obvious.
The second one is used to instantiate the C++
counterpart of the Raku class and to pass it the parameters its constructor
needs. In this second step, the parent class whose the subClass method is
called must be explicitely specified:
self.ParentClass::subClass($param, ...);
The following example shows how to subclass a QLabel and override its QMousePressEvent method.
Pure C++ version:
``` C++
class MyLabel : public QLabel { public : MyLabel(const QString txt) : QLabel(txt) { }
void mousePressEvent(QMouseEvent* event)
{
// Do something when the mouse is pressed on the label
}
};
...
// Instantiation of the label in the main function : MyLabel * label = new MyLabel("text on the label");
**Raku version:**
``` Raku
use Qt::QtWidgets;
use Qt::QtWidgets::QLabel;
use Qt::QtWidgets::QMouseEvent;
class MyLabel is QLabel
{
has Str $.txt;
submethod TWEAK { self.QLabel::subClass($!txt); }
method mousePressEvent(QMouseEvent $event)
{
# Do something when the mouse is pressed on the label
}
}
...
# Instantiation of the label in the main program :
my $label = MyLabel.new(txt => "text on the label");
A very simple clock displaying the current time.
raku examples/clock_fixedSize.raku
The same clock with a resizable window.
raku examples/clock_resizable.raku
A graphical interface to solve quadratic equations.
raku examples/2deg_eqn_solver.raku
A small example showing how to draw with the mouse and how to get file names using QFileDialog methods.
raku examples/sketch_board.raku
A tiny text editor build with QTextEdit
raku examples/editor.raku
A demonstration of QSlider, QDial, QCheckBox and QRadioButton widgets.
raku examples/sliders.raku
Ideally, inserting "use Qt::QtWidgets;" at the beginning of a script should be
sufficient to import all the elements of the Qt::QtWidgets module.
Unfortunately it's not the case and seems not to be possible with the current
version of Raku (except by gathering all the classes of this API inside a single
huge source file).
Currently a specific use instruction is needed for each Qt class used in
a script.
That's why a tool named guessuse is provided to help the user to find what use instructions a given script needs.
When called with the name of a raku file as argument, it writes out the list of use instructions related to Qt::QtWidgets needed by this script.
For example, the command:
guessUse examples/sketch_board.raku
prints out the following lines:
use Qt::QtWidgets; use Qt::QtWidgets::QAction; use Qt::QtWidgets::QApplication; use Qt::QtWidgets::QBrush; use Qt::QtWidgets::QColor; use Qt::QtWidgets::QFileDialog; use Qt::QtWidgets::QHBoxLayout; use Qt::QtWidgets::QMenu; use Qt::QtWidgets::QMouseEvent; use Qt::QtWidgets::QPaintEvent; use Qt::QtWidgets::QPainter; use Qt::QtWidgets::QPen; use Qt::QtWidgets::QPushButton; use Qt::QtWidgets::QVBoxLayout; use Qt::QtWidgets::QWidget; use Qt::QtWidgets::Qt;
Beware that this tool, when scanning a source file, doesn't make any difference between code, comments and character strings and may very well print out "use" instruction for some unneeded compunit.
guessuse resides in the the bin directory of the distribution and is installed by zef along with the Qt::QtWidgets module.
This module has been tested with Qt 5.9.4 and gcc 5.5.0
and with Qt 5.15.2 and gcc 10.3.0.
Many other versions should be usable as well.
zef install Qt::QtWidgets
The source code is available here: https://github.com/yguillemot/Raku-Qt-QtWidgets.git
Given the large number of Qt Classes and methods, manually writing such a
code is very tedious and error prone.
That's why this source and its associated documentation have been
automatically generated from the Qt C++ headers files coming with the Qt
development package.
The building tools are available here: https://github.com/yguillemot/RaQt_maker.git
Yves Guillemot \<[email protected]>
Copyright (C) 2021 Yves Guillemot
This software is free: you can redistribute and/or modify it under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.