LCL Defines: what changed

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

Old	New		Line
1	1		This page documents the defines that can be utilized to recompile the different widgetsets of LCL. It isn´t a comprehensive list, but may become one as more defines are added. It also mentions defines that are automatically set when you select various options, such as widgetset, in Lazarus. See Also [[Platform defines]]
2	2
3	3		## Why use defines?
4	4
5	5		Defines allow to add non-standard functionality to LCL, test experimental features or to add debug output that helps testing the widgetsets.
6	6
7	7		The defines are also useful as 'read only' for you to determine, for example, to include particular code on particular platforms. For example -
8	8
9	9		``` pascal
10	10		{$ifdef WINDOWS}
11	11		// do some WINDOWS specific stuff
12	12		{$else}
13	13		// do whatever but only on non-windows platforms
14	14		{$endif}
15	15		```
16	16
17	17		## Recompiling LCL with a define
18	18
19	19		To recompile LCL with a special define go to the Lazarus menu Tools -\> "Configure Build Lazarus". Add there in the Options field:
20	20
21	21		`-d<DEFINE_NAME>`
22	22
23	23		So if you wish to add the PassWin32MessagesToLCL define, you will add
24	24
25	25		`-dPassWin32MessagesToLCL`
26	26
27	27		to this box.
28	28
29	29		## General LCL defines
30	30
31	31		- DEBUG_SHELLCTRLS - Turns on the use of WriteLn to output debug information for the ShellCtrls unit.
32	32
33	33		#### LCL Version
34	34
35	35		Sometimes its necessary to do things differently depending on the LCL (ie Lazarus) version its going to be compiled with. The LCL_FULLVERSION define can be read like this -
36	36
37	37		``` pascal
38	38		{$if (lcl_fullversion >= 2000600)}
39	39		DoSomething(); // only do this for Lazarus 2.0.6 or later
40	40		{$endif}
41	41		```
42	42
43	43		LCL thinks of its versions in that seven digit number:
44	44
45	45		- 2010000 is 2.1.0 or 2.01.00.00
46	46		- 2000600 is 2.0.6 or 2.00.06.00
47	47
48	48		#### PLATFORM
49	49
50	50		You would not normally set one of these, they are set for you when you choose compile options in Lazarus. Useful to read to make platform specific decisions at compile time.
51	51
52	52		- UNIX - eg, Linux, macOS, Ultrix
53	53		- WINDOWS - all MS Windows platforms
54	54		- DARWIN - macOS
55	55
56	56		There are many more ....
57	57
58	58		#### Widget Set
59	59
60	60		You would not normally set one of these, they are set for you when you choose compile options in Lazarus. Useful to read to make widget set specific decisions at compile time.
61	61
62	62		- LCLCOCOA
63	63		- LCLCARBON
64	64		- LCLGTK2
65	65		- LCLGTK3
66	66		- LCLQt (for Qt4)
67	67		- LCLQt5
68	68		- LCLQt6
69	69
70	70		## Win32 defines
71	71
72	72		- DisableWindowsUnicodeSupport - Turns off Unicode support on Windows. The win32 interface gives string in ansi encoding to the LCL (instead of UTF8).
73	73		- DisableVistaDialogs - Turns off Windows Vista (and higher) file dialogs ([IFileDialog](https://learn.microsoft.com/en-us/windows/win32/api/shobjidl_core/nn-shobjidl_core-ifiledialog)) and uses the older style dialogs.
74	74
75	75		## WinCE defines
76	76
77	77		- VerboseWinCE - Turns on the use of writelns to output debug information. Useful in desktop windows to trace bugs which are reproducible in the desktop too.
78	78
79	79		## Gtk defines
80	80
81	81		- LCLGTK2 - Set when you choose the GTK2 widget set. Treat as read only.
82	82
83	83		- LCLGTK3 - Set when you choose the GTK3 widget set. Treat as read only.
84	84
85	85		- DebugLCLComponents - This activates saving information on every creation or destruction of LCL components, device contexts, gdi objects (pen, brush, font, ...) and main widgets. It will spot mem leaks and double frees with stacktraces.
86	86
87	87		- TraceGDICalls - This activates saving information on every creation or destruction of gdi objects (pen, brush, font, ...). It will spot mem leaks and double frees with stacktraces.
88	88
89	89		- GTK2_USE_OLD_CAPTURE - As of lazarus 0.9.29 r27638 we use new way of capturing (TGtk2WidgetSet.SetCapture). Old way can be reached with this define.
90	90
91	91		It's used only for debugging purposes (eg. diff in capturing before old & new code) if some bug is filled against gtk2 capturing.
92	92
93	93		- USE_GTK_MAIN_OLD_ITERATION - As of lazarus 0.9.29 r27896 we use g_main_context* instead of g_main* which is deprecated from gtk2-2.2.
94	94
95	95		This define fixes sending/receiving messages via PostMessage() from other threads than main.Also, we hook g_main_context's poll function to make g_main_context_wakeup accurate.From glib2 \>= 2.24 g_main_context_wakeup is enough, but for smaller versions we need to check if new message arrived (from another thread), and interrupt main_context_iteration. For those who want to use deprecated gtk_main_* there's USE_GTK_MAIN_OLD_ITERATION.
96	96
97	97		- GTK2OLDENUMFONTFAMILIES - As of lazarus 0.9.31 r35400 TGtk2WidgetSet.EnumFontFamiliesEx() does not use raw X11 fonts naming, but pango via fontconfig.
98	98
99	99		Old fashioned font names can be used with this define.
100	100
101	101		- GTK2USEDUMMYNOTEBOOKPAGE - As of lazarus 1.1 svn revision 39882 dummy notebook page isn't used anymore for gtk2 notebook. If some old gtk2 version
102	102
103	103		needs it just use this define and pls. report issue about gtk2 version and needed dummy notebook page.
104	104
105	105		## Qt defines
106	106
107	107		You can use the following defines while building LCL to configure your Qt Interface:
108	108
109	109		- LCLQT - Set when you choose the Qt4 widget set. Treat as read only.
110	110
111	111		- LCLQT5 - Set when you choose the Qt5 widget set. Treat as read only.
112	112
113	113		- VerboseQt - Writes extensive debug information about the creation and deletion of Qt objects and LCL Objects to the StdOut.
114	114
115	115		- VerboseQtWinAPI - Writes extensive debug information about the Qt implementation of the functions on the LCLIntf unit to StdOut.
116	116
117	117		- VerboseQtEvents - Writes extensive debug information about qt events passed via event filter to the StdOut. If defined VerboseQt then this define isn't needed.
118	118
119	119		- VerboseQtWinAPI_MISSING_IMPLEMENTATION - Writes extensive debug information about the MISSING Qt implementation of the functions on the LCLIntf unit to StdOut.
120	120
121	121		- QTOPIA - Build for qtopia/embedded Qt Interface. See also [[Qt4 binding\|Supported Platforms of FreePascal Qt4 binding]].Do not use QTOPIA define (comment it) if you build qt application for eg. Nokia N9 phone (arm) - it's a pure X11 app, so QTOPIA must be off.
122	122
123	123		- QT_NATIVE_DIALOGS - Build with native dialogs (TOpenDialog, TSaveDialog ...). In that case there's no eg. OnFilterChanged() events since Qt uses static functions for native dialogs.
124	124
125	125		- QTDIALOGS_USES_QT_LOOP - As of Lazarus svn r23536 qtlcl uses LCL loop for QDialog and QFileDialog classes (TQtDialog, TQtMessageBox, TQtFileDialog). If you want to use "old" (original Qt way) then you can use this define, and QDialogs should run in it's own loop managed by Qt. This define doesn't do anything in case we use QT_NATIVE_DIALOGS (for TQtFileDialog only).
126	126
127	127		- QT_ENABLE_LCL_PAINT_TABS - as of r25354 used to allow LCL to paint over tabwidget tabs. PaintEvent from tab provides rect in tab coordinates.
128	128
129	129		- QT_DRAWTEXT_MAP_TO_CLIPRECT - there's an issue (fixed already) [1](http://bugs.freepascal.org/view.php?id=17678) about TCanvas.TextRect() with qtlcl. If you enable QT_DRAWTEXT_MAP_TO_CLIPRECT then Qt will paint your text with respect to DT_WORDBREAK (testpaintrect_2.png), otherwise it works like other widgetsets (testpaintrect_1.png).
130	130
131	131		- VerboseQtCustomControlResizeDeadlock - Writes debug information about intercepted deadlocks inside TQtCustomControl when resized.
132	132
133	133		- DebugQtGDIObjects - writes debug info about TQtGdiObjects class (checks validity of HGDIObj in IsValidGDIObject())
134	134
135	135		- QTSCROLLABLEFORMS - Central widgets of forms are QAbstractScrollArea class, this is enabled by default except if the QTCOCOA define is enabled. If you want less CPU/memory intrusive TCustomForms then uncomment this define. In that case we use QWidget as central widget of TCustomForm, but in that case there's no scrollbars in TCustomForm (eg TCustomForm.AutoScroll means nothing, same applies to TCustomForm. Vertical & Horizontal scrollbars.
136	136
137	137		- QTCOCOA - Automatically enabled if we are on DARWIN and CPU=64 bit.If this define is enabled QTSCROLLABLEFORMS is disabled. When QTSCROLLABLEFORMS is enabled with QTCOCOA there are various crashes which aren't fixed yet.
138	138
139	139		- QtUseNativeEventLoop - On non X11 targets we use the Qt native loop instead of the LCL one. Valid only for Qt5 widgetset.
140	140
141	141		### Legacy
142	142
143		-	~~<div class="mw-collapsible mw-collapsed">~~
144		-
145	143		Many Qt defines have become unnecessary, entries moved here for clarity.
146	144
147		-	~~<div class="mw-collapsible-content">~~
148		-
149		-	- <s>USE_QT_4_3 - The default Qt version utilized by the interface is 4.2 or superior. By setting this define you allow the interface to use 4.3+ features, like MDI Forms.</s> - Made default and removed as of 0.9.25
150		-	- <s>QT_HIDDEN_BUTTON_WORKAROUND - This activates a work around for a LCL miss-behavior which makes it create a hidden button to overcome some Gtk problem. This should be removed after LCL is fixed. Link for the bug: <http://www.freepascal.org/mantis/view.php?id=9152> </s>
151		-	- <s>QT_LAZARUS_IDE_WORKAROUND - Activates workaround for invisible mainmenu inside lazarus ide, also moving offsets of TGraphicControl descendants , because geometry of form doesn't take TMainMenu height and TToolbar height into account. This should be removed, as soon as we fix offsets, and accounting of TMainMenu & TToolBar height.</s>
152		-	~~- <s>VerboseQtWinAPI_DEBUG_CLIPBOARD - Writes extensive debug information about LCL clipboard operations.</s>~~
153		-	- <s>QT_NO_MENU_EFFECTS - Turns off menu effects, fading and animating, which sometimes produces problems (eg. stays visible even they are closed). It is also possible that this is an Qt bug, but have to check it first.</s>
154		-	- <s>USE_QT_44 - The default Qt version utilized by the interface is 4.3 or superior. By setting this define you allow the interface to use qt 4.4 features like better QPrinter,QPainter support etc.Also, if you use this define, you must download qt bindings for 4.4 (1.66 or superior).</s> as of lazarus svn r 21913 qt-4.5.X is default (no more USE_QT_XX defines).
155		-	- <s>USE_QT_45 - The default Qt version utilized by the interface is 4.3 or superior. By setting this define you allow the interface to use qt 4.5 features like better QPrinter,QPainter support etc.Also, if you use this define, you must download qt bindings for 4.5 (1.69 or superior).</s> as of lazarus svn r 21913 qt-4.5.X is default (no more USE_QT_XX defines).
156		-	- <s>QTSizeFix - fixes resizing overhead by reducing InvalidateClientRectCache() calls to minimum.Now only TQtPage calls it from resize event. Works ok with -dOldAutoSize and especially with new autosize algorithms.Will be set as default soon (and removed define).</s> as of lazarus svn revision 25065 this is default behaviour, define removed.
157		-
158		-	~~</div>~~
159		-
160		-	~~</div>~~
	145	+	- USE_QT_4_3 - The default Qt version utilized by the interface is 4.2 or superior. By setting this define you allow the interface to use 4.3+ features, like MDI Forms. - Made default and removed as of 0.9.25
	146	+	- QT_HIDDEN_BUTTON_WORKAROUND - This activates a work around for a LCL miss-behavior which makes it create a hidden button to overcome some Gtk problem. This should be removed after LCL is fixed. Link for the bug: <http://www.freepascal.org/mantis/view.php?id=9152>
	147	+	- QT_LAZARUS_IDE_WORKAROUND - Activates workaround for invisible mainmenu inside lazarus ide, also moving offsets of TGraphicControl descendants , because geometry of form doesn't take TMainMenu height and TToolbar height into account. This should be removed, as soon as we fix offsets, and accounting of TMainMenu & TToolBar height.
	148	+	- VerboseQtWinAPI_DEBUG_CLIPBOARD - Writes extensive debug information about LCL clipboard operations.
	149	+	- QT_NO_MENU_EFFECTS - Turns off menu effects, fading and animating, which sometimes produces problems (eg. stays visible even they are closed). It is also possible that this is an Qt bug, but have to check it first.
	150	+	- USE_QT_44 - The default Qt version utilized by the interface is 4.3 or superior. By setting this define you allow the interface to use qt 4.4 features like better QPrinter,QPainter support etc.Also, if you use this define, you must download qt bindings for 4.4 (1.66 or superior). as of lazarus svn r 21913 qt-4.5.X is default (no more USE_QT_XX defines).
	151	+	- USE_QT_45 - The default Qt version utilized by the interface is 4.3 or superior. By setting this define you allow the interface to use qt 4.5 features like better QPrinter,QPainter support etc.Also, if you use this define, you must download qt bindings for 4.5 (1.69 or superior). as of lazarus svn r 21913 qt-4.5.X is default (no more USE_QT_XX defines).
	152	+	- QTSizeFix - fixes resizing overhead by reducing InvalidateClientRectCache() calls to minimum.Now only TQtPage calls it from resize event. Works ok with -dOldAutoSize and especially with new autosize algorithms.Will be set as default soon (and removed define). as of lazarus svn revision 25065 this is default behaviour, define removed.
161	153
162	154		## Carbon defines
163	155
164	156		List of Carbon defines used to show debug info when tracing:
165	157
166	158		- DebugEventLoop
167	159		- VerboseObject - Carbon interface application
168	160		- VerboseTimer
169	161		- VerboseWinAPI
170	162		- VerboseLCLIntf
171	163		- VerboseMouse
172	164		- VerboseCursor
173	165		- VerboseKeyboard
174	166		- VerbosePaint
175	167		- VerboseCanvas
176	168		- VerboseMenu
177	169		- VerboseScroll
178	170		- VerboseWidget - TCarbonWidget class
179	171		- VerboseAppEvent - Carbon application event handlers
180	172		- VerboseControlEvent - Carbon control event handlers
181	173		- VerboseWindowEvent - Carbon window event handlers
182	174		- VerboseCommonEvent - Carbon common event handlers
183	175		- VerboseWSClass - TCarbonWS classes
184	176		- VerboseCarbonTrayIcon - TCarbonWSTrayIcon verbose mode
185	177
186	178		Other defines:
187	179
188	180		- CarbonUseCocoa - Activates using Cocoa controls. Removed in Lazarus 0.9.29
189	181		- CarbonDontUseCocoa - Deactivates using Cocoa controls. Added in Lazarus 0.9.29
190	182		- CarbonUsePrivateAPIs - Activates using _NSGetCarbonMenu in TTrayIcon. Not very useful at the moment.
191	183
192	184		## FPC Optimization Defines
193	185
194	186		There are also a number of defines possible that apply to the FP Compiler - see [[Optimization\|Optimization in Code]]
195	187
196	188		## See Also
197	189
198	190		[Free Pascal Compiler Documentation - Compiler defines during compilation](https://www.freepascal.org/docs-html/prog/progap7.html) such as CPU, Platform, compiler ability etc.
199	191
200	192		---
201	193		From the Free Pascal wiki, page "LCL Defines", as it stood on 2024-01-26 after a change by Alextpp, 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).
202	194		Category: LCL

Back to history