Qt4 binding: what changed

Revision 1 to 2. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		(Qt only)
2	2
3	3		# Download Free Pascal Qt4 Binding
4	4
5	5		The binding releases are uploaded to the [FPC Qt4 Binding Home Page](http://users.telenet.be/Jan.Van.hijfte/qtforfpc/fpcqt4.html).
6	6
7	7		# Install Free Pascal Qt4 Binding
8	8
9	9		The download contains a file README.TXT which contains the installation instructions.
10	10
11	11		# Links
12	12
13	13		- [Qt Documentation](http://doc.trolltech.com/)
14	14		- [Pascal Qt4 binding home page](http://users.telenet.be/Jan.Van.hijfte/qtforfpc/fpcqt4.html)
15	15		- [Pascal Qt2/E binding home page](http://users.telenet.be/Jan.Van.hijfte/qtforfpc/qtedemo.html)
16	16		- [[Qt Interface\|Lazarus Qt4 interface]]
17	17		- [[Qt Interface Mac\|Compile instructions for Mac]]
18	18		- [[Qt4 Maemo Binding\|FreePascal Qt4 Binding for Maemo]]
19	19
20	20		# How to use the Qt4 binding
21	21
22	22		## License
23	23
24	24		Since Qt4 is also available under LGPL, there is no difference in licensing with e.g. Gtk. LGPL allows development of both free and proprietary software without any license fees or royalties. [Nokia Qt License info](http://qt.nokia.com/products/licensing)
25	25
26	26		## Demo Programs
27	27
28	28		The FPC Qt4 Binding is not meant to create Qt applications in FPC. But it should allow the Lazarus LCL developers to create a Qt Widget set for Lazarus. A Lazarus Qt Widget set allows Lazarus developers to create programs for the entire set of platforms supported by Qt (Windows, Linux, Linux Embedded, OS X, ...). The provided demoes on [FPC Qt4 Binding Home Page](http://users.telenet.be/Jan.Van.hijfte/qtforfpc/fpcqt4.html) provide insight in how to use the binding for LCL/Qt development. The lazarus user may however also choose to make some direct Qt4 binding calls to achieve things not yet supported in Lazarus/LCL such as WebKit support.
29	29
30	30		The Qt2 Embedded binding was intended to create full FPC Qt programs and therefore included an extra advanced object oriented layer of Pascal classes and interfaces on top of the Qt classes. [Qt/E demo](http://users.pandora.be/Jan.Van.hijfte/qtforfpc/qtedemo.html). Though this extra layer is convenient, it was chosen not to create one for Qt4 to avoid any performance penalty or code bloat for LCL/Qt.
31	31
32	32		## Use the Qt Documentation
33	33
34	34		### How to create a Class
35	35
36	36		Look up the Qt Class you would like to use. Suppose it is [QWidget](http://doc.trolltech.com/4.6/qwidget.html). Some classes provide several constructors (with different parameters). The binding provides for most constructors a corresponding factory function QtClassName_create(parameters). Store the class in a variable of type QtClassName+H. The beginning of Qt4.pas provides you with a list of all supported classes. That same list also serves to provide type safe usage of the Qt class handles. The list encodes the Class hierarchy.
37	37
38	38		``` pascal
39	39		var W : QWidgetH;
40	40		...
41	41		W := QWidget_create(nil,0);
42	42
43	43		```
44	44
45	45		### How to call a method of a Qt Class
46	46
47	47		Use the Nokia Qt documentaton to find out how and when to use which method. Suppose you want to use [void QWidget::setFixedHeight ( int h )](http://doc.trolltech.com/4.5/qwidget.html#setFixedHeight) The corresponding Pascal fuction will be ClassName+_+MethodName. So look in Qt4.pas for the definition of QWidget_setFixedHeight
48	48
49	49		``` pascal
50	50		procedure QWidget_setFixedHeight(handle: QWidgetH; h: Integer);
51	51
52	52		```
53	53
54	54		Note how the pascal function has an additional parameter: the Qt Class instance handle of your QWidget Class. Calling the setFixedHeight method will be like this
55	55
56	56		``` pascal
57	57		QWidget_ setFixedHeight(W,100);
58	58
59	59		```
60	60
61	61		### How to hook a Pascal Method to a signal of a Qt Class
62	62
63	63		Qt classes can emit signals and other classes can hook method (slots) to these signals. The binding allows to hook Pascal methods to the Qt classes. To be able to do this, an intermediate Qt class needs to be created. For every class that emits signals, that intermediate class, referred to as hook, is provided in the binding and is called ClassName_hookH. This class can connect to all signals of its corresponding class and will call the corresponding pascal method upon occurrence of the signal.
64	64
65	65		Example: The Qt Class QAbstractButton has a [signal clicked](http://doc.trolltech.com/4.5/qabstractbutton.html#clicked). The hook class of the binding is QAbstractButton_hookH.
66	66
67	67		``` pascal
68	68		var
69	69		hook : QAbstractButton_hookH;
70	70		...
71	71		hook:=QAbstractButton_hook_create(AbstractButtonHandle);
72	72		QAbstractButton_hook_hook_clicked(hook, @Clicked);
73	73
74	74		```
75	75
76	76		The definition of hook_hook_clicked shows the type of the Pascal Method to provide:
77	77
78	78		``` pascal
79	79		procedure QAbstractButton_hook_hook_clicked(handle: QAbstractButton_hookH; hook: QAbstractButton_clicked_Event);
80	80
81	81		```
82	82
83	83		That Pascal Method type is defined as:
84	84
85	85		``` pascal
86	86		type
87	87		QAbstractButton_clicked_Event = procedure (checked: Boolean = False) of object '''cdecl''';
88	88
89	89		```
90	90
91	91		Therefore the method Clicked should be defined as: (Take note of the cdecl calling convention)
92	92
93	93		``` pascal
94	94		TButton = class (TObject)
95	95		...
96	96		procedure Clicked(checked: Boolean);'''cdecl''';
97	97		...
98	98		procedure TButton.Clicked(checked: Boolean = False);'''cdecl''';
99	99		begin
100	100		end;
101	101
102	102		```
103	103
104	104		### C++ Multiple inheritance
105	105
106	106		Some Qt Classes inherit from more than 1 class. QWidget inherits from QObject and QPaintDevice. When you create in C++ a QWidget instance, there are actually two instances that get created. One instance handle for QObject and one for QPaintDevice. In the binding, the returned handle will be for the first parent (QObject). To use the methods provided through inheritance by the second parent, you need to use the second instance handle. That second instance handle is obtained by using a function called FirstClass_To_SecondClass:
107	107
108	108		``` pascal
109	109		function QWidget_to_QPaintDevice(handle: QWidgetH): QPaintDeviceH;
110	110
111	111		```
112	112
113	113		In the demo program you notice how the paint event is used to paint on a QWidget. To paint, you need to create a QPainter (like canvas) from the QWidget. The Qt documentation shows that the constructor of QPainter requires a QPaintDevice. So here is an extract of the demo
114	114
115	115		``` pascal
116	116		var PaintBox : QWidgetH;
117	117		PaintBox:=QWidget_create();
118	118		...
119	119		// In the paint method
120	120		var CV : QPainterH;
121	121		CV:=QPainter_create(QWidget_to_QPaintDevice(PaintBox));
122	122
123	123		```
124	124
125	125		Do not use typecasting like QPaintDeviceH(PaintBox). The compiler would complain if you did this anyhow. See type safety below.
126	126
127	127		# Technical information
128	128
129	129		## Supported Platforms
130	130
131	131		The Qt library works on different platforms such as Linux/BSD, Windows, OS X and Embedded. Depending of the platform a number of methods are available or not.
132	132
133	133		Example functions:
134	134
135	135		- Windows only function: QPixmap_toWinHBITMAP
136	136		- Linux only function: QApplication_x11EventFilter
137	137		- macOS only function: QApplication_macEventFilter
138	138		- Embedded only function: QApplication_qwsEventFilter
139	139
140	140		Qt achieves this with conditional defines such as Q_WS_MAC or Q_WS_QWS. There are many more Q_XXX that allow to fine tune the Qt library for many platforms. You can e.g. configure Qt to not include CUPS support with QT_NO_CUPS. The Qt library source that is contained in the Windows Qt Download or the Embedded download is pretty similar, only very platform specific include files are omitted. The key difference is that the config files are different, e.g. in qconfig.h Q_WS_QWS is enabled in the Embedded Qt Download and not in the qconfig.h from other Platform downloads
141	141
142	142		The pascal Qt interface library also uses a single source for all platforms by using conditional defines. Not as many defines as in Qt are used, the sole aim was to cope with the different platforms: Linux, Windows, OS X and Embedded.
143	143
144	144		This is achieved by defining for a given platform a number of QT_XXX defines and then converting the headers with moc. Moc allows the provision of defines so that the methods that are available when these defines are set, are the only ones visible.
145	145
146	146		The different binding platform defines are:
147	147
148	148		\| Platform define \| List of Qt defines \|
149	149		\|-----------------\|----------------------------------------------------\|
150	150		\| BINUX \| Q_WS_X11 Q_OS_LINUX Q_OS_UNIX \|
151	151		\| MSWINDOWS \| Q_WS_WIN \|
152	152		\| DARWIN \| Q_WS_MAC Q_OS_UNIX \|
153	153		\| QTOPIA \| Q_WS_QWS Q_OS_LINUX Q_OS_UNIX QT_NO_SESSIONMANAGER \|
154	154
155	155		Platforms
156	156
157	157		Binux stands for BSD/Linux.
158	158
159	159		The binding consists of a C++ part, that uses above defines to enclose platform specific methods. To compile the code on a given platform, the respective define should be set. In the V1.X versions, the platform specific compile scripts defined the appropriate platform, in the V2.X the provided qmake project automatically sets the proper platform define.
160	160
161	161		The binding also consists of a pascal part. In that part the different defines are enabled by using the free pascal predefined defines or they just are the same.
162	162
163	163		Note that embedded is a special platform, that is both linux and embedded. (I did not look into the recently created wince and symbian qt variant yet). But to avoid the inclusion of any missing X11 libraries, you should not define BINUX for the compilation of the library or qt4.pas. The V1.X library source package for Linux contains 2 compile scripts, one for linux (compile_lib.sh) that defines BINUX and one for Qt/Embedded (compile_lib_qtopia.sh) that defines QTOPIA and allows calling either gcc (intel qvfb) or arm-linux-gcc (arm embedded). In the V2.X bindings, you need to set QTOPIA yourself in the qmake project.
164	164
165	165		The lazarus lcl qt interface, also uses platform specific defines in the lcl code that calls the Qt binding. To correctly compile the lcl for embedded, you need to set the define QTOPIA. The other used defines (LINUX, WINDOWS, DARWIN=macOS) are done automatically by using existing platform specific defines provided by fpc.
166	166
167	167		To compile lazarus for embedded/qtopia:
168	168
169		-	~~` make PREFIX=/usr clean all LCL_PLATFORM=qt OPT="-dQTOPIA"`~~
	169	+	```text
	170	+	make PREFIX=/usr clean all LCL_PLATFORM=qt OPT="-dQTOPIA"
	171	+	```
170	172
171	173		<http://users.telenet.be/Jan.Van.hijfte/qtforfpc/Lazarus_Embedded.png> last Version verified to work is 0.9.29
172	174
173	175		## Type safe Qt Class Handles
174	176
175	177		In Qt4.pas you will see a large list of type definitions of Qt Class handles.
176	178
177	179		``` pascal
178	180		QWidgetH = class(QObjectH) end;
179	181		QAbstractButtonH = class(QWidgetH) end;
180	182		QPushButtonH = class(QAbstractButtonH) end;
181	183
182	184		```
183	185
184	186		This list ensures type safety and encodes the class hierarchy.
185	187
186	188		### Inheritance
187	189
188	190		This way you can call an inherited function using a descendant class type. The extract of the list shows that QPushButton descends from QWidget, so you can call the inherited method "width" from QWidget with your QPushButton handle
189	191
190	192		``` pascal
191	193		var Btn : QPushButtonH;
192	194		...
193	195		Btn := QPushButton_create(parent);
194	196		writeln('Button Width:',QWidget_width(Btn));
195	197
196	198		```
197	199
198	200		### Type Safe Class Parameters
199	201
200	202		In the Multiple inheritance paragraph, you have seen that you need to call a convert function to convert your QWidget to a QPaintDevice. If you didn't use the convert the compiler would complain. Suppose we omit the convert function
201	203
202	204		``` pascal
203	205
204	206		// Do not do this !!!
205	207		CV:=QPainter_create(PaintBox);
206	208
207	209		```
208	210
209	211		The type safety net will make the compiler complain like this:
210	212
211		-	~~`demo.pas(265,30) Error: Incompatible type for arg no. 1: Got "QWidgetH", expected "QPaintDeviceH"`~~
	213	+	``` pascal
	214	+	demo.pas(265,30) Error: Incompatible type for arg no. 1: Got "QWidgetH", expected "QPaintDeviceH"
	215	+	```
212	216
213	217		Similar if you would not use the convert function, but would just use typecast like this
214	218
215	219		``` pascal
216	220		// Do '''not''' do this !!!
217	221		CV:=QPainter_create(QPaintDeviceH(PaintBox));
218	222
219	223		```
220	224
221	225		The compiler will complain with:
222	226
223		-	~~`demo.pas(266,21) Warning: Class types "QWidgetH" and "QPaintDeviceH" are not related`~~
	227	+	```text
	228	+	demo.pas(266,21) Warning: Class types "QWidgetH" and "QPaintDeviceH" are not related
	229	+	```
224	230
225	231		That typecast would not change the handle. Handles are just numbers, the returned handle/number of QWidget_to_QPaintDevice is different than the PaintBox handle/number. It indirectly points to a different Virtual Method Table.
226	232
227	233		### Type Safe Method Parameters
228	234
229	235		The Pascal methods that can be provided to the Hook classes, need to be of the correct function type. This prevents otherwise not so pleasant stack problems when the binding c++ code calls the provided pascal method.
230	236
231	237		## Qt Enums and QFlags
232	238
233	239		Qt uses a template class QFlags\<Enum\> when passing combinations of an Enum to a method. This Qt Doc [WindowType](http://doc.trolltech.com/4.5/qt.html#WindowType-enum) defines the enum Qt::WindowType and the associated Qt Class Qt::WindowFlags. In the header file the flags are declared like this
234	240
235	241		``` cpp
236	242		Q_DECLARE_FLAGS(WindowFlags, WindowType)
237	243
238	244		```
239	245
240	246		More about this macro: [Q_DECLARE_FLAGS](http://doc.trolltech.com/4.4/qflags.html#Q_DECLARE_FLAGS)
241	247
242	248		Alot of methods have a QFlags Qt Class as a parameter. Normally we would need to create a instance of this class, pass it to the method and delete it ourselves in the pascal code. To avoid all this hassle the binding generator changed all methods to allow for passing a pascal cardinal type.
243	249
244	250		Let's sample this with the following constructor [QMainWindow](http://doc.trolltech.com/4.0/qmainwindow.html#QMainWindow). The constructor needs the QFlags Qt::WFlags. The Qt doc shows that this is just a synonym for Qt::WindowFlags. The following Qt4.pas extract show that the enums are declared as cardinals, so that "or" combination are allowed ("or" on pascal enums is not allowed). Sometimes these enums are used as default value of a parameter in a function. As pascal does not allow typed constants in default values, the different values of the enums are declared as untyped constants. The corresponding QFlags\<\> type is simply redeclared as the same type as the enum. Its name and the comments allow for easy cross reference Qt4.pas and the Qt documentation.
245	251
246	252		``` pascal
247	253		type
248	254		QtWindowType = cardinal; // Qt::WindowType (4)
249	255		QtWindowFlags = QtWindowType; // QFlags<>
250	256		const
251	257		QtWidget = 0 { $0 };
252	258		QtWindow = 1 { $1 };
253	259		QtDialog = 3 { $3 };
254	260		... etc
255	261
256	262		```
257	263
258	264		Now lets use this on QMainWindow. The following code creates a MainWindow that stays on top and has a small toolwindow title bar:
259	265
260	266		``` pascal
261	267		MainWindow:=QMainWindow_create(nil,QtTool or QtWindowStaysOnTopHint);
262	268
263	269		```
264	270
265	271		## Floating Point Exceptions
266	272
267	273		Throughout the Qt-library, Trolltech does not check for divisions by zero for floating points. No exceptions are generated because FPEs (Floating Point Exceptions) have been disabled. However when you link an FPC program to a library, FPC re-enables FPEs. To solve this the call fedisableexcept(FE_ALL_EXCEPT) was added to Qt4.pas. Otherwise several graphic painting calls would cause exceptions.
268	274
269	275		E.g. a call to QPainter::drawLine() will ultimately lead to a call to qt_tesselate_polygon in qpaintengine_x11.cpp where a division by zero will lead to an exception in the line:
270	276
271	277		``` cpp
272	278		edge.m = (p1.y() - p2.y()) / (p1.x() - p2.x()); // line derivative
273	279
274	280		```
275	281
276	282		## Pascalify Qt Classes
277	283
278	284		### What is the problem
279	285
280	286		The binding allows you to create Qt classes by reference but not by value. Assignment of one Qt class by value to another is impossible, because the pascal compiler does not know the interior of a C++ Qt Class. As this may not be clear, let us make an example.
281	287
282	288		### Example of the problem
283	289
284	290		In C++ you can write:
285	291
286	292		``` cpp
287	293		QColor hourColor(127, 0, 127);
288	294		painter.setBrush(hourColor)
289	295
290	296		```
291	297
292	298		At the end of this procedure you do not have to delete the QColor instance. The binding without pascalify of QColor would force you to write:
293	299
294	300		``` pascal
295	301		var hourColor : QColorH;//*QColor
296	302		hourColor:=QColor_create(127,0,127); //new QColor()
297	303		brush:=QBruh_create(hourColor);
298	304		QColor_destroy(hourColor)
299	305
300	306		```
301	307
302	308		The destroy is rather annoying for small classes like QRect and QColor.
303	309
304	310		### Solution:Pascalify
305	311
306	312		Pascalify means the creation of a pascal record that is binary compatible with the Qt class. Qt classes without a VMT like QColor, QRect or QRectF are easy targets. If you provide a pointer to this record, the C++ compiler will not notice the difference. So now you can simply write
307	313
308	314		``` pascal
309	315		var HourColor : TQColor;// a pascal record type compatible with QColor
310	316		QColor_fromRGB(@hourColor,127,0,127);
311	317		brush:=QBrush_create(@hourColor);
312	318		```
313	319
314	320		Now you do not need to free the QColor so there is less chance for a memory leak.
315	321
316	322		Note: QRect and PRect use the same trick but with some extra adjustments for two reasons:
317	323
318		-	~~`* In macOS the layout of QRect is different than the layout of TRect in pascal.`\~~
319		-	~~`* The TRect definition of LCL is different from Qt, with respect to the inclusion of the right and bottom line.`~~
	324	+	```text
	325	+	* In macOS the layout of QRect is different than the layout of TRect in pascal.
	326	+	* The TRect definition of LCL is different from Qt, with respect to the inclusion of the right and bottom line.
	327	+	```
320	328
321	329		The interface adjust with +1 when going to Qt or with -1 when going to Pascal.
322	330
323	331		Internal code sample for clarity:
324	332
325	333		``` cpp
326	334		inline void copyPRectToQRect(PRect pr, QRect &qr)
327	335		{
328	336		#if defined DARWIN
329	337		qr.setLeft(((QRect *)pr)->top());
330	338		qr.setTop(((QRect *)pr)->left());
331	339		qr.setRight(((QRect *)pr)->bottom()-1);
332	340		qr.setBottom(((QRect *)pr)->right()-1);
333	341		#else
334	342		qr.setLeft(((QRect *)pr)->left());
335	343		qr.setTop(((QRect *)pr)->top());
336	344		qr.setRight(((QRect *)pr)->right()-1);
337	345		qr.setBottom(((QRect *)pr)->bottom()-1);
338	346		#endif
339	347		}
340	348		```
341	349
342	350		# FAQ
343	351
344	352		## I get linker error /usr/bin/ld: cannot find -lQt4Pas
345	353
346	354		The Qt4Pas comes with a library (e.g. under Linux libqt4.so) which must be installed. See installation.
347	355
348	356		---
349	357		From the Free Pascal wiki, page "Qt4 binding", as it stood on 2020-02-23 after a change by Trev, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
350	358		Category: Interfaces
351	359		Category: Qt

Back to history