LCL Internals: what changed

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

Old	New		Line
1	1		------------------------------------------------------------------------
2	2
3	3		> Note: This document is work in progress. You can help by writing sections of this document. If you cannot find the information you are looking for in this document, please add your question to the discussion page. This will help us to write documentation at a level that is neither too simple nor too complicated, and fully cover the areas that people want to know about.
4	4
5	5		------------------------------------------------------------------------
6	6
7	7		## Internals of the LCL
8	8
9	9		There is the LCL, and the "interface". The LCL is the part that is platform independent, and it resides in the lazarus/lcl/ directory. This directory contains mainly class definitions. Many of the different controls are actually implemented in the lazarus/lcl/include/ directory in the various .inc files. This is to find the implementation of a specific control, TCustomMemo for example, faster (which is in custommemo.inc). Every .inc starts with a line {%MainUnit ...} to define where it is included.
10	10
11	11		Then there is the "interface" which lives in a subdirectory of the lazarus/lcl/interfaces/ directory. The gtk interface is in gtk/, win32 in win32/, etc. They all have a Interfaces unit, which is used by the lcl and creates the main interface object. Usually the main interface object is defined in XXint.pp (win32int.pp), and implemented in various inc files, XXobject.inc, for the interface specific methods, XXwinapi.inc for winapi implementation methods, XXlistsl.inc for implementation of the stringlist used by the TComboBox, TListBox, and other such controls, XXcallback.inc for handling of widget events and taking appropriate action to notify the LCL.
12	12
13	13		Every control has a WidgetSetClass property which is of the 'mirror' class in the interfaces directory, for example: mirror of TCustomEdit is TWSCustomEdit, which methods are implemented by TWin32WSCustomEdit in win32wsstdctrls. This is the way the LCL communicates with the interface, and how it lets the interface do things.
14	14
15	15		Communication of interface back to LCL is mostly done by sending messages, usually 'DeliverMessage' which calls TControl.Perform(\<message_id\>, wparam, lparam) with wparam and lparam being the extra info for the message.
16	16
17	17		### Pie and RadialPie
18	18
19	19		The LCLIntf unit contains two functions to draw pie-shapes:
20	20
21		-	~~`function `[[doc:lcl/lclintf/pie.html\|Pie]]`(DC: HDC; x1, y1, x2, y2, sx, sy, ex, ey: Integer): Boolean;`\~~
22		-	~~`function `[[doc:lcl/lclintf/radialpie.html\|RadialPie]]`(DC: HDC; x1, y1, x2, y2, Angle1, Angle2: Integer): Boolean; `~~
	21	+	``` pascal
	22	+	function Pie(DC: HDC; x1, y1, x2, y2, sx, sy, ex, ey: Integer): Boolean;
	23	+	function RadialPie(DC: HDC; x1, y1, x2, y2, Angle1, Angle2: Integer): Boolean;
	24	+	```
