Creating LCL Control From Libraries: what changed

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

Title: Creating LCL Control From Libraries

New		Line
1	+	## About
2	+
3	+	Due to several problems, LCL components and ansistrings cannot be passed between a library (dll/so/dynlib) and an application (exe/app).
4	+
5	+	This interface provides a simple API between the library and the application to create LCL UI controls application-side, however controlled by dummies library-side.
6	+
7	+	## Examples
8	+
9	+	### Usage example 1 (library)
10	+
11	+	``` pascal
12	+	procedure init; stdcall;
13	+	var myBtn:TRHandle;
14	+	begin
15	+	myBtn:=RCreate(StrToRstr('TButton'));
16	+	RSetStrProp(myBtn,StrToRstr('Caption'),StrToRstr('Hello world!'));
17	+	end;
18	+
19	+	exports init;
20	+	```
21	+
22	+	### Usage example 2 (library)
23	+
24	+	``` pascal
25	+	procedure init(RApplication,RParent:TRHandle); stdcall;
26	+	var winCtrl:TRWinControl;
27	+	begin
28	+	winCtrl:=TRWinControl.Create(RApplication);
29	+	winCtrl.Left:=20;
30	+	winCtrl.Top:=10;
31	+	winCtrl.Width:=100;
32	+	winCtrl.Height:=24;
33	+	winCtrl.Parent:=RParent;
34	+	end;
35	+
36	+	exports init;
37	+	```
38	+
39	+	### Usage example 3 (application)
40	+
41	+	``` pascal
42	+	type
43	+	TDllInit1=procedure(intr:TRWinControlInterface); stdcall;
44	+	TDllInit2=procedure(intr:TRWinControlInterface; Appl,Parnt:TRHandle); stdcall;
45	+
46	+	var
47	+	lib:TLibHandle;
48	+	init1:TDllInit1;
49	+	init2:TDllInit2;
50	+	begin
51	+	RegisterClass(TButton);
52	+	RegisterClass(TWinControl);
53	+
54	+	// library example 1
55	+	lib:=LoadLibrary('library1.'+SharedSuffix);
56	+	init1:=TDllInit(GetProcAddress(lib,'init'));
57	+	init1(FillRWinControlInterface);
58	+	FreeLibrary(lib);
59	+
60	+	// library example 2
61	+	lib:=LoadLibrary('library2.'+SharedSuffix);
62	+	init2:=TDllInit(GetProcAddress(lib,'init'));
63	+	init2(FillRWinControlInterface,TRHandle(Application),TRHandle(Panel1));
64	+	FreeLibrary(lib);
65	+	end.
66	+	```
67	+
68	+	## Technical details
69	+
70	+	### Passing strings
71	+
72	+	Strings cannot be usually passed between a library and an application. Since this system requires passing strings, a solution has been included:
73	+
74	+	- You can either use simple PChars
75	+	- Fast but not suitable for binary data (especially containing null characters)
76	+	- Or use the binary string system
77	+	- This probably is slower then just using PChars but it allows passing any type of data up to 2Gb.
78	+
79	+	To make it easy to switch, just type this switch
80	+
81	+	``` pascal
82	+	{$DEFINE USE_BIN_STR}
83	+	```
84	+
85	+	on the very top of your "rwincontrol" unit. If this switch is set, binary strings support is enabled. If not, the more conventional PChars are used.
86	+
87	+	### How does it work?
88	+
89	+	A set of functions in the application are passed to the library as pointers in a record (TRWinControlInterface). Each time a library needs to change or create a control these functions are called. They basically make use of RTTI to provide this functionality.
90	+
91	+	### What type of LCL controls?
92	+
93	+	Actually, it's not just LCL but any other class you want. You just have to register your class application-side and provide a suitable wrapper library-side (though it is not required). To register a class, put something like the following code in the initialization section of your program:
94	+
95	+	``` pascal
96	+	RegisterClass(TMyClass);
97	+	```
98	+
99	+	## FAQ/Troubleshoot
100	+
101	+	#### I get "class not found" errors
102	+
103	+	You have to register that class application-side. See #What type of LCL controls?
104	+
105	+	#### Where do I download the sources?
106	+
107	+	[View Source Code](https://www.dropbox.com/sh/fanban54tb31p5e/AACSIXObpVfAIsinz0Sbbzkma?dl=0) or [Download Zip](https://www.dropbox.com/sh/fanban54tb31p5e/AACSIXObpVfAIsinz0Sbbzkma?dl=1)
108	+
109	+	## Copyright
110	+
111	+	Devised and created by Christian Sciberras, with the help of the following people from \#lazarus-ide IRC (alphabetical):
112	+
113	+	- Andreas '\pub\bash0r' Schneider
114	+	- Dmitry 'skalogryz' Boyarintsev
115	+	- Marc 'giantm' Weustink
116	+	- Vincent 'fpcfan' Snijders
117	+
118	+	## License
119	+
120	+	© 2009 Covac Software. You may copy, store, modify and sell this software/source as long as you keep copyright comments in the source code intact.
121	+
122	+	---
123	+	From the Free Pascal wiki, page "Creating LCL Control From Libraries", as it stood on 2020-02-08 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).
124	+	Category: LCL

Back to history