Extending the IDE: what changed

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

Old	New		Line
1	1		# Extending the IDE
2	2
3	3		## Overview
4	4
5	5		The Lazarus IDE supports several types of plugins:
6	6
7	7		Components
8	8		These are the items found on the Component Palette. For example, TButton (found on the Standard page) can be used to create Buttons.
9	9
10	10		Component Editors
11	11		When you double-click a component in the Designer, a component editor is invoked. The component editor may also add an extra item to the Designer's popup menu (accessed when you right-click on a component in the Designer).
12	12
13	13		Property Editors
14	14		Each row in the grid section of the Object Inspector uses a property editor to allow that property's value to be set or altered.
15	15
16	16		Experts
17	17		Experts encompass all other plugin types. They might register new menu item(s), register short cuts, or extend other IDE features.
18	18
19	19		There are two possible ways to add your own plugins to the Lazarus IDE:
20	20
21	21		1. Write a package, install it and register your plugin(s) in the 'Register' procedure of a unit.
22	22		2. Extend the Lazarus code, and send your svn diff to the Lazarus mailing list.
23	23
24	24		## Packages and Makefile Dependencies
25	25
26	26		The following steps are necessary, if adding new package dependencies.
27	27
28	28		- Create/Update the Makefile for the package via Package editor / More ... / Create Makefile.
29	29		- Fix all dependencies. See tools/updatemakefiles.lpi
30	30
31	31		# Menu items
32	32
33	33		You can add new menu items, hide or move existing ones and add sub menus, sections. For your own forms you can register the TMainMenu/TPopupMenu so that other packages can extend your form further. The unit MenuIntf of the package IDEIntf contains all registration for menus and many standard menu items of the IDE itself.
34	34
35	35		## Adding a menu item
36	36
37	37		A single menu item like 'View Object Inspector' is called a TIDEMenuCommand. You can create one with RegisterIDEMenuCommand, which has two forms with lots of parameters:
38	38
39	39		``` pascal
40	40		function RegisterIDEMenuCommand(Parent: TIDEMenuSection;
41	41		const Name, Caption: string;
42	42		const OnClickMethod: TNotifyEvent = nil;
43	43		const OnClickProc: TNotifyProcedure = nil;
44	44		const Command: TIDECommand = nil;
45	45		const ResourceName: String = ''
46	46		): TIDEMenuCommand; overload;
47	47		function RegisterIDEMenuCommand(const Path, Name, Caption: string;
48	48		const OnClickMethod: TNotifyEvent = nil;
49	49		const OnClickProc: TNotifyProcedure = nil;
50	50		const Command: TIDECommand = nil;
51	51		const ResourceName: String = ''
52	52		): TIDEMenuCommand; overload;
53	53		```
54	54
55	55		The difference between those two is only how you specify the parent menu section. You can give the menu section directly or indirectly via the path. Many standard sections can be found in the MenuIntf unit. For example the section mnuTools, which is the Tools menu of the main IDE bar. It contains a section itmSecondaryTools, the recommended section for third party tools.
56	56
57	57		The following registers a new menu command, with the name 'MyTool', the caption 'Start my tool' and when clicked executes the procedure StartMyTool:
58	58
59	59		``` pascal
60	60		procedure StartMyTool;
61	61		begin
62	62		...executed when menu item is clicked...
63	63		end;
64	64
65	65		procedure Register;
66	66		begin
67	67		RegisterIDEMenuCommand(itmSecondaryTools, 'MyTool','Start my tool',nil,@StartMyTool);
68	68		end;
69	69		```
70	70
71	71		If you want to call a method instead of a procedure use the OnClickMethod parameter.
72	72
73	73		This menu item does not have a shortcut. If you want a shortcut you must create a TIDECommand and pass it in the Command parameter. For example:
74	74
75	75		``` pascal
76	76		uses ... IDECommands, MenuIntf;
77	77		...
78	78		var
79	79		Key: TIDEShortCut;
80	80		Cat: TIDECommandCategory;
81	81		CmdMyTool: TIDECommand;
82	82		begin
83	83		// register IDE shortcut and menu item
84	84		Key := IDEShortCut(VK_UNKNOWN,[],VK_UNKNOWN,[]);
85	85		Cat:=IDECommandList.FindCategoryByName(CommandCategoryToolMenuName);
86	86		CmdMyTool := RegisterIDECommand(Cat,'Start my tool', 'Starts my tool to do some stuff', Key, nil, @StartMyTool);
87	87		RegisterIDEMenuCommand(itmSecondaryTools, 'MyTool', 'Start my tool', nil, nil, CmdMyTool);
88	88		end;
89	89		```
90	90
91	91		# Shortcuts
92	92
93	93		All shortcuts (keys that invoke some action) are registered in the IDECommandList. Here is an example how to find all commands that react on key Ctrl-D or two key combinations starting with Ctrl-D:
94	94
95	95		``` pascal
96	96		uses
97	97		Classes, SysUtils, LCLProc, IDECommands;
98	98
99	99		procedure ListCtrlD;
100	100		// list all idecommands with shortcut Ctrl-D
101	101		var
102	102		i: integer;
103	103		Cmd: TIDECommand;
104	104		Commands: TFPList;
105	105		begin
106	106		Commands:=IDECommandList.FindCommandsByShortCut(IDEShortCut(VK_D,[],VK_UNKNOWN,[]));
107	107		try
108	108		for i:=0 to Commands.Count-1 do begin
109	109		Cmd:=TIDECommand(Commands[i]);
110	110		writeln('Cmd: ',Cmd.Name,
111	111		' A=',dbgs(Cmd.ShortcutA.Shift1),'-',Cmd.ShortcutA.Key1,
112	112		',',dbgs(Cmd.ShortcutA.Shift2),'-',Cmd.ShortcutA.Key2,
113	113		' B=',dbgs(Cmd.ShortcutB.Shift1),'-',Cmd.ShortcutB.Key1,
114	114		',',dbgs(Cmd.ShortcutB.Shift2),'-',Cmd.ShortcutB.Key2
115	115		);
116	116		end;
117	117		finally
118	118		Commands.Free;
119	119		end;
120	120		end;
121	121		```
122	122
123	123		# Config files
124	124
125	125		## Load/Save settings
126	126
127	127		All configuration files of the IDE are stored in one directory as xml files. Packages can add their own files there too. The [[pcp\|primary config path]] directory can be read with:
128	128
129	129		``` pascal
130	130		uses LazIDEIntf;
131	131		...
132	132		Directory := LazarusIDE.GetPrimaryConfigPath;
133	133		```
134	134
135	135		Packages can create their own xml files with:
136	136
137	137		``` pascal
138	138		uses
139	139		..., LCLProc, BaseIDEIntf, LazConfigStorage;
140	140
141	141		const
142	142		Version = 1;
143	143		var
144	144		Config: TConfigStorage;
145	145		SomeValue: String;
146	146		SomeInteger: Integer;
147	147		SomeBoolean: Boolean;
148	148		FileVersion: LongInt;
149	149		begin
150	150		SomeValue:='Default';
151	151		SomeInteger:=3;
152	152		SomeBoolean:=true;
153	153
154	154		// save settings
155	155		try
156	156		Config:=GetIDEConfigStorage('mysettings.xml',false);
157	157		try
158	158		// store the version number so future extensions can handle old config files
159	159		Config.SetDeleteValue('Path/To/The/Version',Version,0);
160	160		// store string variable "SomeValue"
161	161		// if SomeValue has the default value the entry is not stored,
162	162		// so only the differences to the default are stored.
163	163		// This way the xml is kept short and defaults may change in future.
164	164		Config.SetDeleteValue('Path/To/Some/Value',SomeValue,'Default');
165	165		Config.SetDeleteValue('Path/To/Some/Integer',SomeInteger,3);
166	166		Config.SetDeleteValue('Path/To/Some/Boolean',SomeBoolean,true);
167	167		// there are more overloads for SetDeleteValue, find out with Ctrl+Space
168	168		finally
169	169		Config.Free;
170	170		end;
171	171
172	172		except
173	173		on E: Exception do begin
174	174		DebugLn(['Saving mysettings.xml failed: ',E.Message]);
175	175		end;
176	176		end;
177	177
178	178		// load settings
179	179		try
180	180		Config:=GetIDEConfigStorage('mysettings.xml',true);
181	181		try
182	182		// read the version of the config
183	183		FileVersion:=Config.GetValue('Path/To/The/Version',0);
184	184		// read a string variable "SomeValue". If the entry does not exist, use
185	185		// the Default
186	186		SomeValue:=Config.GetValue('Path/To/Some/Value','Default');
187	187		SomeInteger:=Config.GetValue('Path/To/Some/Integer',3);
188	188		SomeBoolean:=Config.GetValue('Path/To/Some/Boolean',true);
189	189		finally
190	190		Config.Free;
191	191		end;
192	192		except
193	193		on E: Exception do begin
194	194		DebugLn(['Loading mysettings.xml failed: ',E.Message]);
195	195		end;
196	196		end;
197	197		end;
198	198		```
199	199
200	200		Notes:
201	201
202	202		- Every IDE plugin should use its own config file. Especially you must not use the standard IDE option files like [[editoroptions.xml]] or [[environmentoptions.xml]].
203	203		- GetIDEConfigStorage when loading checks if the file exists and if not it will copy the template from the secondary config directory.
204	204		- Since 0.9.31 you can use this function to load a file outside the primary config directory.
205	205
206	206		# Components
207	207
208	208		## Extending existing components
209	209
210	210		Source: [1](http://lazarus.freepascal.org/index.php/topic,17733.msg98425.html#msg98425) It is straightforward to customise existing LCL components, e.g. if you want to add properties.
211	211
212	212		Add the properties you need with appropriate setter and getter methods and storage fields.
213	213
214	214		Then instantiate them 'by hand', giving an owner component (to handle later destruction), and set Parent and possibly Top and Left and any other defaults your component needs when initialized.
215	215
216	216		When you are satisfied that your customised component is debugged, add a RegisterComponent() call to stick it on the IDE Component Palette and save you having to do the setup code 'by hand' (look at any component's source to see how to do this).
217	217
218	218		Here is a simple example:
219	219
220	220		``` pascal
221	221		unit Unit1;
222	222
223	223		{$mode objfpc}{$H+}
224	224
225	225		interface
226	226
227	227		uses
228	228		Classes, SysUtils, Forms, StdCtrls;
229	229
230	230		type
231	231		TEdX = class(TEdit)
232	232		private
233	233		FNewIntProp: integer;
234	234		FNewStrProp: string;
235	235		procedure SetNewIntProp(AValue: integer);
236	236		procedure SetNewStrProp(AValue: string);
237	237		public
238	238		constructor Create(theComponent: TComponent); override;
239	239		property NewIntProp: integer read FNewIntProp write SetNewIntProp;
240	240		property NewStrProp: string read FNewStrProp write SetNewStrProp;
241	241		end;
242	242
243	243		TForm1 = class(TForm)
244	244		procedure FormCreate(Sender: TObject);
245	245		private
246	246		edX: TEdX;
247	247		public
248	248		end;
249	249
250	250		var
251	251		Form1: TForm1;
252	252
253	253		implementation
254	254
255	255		{ TForm1 }
256	256
257	257		procedure TForm1.FormCreate(Sender: TObject);
258	258		begin
259	259		edX:= TEdX.Create(Self);
260	260		edX.Parent:= Self;
261	261		edX.Caption:= IntToStr(edX.NewIntProp);
262	262		Caption:= edX.NewStrProp;
263	263		end;
264	264
265	265		{$R *.lfm}
266	266
267	267		{ TEdX }
268	268
269	269		procedure TEdX.SetNewIntProp(AValue: integer);
270	270		begin
271	271		if FNewIntProp=AValue then Exit;
272	272		FNewIntProp:=AValue;
273	273		// add custom code here
274	274		end;
275	275
276	276		procedure TEdX.SetNewStrProp(AValue: string);
277	277		begin
278	278		if FNewStrProp=AValue then Exit;
279	279		FNewStrProp:=AValue;
280	280		// add custom code here
281	281		end;
282	282
283	283		constructor TEdX.Create(theComponent: TComponent);
284	284		begin
285	285		inherited Create(theComponent);
286	286		FNewStrProp:= 'new string property value';
287	287		FNewIntProp:= 99;
288	288		end;
289	289
290	290		end.
291	291		```
292	292
293	293		## Writing components
294	294
295	295		Main article: [[How To Write Lazarus Component]]
296	296
297	297		You can create new components via the package editor.
298	298
299	299		Create or open a package, click on add, click on New Component, fill in the items: Ancestor Type = TButton, New class name = TMyButton, palette page = Misc, Unit file name = mybutton.pas (this file will be created), unit name MyButton and click ok.
300	300
301	301		### Giving a new component an icon for the component palette
302	302
303	303		Create an image file of the format .bmp, .xpm or .png with the same name as the component class. For example tmybutton.png and save it in the package source directory. The image can be created by any graphic program (e.g. gimp) and should be no bigger than 24x24 pixel. Then convert the image to a resource file with the lazres tool, which can be found in the lazarus/tools directory:
304	304
305	305		``` bash
306	306		~/lazarus/tools/lazres mybutton.lrs tmybutton.png
307	307		# note: Laz trunk/1.4+? uses .res resource files instead of .lrs files:
308	308		~/lazarus/tools/lazres mybutton.res tmybutton.png
309	309		```
310	310
311	311		This creates an pascal include file, which is used in the initialization section of mybutton.pas:
312	312
313	313		``` pascal
314	314		initialization
315	315		{$I mybutton.lrs}
316	316		// or in newer Lazarus version - to docheck syntax
317	317		{$R mybutton.res}
318	318		```
319	319
320	320		Install the package.
321	321
322	322		### Hiding a component in the component palette
323	323
324	324		Package IDEIntf, unit componentreg:
325	325
326		-	~~`IDEComponentPalette.FindComponent('TButton').Visible:=false;`~~
	326	+	``` pascal
	327	+	IDEComponentPalette.FindComponent('TButton').Visible:=false;
	328	+	```
327	329
328	330		## Writing component editors
329	331
330	332		A component editor handles things like double clicking on a component in a designer or adding menu items when right clicking on a component. Writing a component editor is easy. See the unit componenteditors.pas of the package IDEIntf for lots of examples. For instance to show an editor when double clicking see TCheckListBoxComponentEditor.
331	333
332	334		## Writing property editors
333	335
334	336		Each type of property (integer, string, TFont, ...) in the Object Inspector needs a property editor. If your component has a property Password of type string, then you can define a property editor for your specific component class, with a property named Password of type string. The unit propedits.pp of the package IDEIntf contains many of the standard property editors used by the IDE itself. For example the TStringPropertyEditor is the default property editor for all strings, while TComponentNamePropertyEditor is more specific and handles only TComponent.Name. See the unit for plenty of examples.
335	337
336	338		### Hiding a property in the Object Inspector
337	339
338	340		There is a special property editor for hiding:
339	341
340	342		``` pascal
341	343		RegisterPropertyEditor(TypeInfo(TAnchorSide), TControl, 'AnchorSideLeft', THiddenPropertyEditor);
342	344		```
343	345
344	346		### Find out what property editor is used for a property
345	347
346	348		``` pascal
347	349		uses Classes, TypInfo, PropEdits;
348	350		var
349	351		Instance: TPersistent; // your instance
350	352		PropInfo: PPropInfo;
351	353		EdClass: TPropertyEditorClass;
352	354		begin
353	355		PropInfo:=GetPropInfo(Instance.ClassType,'Name'); // replace Name with the property name you are searching for
354	356		GetEditorClass(PropInfo, Instance);
355	357		end;
356	358		```
357	359
358	360		# Forms
359	361
360	362		The IDE allows to easily create descendants of forms and frames. These forms can have new published components and new published methods. But you when you add new published properties, they are not accessible via the Object Inspector. They work only at runtime. The methods in the IDE are fake, they can not be executed. The IDE can create the components, because their classes are registered in the component palette. Your new properties only exist in your source code. The IDE can not fake them yet. That's why you have to register the new class. That means:
361	363
362	364		- create a design time package (or extend an existing one)
363	365		- your form must be in a unit of this package
364	366
365	367		``` pascal
366	368		...
367	369		interface
368	370
369	371		uses FormEditingIntf, Forms;
370	372
371	373		type
372	374		TYourForm = class(TForm)
373	375		private
374	376		FYourProperty: integer;
375	377		published
376	378		property YourProperty: integer read FYourProperty write FYourProperty;
377	379		end;
378	380
379	381		procedure Register;
380	382
381	383		implementation
382	384
383	385		procedure Register;
384	386		begin
385	387		FormEditingHook.RegisterDesignerBaseClass(TYourForm);
386	388		end;
387	389		...
388	390		```
389	391
390	392		- check the "Register" in the package editor for this unit.
391	393		- Install the package in the IDE
392	394
393	395		# Designer
394	396
395	397		## Writing a designer mediator
396	398
397	399		The standard designer allows to visually edit LCL controls, while all others are shown as icons(like TOpenDialog or TDataSource). To visually edit non LCL control, you need to create a designer mediator. This can be used to design webpages, UML diagrams or other widgetsets like [[fpGUI]]. There is a complete example in examples/designnonlcl/.
398	400
399	401		- Install the example package examples/designnonlcl/notlcldesigner.lpk and restart the IDE. This will register the designer mediator for TMyWidget components and add the new components TMyButton, TMyGroupBox to the component palette.
400	402		- Open the the example project examples/designnonlcl/project/NonLCL1.lpi.
401	403		- Open the unit1.pas and show the designer form (F12). You should see the components as red rectangles, which can be selected, moved and resized like LCL controls.
402	404
403	405		## Create a new unique component name
404	406
405	407		``` pascal
406	408		uses FormEditingIntf;
407	409
408	410		...
409	411
410	412		NewName:=FormEditingHook.CreateUniqueComponentName(AComponent);
411	413
412	414		// Or if you need to create the name before creating the component:
413	415
414	416		NewName:=FormEditingHook.CreateUniqueComponentName(ComponentClassName,OwnerComponent);
415	417		// ComponentClassName will be used as prefix, without a leading T.
416	418		// OwnerComponent is the new owner of the new component.
417	419		```
418	420
419	421		## Select a component in the designer/object inspector
420	422
421	423		``` pascal
422	424		uses propedits;
423	425		..
424	426		GlobalDesignHook.SelectOnlyThis(AComponent);
425	427		```
426	428
427	429		## Get unit, designer, form of a file
428	430
429	431		``` pascal
430	432		uses ProjectIntf, LazIDEIntf, ComponentEditors;
431	433		...
432	434		// open file
433	435		if LazarusIDE.DoOpenEditorFile(Filename,-1,-1,[ofAddToRecent])<>mrOk then exit;
434	436		// get file interface
435	437		aFile:=LazarusIDE.ActiveProject.FindFile(Filename,[]);
436	438		// get designer
437	439		aDesigner:=TComponentEditorDesigner(LazarusIDE.GetDesignerWithProjectFile(AFile,true));
438	440		if aDesigner=nil then
439	441		exit; // this unit has no resource (form, frame, datamodule, etc.)
440	442		// get form
441	443		aForm:=aDesigner.Form;
442	444		```
443	445
444	446		## Save unit, designer form
445	447
446	448		``` pascal
447	449		uses LazIDEIntf;
448	450		...
449	451		if LazarusIDE.DoSaveEditorFile(Filename,[])<>mrOk then exit;
450	452		```
451	453
452	454		## Save designer form as Pascal
453	455
454	456		- Use the function FormEditingHook.SaveComponentAsPascal of unit FormEditingfIntf. See examples/pascalstream/CopyAsPasPkg/copyaspasdemounit1.pas.
455	457
456	458		# Event handlers
457	459
458	460		There are several events in the IDE, for which plugins can add their own handlers.
459	461
460	462		## Designer events
461	463
462	464		In propedits.pp there is a "GlobalDesignHook" object, which maintains several events for designing. Each event calls a list of handlers. The default handlers are added by the IDE. You can add your own handlers with the AddHandlerXXX and RemoveHandlerXXX methods. They will be called before the default handlers.
463	465
464	466		Examples:
465	467
466	468		- Adding your handler (this is normally done in the constructor of your object):
467	469
468		-	~~` GlobalDesignHook.AddHandlerPersistentAdded(@YourOnPersistentAdded);`~~
	470	+	```text
	471	+	GlobalDesignHook.AddHandlerPersistentAdded(@YourOnPersistentAdded);
	472	+	```
469	473
470	474		- Removing your handler:
471	475
472		-	~~` GlobalDesignHook.RemoveHandlerPersistentAdded(@YourOnPersistentAdded);`~~
	476	+	```text
	477	+	GlobalDesignHook.RemoveHandlerPersistentAdded(@YourOnPersistentAdded);
	478	+	```
473	479
474	480		- You can remove all handlers at once. For example, it is a good idea to add this line in the destructor of your object:
475	481
476		-	~~` GlobalDesignHook.RemoveAllHandlersForObject(Self);`~~
	482	+	```text
	483	+	GlobalDesignHook.RemoveAllHandlersForObject(Self);
	484	+	```
477	485
478	486		The handlers of GlobalDesignHook:
479	487
480	488		- Lookup root
481	489		- ChangeLookupRoot - Called when the "LookupRoot" changed. The "LookupRoot" is the owner object of the currently selected components. Normally this is a TForm.
482	490		- Methods
483	491		- CreateMethod
484	492		- GetMethodName
485	493		- GetMethods
486	494		- MethodExists
487	495		- RenameMethod
488	496		- ShowMethod
489	497		- MethodFromAncestor
490	498		- ChainCall
491	499		- Components
492	500		- GetComponent
493	501		- GetComponentName
494	502		- GetComponentNames
495	503		- GetRootClassName
496	504		- AddClicked - Called when the user selected a component class and clicked on the designer to add a new component. You can change the component class and the parent.
497	505		- ComponentRenamed - Called when a component was renamed
498	506		- TPersistent objects
499	507		- PersistentAdded - Called when a new TPersistent was added to the LookupRoot
500	508		- PersistentDeleting - Called before a TPersistent is freed.
501	509		- DeletePersistent - Called by the IDE to delete a TPersistent.
502	510		- GetSelectedPersistents - Called when getting the current selection of TPersistent.
503	511		- SetSelectedPersistents - Called when setting the current selection of TPersistent.
504	512		- GetObject
505	513		- GetObjectName
506	514		- GetObjectNames
507	515		- Modifing
508	516		- Modified
509	517		- Revert
510	518		- RefreshPropertyValues
511	519		- Selection
512	520		- SetSelection
513	521		- GetSelection
514	522
515	523		### Examples for designer events
516	524
517	525		#### Example: When dropping a new component move control to a child
518	526
519	527		``` pascal
520	528		...
521	529		type
522	530		TYourDesignerExtension = class
523	531		private
524	532		function AddClicked(ADesigner: TIDesigner;
525	533		MouseDownComponent: TComponent; Button: TMouseButton;
526	534		Shift: TShiftState; X, Y: Integer;
527	535		var AComponentClass: TComponentClass;
528	536		var NewParent: TComponent): boolean of object;
529	537		public
530	538		constructor Create;
531	539		destructor Destroy; override;
532	540		end;
533	541
534	542		...
535	543		constructor TYourDesignerExtension.Create;
536	544		begin
537	545		// register your handler
538	546		GlobalDesignHook.AddHandlerAddClicked(@AddClicked);
539	547		end;
540	548
541	549		destructor TYourDesignerExtension.Destroy;
542	550		begin
543	551		// remove your handler:
544	552		GlobalDesignHook.RemoveHandlerAddClicked(@AddClicked);
545	553		end;
546	554
547	555		function TYourDesignerExtension.AddClicked(ADesigner: TIDesigner;
548	556		MouseDownComponent: TComponent; Button: TMouseButton;
549	557		Shift: TShiftState; X, Y: Integer;
550	558		var AComponentClass: TComponentClass;
551	559		var NewParent: TComponent): boolean of object;
552	560		begin
553	561		// in this example TYourControl is a custom control with a ChildControl.
554	562		// Whenever the user drops a control on the TYourControl instead of adding
555	563		// the new control to the TYourControl, the new control is added as child
556	564		// of ChildControl.
557	565		// created
558	566		if MouseDownComponent is TYourControl then
559	567		NewParent:=TYourControl(MouseDownComponent).ChildControl;
560	568		Result:=true;
561	569		end;
562	570		```
563	571
564	572		### Disabling the designer mouse handler
565	573
566	574		Normally the designer catches all mouse events of a component. If your custom control should handle the mouse events handle you can either set the csDesignInteractive ControlStyle or you can fine control it via the message CM_DESIGNHITTEST in your control:
567	575
568	576		``` pascal
569	577		type
570	578		TYourControl = class(TCustomControl)
571	579		protected
572	580		procedure CMDesignHitTest(var Message: TLMessage); message CM_DESIGNHITTEST;
573	581		end;
574	582		...
575	583		procedure TYourControl.CMDesignHitTest(var Message: TLMessage);
576	584		var
577	585		p: TSmallPoint;
578	586		aShiftState: TShiftState;
579	587		begin
580	588		aShiftState:=KeysToShiftState(PtrUInt(Message.WParam));
581	589		p:=TSmallPoint(longint(Message.LParam));
582	590		debugln(['TForm1.CMDesignHitTest ShiftState=',dbgs(aShiftState),' x=',p.x,' y=',p.y]);
583	591		if SkipDesignerMouseHandler then
584	592		Message.Result:=1; // now the designer calls the normal MouseUp, MouseMove and MouseDown methods.
585	593		end;
586	594		```
587	595
588	596		## Getting notified when a designer form is modified
589	597
590	598		Every designed LCL form has a Designer of type TIDesigner. The IDE creates designers of type TComponentEditorDesigner defined in the IDEIntf unit componenteditors. For example:
591	599
592	600		``` pascal
593	601		procedure TYourAddOn.OnDesignerModified(Sender: TObject);
594	602		var
595	603		IDEDesigner: TComponentEditorDesigner;
596	604		begin
597	605		IDEDesigner:=TComponentEditorDesigner(Sender);
598	606		...
599	607		end;
600	608
601	609		procedure TYourAddOn.ConnectDesignerForm(Form1: TCustomForm);
602	610		var
603	611		IDEDesigner: TComponentEditorDesigner;
604	612		begin
605	613		IDEDesigner:=TComponentEditorDesigner(Form1.Designer);
606	614		IDEDesigner.AddHandlerModified(@OnDesignerModified);
607	615		end;
608	616		```
609	617
610	618		## Project events
611	619
612	620		These events are defined in unit LazIDEIntf.
613	621
614	622		- LazarusIDE.AddHandlerOnProjectClose: called before a project is closed
615	623		- LazarusIDE.AddHandlerOnProjectOpened: called after the project was completely opened (for example all required packages were loaded, units were opened in the source editor)
616	624		- LazarusIDE.AddHandlerOnSavingAll: called before IDE saves everything
617	625		- LazarusIDE.AddHandlerOnSavedAll: called after IDE saved everything
618	626		- LazarusIDE.AddHandlerOnProjectBuilding: called before IDE builds the project
619	627		- LazarusIDE.AddHandlerOnProjectDependenciesCompiling: called before IDE compiles package dependencies of project
620	628		- LazarusIDE.AddHandlerOnProjectDependenciesCompiled: called after IDE compiled package dependencies of project
621	629		- LazarusIDE.AddHandlerOnProjectBuildingFinished: called after IDE built the project (successful or not) (since 1.5)
622	630		- LazarusIDE.AddHandlerOnLoadSaveCustomData: called after loading/before saving a project's CustomData or a project file's CustomData. On save the CustomData is cloned to a temporary tree, so it is free for altering before save. Use this (since 2.3)
623	631
624	632		## Other IDE events
625	633
626	634		uses LazIDEIntf;
627	635
628	636		Call these in the Register procedure of your package:
629	637
630	638		- LazarusIDE.AddHandlerOnIDERestoreWindows: called when IDE is restores its windows (before opening the first project)
631	639		- LazarusIDE.AddHandlerOnIDEClose: called when IDE is shutting down (after closequery, so no more interactivity)
632	640		- LazarusIDE.AddHandlerOnQuickSyntaxCheck: called when the menu item or the shortcut for Quick syntax check is executed
633	641		- LazarusIDE.AddHandlerOnLazarusBuilding: // called before IDE builds Lazarus IDE (since 1.5)
634	642		- LazarusIDE.AddHandlerOnLazarusBuildingFinished: // called after IDE builds Lazarus IDE (since 1.5)
635	643		- LazarusIDE.AddHandlerGetFPCFrontEndParams: // called when the IDE gets the parameters of the 'fpc' front end tool (since 1.5)
636	644		- LazarusIDE.AddHandlerGetFPCFrontEndPath: // called when the IDE gets the path of the 'fpc' front end tool (since 1.5)
637	645		- LazarusIDE.AddHandlerOnUpdateIDEComponentPalette: ?
638	646		- LazarusIDE.AddHandlerOnUpdateComponentPageControl: ?
639	647		- LazarusIDE.AddHandlerOnShowDesignerFormOfSource: // called after showing a designer form for code editor (AEditor can be nil!) (since 1.5)
640	648		- LazarusIDE.AddHandlerOnShowSourceOfActiveDesignerForm: // called after showing a code of designer form (since 1.5)
641	649		- LazarusIDE.AddHandlerOnChangeToolStatus: //called when IDEToolStatus has changed (e.g. itNone-\>itBuilder etc.) (since 1.5)
642	650
643	651		Call these in the initialization section of one of your units:
644	652
645	653		- AddBootHandler
646	654		- AddBootHandler(libhTransferMacrosCreated,@YourProc): called after IDEMacros were created (since 1.3)
647	655		- AddBootHandler(libhEnvironmentOptionsLoaded,@YourProc): called after environment options were loaded (since 1.3)
648	656
649	657		# Project
650	658
651	659		## Current Project
652	660
653	661		The current main project can be obtained by LazarusIDE.ActiveProject. (unit LazIDEIntf)
654	662
655	663		## All units of current project
656	664
657	665		Note that the term "units of project" is ambiguous.
658	666
659	667		- The project inspector shows the list of the .lpi file. The project might not use all these units on all platforms and maybe the developer forgot to add all used units.
660	668		- Units from used packages are not project units.
661	669
662	670		### All units of the project inspector
663	671
664	672		To iterate through all pascal units listed in the project inspector you can use for example:
665	673
666	674		``` pascal
667	675		uses
668	676		LCLProc, FileUtil, LazIDEIntf, ProjectIntf;
669	677
670	678		procedure ListProjectUnits;
671	679		var
672	680		LazProject: TLazProject;
673	681		i: Integer;
674	682		LazFile: TLazProjectFile;
675	683		begin
676	684		LazProject:=LazarusIDE.ActiveProject;
677	685		if LazProject<>nil then
678	686		for i:=0 to LazProject.FileCount-1 do
679	687		begin
680	688		LazFile:=LazProject.Files[i];
681	689		if LazFile.IsPartOfProject
682	690		and FilenameIsPascalUnit(LazFile.Filename)
683	691		then
684	692		debugln(LazFile.Filename);
685	693		end;
686	694		end;
687	695		```
688	696
689	697		### All used units of project
690	698
691	699		To find all currently used units of a project/package you can use the following. Note that the IDE needs to parse all units, so it can take some time.
692	700
693	701		``` pascal
694	702		uses
695	703		LazLoggerBase, LazIDEIntf, ProjectIntf;
696	704
697	705		procedure ListProjectUnits;
698	706		var
699	707		LazProject: TLazProject;
700	708		i: Integer;
701	709		begin
702	710		LazProject:=LazarusIDE.ActiveProject;
703	711		if LazProject<>nil then
704	712		begin
705	713		Units:=LazarusIDE.FindUnitsOfOwner(LazProject,[fuooListed,fuooUsed]); // add fuooPackages to include units from packages
706	714		try
707	715		for i:=0 to Units.Count-1 do
708	716		debugln('Filename=',Units[i]);
709	717		finally
710	718		Units.Free;
711	719		end;
712	720		end;
713	721		end;
714	722		```
715	723
716	724		## The .lpr, .lpi and .lps file of a project
717	725
718	726		``` pascal
719	727		uses
720	728		LCLProc, FileUtil, ProjectIntf, LazIDEIntf;
721	729		var
722	730		LazProject: TLazProject;
723	731		begin
724	732		LazProject:=LazarusIDE.ActiveProject;
725	733		// every project has a .lpi file:
726	734		DebugLn(['Project'' lpi file: ',LazProject.ProjectInfoFile]);
727	735
728	736		// if the project session information is stored in a separate .lps file:
729	737		if LazProject.SessionStorage<>pssNone then
730	738		DebugLn(['Project'' lps file: ',LazProject.ProjectSessionFile]);
731	739
732	740		// If the project has a .lpr file it is the main source file:
733	741		if (LazProject.MainFile<>nil)
734	742		and (CompareFileExt(LazProject.MainFile.Filename,'lpr')=0) then
735	743		DebugLn(['Project has lpr file: ',LazProject.MainFile.Filename]);
736	744		end;
737	745		```
738	746
739	747		## The executable / target file name of a project
740	748
741	749		There is a macro \$(TargetFile), which can be used in paths and external tools. You can query the macro in code:
742	750
743	751		``` pascal
744	752		uses MacroIntf;
745	753
746	754		function MyGetProjectTargetFile: string;
747	755		begin
748	756		Result:='$(TargetFile)';
749	757		if not IDEMacros.SubstituteMacros(Result) then
750	758		raise Exception.Create('unable to retrieve target file of project');
751	759		end;
752	760		```
753	761
754	762		See here for more macros: [[IDE Macros in paths and filenames]].
755	763
756	764		## Add your own project type
757	765
758	766		You can add items to the 'New ...' dialog:
759	767
760	768		- See the unit ProjectIntf of the package IDEIntf.
761	769		- See the [[Project Templates]]
762	770
763	771		## Add your own file type
764	772
765	773		You can add items to the 'New ...' dialog:
766	774
767	775		- See the unit ProjectIntf of the package IDEIntf.
768	776		- Choose a base class TFileDescPascalUnit for normal units or TFileDescPascalUnitWithResource for a new form/datamodule.
769	777
770	778		### Add a new file type
771	779
772	780		``` pascal
773	781		uses ProjectIntf;
774	782		...
775	783		{ TFileDescText }
776	784
777	785		TFileDescMyText = class(TProjectFileDescriptor)
778	786		public
779	787		constructor Create; override;
780	788		function GetLocalizedName: string; override;
781	789		function GetLocalizedDescription: string; override;
782	790		end;
783	791		...
784	792
785	793		procedure Register;
786	794
787	795		implementation
788	796
789	797		procedure Register;
790	798		begin
791	799		RegisterProjectFileDescriptor(TFileDescMyText.Create,FileDescGroupName);
792	800		end;
793	801
794	802		{ TFileDescMyText }
795	803
796	804		constructor TFileDescMyText.Create;
797	805		begin
798	806		inherited Create;
799	807		Name:='MyText'; // do not translate this
800	808		DefaultFilename:='text.txt';
801	809		AddToProject:=false;
802	810		end;
803	811
804	812		function TFileDescText.GetLocalizedName: string;
805	813		begin
806	814		Result:='My Text'; // replace this with a resourcestring
807	815		end;
808	816
809	817		function TFileDescText.GetLocalizedDescription: string;
810	818		begin
811	819		Result:='An empty text file';
812	820		end;
813	821		```
814	822
815	823		### Add a new form type
816	824
817	825		``` pascal
818	826		uses ProjectIntf;
819	827
820	828		...
821	829		TFileDescPascalUnitWithMyForm = class(TFileDescPascalUnitWithResource)
822	830		public
823	831		constructor Create; override;
824	832		function GetInterfaceUsesSection: string; override;
825	833		function GetLocalizedName: string; override;
826	834		function GetLocalizedDescription: string; override;
827	835		end;
828	836		...
829	837
830	838		procedure Register;
831	839
832	840		implementation
833	841
834	842		procedure Register;
835	843		begin
836	844		RegisterProjectFileDescriptor(TFileDescPascalUnitWithMyForm.Create,FileDescGroupName);
837	845		end;
838	846
839	847		{ TFileDescPascalUnitWithMyForm }
840	848
841	849		constructor TFileDescPascalUnitWithMyForm.Create;
842	850		begin
843	851		inherited Create;
844	852		Name:='MyForm'; // do not translate this
845	853		ResourceClass:=TMyForm;
846	854		UseCreateFormStatements:=true;
847	855		end;
848	856
849	857		function TFileDescPascalUnitWithMyForm.GetInterfaceUsesSection: string;
850	858		begin
851	859		Result:='Classes, SysUtils, MyWidgetSet';
852	860		end;
853	861
854	862		function TFileDescPascalUnitWithForm.GetLocalizedName: string;
855	863		begin
856	864		Result:='MyForm'; // replace this with a resourcestring
857	865		end;
858	866
859	867		function TFileDescPascalUnitWithForm.GetLocalizedDescription: string;
860	868		begin
861	869		Result:='Create a new MyForm from example package NotLCLDesigner';
862	870		end;
863	871		```
864	872
865	873		## Add new file
866	874
867	875		Adding a new file to the project: uses LazIDEIntf, ProjectIntf;
868	876
869		-	~~`LazarusIDE.DoNewEditorFile(FileDescriptorUnit,``,``,[nfIsPartOfProject,nfOpenInEditor]);`~~
	877	+	```text
	878	+	LazarusIDE.DoNewEditorFile(FileDescriptorUnit,,,[nfIsPartOfProject,nfOpenInEditor]);
	879	+	```
870	880
871	881		The FileDescriptorUnit generates a default code and a default filename. The new file is opened in the source editor and it is not yet saved to disk.
872	882
873	883		You can create a new file with specific filename and custom source:
874	884
875		-	~~`LazarusIDE.DoNewEditorFile(FileDescriptorUnit,NewFilename,NewSource,[nfIsPartOfProject,nfOpenInEditor]);`~~
	885	+	```text
	886	+	LazarusIDE.DoNewEditorFile(FileDescriptorUnit,NewFilename,NewSource,[nfIsPartOfProject,nfOpenInEditor]);
	887	+	```
876	888
877	889		Keep in mind that the file is not saved to disk. This is done when the user triggers a Save.
878	890
879	891		Alternatively you can create a file via codetools or directly on disk (e.g. TFileStream) and open that in the source editor:
880	892
881		-	~~` LazarusIDE.DoOpenEditorFile(Filename,-1,-1,[ofAddToRecent]);`~~
	893	+	```text
	894	+	LazarusIDE.DoOpenEditorFile(Filename,-1,-1,[ofAddToRecent]);
	895	+	```
882	896
883	897		## Store custom values in lpi/lps
884	898
885	899		You can store your own data via name/value pairs in CustomData and CustomSessionData.
886	900
887		-	~~`LazarusIDE.ActiveProject.CustomData['Name']:=Value; // stored in lpi - x-platform, shared data`\~~
888		-	~~`LazarusIDE.ActiveProject.CustomSessionData['Name']:=Value; // stored in lps - only this machine`~~
	901	+	``` pascal
	902	+	LazarusIDE.ActiveProject.CustomData['Name']:=Value; // stored in lpi - x-platform, shared data
	903	+	LazarusIDE.ActiveProject.CustomSessionData['Name']:=Value; // stored in lps - only this machine
	904	+	```
889	905
890	906		### Store custom filenames in lpi/lps
891	907
892	908		Filenames should be stored relative in the lpi and some care must be taken because platform specifics. Here is an example from the pas2jsdsgn package:
893	909
894	910		Hook the OnLoadSaveCustomData handler:
895	911
896	912		``` pascal
897	913		uses
898	914		LazIDEIntf, ProjectIntf, AvgLvlTree;
899	915
900	916		...
901	917		// in registration
902	918		LazarusIDE.AddHandlerOnLoadSaveCustomData(@OnLoadSaveCustomData);
903	919
904	920		...
905	921		procedure TPJSController.OnLoadSaveCustomData(Sender: TObject; Load: boolean;
906	922		CustomData: TStringToStringTree; PathDelimChanged: boolean);
907	923		var
908	924		fn: String;
909	925		aProject: TLazProject;
910	926		begin
911	927		if Sender is TLazProject then
912	928		begin
913	929		aProject:=TLazProject(Sender);
914	930		if CustomData[PJSProjectWebBrowser]='1' then
915	931		begin
916	932		fn:=CustomData[PJSProjectHTMLFile];
917	933		if fn<>'' then
918	934		begin
919	935		if Load then
920	936		aProject.ConvertFromLPIFilename(fn)
921	937		else
922	938		aProject.ConvertToLPIFilename(fn);
923	939		CustomData[PJSProjectHTMLFile]:=fn;
924	940		end;
925	941		end;
926	942		end;
927	943		if PathDelimChanged then ;
928	944		end;
929	945		```
930	946
931	947		# Packages
932	948
933	949		You can perform various actions with [[Lazarus Packages\|Packages]]:
934	950
935	951		## Search in all packages
936	952
937	953		Iterate all packages loaded in the IDE (since 0.9.29).
938	954
939	955		``` pascal
940	956		uses PackageIntf;
941	957		...
942	958		for i:=0 to PackageEditingInterface.GetPackageCount-1 do
943	959		writeln(PackageEditingInterface.GetPackages(i).Name);
944	960		```
945	961
946	962		## Search a package with a name
947	963
948	964		``` pascal
949	965		uses PackageIntf;
950	966		...
951	967		var
952	968		Pkg: TIDEPackage;
953	969		begin
954	970		Pkg:=PackageEditingInterface.FindPackageWithName('LCL');
955	971		if Pkg<>nil then
956	972		...
957	973		end;
958	974		```
959	975
960	976		Note: FindPackageWithName does not open the package editor. For that use DoOpenPackageWithName.
961	977
962	978		## Get lpk filename of an installed package
963	979
964	980		``` pascal
965	981		uses PackageIntf;
966	982		...
967	983		var
968	984		Pkg: TIDEPackage;
969	985		begin
970	986		Pkg:=PackageEditingInterface.FindPackageWithName('LCL');
971	987		if Pkg<>nil then
972	988		LPKFilename:=Pkg.Filename;
973	989		end;
974	990		```
975	991
976	992		## Install packages
977	993
978	994		Note: Only install packages with IDE plugins. Installing other packages can make the IDE unstable.
979	995
980	996		``` pascal
981	997		uses PackageIntf, contnrs;
982	998		...
983	999		PkgList:=TObjectList.create(true);
984	1000		try
985	1001		Pkg:=TLazPackageID.Create;
986	1002		Pkg.Name:='Cody';
987	1003		PkgList.Add(Pkg);
988	1004		// check if the IDE can find the cody.lpk and all dependencies
989	1005		// The IDE will prompt some warnings/confirmations if something looks strange.
990	1006		if not PackageEditingInterface.CheckInstallPackageList(PkgList,[]) then
991	1007		exit;
992	1008		// in this example we have checked already, so skip the warnings
993	1009		// and rebuild the IDE
994	1010		if PackageEditingInterface.InstallPackages(PkgList,[piiifSkipChecks,piiifRebuildIDE])<>mrOK then
995	1011		exit;
996	1012		finally
997	1013		PkgList.Free;
998	1014		end;
999	1015		```
1000	1016
1001	1017		## Open a package file (lpk)
1002	1018
1003	1019		``` pascal
1004	1020		uses PackageIntf, FileUtil;
1005	1021		...
1006	1022		var
1007	1023		pkg: TIDEPackage;
1008	1024		begin
1009	1025		if PackageEditingInterface.DoOpenPackageFile(LPKFilename,[pofAddToRecent],false)<>mrOk then
1010	1026		exit;
1011	1027		Pkg:=PackageEditingInterface.FindPackageWithName(ExtractFilenameOnly(LPKFilename));
1012	1028		...
1013	1029		end;
1014	1030		```
1015	1031
1016	1032		> Warning: The IDE automatically closes unused packages on idle. Never keep a reference to an TIDEPackage.
1017	1033
1018	1034		## Find the package(s) of a unit
1019	1035
1020	1036		You have the file name of a unit, e.g. '/home/user/unit.pas', and you want to know to which package(s) and project(s) it belongs use this:
1021	1037
1022	1038		``` pascal
1023	1039		uses Classes, PackageIntf, ProjectIntf;
1024	1040		...
1025	1041		var
1026	1042		Owners: TFPList;
1027	1043		i: Integer;
1028	1044		o: TObject;
1029	1045		begin
1030	1046		Owners:=PackageEditingInterface.GetPossibleOwnersOfUnit('/full/path/of/unit.pas',[]);
1031	1047		if Owners=nil then begin
1032	1048		// unit is not directly associated with a project/package
1033	1049		// maybe the unit was for some reason not added, but is reachable
1034	1050		// search in all unit paths of all projects/packages
1035	1051		// Beware: This can lead to false hits
1036	1052		Owners:=PackageEditingInterface.GetPossibleOwnersOfUnit('/full/path/of/unit.pas',
1037	1053		[piosfExcludeOwned,piosfIncludeSourceDirectories]);
1038	1054		end;
1039	1055		if Owners=nil then exit;
1040	1056		try
1041	1057		for i:=0 to Owners.Count-1 do begin
1042	1058		o:=TObject(Owners[i]);
1043	1059		if o is TIDEPackage then begin
1044	1060		writeln('Owner is package ',TIDEPackage(o).Name);
1045	1061		end else if o is TLazProject then begin
1046	1062		writeln('Owner is project ',TLazProject(o).ProjectInfoFile);
1047	1063		end;
1048	1064		end;
1049	1065		finally
1050	1066		Owners.Free;
1051	1067		end;
1052	1068		```
1053	1069
1054	1070		## Find the required package(s) of a project/package
1055	1071
1056	1072		You have a project or a package and you want to know which package(s) are required use this:
1057	1073
1058	1074		``` pascal
1059	1075		uses Classes, PackageIntf, ProjectIntf;
1060	1076		...
1061	1077		var
1062	1078		lPkgList: TFPList;
1063	1079		i: Integer;
1064	1080		begin
1065	1081		PackageEditingInterface.GetRequiredPackages(LazarusIDE.ActiveProject, lPkgList, [pirNotRecursive]);
1066	1082		try
1067	1083		for i := 0 to lPkgList.Count - 1 do begin
1068	1084		writeln('required package is ' + TIDEPackage(lPkgList[i]).Filename);
1069	1085		end;
1070	1086		finally
1071	1087		lPkgList.Free;
1072	1088		end;
1073	1089		...
1074	1090		```
1075	1091
1076	1092		# Windows
1077	1093
1078	1094		There are basically four types of IDE windows.
1079	1095
1080	1096		- the main IDE bar is the Application.MainForm. It is always present.
1081	1097		- floating/dockable windows like the Source Editors, the Object Inspectors and Messages.
1082	1098		- the modal forms, like the find dialog, options dialogs and questions.
1083	1099		- hints and completion forms
1084	1100
1085	1101		## Adding a new dockable IDE window
1086	1102
1087	1103		What is a dockable IDE window: Windows like the Source Editor or the Object Inspector are floating windows, that can be docked if a docking package is installed, and its state, position and size is stored and restored on next IDE start. In order to restore a window the IDE needs a creator as defined in the unit IDEWindowIntf of the package IDEIntf. Each dockable window must have a unique name. Do not use generic names like 'FileBrowser' because this will easily clash with other packages. And don't use short names like 'XYZ', because the creator is responsible for all forms beginning with this name.
1088	1104
1089	1105		### How to register a dockable IDE window
1090	1106
1091	1107		Remember to choose a long unique name that is a valid pascal identifier. Your window can have any caption you want.
1092	1108
1093	1109		``` pascal
1094	1110		uses SysUtils, IDEWindowIntf;
1095	1111		...
1096	1112		var MyIDEWindow: TMyIDEWindow = nil;
1097	1113
1098	1114		procedure CreateMyIDEWindow(Sender: TObject; aFormName: string; var AForm: TCustomForm; DoDisableAutoSizing: boolean);
1099	1115		begin
1100	1116		// check the name
1101	1117		if CompareText(aFormName,MyIDEWindowName)<>0 then exit;
1102	1118		// create the form if not already done and disable autosizing
1103	1119		IDEWindowCreators.CreateForm(MyIDEWindow,TMyIDEWindowm,DoDisableAutosizing,Application);
1104	1120		... init the window ...
1105	1121		AForm:=MyIDEWindow;
1106	1122		end;
1107	1123
1108	1124		procedure Register;
1109	1125		begin
1110	1126		IDEWindowCreators.Add('MyIDEWindow',@CreateMyIDEWindow,nil,'100','50%','+300','+20%');
1111	1127		// the default boundsrect of the form is:
1112	1128		// Left=100, Top=50% of Screen.Height, Width=300, Height=20% of Screen.Height
1113	1129		// when the IDE needs an instance of this window it calls the procedure CreateMyIDEWindow.
1114	1130		end;
1115	1131		```
1116	1132
1117	1133		### Showing an IDE window
1118	1134
1119	1135		Do not use Show. Use:
1120	1136
1121	1137		``` pascal
1122	1138		IDEWindowCreators.ShowForm(MyIDEWindow,false);
1123	1139		```
1124	1140
1125	1141		This will work with docking. The docking system might wrap the form into a docking site. The BringToFront parameter tells the docking system to make the form and all its parent sites visible and bring the top level site to the front.
1126	1142
1127	1143		### Notes about IDEWindowCreators and SimpleLayoutStorage
1128	1144
1129	1145		The IDEWindowCreators.SimpleLayoutStorage simply stores the BoundsRect and WindowState of all forms that were once opened. It is used as fallback if no dockmaster is installed. It stores the state even if a DockMaster is installed, so that when the dockmaster is uninstalled the forms bounds are restored.
1130	1146
1131	1147		The IDEWindowCreators is used by all dockable forms to register themselves and to show forms. When showing a form the Creator checks if a IDEDockMaster is installed and will delegate the showing to it. If no IDEDockMaster is installed it simply shows the form. The IDEDockMaster can use the information in the IDEWindowCreators to create forms by names and get an idea where to place a form when showing it for the first time. For more details see the packages AnchorDockingDsgn and EasyDockMgDsgn.
1132	1148
1133	1149		# CodeTools
1134	1150
1135	1151		The CodeTools is a package providing a vast amount of functions to parse, search and change pascal sources and some basic functions for other languages as well. You can use them without the IDE too. It is recommended that you read first about the CodeTools in general before using them in the IDE: [[Codetools]].
1136	1152
1137	1153		Before calling any of the CodeTools functions in the IDE you should commit the current changes of the source editor to the CodeTools buffers:
1138	1154
1139	1155		``` pascal
1140	1156		uses LazIDEIntf;
1141	1157		...
1142	1158		// save changes in source editor to codetools
1143	1159		LazarusIDE.SaveSourceEditorChangesToCodeCache(-1); // -1: commit all source editors
1144	1160		```
1145	1161
1146	1162		## Adding a resource directive to a file
1147	1163
1148	1164		This adds a {\$R example.res} to a pascal unit:
1149	1165
1150	1166		``` pascal
1151	1167		procedure AddResourceDirectiveToPascalSource(const Filename: string);
1152	1168		var
1153	1169		ExpandedFilename: String;
1154	1170		CodeBuf: TCodeBuffer;
1155	1171		begin
1156	1172		// make sure the filename is trimmed and contains a full path
1157	1173		ExpandedFilename:=CleanAndExpandFilename(Filename);
1158	1174
1159	1175		// save changes in source editor to codetools
1160	1176		LazarusIDE.SaveSourceEditorChangesToCodeCache(-1);
1161	1177
1162	1178		// load the file
1163	1179		CodeBuf:=CodeToolBoss.LoadFile(ExpandedFilename,true,false);
1164	1180
1165	1181		// add the resource directive
1166	1182		if not CodeToolBoss.AddResourceDirective(CodeBuf,'example.res') then
1167	1183		LazarusIDE.DoJumpToCodeToolBossError;
1168	1184		end;
1169	1185		```
1170	1186
1171	1187		The codetools provides also functions like FindResourceDirective and RemoveDirective.
1172	1188
1173	1189		## Getting the search paths for units and include files
1174	1190
1175	1191		There are many different search paths in the IDE from projects, packages, the fpc and lazarus directory and there are many types of paths: before or after resolving macros, with or without inherited search paths, as relative or absolute paths. All files in a directory share the same set of search paths. You can get the search paths for each directory fully resolved by asking the codetools:
1176	1192
1177	1193		``` pascal
1178	1194		uses CodeToolManager;
1179	1195		...
1180	1196
1181	1197		Dir:=''; // the empty directory is for new files and has the same settings as the project directory
1182	1198
1183	1199		// Getting the search paths for include files:
1184	1200		Path:=CodeToolBoss.GetIncludePathForDirectory(Dir);
1185	1201
1186	1202		// Getting the search paths for units:
1187	1203		// This search path is passed to the compiler.
1188	1204		// It contains the package output directories, but not the package source directories.
1189	1205		Path:=CodeToolBoss.GetUnitPathForDirectory(Dir);
1190	1206
1191	1207		// There can be additional unit search paths for the IDE only (not passed to the compiler)
1192	1208		Path:=CodeToolBoss.GetSrcPathForDirectory(Dir);
1193	1209
1194	1210		// The complete search path contains also all package source paths for units:
1195	1211		Path:=CodeToolBoss.GetCompleteSrcPathForDirectory(Dir);
1196	1212		```
1197	1213
1198	1214		# Source Editor
1199	1215
1200	1216		## Active source editor
1201	1217
1202	1218		``` pascal
1203	1219		uses SrcEditorIntf;
1204	1220		...
1205	1221		Editor:=SourceEditorManagerIntf.ActiveEditor;
1206	1222		if Editor=nil then exit;
1207	1223		Filename:=Editor.FileName;
1208	1224		ScreenPos:=Editor.CursorScreenXY; // glyph/character and line, both 1-based
1209	1225		TextPos:=Editor.CursorTextXY; // byte and line, both 1-based
1210	1226		```
1211	1227
1212	1228		## Find source editor
1213	1229
1214	1230		You can search for a disk file using the expanded filename. Keep in mind, that newly created files usually have filenames without directory.
1215	1231
1216	1232		``` pascal
1217	1233		uses SrcEditorIntf;
1218	1234		...
1219	1235		Editor:=SourceEditorManagerIntf.SourceEditorIntfWithFilename(aFilename);
1220	1236		if Editor=nil then exit;
1221	1237		Filename:=Editor.FileName; // can be different to what you searchedm e.g. due to UTF-8 and case insensitive file system
1222	1238		```
1223	1239
1224	1240		## Edit source
1225	1241
1226	1242		``` pascal
1227	1243		// You can set the whole source editor text and wipe out the undo history
1228	1244		Editor.SourceText:='New content';
1229	1245
1230	1246		// In order to keep the undo history use the Selection:
1231	1247		Editor.BlockBegin:=Point(1,1);
1232	1248		Editor.BlockEnd:=Point(1,Editor.LineCount+1);
1233	1249		Editor.Selection:='New Content';
1234	1250		```
1235	1251
1236	1252		# SynEdit
1237	1253
1238	1254		## Getting the settings for a TSynEdit
1239	1255
1240	1256		When you have a dialog using a TSynEdit and you want to use the same font and settings like the source editor use:
1241	1257
1242	1258		``` pascal
1243	1259		uses SrcEditorIntf;
1244	1260		...
1245	1261		SourceEditorManagerIntf.GetEditorControlSettings(ASynEdit);
1246	1262		```
1247	1263
1248	1264		## Getting the settings for a SynEdit highlighter
1249	1265
1250	1266		When you have a dialog using a TSynEdit with a highlighter and you want to use the same colors like the source editor highlighter for this language use:
1251	1267
1252	1268		``` pascal
1253	1269		uses SrcEditorIntf;
1254	1270		...
1255	1271		SourceEditorManagerIntf.GetHighlighterSettings(ASynHighlighter);
1256	1272		```
1257	1273
1258	1274		See for an example: TSQLStringsPropertyEditorDlg.Create in the unit [SQLStringsPropertyEditorDlg](http://svn.freepascal.org/svn/lazarus/trunk/components/sqldb/sqlstringspropertyeditordlg.pas).
1259	1275
1260	1276		# Help
1261	1277
1262	1278		## Adding help for sources
1263	1279
1264	1280		First create a THelpDatabase:
1265	1281
1266	1282		``` pascal
1267	1283		HelpDB := TFPDocHTMLHelpDatabase(
1268	1284		HelpDatabases.CreateHelpDatabase('ANameOfYourChoiceForTheDatabase',
1269	1285		TFPDocHTMLHelpDatabase,true));
1270	1286		HelpDB.DefaultBaseURL := 'http://your.help.org/';
1271	1287
1272	1288		FPDocNode := THelpNode.CreateURL(HelpDB,
1273	1289		'Package1 - A new package',
1274	1290		'file://index.html');
1275	1291		HelpDB.TOCNode := THelpNode.Create(HelpDB,FPDocNode);// once as TOC
1276	1292		DirectoryItem := THelpDBISourceDirectory.Create(FPDocNode,'$(PkgDir)/lcl',
1277	1293		'.pp;.pas',false);// and once as normal page
1278	1294		HelpDB.RegisterItem(DirectoryItem);
1279	1295		```
1280	1296
1281	1297		## Adding lines to the messages window
1282	1298
1283	1299		``` pascal
1284	1300		unit IDEMsgIntf, IDEExternToolIntf;
1285	1301		...
1286	1302		var Dir: String;
1287	1303		begin
1288	1304		Dir:=GetCurrentDir;
1289	1305		IDEMessagesWindow.AddCustomMessage(mluProgress,'Some important message','file.pas',0,0,'My section');
1290	1306		end;
1291	1307		```
1292	1308
1293	1309		# IDE options frame
1294	1310
1295	1311		## Open options in a specific frame
1296	1312
1297	1313		``` pascal
1298	1314		uses LazIDEIntf;
1299	1315		...
1300	1316		LazarusIDE.DoOpenIDEOptions(TYourIDEOptionsFrame);
1301	1317		```
1302	1318
1303	1319		# Miscellaneous
1304	1320
1305	1321		## Adding a macro
1306	1322
1307	1323		You can add your own IDE macros:
1308	1324
1309	1325		``` pascal
1310	1326		uses MacroIntf, MacroDefIntf;
1311	1327
1312	1328		procedure Register;
1313	1329		begin
1314	1330		// registering a Macro with a fixed value:
1315	1331		IDEMacros.Add(TTransferMacro.Create('MyMacro1','Value','Description',nil,[]));
1316	1332		end;
1317	1333
1318	1334		// registering a Macro with a dynamic value requires a method of an object
1319	1335		procedure TForm1.Init;
1320	1336		begin
1321	1337		IDEMacros.Add(TTransferMacro.Create('MyMacro','Value','Description',@OnResolveMyMacro,[]));
1322	1338		end;
1323	1339
1324	1340		function TForm1.OnResolveMyMacro(const s: string; const Data: PtrInt;
1325	1341		var Abort: boolean): string;
1326	1342		// s is the parameter. For example $MyMacro(parameter)
1327	1343		// Data is the querying instance. Can be nil.
1328	1344		// If there is an error set Abort to true.
1329	1345		// The result string can contain macros. For example Result:='$(FPCVer)/$(TargetOS)';
1330	1346		begin
1331	1347		Result:='MyValue';
1332	1348		end;
1333	1349		```
1334	1350
1335	1351		## Query an IDE macro
1336	1352
1337	1353		``` pascal
1338	1354		uses MacroIntf;
1339	1355
1340	1356		function GetCurrentFPCSourceDirectory: string;
1341	1357		begin
1342	1358		Result:='$(FPCSrcDir)';
1343	1359		if not IDEMacros.SubstituteMacros(Result) then
1344	1360		raise Exception.Create('unable to retrieve FPCSrcDir');
1345	1361		end;
1346	1362		```
1347	1363
1348	1364		## Debugging the IDE
1349	1365
1350	1366		- Open a Lazarus instance (called 1st instance of Lazarus).
1351	1367		- Compile the IDE as usual e.g. via Tools/Build Lazarus. Make sure you set up debugging flags like -g or -gw2. Best is to use the profile "Debug IDE" which contains many flags useful for debugging.
1352	1368		- Open the ide\lazarus.lpi project (always with the 1st instance of Lazarus).
1353	1369		- Compile this lazarus project (always with the 1st instance of Lazarus): another instance of Lazarus should appear (called 2nd instance of Lazarus).
1354	1370		- Set breakpoints as needed etc in the opened source code (in the 1st instance of Lazarus), and play with 2nd run-time instance: for example, install a design-time static package *.lpk, then use, interact with this just installed package inside this 2nd instance.
1355	1371
1356	1372		## Adding a parser for external tool
1357	1373
1358	1374		There is an example parser for the Delphi dcc32.exe compiler in compilers/delphi/lazdelphi.lpk.
1359	1375
1360	1376		It parses the output of dcc32.exe for filename and line number, etc, so when you click on an error or hint in the Messages window the IDE jumps to the right position.
1361	1377
1362	1378		After installing this package, you can call dcc32.exe in any project/package instead of fpc: In Compiler Options / Compiler Commands:
1363	1379
1364	1380		- Execute Before: pathofdcc32.exe params...
1365	1381		- Parsers: check "Delphi Compiler"
1366	1382		- Compiler: Skip calling compiler
1367	1383
1368	1384		## See also
1369	1385
1370	1386		- [[Creating IDE Help]]
1371	1387		- [[Help protocol]]
1372	1388		- [[How To Write Lazarus Component]]
1373	1389
1374	1390		---
1375	1391		From the Free Pascal wiki, page "Extending the IDE", as it stood on 2023-12-04 after a change by Jpasj, 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