23	25
24	26		The Pie function uses a two points (sx,sy) and (ex,ey) to indicate start and end of the arc. RadialPie uses Angles to indicate start and end of the arc.
25	27
26	28		Pie calls TWidgetSet.Pie and RadialPie calls TWidgetSet.RadialPie. The default implementation of TWidgetSet.Pie is to convert the parameters to angles and to call TWidgetSet.RadialPie. TWidgetSet.RadialPie creates an array of points for the arc and calls TWidgetSet.Polygon.
27	29
28	30		The win32 widgetset overrides TWidgetSet.Pie to call the Windows Pie function directly.
29	31
30	32		> Note: in older versions of Lazarus there existed RadialPie with angles which did the same as the current RadialPie and RadialPie, which does the same as our Pie. Those functions have been removed in Lazarus 0.9.21.
31	33
32	34		### Adding a new unit to the LCL
33	35
34	36		First add the new unit name into allclunits.pp.
35	37
36	38		To make sure the unit is registered in the components palette see the files RegisterLCL.pas and pkgfileslcl.inc, they are located in lazarus/packager.
37	39
38	40		## How to create a new Widgetset
39	41
40	42		This is a step-by-step tutorial of developing a new [[Widgetset\|widgetset]]. It is based on my experience creating the basics of the new qt4 interface.
41	43
42	44		To start with, why would someone want to add an Widgetset? The answer is to be able to port existing lazarus software to more platforms, without modifying their code.
43	45
44	46		Now, let´s write the widgetset. First of all, you need to have pascal bindings for the widget and know how to use it. Normally this is not hard. A few hours doing basic tutorials available on the internet should be enougth to get started. If the bindings do not exist already, you need to create them. If the tutorials are on another language, translate them to pascal and make them work.
45	47
46	48		Now, for Qt I utilized Den Jean qt4 bindings for pascal, and created a very basic Qt program using them:
47	49
48	50		``` pascal
49	51		program qttest;
50	52
51	53		uses qt4;
52	54
53	55		var
54	56		App: QApplicationH;
55	57		MainWindow: QMainWindowH;
56	58		begin
57	59		App := QApplication_Create(@argc,argv);
58	60
59	61		MainWindow := QMainWindow_Create;
60	62
61	63		QWidget_show(MainWindow);
62	64
63	65		QApplication_Exec;
64	66		end.
65	67		```
66	68
67	69		The above project compiles and creates a qt4 program. Now we will use its code to write a new widgetset. After we are done, the lazarus program below will compile fine into a qt4 software:
68	70
69	71		``` pascal
70	72		program qttest;
71	73
72	74		{$mode objfpc}{$H+}
73	75
74	76		uses
75	77		Interfaces, Classes, Forms,
76	78		{ Add your units here }
77	79		qtform;
78	80
79	81		begin
80	82		Application.Initialize;
81	83		Application.CreateForm(TForm1, Form1);
82	84		Application.Run;
83	85		end.
84	86		```
85	87
86	88		Where the form is maintained by Lazarus IDE and designed visually.
87	89
88	90		The first thing to do on a new widgetset is add an empty skeleton for it. Very early development widgetsets, like qt and carbon, can serve as an skeleton.
89	91
90	92		Looking at the files on the many widgets you can see the first file to be called by the lcl: Interfaces.pas This file just calls another called QtInt.pas or similar. QtInt.pas has the code for the TWidgetSet class, which we must implement. On an empty skeleton you can see that the class has various functions it must implement:
91	93
92	94		``` pascal
93	95		TQtWidgetSet = Class(TWidgetSet)
94	96		private
95	97		App: QApplicationH;
96	98		public
97	99		{$I qtwinapih.inc}
98	100		{$I qtlclintfh.inc}
99	101		public
100	102		// Application
101	103		procedure AppInit(var ScreenInfo: TScreenInfo); override;
102	104		procedure AppRun(const ALoop: TApplicationMainLoop); override;
103	105		procedure AppWaitMessage; override;
104	106		procedure AppProcessMessages; override;
105	107		procedure AppTerminate; override;
106	108		procedure AppMinimize; override;
107	109		procedure AppBringToFront; override;
108	110		public
109	111		constructor Create;
110	112		destructor Destroy; override;
111	113		function DCGetPixel(CanvasHandle: HDC; X, Y: integer): TGraphicsColor; override;
112	114		procedure DCSetPixel(CanvasHandle: HDC; X, Y: integer; AColor: TGraphicsColor); override;
113	115		procedure DCRedraw(CanvasHandle: HDC); override;
114	116		procedure SetDesigning(AComponent: TComponent); override;
115	117
116	118		function InitHintFont(HintFont: TObject): Boolean; override;
117	119
118	120		// create and destroy
119	121		function CreateComponent(Sender : TObject): THandle; override; // deprecated
120	122		function CreateTimer(Interval: integer; TimerFunc: TFNTimerProc): integer; override;
121	123		function DestroyTimer(TimerHandle: integer): boolean; override;
122	124		end;
123	125		```
124	126
125	127		### How to implement a new windowed component
126	128
127	129		Windowed components are all descendents from TWinControl. Those controls have a Handle and thus, should be created by the Widgetset. It's easy to add new windowed components to a widgetset.
128	130
129	131		Let's say you want to add TQtWSCustomEdit to Qt Widgetset. To start with TCustomEdit is a descendent of TWinControl and is located on the StdCtrls unit.
130	132
131	133		Now, go to QtWSStrCtrls unit and look for the declaration of TQtWSCustomEdit.
132	134
133	135		``` pascal
134	136
135	137		TQtWSCustomEdit = class(TWSCustomEdit)
136	138		private
137	139		protected
138	140		public
139	141		end;
140	142		```
141	143
142	144		Add static methods that are declared on TWSCustomEdit and override them. The code should now look like this:
143	145
144	146		``` pascal
145	147
146	148		TQtWSCustomEdit = class(TWSCustomEdit)
147	149		private
148	150		protected
149	151		public
150	152		class function CreateHandle(const AWinControl: TWinControl;
151	153		const AParams: TCreateParams): HWND; override;
152	154		class procedure DestroyHandle(const AWinControl: TWinControl); override;
153	155		{ class function GetSelStart(const ACustomEdit: TCustomEdit): integer; override;
154	156		class function GetSelLength(const ACustomEdit: TCustomEdit): integer; override;
155	157
156	158		class procedure SetCharCase(const ACustomEdit: TCustomEdit; NewCase: TEditCharCase); override;
157	159		class procedure SetEchoMode(const ACustomEdit: TCustomEdit; NewMode: TEchoMode); override;
158	160		class procedure SetMaxLength(const ACustomEdit: TCustomEdit; NewLength: integer); override;
159	161		class procedure SetPasswordChar(const ACustomEdit: TCustomEdit; NewChar: char); override;
160	162		class procedure SetReadOnly(const ACustomEdit: TCustomEdit; NewReadOnly: boolean); override;
161	163		class procedure SetSelStart(const ACustomEdit: TCustomEdit; NewStart: integer); override;
162	164		class procedure SetSelLength(const ACustomEdit: TCustomEdit; NewLength: integer); override;
163	165
164	166		class procedure GetPreferredSize(const AWinControl: TWinControl;
165	167		var PreferredWidth, PreferredHeight: integer); override;}
166	168		end;
167	169		```
168	170
169	171		The commented part of the code are procedures you need to implement for TCustomEdit to be fully functional, but just CreateHandle and DestroyHandle should be enough for it to be show on the form and be editable, so it fits our needs in this article.
170	172
171	173		Hit CTRL+SHIFT+C to code complete and the implement CreateHandle and DestroyHandle. In the case of Qt4 the code will be like this:
172	174
173	175		``` pascal
174	176		{ TQtWSCustomEdit }
175	177
176	178		class function TQtWSCustomEdit.CreateHandle(const AWinControl: TWinControl;
177	179		const AParams: TCreateParams): HWND;
178	180		var
179	181		Widget: QWidgetH;
180	182		Str: WideString;
181	183		begin
182	184		// Creates the widget
183	185		WriteLn('Calling QTextDocument_create');
184	186		Str := WideString((AWinControl as TCustomMemo).Lines.Text);
185	187		Widget := QTextEdit_create(@Str, QWidgetH(AWinControl.Parent.Handle));
186	188
187	189		// Sets it's initial properties
188	190		QWidget_setGeometry(Widget, AWinControl.Left, AWinControl.Top,
189	191		AWinControl.Width, AWinControl.Height);
190	192
191	193		QWidget_show(Widget);
192	194
193	195		Result := THandle(Widget);
194	196		end;
195	197
196	198		class procedure TQtWSCustomEdit.DestroyHandle(const AWinControl: TWinControl);
197	199		begin
198	200		QTextEdit_destroy(QTextEditH(AWinControl.Handle));
199	201		end;
200	202		```
201	203
202	204		Now uncomment the like "RegisterWSComponent(TCustomEdit, TQtWSCustomEdit);" on the bottom of the unit and that's it!
203	205
204	206		You can now drop a TCustomEdit on the bottom of a form and expect it to work. :^)
205	207
206	208		### Implementing TBitmap
207	209
208	210		To implement TBitmap it is necessary to understand TRawImage and TLazIntfImage as explained here: [[Developing with Graphics\|Developing with Graphics#Working with TLazIntfImage.2C TRawImage and TLazCanvas]]
209	211
210	212		So, let's say you want to compile the following code:
211	213
212	214		``` pascal
213	215		procedure TMyForm.HandleOnPaint(Sender: TObject);
214	216		var
215	217		Bitmap: TBitmap;
216	218		begin
217	219		Bitmap := TBitmap.Create;
218	220		try
219	221		Bitmap.LoadFromFile('myfile.bmp');
220	222		Canvas.Draw(0, 0, Bitmap);
221	223		finally
222	224		Bitmap.Free;
223	225		end;
224	226		end;
225	227		```
226	228
227	229		Below is the order on which functions from the widgetset interface are called when executing that code:
228	230
229	231		1 - BeginPaint
230	232
231	233		This will be called only if the OnPaint event sends zero as the DC for the paint event
232	234
233	235		2 - GetDC(0);
234	236
235	237		Just create a device context.
236	238
237	239		3 - TCDWidgetSet.RawImage_QueryDescription
238	240
239	241		The default implementation of this routine is good for most widgetsets
240	242
241	243		4 - TCDWidgetSet.RawImage_CreateBitmaps
242	244
243	245		Here you need to create a native image object and load it from RawData.Data where the information is stored based on your description of the pixel format on item 2.
244	246
245	247		5 - CreateCompatibleDC(0)
246	248
247	249		This creates a temporary DC just to store the image, but at this point there is no information about the image so at this point this DC is really dummy
248	250
249	251		6 - SelectObject
250	252
251	253		With the image as the object to be selected and the DC just created above as target DC.
252	254
253	255		7 - StretchMaskBlt
254	256
255	257		Finally the drawing function! DestDC is the DC allocated on BeginPaint.
256	258
257	259		8 - EndPaint
258	260
259	261		Again, not always utilized.
260	262
261	263		### TBitmap.LoadFromDevice for screenshot taking
262	264
263	265		It is recomended that you first implement TBitmap before trying this step.
264	266
265	267		On LCL you can use the following code takes a screenshot from the entire screen and paints it on the canvas:
266	268
267	269		``` pascal
268	270		var
269	271		ScreenDC: HDC;
270	272		Bitmap: TBitmap;
271	273		begin
272	274		Bitmap := TBitmap.Create;
273	275		try
274	276		ScreenDC := GetDC(0);
275	277		Bitmap.LoadFromDevice(ScreenDC);
276	278		ReleaseDC(0, ScreenDC);
277	279		Canvas.Draw(0, 0, Bitmap);
278	280		finally
279	281		Bitmap.Free;
280	282		end;
281	283		end;
282	284		```
283	285
284	286		If you already implemented TBitmap, there are only 2 new functions to be implemented for LoadFromDevice: GetDeviceSize and GetRawImageFromDevice
285	287
286	288		Below is a big trace, covering all widgetset functions being called on a OnPaint event that takes a screenshot and paints it on the screen. This trace was taken with Qt widgetset, and may have some imperfections. The Handle numbers should be used to check which object is being utilized on the functions.
287	289
288		-	~~` [WinAPI BeginPaint] Result=-1220713544`\~~
289		-	~~` [WinAPI GetClientBounds]`\~~
290		-	~~` [WinAPI SetWindowOrgEx] DC: -1220713544 NewX: 0 NewY: 0`~~
	290	+	```text
	291	+	[WinAPI BeginPaint] Result=-1220713544
	292	+	[WinAPI GetClientBounds]
	293	+	[WinAPI SetWindowOrgEx] DC: -1220713544 NewX: 0 NewY: 0
	294	+	```
291	295
292	296		\<syntaxhighlight lang="pascal\> //Enters on Paint event
293	297
294	298		Bitmap := TBitmap.Create; try
295	299
296	300		` ScreenDC := GetDC(0);`
297	301
298		-	~~` [WinAPI GetDC] hWnd: 0 Result: -1220712920`~~
	302	+	```text
	303	+	[WinAPI GetDC] hWnd: 0 Result: -1220712920
	304	+	```
299	305
300	306		``` pascal
301	307		Bitmap.LoadFromDevice(ScreenDC);
302	308		```
303	309
304		-	~~` [WinAPI GetDeviceSize]`\~~
305		-	~~` [WinAPI GetRawImageFromDevice] SrcDC: -1220712920 SrcWidth: 0 SrcHeight: 0`\~~
306		-	~~` [WinAPI CreateBitmapFromRawImage] Width:1024 Height:768 DataSize: 3145728 CreateMask: False Bitmap:-1220746696`\~~
307		-	~~` [WinAPI GetObject] GDIObj: -1220746696 Result=84 ObjectType=Image`~~
	310	+	```text
	311	+	[WinAPI GetDeviceSize]
	312	+	[WinAPI GetRawImageFromDevice] SrcDC: -1220712920 SrcWidth: 0 SrcHeight: 0
	313	+	[WinAPI CreateBitmapFromRawImage] Width:1024 Height:768 DataSize: 3145728 CreateMask: False Bitmap:-1220746696
	314	+	[WinAPI GetObject] GDIObj: -1220746696 Result=84 ObjectType=Image
	315	+	```
308	316
309	317		``` pascal
310	318		ReleaseDC(0, ScreenDC);
311	319		```
312	320
313		-	~~` [WinAPI ReleaseDC] hWnd: 0 DC: -1220712920`~~
	321	+	```text
	322	+	[WinAPI ReleaseDC] hWnd: 0 DC: -1220712920
	323	+	```
314	324
315	325		``` pascal
316	326		Canvas.Draw(0, 0, Bitmap);
317	327		```
318	328
319		-	~~` [WinAPI CreateCompatibleDC] DC: 0`\~~
320		-	~~` [WinAPI GetDC] hWnd: 0 Result: -1220712920`\~~
321		-	~~` [WinAPI SelectObject] DC=-1220712920 GDIObj=-1220746696 Result=0 ObjectType=Image`\~~
322		-	~~` [WinAPI StretchMaskBlt] DestDC:-1220713544 SrcDC:-1220712920 Image:137185120 X:0 Y:0 W:1024 H:768 XSrc:0 YSrc:0 WSrc:1024 HSrc:768`~~
	329	+	```text
	330	+	[WinAPI CreateCompatibleDC] DC: 0
	331	+	[WinAPI GetDC] hWnd: 0 Result: -1220712920
	332	+	[WinAPI SelectObject] DC=-1220712920 GDIObj=-1220746696 Result=0 ObjectType=Image
	333	+	[WinAPI StretchMaskBlt] DestDC:-1220713544 SrcDC:-1220712920 Image:137185120 X:0 Y:0 W:1024 H:768 XSrc:0 YSrc:0 WSrc:1024 HSrc:768
	334	+	```
323	335
324	336		``` pascal
325	337		finally
326	338		Bitmap.Free;
327	339		end;
328	340		```
329	341
330		-	~~` [WinAPI SelectObject] DC=-1220712920 GDIObj=0 Invalid GDI Object`\~~
331		-	~~` [WinAPI DeleteObject] GDIObject: -1220746696 Result=False ObjectType=Image`~~
	342	+	``` pascal
	343	+	[WinAPI SelectObject] DC=-1220712920 GDIObj=0 Invalid GDI Object
	344	+	[WinAPI DeleteObject] GDIObject: -1220746696 Result=False ObjectType=Image
	345	+	```
332	346
333	347		Now exited the OnPaint event
334	348
335		-	~~` [WinAPI DeleteObject] GDIObject: 0`\~~
336		-	~~` [WinAPI DeleteObject] GDIObject: 0`\~~
337		-	~~` [WinAPI DeleteObject] GDIObject: 0`\~~
338		-	~~` [WinAPI DeleteObject] GDIObject: 0`\~~
339		-	~~` [WinAPI SetWindowOrgEx] DC: -1220713544 NewX: -152 NewY: -246`\~~
340		-	~~` [WinAPI DeleteObject] GDIObject: 0`\~~
341		-	~~` [WinAPI DeleteObject] GDIObject: 0`\~~
342		-	~~` [WinAPI DeleteObject] GDIObject: 0`\~~
343		-	~~` [WinAPI DeleteObject] GDIObject: 0`~~
	349	+	```text
	350	+	[WinAPI DeleteObject] GDIObject: 0
	351	+	[WinAPI DeleteObject] GDIObject: 0
	352	+	[WinAPI DeleteObject] GDIObject: 0
	353	+	[WinAPI DeleteObject] GDIObject: 0
	354	+	[WinAPI SetWindowOrgEx] DC: -1220713544 NewX: -152 NewY: -246
	355	+	[WinAPI DeleteObject] GDIObject: 0
	356	+	[WinAPI DeleteObject] GDIObject: 0
	357	+	[WinAPI DeleteObject] GDIObject: 0
	358	+	[WinAPI DeleteObject] GDIObject: 0
	359	+	```
344	360
345	361		``` pascal
346	362		TWidgetSet.InitializeCriticalSection
347	363		TWidgetSet.EnterCriticalSection
348	364		```
349	365
350		-	~~` [WinAPI SelectObject] DC=-1220713544 GDIObj=0 Invalid GDI Object`\~~
351		-	~~` [WinAPI MoveToEx] DC:-1220713544 X:0 Y:0`\~~
352		-	~~` [WinAPI SelectObject] DC=-1220713544 GDIObj=-1220746760 Result=-1220746856 ObjectType=Brush`\~~
353		-	~~` [WinAPI SelectObject] DC=-1220713544 GDIObj=-1220746856 Result=-1220746856 ObjectType=Brush`~~
	366	+	``` pascal
	367	+	[WinAPI SelectObject] DC=-1220713544 GDIObj=0 Invalid GDI Object
	368	+	[WinAPI MoveToEx] DC:-1220713544 X:0 Y:0
	369	+	[WinAPI SelectObject] DC=-1220713544 GDIObj=-1220746760 Result=-1220746856 ObjectType=Brush
	370	+	[WinAPI SelectObject] DC=-1220713544 GDIObj=-1220746856 Result=-1220746856 ObjectType=Brush
	371	+	```
354	372
355	373		``` pascal
356	374		TWidgetSet.LeaveCriticalSection
357	375		```
358	376
359		-	~~` [WinAPI SetWindowOrgEx] DC: -1220713544 NewX: 0 NewY: 0`\~~
360		-	~~` [WinAPI EndPaint] Handle: -1220611768 PS.HDC: -1220713544`~~
	377	+	```text
	378	+	[WinAPI SetWindowOrgEx] DC: -1220713544 NewX: 0 NewY: 0
	379	+	[WinAPI EndPaint] Handle: -1220611768 PS.HDC: -1220713544
	380	+	```
361	381
362	382		### Implementing drawing in the OnPaint event of a form or another control
363	383
364	384		For drawing in the OnPaint event of a form, the event itself comes from the underlaying widgetset library. The LCL interface should handle this event and create an appropriate DC object on the event handler and then call LCLSendPaintMsg. Besides that one should also implement the corresponding drawing methods, such as Rectangle or ExtTextOut. Pen, Brush and Font related routines might also be useful.
365	385
366	386		Here is the OnPaint event handler from the Cocoa widgetset which shows how it calls LCLSentPaintMsg:
367	387
368	388		``` pascal
369	389		procedure TLCLCommonCallback.Draw(ControlContext: NSGraphicsContext;
370	390		const bounds, dirty:NSRect);
371	391		var
372	392		struct : TPaintStruct;
373	393		begin
374	394		if not Assigned(Context) then Context:=TCocoaContext.Create;
375	395
376	396		Context.ctx:=ControlContext;
377	397		if Context.InitDraw(Round(bounds.size.width), Round(bounds.size.height)) then
378	398		begin
379	399		FillChar(struct, SizeOf(TPaintStruct), 0);
380	400		struct.hdc := HDC(Context);
381	401		{$IFDEF VerboseWinAPI}
382	402		DebugLn(Format('[TLCLCommonCallback.Draw] OnPaint event started context: %x', [HDC(context)]));
383	403		{$ENDIF}
384	404		LCLSendPaintMsg(Target, HDC(Context), @struct);
385	405		{$IFDEF VerboseWinAPI}
386	406		DebugLn('[TLCLCommonCallback.Draw] OnPaint event ended');
387	407		{$ENDIF}
388	408		end;
389	409		end;
390	410		```
391	411
392	412		And a list of WinAPI routines which were called when running this event:
393	413
394	414		[TCocoaWidgetSet.GetDC] hWnd: 0 Result: 12400C0
395	415		[TLCLCommonCallback.Draw] OnPaint event started context: 1240340
396	416		TCocoaWidgetSet.CreatePenIndirect
397	417		TCocoaWidgetSet.SelectObject DC: 1240340 GDIObj: 10EC460
398	418		TCocoaWidgetSet.SelectObject Result: 0
399	419		TCocoaWidgetSet.SelectObject DC: 1240340 GDIObj: 10EBF00
400	420		TCocoaWidgetSet.SelectObject Result: 0
401	421		[TCocoaWidgetSet.Rectangle] DC: 1240340 X1: 100 Y1: 100 X2: 200 Y2: 200
402	422		TCocoaWidgetSet.SelectObject DC: 1240340 GDIObj: 10EC4A0
403	423		TCocoaWidgetSet.SelectObject Result: 0
404	424		[TCocoaWidgetSet.GetTextExtentPoint] DC: 1240340 Str: Some text Count: 9
405	425		[TCocoaWidgetSet.GetTextExtentPoint] Size: 65,17
406	426		[TLCLCommonCallback.Draw] OnPaint event ended
407	427
408	428		### Implementing TLabel
409	429
410	430		Implementing TLabel is particularly hard, despite it being such a basic component, because it requires that almost all painting be implemented. TLabel is not a windowed control, instead it depends on paint messages to be drawn directly into the form canvas.
411	431
412	432		Before trying to get TLabel working it is recomended to test if drawing functions such as Rectangle work inside a form's OnPaint event.
413	433
414	434		Several WinAPI methods need to be implemented, particularly:
415	435
416	436		Device Context Methods
417	437
418	438		BeginPaint, GetDC, EndPaint, ReleaseDC, CreateCompatibleDC
419	439
420	440		see [[Device Contexts and GDI objects in the LCL interfaces]]
421	441
422	442		GDI Objects Methods
423	443
424	444		SelectObject, DeleteObject, CreateFontIndirect, CreateFontIndirectEx
425	445
426	446		Miscelaneous functions
427	447
428	448		InvalidateRect, GetClientBounds, SetWindowOrgEx
429	449
430	450		Text drawing Methods
431	451
432	452		DrawText. Instead of implementing DrawText one can also use the default TWidgetSet.DrawText, like the Carbon and Cocoa widgetsets do. But in this case it is necessary that one implements at least GetTextMetrics, GetTextExtentPoint and ExtTextOut. Without GetTextMetrics a form with a label will crash because the autosize will not be able to calculate the appropriate size for the label.
433	453
434	454		Region functions to determine if the control is behind another
435	455
436	456		CombineRgn, CreateRectRgn, GetClipRGN, RectVisible
437	457
438	458		Below is the order in which paint procedures are called on a form with only one TLabel, to better understand the painting sequence:
439	459
440	460		1 - GetDC is called once on software startup with hWnd = 0
441	461
442	462		2 - The form is shown
443	463
444	464		3 - GetDC is called again (this wouldn't happen without the label). A few font related functions are called, as well as DrawText with CalcRect set to True to calculate the size of the label.
445	465
446	466		4 - InvalidateRect is called on the form canvas
447	467
448	468		5 - Control goes back to the operating system until a paint message comes from the widgetset
449	469
450	470		6 - BeginPaint is called, and at this point code on OnPaint event of the form will be executed
451	471
452	472		7 - DrawText is called again with CalcRect set to false
453	473
454	474		8 - The Painting ends.
455	475
456	476		### Implementing visibility for forms and controls and window state
457	477
458	478		The code that controls visibility is split between visibility for forms, and for controls
459	479
460	480		Visibility for forms and window state
461	481
462	482		This part also controls the state of the window (minimized, maximized or normal). It is implemented as a copy of the Windows API function ShowWindow, so you must implemente the TMyWidgetset.ShowWindow on the file mywinapi.inc Don´t forget to also add a header to the file mywinapih.inc
463	483
464	484		Below is code that implements this function on the Qt widgetset. It should be very easy to understand, copy and implement on your own widgetset. You can also take a look how Gtk implements this. On Windows, the Windows API is called directly, of course, so there is no code to look at.
465	485
466	486		``` pascal
467	487		{------------------------------------------------------------------------------
468	488		function ShowWindow(hWnd: HWND; nCmdShow: Integer): Boolean;
469	489
470	490		nCmdShow:
471	491		SW_SHOWNORMAL, SW_MINIMIZE, SW_SHOWMAXIMIZED
472	492		------------------------------------------------------------------------------}
473	493		function TQtWidgetSet.ShowWindow(hWnd: HWND; nCmdShow: Integer): Boolean;
474	494		var
475	495		Widget: QWidgetH;
476	496		begin
477	497		{$ifdef VerboseQtWinAPI}
478	498		WriteLn('WinAPI ShowWindow');
479	499		{$endif}
480	500
481	501		Result := False;
482	502
483	503		Widget := QWidgetH(hWnd);
484	504
485	505		// if Widget = nil then RaiseException('TQtWidgetSet.ShowWindow hWnd is nil');
486	506
487	507		case nCmdShow of
488	508
489	509		SW_SHOW: QWidget_setVisible(Widget, True);
490	510
491	511		SW_SHOWNORMAL: QWidget_showNormal(Widget);
492	512
493	513		SW_MINIMIZE: QWidget_setWindowState(Widget, QtWindowMinimized);
494	514
495	515		SW_SHOWMINIMIZED: QWidget_showMinimized(Widget);
496	516
497	517		SW_SHOWMAXIMIZED: QWidget_showMaximized(Widget);
498	518
499	519		SW_HIDE: QWidget_setVisible(Widget, False);
500	520
501	521		end;
502	522
503	523		Result := True;
504	524		end;
505	525		```
506	526
507	527		Visibility for controls
508	528
509	529		For controls inside a form you need to implement TMyWSWinControl.ShowHide class function that resides on the TMyWSWinControl class on the file mywscontrols.pp
510	530
511	531		Remember that most controls are descendent from TWinControl, so implementing this function there will guarantee that the Visible property is implemented for all standard controls that have it. Below is a sample code for Qt widgetset.
512	532
513	533		``` pascal
514	534		{------------------------------------------------------------------------------
515	535		Method: TQtWSWinControl.ShowHide
516	536		Params: AWinControl - the calling object
517	537
518	538		Returns: Nothing
519	539
520	540		Shows or hides a widget.
521	541		------------------------------------------------------------------------------}
522	542		class procedure TQtWSWinControl.ShowHide(const AWinControl: TWinControl);
523	543		begin
524	544		if AWinControl = nil then exit;
525	545
526	546		if not AWinControl.HandleAllocated then exit;
527	547
528	548		if AWinControl.HandleObjectShouldBeVisible then
529	549		QWidget_setVisible(TQtWidget(AWinControl.Handle).Widget, True)
530	550		else QWidget_setVisible(TQtWidget(AWinControl.Handle).Widget, False);
531	551		end;
532	552		```
533	553
534	554		### Implementing TStrings based Components
535	555
536	556		Some components use a TStrings to store the information they display, such as: TCustomMemo, TCustomListBox and TCustomComboBox.
537	557
538	558		To implement those it is not enougth to only implement their functions on the TQtCustomMemo class for example. One of the functions to implement will be called GetStrings, which looks like this:
539	559
540	560		``` pascal
541	561		class function TQtWSCustomListBox.GetStrings(const ACustomListBox: TCustomListBox): TStrings;
542	562		var
543	563		ListWidgetH: QListWidgetH;
544	564		begin
545	565		ListWidgetH := QListWidgetH((TQtWidget(ACustomListBox.Handle).Widget));
546	566		Result := TQtListStrings.Create(ListWidgetH, ACustomListBox);
547	567		end;
548	568		```
549	569
550	570		This function must return a TStrings descendent designed to detect when strings are added to or removed from the string list and to send this information to the widgetset to update the control. For example, the following declaration shows what TQtListStrings looks like:
551	571
552	572		``` pascal
553	573
554	574		TQtListStrings = class(TStrings)
555	575		private
556	576		FListChanged: Boolean; // StringList and QtListWidget out of sync
557	577		FStringList: TStringList; // Holds the items to show
558	578		FQtListWidget: QListWidgetH; // Qt Widget
559	579		FOwner: TWinControl; // Lazarus Control Owning ListStrings
560	580		FUpdating: Boolean; // We're changing Qt Widget
561	581		procedure InternalUpdate;
562	582		procedure ExternalUpdate(var Astr: TStringList; Clear: Boolean = True);
563	583		procedure IsChanged; // OnChange triggered by program action
564	584		protected
565	585		function GetTextStr: string; override;
566	586		function GetCount: integer; override;
567	587		function Get(Index : Integer) : string; override;
568	588		//procedure SetSorted(Val : boolean); virtual;
569	589		public
570	590		constructor Create(ListWidgetH : QListWidgetH; TheOwner: TWinControl);
571	591		destructor Destroy; override;
572	592		procedure Assign(Source : TPersistent); override;
573	593		procedure Clear; override;
574	594		procedure Delete(Index : integer); override;
575	595		procedure Insert(Index : integer; const S: string); override;
576	596		procedure SetText(TheText: PChar); override;
577	597		//procedure Sort; virtual;
578	598		public
579	599		//property Sorted: boolean read FSorted write SetSorted;
580	600		property Owner: TWinControl read FOwner;
581	601		function ListChangedHandler(Sender: QObjectH; Event: QEventH): Boolean; cdecl;
582	602		end;
583	603		```
584	604
585	605		You can see its implementation in the qtobjects.pas unit of the qt interface
586	606
587	607		### Implementing Menus
588	608
589	609		Menus are available on the LCL to create main menus or popup menus. A TMenu is the owner of a larger menu structure with many items. Items can have subitems, and don't need extra TMenus.
590	610
591	611		Also remember that on LCL the handle is only created when needed and at that time all properties of the controls are already initialized. This helps a lot on widgetsets where depending on the properties of a menu item it can be of one class or another, like Qt.
592	612
593	613		The following things need to be implemented in order for the menus to work:
594	614
595	615		1\) All methods on the QtWSMenus unit, which will implement menu creation and modification
596	616
597	617		2\) function TWinCEWidgetSet.SetMenu(AWindowHandle: HWND; AMenuHandle: HMENU): Boolean; from the wincewinapi.inc file, which will implement support for a main menu associated with a window.
598	618
599	619		#### Menu Creation Order
600	620
601	621		One important thing to understand when implementing menus, is in which order they are created. For example, we want to create the following menu structure:
602	622
603	623		![](/wiki-images/6/69/Menu_creation_order.png)
604	624
605	625		And when our application is executed, there will be a 'Creating MenuItem' message with the caption of the menu each time TQtWSMenuItem.CreateHandle is called, and a 'Creating Menu' message with the name of the menu (TMenu descendents don't have a caption), each time TQtWSMenu.CreateHandle is called.
606	626
607	627		Here is the resulting output of such software:
608	628
609	629		Creating Menu. Name: MainMenu1
610	630		Creating MenuItem: Item1 Parent=Menu.Items : TMenuItem
611	631		Creating MenuItem: SubItem11 Parent=Item1 : TMenuItem
612	632		Creating MenuItem: SubItem12 Parent=Item1 : TMenuItem
613	633		Creating MenuItem: SubItem13 Parent=Item1 : TMenuItem
614	634		Creating MenuItem: SubItem14 Parent=Item1 : TMenuItem
615	635		Creating MenuItem: SubSubItem141 Parent=SubItem14 : TMenuItem
616	636		Creating MenuItem: SubSubItem142 Parent=SubItem14 : TMenuItem
617	637		Creating MenuItem: SubSubItem143 Parent=SubItem14 : TMenuItem
618	638		Creating MenuItem: SubSubItem144 Parent=SubItem14 : TMenuItem
619	639		Creating MenuItem: Item2 Parent=Menu.Items : TMenuItem
620	640		Creating MenuItem: SubItem21 Parent=Item2 : TMenuItem
621	641		Creating MenuItem: SubItem22 Parent=Item2 : TMenuItem
622	642		Creating MenuItem: SubItem23 Parent=Item2 : TMenuItem
623	643		Creating MenuItem: Item3 Parent=Menu.Items : TMenuItem
624	644		Creating MenuItem: Item4 Parent=Menu.Items : TMenuItem
625	645
626	646		For all MenuItems one can use GetParentMenu to get their parent owner: Menu (TMainMenu).
627	647
628	648		### Control enabling/disabling
629	649
630	650		The current way to set control enabling/disabling is by implementing the winapi EnableWindow. This API should work generically on any control. It should enable/disable mouse and keyboard input for the specified window or control, but also mark it as uneditable by the user, by making it greyed for example.
631	651
632	652		``` pascal
633	653		{------------------------------------------------------------------------------
634	654		Method: EnableWindow
635	655		Params: HWnd - handle to window
636	656		BEnable - whether to enable the window
637	657		Returns: If the window was previously disabled
638	658
639	659		Enables or disables mouse and keyboard input to the specified window or
640	660		control.
641	661		------------------------------------------------------------------------------}
642	662		function TWin32WidgetSet.EnableWindow(hWnd: HWND; bEnable: Boolean): Boolean;
643	663		```
644	664
645	665		### Return Control Text (Captions)
646	666
647	667		The method to return control text is GetText().
648	668
649	669		However, the method doesn't always have to return text (even if it can). It should only return text (by assigning AText value and setting result to TRUE), if a user can modify the text on the control itself (typically by typing it in by keyboard or some other manipulation).
650	670
651	671		If the text itself is considered to be "static" then method can return FALSE at all times.
652	672
653	673		LCL caches the text most of the time, and thus if control returns false, it would pull the cached value.
654	674
655	675		``` pascal
656	676		{------------------------------------------------------------------------------
657	677		Function: TWSWinControl.GetText
658	678		Params: Sender: The control to retrieve the text from
659	679		Returns: the requested text
660	680
661	681		Retrieves the text from a control.
662	682		------------------------------------------------------------------------------}
663	683		class function TWSWinControl.GetText(const AWinControl: TWinControl; var AText: String): Boolean;
664	684		```
665	685
666	686		### Shaped Windows
667	687
668	688		Windows can be shaped based on a TBitmap or on a TRegion. The region is the visible part.
669	689
670	690		To implement shaped windows based on a TBitmap, implement TWSWinControl.setShape
671	691
672	692		To implement shaped windows based on a TRegion implement LCLIntf.SetWindowRgn
673	693
674	694		See also: [[LCL Tips\|LCL Tips#Creating a non-rectangular window or control]]
675	695
676	696		### System colors
677	697
678	698		Some color constants are actually system colors, like clBtnFace, clForm, clWindow, etc, etc.
679	699
680	700		To implement support for system colors the WinAPI routine GetSysColor should be implemented:
681	701
682		-	~~`function GetSysColor(nIndex: Integer): DWORD; override;`~~
	702	+	``` pascal
	703	+	function GetSysColor(nIndex: Integer): DWORD; override;
	704	+	```
683	705
684	706		And here is a snip of the color constants which should be supported. Check LCLType for the latest values:
685	707
686	708		``` pascal
687	709		//==============================================
688	710		// API system Color constants pbd
689	711		// note these are usually shown ORed with
690	712		// $80000000 as these would have interfered with
691	713		// other MS color enumerations
692	714		// GetSysColor and SetSysColor expects the values
693	715		// below
694	716		//==============================================
695	717
696	718		type
697	719		COLORREF = LongInt;
698	720		TColorRef = COLORREF;
699	721
700	722		const
701	723		CLR_INVALID = TColorRef($FFFFFFFF);
702	724
703	725		COLOR_SCROLLBAR = 0;
704	726		COLOR_BACKGROUND = 1;
705	727		COLOR_ACTIVECAPTION = 2;
706	728		COLOR_INACTIVECAPTION = 3;
707	729		COLOR_MENU = 4;
708	730		COLOR_WINDOW = 5;
709	731		COLOR_WINDOWFRAME = 6;
710	732		COLOR_MENUTEXT = 7;
711	733		COLOR_WINDOWTEXT = 8;
712	734		COLOR_CAPTIONTEXT = 9;
713	735		COLOR_ACTIVEBORDER = 10;
714	736		COLOR_INACTIVEBORDER = 11;
715	737		COLOR_APPWORKSPACE = 12;
716	738		COLOR_HIGHLIGHT = 13;
717	739		COLOR_HIGHLIGHTTEXT = 14;
718	740		COLOR_BTNFACE = 15;
719	741		COLOR_BTNSHADOW = 16;
720	742		COLOR_GRAYTEXT = 17;
721	743		COLOR_BTNTEXT = 18;
722	744		COLOR_INACTIVECAPTIONTEXT = 19;
723	745		COLOR_BTNHIGHLIGHT = 20;
724	746		COLOR_3DDKSHADOW = 21;
725	747		COLOR_3DLIGHT = 22;
726	748		COLOR_INFOTEXT = 23;
727	749		COLOR_INFOBK = 24;
728	750		// PBD: 25 is unassigned in all the docs I can find
729	751		// if someone finds what this is supposed to be then fill it in
730	752		// note defaults below, and cl[ColorConst] in graphics
731	753		COLOR_HOTLIGHT = 26;
732	754		COLOR_GRADIENTACTIVECAPTION = 27;
733	755		COLOR_GRADIENTINACTIVECAPTION = 28;
734	756		COLOR_MENUHILIGHT = 29;
735	757		COLOR_MENUBAR = 30;
736	758
737	759		COLOR_FORM = 31;
738	760
739	761		COLOR_ENDCOLORS = COLOR_FORM;
740	762
741	763		COLOR_DESKTOP = COLOR_BACKGROUND;
742	764		COLOR_3DFACE = COLOR_BTNFACE;
743	765		COLOR_3DSHADOW = COLOR_BTNSHADOW;
744	766		COLOR_3DHIGHLIGHT = COLOR_BTNHIGHLIGHT;
745	767		COLOR_3DHILIGHT = COLOR_BTNHIGHLIGHT;
746	768		COLOR_BTNHILIGHT = COLOR_BTNHIGHLIGHT;
747	769
748	770		MAX_SYS_COLORS = COLOR_ENDCOLORS;
749	771		SYS_COLOR_BASE = TColorRef($80000000);
750	772		```
751	773
752	774		### ShowMessage
753	775
754	776		These standard dialogs are implemented purely in the LCL in the following places:
755	777
756	778		- Class TPromptDialog file lcl/include/promptdialog.inc
757	779
758	780		### SpinEdit
759	781
760	782		Both TFloatSpinEdit and TSpinEdit are implemented in the class TWSFloatSpinEdit.
761	783
762	784		### Clipboard
763	785
764	786		Clipboard support is implemented in lclintf by implementing Windows API routines. The routines are:
765	787
766	788		``` pascal
767	789		function ClipboardFormatToMimeType(FormatID: TClipboardFormat): string; {$IFDEF IF_BASE_MEMBER}virtual;{$ENDIF}
768	790		function ClipboardGetData(ClipboardType: TClipboardType;
769	791		FormatID: TClipboardFormat; Stream: TStream): boolean; {$IFDEF IF_BASE_MEMBER}virtual;{$ENDIF}
770	792		// ! ClipboardGetFormats: List will be created. You must free it yourself with FreeMem(List) !
771	793		function ClipboardGetFormats(ClipboardType: TClipboardType;
772	794		var Count: integer; var List: PClipboardFormat): boolean; {$IFDEF IF_BASE_MEMBER}virtual;{$ENDIF}
773	795		function ClipboardGetOwnerShip(ClipboardType: TClipboardType;
774	796		OnRequestProc: TClipboardRequestEvent; FormatCount: integer;
775	797		Formats: PClipboardFormat): boolean; {$IFDEF IF_BASE_MEMBER}virtual;{$ENDIF}
776	798		function ClipboardRegisterFormat(const AMimeType: string): TClipboardFormat; {$IFDEF IF_BASE_MEMBER}virtual;{$ENDIF}
777	799		```
778	800
779	801		Sequence of calls during program startup:
780	802
781	803		``` pascal
782	804		TCocoaWidgetSet.ClipboardRegisterFormat AMimeType=image/bmp Result=51027040
783	805		TCocoaWidgetSet.ClipboardRegisterFormat AMimeType=image/delphi.bitmap Result=0
784	806		TCocoaWidgetSet.ClipboardRegisterFormat AMimeType=image/xpm Result=0
785	807		TCocoaWidgetSet.ClipboardRegisterFormat AMimeType=image/png Result=0
786	808		TCocoaWidgetSet.ClipboardRegisterFormat AMimeType=image/jpeg Result=0
787	809		```
788	810
789	811		Sequence of calls during "Caption := Clipboard.AsText":
790	812
791	813		``` pascal
792	814		TCocoaWidgetSet.ClipboardRegisterFormat AMimeType=text/plain Result=51026976
793	815		TCocoaWidgetSet.ClipboardGetData ClipboardType=clipboard FormatID: 51026976
794	816		```
795	817
796	818		### TSpeedButton
797	819
798	820		This control is a TGraphicControl descendent, so it has no handle and paints itself. To retain native look, it uses the function ThemeServices.DrawElement(Details.Element=teButton) to paint itself, so implement this function to have this control working. Naturally, lot's of other DC, WindowOrg, Text Drawing and Painting routines will have to be working, as explained for TLabel.
799	821
800	822		### TRadioButton and TCheckButton
801	823
802	824		Messages:
803	825
804	826		Basically the Widgetset must do:
805	827
806	828		- Send LM_CHANGE when a radio button is unchecked/checked (LCL will take care if OnClick will be called or not)
807	829		- Dont send LM_CHANGE when TWSCustomCheckBox.SetState is called (SetChecked)
808	830
809	831		See also this bug report: <http://bugs.freepascal.org/view.php?id=13939>
810	832
811	833		### FullScreen support
812	834
813	835		FullScreen is implemented as a Windows state wsFullScreen, and as such is implemented in LCLIntf.ShowWindow where the constant SW_SHOWFULLSCREEN should be handled.
814	836
815	837		## An example of how the LCL interfaces work
816	838
817	839		Below is a simple example. Suppose you have developed a trayicon component. How would you implement it in the LCL to work correctly on the various different supported platforms?
818	840
819	841		You would need to generate the following files:
820	842
821	843		\trayicon.pas
822	844
823	845		\wstrayicon.pas
824	846
825	847		\gtk\gtkwstrayicon.pas
826	848
827	849		\gtk\trayintf.pas
828	850
829	851		\win32\win32wstrayicon.pas
830	852
831	853		\win32\trayintf.pas
832	854
833	855		Providing separate wsXXX.pas and \\\$(LCLWidgetType)\XXXintf.pas files avoids the need for ifdefs altogether. You will need to add as a unit path \$(LCLWidgetType) to the XXXintf.pas file in order initialize the correct trayintf.pas file, which in turn initializes the correct WS Tray class.
834	856
835	857		Inside trayicon.pas you include wstrayicon. Derive your main class from an LCL class, and only use wstrayicon in its implementation. All LCL classes that communicate with a widgetset, must be derived from [[doc:/lcl/lclclasses/tlclcomponent.html\|TLCLComponent]] declared in the [[doc:/lcl/lclclasses\|LCLClasses]] unit.
836	858
837	859		``` pascal
838	860		unit TrayIcon;
839	861
840	862		interface
841	863
842	864		type
843	865		TTrayIcon = class(TLCLComponent)
844	866		public
845	867		procedure DoTray;
846	868		end;
847	869
848	870		implementation
849	871
850	872		uses wstrayicon;
851	873
852	874		procedure TTrayIcon.DoTray;
853	875		begin
854	876		// Call wstrayicon
855	877		end;
856	878
857	879		end.
858	880		```
859	881
860	882		in trayintf you use gtkwstrayicon or win32trayicon depending on which trayintf file it is.
861	883
862	884		in wstrayicon you create a class like so:
863	885
864	886		``` pascal
865	887		unit WSTrayIcon;
866	888
867	889		uses WSLCLClasses, Controls, TrayIcon; // and other things as well
868	890
869	891		TWSTrayIconClass = class of TWSTrayIcon;
870	892		TWSTrayIcon = class(TWSWinControl);
871	893		public
872	894		class procedure EmbedTrayIcon(const ATrayIcon: TCustomTrayIcon);
873	895		virtual; // these must all be virtual and class procedures!!
874	896		class procedure RemoveTrayIcon(const ATrayIcon: TCustomTrayIcon); virtual;
875	897		....
876	898		end;
877	899		...
878	900
879	901		implementation
880	902
881	903		procedure TWSTrayIcon.EmbedTrayIcon(const ATrayIcon: TCustomTrayIcon);
882	904		begin
883	905		//do nothing
884	906		end;
885	907
886	908		procedure TWSTrayIcon.RemoveTrayIcon(const ATrayIcon: TCustomTrayIcon);
887	909		begin
888	910		//do nothing
889	911		end;
890	912		```
891	913
892	914		now in gtkwstrayicon.pas do this:
893	915
894	916		``` pascal
895	917		uses WSTrayIcon, WSLCLClasses, Controls, TrayIcon, gtk, gdk;
896	918
897	919		TGtkWSTrayIcon = class(TWSTrayIcon);
898	920		private
899	921		class function FindSystemTray(const ATrayIcon: TCustomTrayIcon):
900	922		TWindow; virtual;
901	923		public
902	924		class procedure EmbedTrayIcon(const ATrayIcon: TCustomTrayIcon); override;
903	925		class procedure RemoveTrayIcon(const ATrayIcon: TCustomTrayIcon);
904	926		override;
905	927		class function CreateHandle(const AWinControl: TWinControl; const
906	928		AParams: TCreateParams): HWND; override;
907	929		....
908	930		end;
909	931		...
910	932
911	933		implementation
912	934
913	935		procedure TGtkWSTrayIcon.CreateHandle(const AWinControl: TWinControl;
914	936		const AParams: TCreateParams): HWND;
915	937		var
916	938		WidgetInfo: PWidgetInfo;
917	939		begin
918	940
919	941		Result := gtk_plug_new;
920	942		WidgetInfo := CreateWidgetInfo(AWinControl, Result); // it's something
921	943		like this anyway
922	944		TGtkWSWincontrolClass(WidgetSetClass).SetCallbacks(AWinControl);
923	945		// and more stuff
924	946		end;
925	947
926	948		function TGtkWSTrayIcon.FindSystemTray(const ATrayIcon:
927	949		TCustomTrayIcon): TWindow;
928	950		begin
929	951		// do something
930	952		end;
931	953
932	954		procedure TGtkWSTrayIcon.EmbedTrayIcon(const ATrayIcon: TCustomTrayIcon);
933	955		var
934	956		SystemTray: TWindow;
935	957		begin
936	958		SystemTray := FindSystemTray(ATrayIcon);
937	959		//do something
938	960		end;
939	961
940	962		procedure TGtkWSTrayIcon.RemoveTrayIcon(const ATrayIcon: TCustomTrayIcon);
941	963		begin
942	964		//do something
943	965		end;
944	966
945	967		......
946	968
947	969		initialization
948	970
949	971		RegisterWSComponent(TCustomTrayIcon, TGtkWSTrayIcon); //this is very
950	972		important!!!
951	973
952	974		end.
953	975		```
954	976
955	977		then finally in trayicon.pas you go as normal
956	978
957	979		``` pascal
958	980		uses WSTrayIcon; //etc. you DON'T include GtkWSTrayIcon here!
959	981
960	982		TCustomTrayIcon = class(TWinControl)
961	983		public
962	984		procedure EmbedControl;
963	985		....
964	986		end;
965	987
966	988		...
967	989		procedure TTrayIcon.EmbedControl;
968	990		begin
969	991		TWSTrayIconClass(WidgetSetClass).EmbedControl(Self);
970	992
971	993		end;
972	994		```
973	995
974	996		## Minimum Toolkit versions
975	997
976	998		\| Lazarus version \| Min. FPC \| Min. Gtk 2 \| Min. Qt 4 \| Min. Windows \| Min. Windows CE \| Min. macOS (Carbon) \| Min. macOS (Cocoa) \| Min. Req. of LCL-CustomDrawn \|
977	999		\|----\|----\|----\|----\|----\|----\|----\|----\|----\|
978	1000		\| 0.9.24 \| 2.2.0 \| 2.6+ \| 4.2+ \| Windows 98+ \| Recommended 4.0+ \| 10.4 \| N/A \| N/A \|
979	1001		\| 0.9.26 \| 2.2.2 \| 2.6+ \| 4.3+ \| Windows 98+ \| Recommended 4.0+ \| 10.4 \| N/A \| N/A \|
980	1002		\| 0.9.28 \| 2.2.4 \| 2.8+ \| 4.5+ \| Windows 98+ \| Recommended 4.0+ \| 10.4 \| N/A \| N/A \|
981	1003		\| 0.9.30 \| 2.4.0 \| 2.8+ \| 4.5+ \| Windows 98+ \| Recommended 5.0+ \| 10.4 \| N/A \| N/A \|
982	1004		\| 0.9.31 \| 2.4.4 \| 2.8+ \| 4.5+ \| Windows 98+ \| Recommended 5.0+ \| 10.4 \| 10.6 \| Android 2.2+, Windows 2000+, X11, Snow Leopard 10.6+ \|
983	1005		\| 1.2.6 \| 2.6.4 \| 2.8+ \| 4.5+* \| Windows 98+ \| Recommended 5.0+ \| 10.4 \| 10.6 \| Android 2.2+, Windows 2000+, X11, Snow Leopard 10.6+ \|
984	1006
985	1007		- \- Actually 4.5.0 ...4.8.4 with pre-built Qt4Pas.dll, 4.8.5+ requires a different Qt4Pas.dll
986	1008
987	1009		See Also: [[Installing Lazarus on macOS\|FPC + Lazarus Compatibility Matrix]].
988	1010
989	1011		---
990	1012		From the Free Pascal wiki, page "LCL Internals", as it stood on 2021-12-09 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).

Back to history