Extending the IDE/zh CN: what changed

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

Old	New		Line
1	1		# 扩展 IDE
2	2
3	3		## 概述
4	4
5	5		Lazarus IDE 支持以下几种类型的插件：
6	6
7	7		组件（Components）
8	8		这些是“组件面板”上的项目。例如 TButton（可以在“标准”页面上找到）可用于创建按钮。
9	9
10	10		组件编辑器（Component Editors）
11	11		当你在“界面设计器（Designer）”中双击一个组件时（比如“TMainMenu”组件），将调用组件编辑器（比如“菜单编辑器”）。组件编辑器还可以在“界面设计器”的右键菜单中添加一个额外的菜单项（右键单击“界面设计器”中的组件时可以访问）。
12	12
13	13		属性编辑器（Property Editors）
14	14		“对象查看器”的列表中的每一行都使用属性编辑器来设置或更改该属性的值。
15	15
16	16		专家（Experts）
17	17		专家包含所有其他插件类型。他们可能会注册新的菜单项，注册快捷方式或扩展其他 IDE 功能。
18	18
19	19		有两种方式可以将自己的插件添加到 Lazarus IDE：
20	20
21	21		1. 编写一个包，安装它并在包单元的“Register”过程中注册你的插件。
22	22		2. 扩展 Lazarus 代码，并将您的 svn diff 发送到 Lazarus 邮件列表。
23	23
24	24		## 包和 Makefile 依赖项
25	25
26	26		如果添加新的包依赖项，则必须执行以下步骤。
27	27
28	28		- 创建 / 通过包编辑器更新包的 MakeFile/ 更多 .../ 创建 Makefile。
29	29		- 修复所有依赖项。请参阅 tools/updatemakefiles.lpi
30	30
31	31		# 菜单项
32	32
33	33		您可以添加新菜单项，隐藏或移动现有菜单项并添加子菜单、菜单区（菜单区是整个菜单中的一块区域，它可以是一个包含子菜单的菜单项，也可以是由分隔符分隔出来的一块区域。如果菜单区中没有子项，则该菜单区将不可见。比如 itmFileNew 就是一个用分隔符分隔的菜单区，它里面包含了“新建单元”、“新建窗体”、“新建 ...” 等菜单项，itmFileRecentOpen 也是一个菜单区，它只是一个菜单项，包含“最近打开的文件”子菜单）。对于您自己的窗体，您可以注册 TMainMenu/TPopupMenu，以便其它包可以进一步扩展您的窗体。IDEIntf 包的 MenuIntf 单元包含菜单的所有注册函数和 IDE 本身的许多标准菜单项。
34	34
35	35		## 添加菜单项
36	36
37	37		像“查看 -\> 对象查看器”这样的单个菜单项称为 TIDEMenuCommand。您可以使用 RegisterIDEMenuCommand 创建一个，它有两个带有大量参数的格式：
38	38
39	39		``` pascal
40	40		function RegisterIDEMenuCommand(
41	41		Parent: TIDEMenuSection;
42	42		const Name, Caption: string;
43	43		const OnClickMethod: TNotifyEvent = nil;
44	44		const OnClickProc: TNotifyProcedure = nil;
45	45		const Command: TIDECommand = nil;
46	46		const ResourceName: String = ''
47	47		): TIDEMenuCommand; overload;
48	48
49	49		function RegisterIDEMenuCommand(
50	50		const Path, Name, Caption: string;
51	51		const OnClickMethod: TNotifyEvent = nil;
52	52		const OnClickProc: TNotifyProcedure = nil;
53	53		const Command: TIDECommand = nil;
54	54		const ResourceName: String = ''
55	55		): TIDEMenuCommand; overload;
56	56		```
57	57
58	58		这两者之间的区别仅在于指定父菜单区的方式。您可以通过 Path 参数直接或间接地给出菜单区。MenuIntf 单元中可以找到许多标准菜单区。例如 mnuTools 菜单区，它是主 IDE 栏的 Tools 菜单。它包含一个子菜单区 itmSecondaryTools，用于第三方工具的推荐菜单区。
59	59
60	60		下面的代码注册了一个新的菜单命令，菜单名（Name）为“MyTool”，菜单标题（Caption）为“我的工具(&T)”，点击后执行 StartMyTool 过程：
61	61
62	62		``` pascal
63	63		procedure StartMyTool;
64	64		begin
65	65		... 点击菜单项后要执行的代码 ...
66	66		end;
67	67
68	68		procedure Register;
69	69		begin
70	70		RegisterIDEMenuCommand(itmSecondaryTools, 'MyTool', ' 我的工具(&T)', nil, @StartMyTool);
71	71		end;
72	72		```
73	73
74	74		如果要调用方法而不是过程，请使用 OnClickMethod 参数。
75	75
76	76		此菜单项没有快捷键。如果需要快捷键，则必须创建一个 TIDECommand 对象并将其传递给 Command 参数。例如：
77	77
78	78		``` pascal
79	79		uses
80	80		... Classes, LCLType, Dialogs, IDECommands, MenuIntf;
81	81
82	82		...
83	83
84	84		procedure StartMyTool(Sender :TObject);
85	85		begin
86	86		ShowMessage('Hello World!');
87	87		end;
88	88
89	89		procedure Register;
90	90		var
91	91		Key: TIDEShortCut;
92	92		Cat: TIDECommandCategory;
93	93		CmdMyTool: TIDECommand;
94	94		begin
95	95		// 注册 IDE 快捷键（Ctrl+Alt+Shift+T）和菜单项
96	96		Key := IDEShortCut(VK_T,[ssCtrl,ssAlt,ssShift],VK_UNKNOWN,[]);
97	97		Cat := IDECommandList.FindCategoryByName(CommandCategoryToolMenuName);
98	98		CmdMyTool := RegisterIDECommand(Cat, 'StartMyTool', ' 启动我的工具 ', Key, nil, @StartMyTool);
99	99		RegisterIDEMenuCommand(itmSecondaryTools, 'MyTool', ' 我的工具 (&T)', nil, nil, CmdMyTool);
100	100		end;
101	101		```
102	102
103	103		## 快捷键
104	104
105	105		所有快捷键都在 IDECommandList 中注册。下面是一个示例，将查找所有使用 Ctrl-D 作为快捷键的命令：
106	106
107	107		``` pascal
108	108		uses
109	109		Classes, SysUtils, Dialogs, LCLType, LCLProc, IDECommands, MenuIntf;
110	110
111	111		// 列出所有使用 Ctrl-D 的 IDE 命令
112	112		procedure ListCtrlD;
113	113		var
114	114		i :integer;
115	115		Cmd :TIDECommand;
116	116		Commands :TFPList;
117	117		begin
118	118		Commands := IDECommandList.FindCommandsByShortCut(IDEShortCut(VK_D, [ssCtrl], VK_UNKNOWN, []));
119	119		try
120	120		for i := 0 to Commands.Count - 1 do
121	121		begin
122	122		Cmd := TIDECommand(Commands[i]);
123	123		ShowMessage(format('Cmd: %s, A = %s - %d, %s - %d' + #13#10 + 'B = %s - %d, %s - %d',
124	124		[Cmd.Name,
125	125		dbgs(Cmd.ShortcutA.Shift1),
126	126		Cmd.ShortcutA.Key1,
127	127		dbgs(Cmd.ShortcutA.Shift2),
128	128		Cmd.ShortcutA.Key2,
129	129		dbgs(Cmd.ShortcutB.Shift1),
130	130		Cmd.ShortcutB.Key1,
131	131		dbgs(Cmd.ShortcutB.Shift2),
132	132		Cmd.ShortcutB.Key2]));
133	133		end;
134	134		finally
135	135		Commands.Free;
136	136		end;
137	137		end;
138	138		```
139	139
140	140		# 配置文件
141	141
142	142		加载和保存配置
143	143
144	144		IDE 的所有配置文件都以 xml 格式存储在一个目录中（主配置目录）。包也可以在那里添加自己的配置文件。可以使用下面的方式读取“主配置目录”：
145	145
146	146		``` pascal
147	147		uses LazIDEIntf;
148	148		...
149	149		Directory := LazarusIDE.GetPrimaryConfigPath;
150	150		```
151	151
152	152		包可以创建自己的 xml 文件：
153	153
154	154		``` pascal
155	155		uses
156	156		..., LCLProc, BaseIDEIntf, LazConfigStorage;
157	157
158	158		const
159	159		Version = 1;
160	160		var
161	161		Config: TConfigStorage;
162	162		SomeValue: String;
163	163		SomeInteger: Integer;
164	164		SomeBoolean: Boolean;
165	165		FileVersion: LongInt;
166	166		begin
167	167		SomeValue:='Default';
168	168		SomeInteger:=3;
169	169		SomeBoolean:=true;
170	170
171	171		// 保存配置
172	172		try
173	173		Config:=GetIDEConfigStorage('mysettings.xml',false);
174	174		try
175	175		// 存储版本号，以便将来的扩展可以处理旧的配置文件
176	176		Config.SetDeleteValue('Path/To/The/Version',Version,0);
177	177		// 存储字符串变量 “someValue”
178	178		// 如果 someValue 的值和默认值相同，则不会存储该项
179	179		// 因此只有与默认值不同的项才会被存储
180	180		// 这样能使 XML 保持简短，并且便于在将来改变默认值。
181	181		Config.SetDeleteValue('Path/To/Some/Value',SomeValue,'Default');
182	182		Config.SetDeleteValue('Path/To/Some/Integer',SomeInteger,3);
183	183		Config.SetDeleteValue('Path/To/Some/Boolean',SomeBoolean,true);
184	184		// 还有很多 SetDeleteValue 的重载，通过 Ctrl+Space（代码提示的快捷键）查看它们。
185	185		finally
186	186		Config.Free;
187	187		end;
188	188
189	189		except
190	190		on E: Exception do begin
191	191		DebugLn(['Saving mysettings.xml failed: ',E.Message]);
192	192		end;
193	193		end;
194	194
195	195		// 加载配置
196	196		try
197	197		Config:=GetIDEConfigStorage('mysettings.xml',true);
198	198		try
199	199		// 读取配置的版本
200	200		FileVersion:=Config.GetValue('Path/To/The/Version',0);
201	201		// 读取字符串变量“SomeValue”。如果该项不存在，则使用默认值。
202	202		SomeValue:=Config.GetValue('Path/To/Some/Value','Default');
203	203		SomeInteger:=Config.GetValue('Path/To/Some/Integer',3);
204	204		SomeBoolean:=Config.GetValue('Path/To/Some/Boolean',true);
205	205		finally
206	206		Config.Free;
207	207		end;
208	208		except
209	209		on E: Exception do begin
210	210		DebugLn(['Loading mysettings.xml failed: ',E.Message]);
211	211		end;
212	212		end;
213	213		end;
214	214		```
215	215
216	216		注意：
217	217
218	218		- 每个 IDE 插件都应该使用自己的配置文件。特别是您不能使用标准 IDE 选项文件，如 editoroptions.xml 或 environmentoptions.xml。
219	219		- GetIDEConfigStorage 在加载时，会检查文件是否存在，如果不存在，它将从辅助配置目录复制模板。
220	220		- 从 0.9.31 开始，您可以使用此函数在主配置目录之外加载文件。
221	221
222	222		# 组件
223	223
224	224		## 扩展现有组件
225	225
226	226		来源：[1](http://lazarus.freepascal.org/index.php/topic,17733.msg98425.html#msg98425) 定制现有的 LCL 组件很简单，例如，如果要添加属性。
227	227
228	228		使用字段及其相应的 setter 和 getter 方法来添加所需的属性。
229	229
230	230		然后“手动”实例化它们，给出一个 OWner 组件（以便处理稍后的销毁操作），并设置 Parent 和可能的 Top 和 Left 以及组件在初始化时需要的任何其他默认值。
231	231
232	232		如果您对自定义组件的调试感到满意，请添加一个 RegisterComponent() 调用以将其加入到 IDE 的组件面板中，并保存您必须“手动”编写的设置代码（查看任一个组件的源代码以了解如何执行此操作）。
233	233
234	234		这是一个简单的例子：
235	235
236	236		``` pascal
237	237		unit Unit1;
238	238
239	239		{$mode objfpc}{$H+}
240	240
241	241		interface
242	242
243	243		uses
244	244		Classes, SysUtils, Forms, StdCtrls;
245	245
246	246		type
247	247		TEdX = class(TEdit)
248	248		private
249	249		FNewIntProp: integer;
250	250		FNewStrProp: string;
251	251		procedure SetNewIntProp(AValue: integer);
252	252		procedure SetNewStrProp(AValue: string);
253	253		public
254	254		constructor Create(theComponent: TComponent); override;
255	255		property NewIntProp: integer read FNewIntProp write SetNewIntProp;
256	256		property NewStrProp: string read FNewStrProp write SetNewStrProp;
257	257		end;
258	258
259	259		TForm1 = class(TForm)
260	260		procedure FormCreate(Sender: TObject);
261	261		private
262	262		edX: TEdX;
263	263		public
264	264		end;
265	265
266	266		var
267	267		Form1: TForm1;
268	268
269	269		implementation
270	270
271	271		{ TForm1 }
272	272
273	273		procedure TForm1.FormCreate(Sender: TObject);
274	274		begin
275	275		edX:= TEdX.Create(Self);
276	276		edX.Parent:= Self;
277	277		edX.Caption:= IntToStr(edX.NewIntProp);
278	278		Caption:= edX.NewStrProp;
279	279		end;
280	280
281	281		{$R *.lfm}
282	282
283	283		{ TEdX }
284	284
285	285		procedure TEdX.SetNewIntProp(AValue: integer);
286	286		begin
287	287		if FNewIntProp=AValue then Exit;
288	288		FNewIntProp:=AValue;
289	289		// 这里填写自定义代码
290	290		end;
291	291
292	292		procedure TEdX.SetNewStrProp(AValue: string);
293	293		begin
294	294		if FNewStrProp=AValue then Exit;
295	295		FNewStrProp:=AValue;
296	296		// 这里填写自定义代码
297	297		end;
298	298
299	299		constructor TEdX.Create(theComponent: TComponent);
300	300		begin
301	301		inherited Create(theComponent);
302	302		FNewStrProp:= 'new string property value';
303	303		FNewIntProp:= 99;
304	304		end;
305	305
306	306		end.
307	307		```
308	308
309	309		## 编写组件
310	310
311	311		主要文章：[[How To Write Lazarus Component]]
312	312
313	313		您可以通过包编辑器创建新组件。
314	314
315	315		创建或打开一个包，单击“添加 -\> 新组件”，填写项目： Ancestor Type = TButton， New class name = TMyButton， palette page = Misc， Unit name = mybutton.pas（将创建此文件），单位名称 MyButton，然后单击确定。
316	316
317	317		### 为组件面板提供一个新组件图标
318	318
319	319		创建格式为 .bmp、.xpm 或 .png 的图像文件，其名称与组件类相同。例如 tmybutton.png 并将其保存在包源目录中。图像可以由任何图形程序（例如 gimp）创建，并且不应大于 24x24 像素。然后使用 lazres 工具将图像转换为资源文件，该工具可以在 lazarus/tools 目录中找到：
320	320
321	321		``` bash
322	322		~/lazarus/tools/lazres mybutton.lrs tmybutton.png
323	323		# note: Laz trunk/1.4+? uses .res resource files instead of .lrs files:
324	324		~/lazarus/tools/lazres mybutton.res tmybutton.png
325	325		```
326	326
327	327		这将创建一个 pascal include 文件，该文件在 mybutton.pas 的初始化部分中使用：
328	328
329	329		``` pascal
330	330		initialization
331	331		{$I mybutton.lrs}
332	332		// 或在较新的 Lazarus 版本中 - to docheck 语法
333	333		{$R mybutton.res}
334	334		```
335	335
336	336		安装包。
337	337
338	338		### 隐藏组件面板中的组件
339	339
340	340		Package IDEIntf, unit componentreg:
341	341
342	342		``` pascal
343	343		IDEComponentPalette.FindComponent('TButton').Visible:=false;
344	344		```
345	345
346	346		## 编写组件编辑器
347	347
348	348		组件编辑器处理诸如双击设计器中的组件或右键单击组件时添加菜单项之类的操作。编写组件编辑器很简单。有关大量示例，请参阅 IDEIntf 包的 componenteditors.pas 单元。例如，双击时显示编辑器，请参阅 TCheckListBoxComponentEditor。
349	349
350	350		## 编写属性编辑器
351	351
352	352		“属性查看器”中的每种属性（整数、字符串、TFont、...）都需要属性编辑器。如果组件具有字符串类型的属性 Password，则可以为特定组件类定义属性编辑器，并使用字符串类型的名为 Password 的属性。在 IDEIntf 的 propedits.pp 单元中包含 IDE 本身使用的许多标准属性编辑器。例如 TStringPropertyEditor 是所有字符串的默认属性编辑器，而 TComponentNamePropertyEditor 更有针对性，它只处理 TComponent.Name。请参阅示例中的单元文件。
353	353
354	354		### 在 Object Inspector 中隐藏属性
355	355
356	356		有一个特殊的属性编辑器用于隐藏：
357	357
358	358		``` pascal
359	359		RegisterPropertyEditor(TypeInfo(TAnchorSide), TControl, 'AnchorSideLeft', THiddenPropertyEditor);
360	360		```
361	361
362	362		### 找出属性使用的属性编辑器
363	363
364	364		``` pascal
365	365		uses Classes, TypInfo;
366	366		var
367	367		Instance: TPersistent; // 你的实例
368	368		PropInfo: PPropInfo;
369	369		EdClass: TPropertyEditorClass;
370	370		begin
371	371		PropInfo:=GetPropInfo(Instance.ClassType,'Name'); // 将 Name 替换为您要搜索的属性名称
372	372		GetEditorClass(PropInfo, Instance);
373	373		end;
374	374		```
375	375
376	376		## 窗体
377	377
378	378		IDE 允许轻松创建窗体和框架的后代。这些窗体可以包含新的 published 组件和新的 published 方法。但是，当您添加新的 published 属性时，无法通过“对象查看器”访问它们。它们仅在运行时工作。IDE 中的方法是伪造的，无法执行。IDE 可以创建组件，因为它们的类已在组件面板中注册。你的新属性仅存在于源代码中，IDE 还不能伪造它们。这就是你必须注册新类的原因。这意味着：
379	379
380	380		- 创建设计时包（或扩展现有包）
381	381		- 您的窗体必须在此包的单元中
382	382
383	383		``` pascal
384	384		...
385	385		interface
386	386
387	387		uses FormEditingIntf, Forms;
388	388
389	389		type
390	390		TYourForm = class(TForm)
391	391		private
392	392		FYourProperty: integer;
393	393		published
394	394		property YourProperty: integer read FYourProperty write FYourProperty;
395	395		end;
396	396
397	397		procedure Register;
398	398
399	399		implementation
400	400
401	401		procedure Register;
402	402		begin
403	403		FormEditingHook.RegisterDesignerBaseClass(TYourForm);
404	404		end;
405	405		...
406	406		```
407	407
408	408		- 检查包编辑器中本单元的“Register”。
409	409		- 在 IDE 中安装包
410	410
411	411		# 界面设计器（Designer）
412	412
413	413		### 编写一个设计器中间层
414	414
415	415		标准设计器允许可视化编辑 LCL 控件，而所有其它控件都显示为图标（如 TOpenDialog 或 TDataSource）。要可视地编辑非 LCL 控件，您需要创建一个设计器中间层。这可用于设计网页，UML 图或其它小部件集，如 [[fpGUI]]。在 examples/designnonlcl/ 中有一个完整的例子。
416	416
417	417		- 安装示例包 examples/designnonlcl/notlcldesigner.lpk 并重新启动 IDE。这将为 TMyWidget 组件注册设计器中间层，并将新组件 TMyButton，TMyGroupBox 添加到组件面板中。
418	418		- 打开示例项目 examples/designnonlcl/project/NonLCL1.lpi。
419	419		- 打开 unit1.pas 并切换到设计器界面（F12）。您应该看到组件为红色矩形，可以像 LCL 控件一样选择，移动和调整大小。
420	420
421	421		## 创建一个新的唯一组件名称
422	422
423	423		``` pascal
424	424		uses FormEditingIntf;
425	425
426	426		...
427	427
428	428		NewName:=FormEditingHook.CreateUniqueComponentName(AComponent);
429	429
430	430		// 或者如果您需要在创建组件之前创建名称：
431	431
432	432		NewName:=FormEditingHook.CreateUniqueComponentName(ComponentClassName,OwnerComponent);
433	433		// ComponentClassName 将用作前缀，没有前导 T.
434	434		// OwnerComponent 是新组件的新所有者。
435	435		```
436	436
437	437		## 在设计器 / 对象检查器中选择一个组件
438	438
439	439		``` pascal
440	440		uses propedits;
441	441		..
442	442		GlobalDesignHook.SelectOnlyThis(AComponent);
443	443		```
444	444
445	445		## 获取单元，设计器，文件的形式
446	446
447	447		``` pascal
448	448		uses ProjectIntf, LazIDEIntf, ComponentEditors;
449	449		...
450	450		// 打开文件
451	451		if LazarusIDE.DoOpenEditorFile(Filename,-1,-1,[ofAddToRecent])<>mrOk then exit;
452	452		// 获取文件界面
453	453		aFile:=LazarusIDE.ActiveProject.FindFile(Filename,[]);
454	454		// 获取设计器
455	455		aDesigner:=TComponentEditorDesigner(LazarusIDE.GetDesignerWithProjectFile(AFile,true));
456	456		if aDesigner=nil then
457	457		exit; // 这个单元没有资源（形式，框架，数据模块等）
458	458		// 获取表单
459	459		aForm:=aDesigner.Form;
460	460		```
461	461
462	462		## 保存单元，设计器窗口
463	463
464	464		``` pascal
465	465		uses LazIDEIntf;
466	466		...
467	467		if LazarusIDE.DoSaveEditorFile(Filename,[])<>mrOk then exit;
468	468		```
469	469
470	470		## 将设计器窗口保存为 Pascal
471	471
472	472		- 使用 FormEditingfIntf 单元的 FormEditingHook.SaveComponentAsPascal 函数。请参阅 examples/pascalstream/CopyAsPasPkg/copyaspasdemounit1.pas。
473	473
474	474		# 事件处理程序
475	475
476	476		IDE 中有几个事件，插件可以为其添加自己的处理程序。
477	477
478	478		## 设计器活动
479	479
480	480		在 propedits.pp 中有一个“GlobalDesignHook”对象，它维护了几个用于设计的事件。每个事件都会调用一个处理程序列表。IDE 添加了默认处理程序。您可以使用 AddHandlerXXX 和 RemoveHandlerXXX 方法添加自己的处理程序。它们将在默认处理程序之前调用。
481	481
482	482		例子：
483	483
484	484		- 添加处理程序（通常在对象的构造函数中完成）：
485	485
486		-	~~` GlobalDesignHook.AddHandlerPersistentAdded(@YourOnPersistentAdded);`~~
	486	+	```text
	487	+	GlobalDesignHook.AddHandlerPersistentAdded(@YourOnPersistentAdded);
	488	+	```
487	489
488	490		- 删除处理程序：
489	491
490		-	~~` GlobalDesignHook.RemoveHandlerPersistentAdded(@YourOnPersistentAdded);`~~
	492	+	```text
	493	+	GlobalDesignHook.RemoveHandlerPersistentAdded(@YourOnPersistentAdded);
	494	+	```
491	495
492	496		- 您可以一次删除所有处理程序。例如，在对象的析构函数中添加此行是个好主意：
493	497
494		-	~~` GlobalDesignHook.RemoveAllHandlersForObject(Self);`~~
	498	+	```text
	499	+	GlobalDesignHook.RemoveAllHandlersForObject(Self);
	500	+	```
495	501
496	502		GlobalDesignHook 的处理程序：
497	503
498	504		- 查找根目录
499	505		- ChangeLookupRoot - 当“LookupRoot”发生变化时调用。“LookupRoot”是当前所选组件的所有者对象。通常这是一个 TForm。
500	506
501	507		- 方法
502	508		- CreateMethod
503	509		- GetMethodName
504	510		- 的 getMethods
505	511		- MethodExists
506	512		- RenameMethod
507	513		- ShowMethod
508	514		- MethodFromAncestor
509	515		- ChainCall
510	516
511	517		- 组件
512	518		- GetComponent
513	519		- GetComponentName
514	520		- GetComponentNames
515	521		- GetRootClassName
516	522		- AddClicked - 在用户选择组件类并单击设计器以添加新组件时调用。您可以更改组件类和父组件。
517	523		- ComponentRenamed - 在重命名组件时调用
518	524
519	525		- TPersistent 对象
520	526		- PersistentAdded - 在将新的 TPersistent 添加到 LookupRoot 时调用
521	527		- PersistentDeleting - 在释放 TPersistent 之前调用。
522	528		- DeletePersistent - 由 IDE 调用以删除 TPersistent。
523	529		- GetSelectedPersistents - 获取当前 TPersistent 选择时调用。
524	530		- SetSelectedPersistents - 在设置 TPersistent 的当前选择时调用。
525	531		- GetObject
526	532		- GetObjectName
527	533		- GetObjectNames
528	534
529	535		- 修改
530	536		- Modified
531	537		- Revert
532	538		- RefreshPropertyValues
533	539
534	540		- 选区
535	541		- SetSelection
536	542		- GetSelection
537	543
538	544		### 设计器活动的例子
539	545
540	546		#### 示例：当放置新组件时，将新组件移动到子组件中
541	547
542	548		``` pascal
543	549		...
544	550		type
545	551		TYourDesignerExtension = class
546	552		private
547	553		function AddClicked(ADesigner: TIDesigner;
548	554		MouseDownComponent: TComponent; Button: TMouseButton;
549	555		Shift: TShiftState; X, Y: Integer;
550	556		var AComponentClass: TComponentClass;
551	557		var NewParent: TComponent): boolean of object;
552	558		public
553	559		constructor Create;
554	560		destructor Destroy; override;
555	561		end;
556	562
557	563		...
558	564		constructor TYourDesignerExtension.Create;
559	565		begin
560	566		// 注册你的处理程序
561	567		GlobalDesignHook.AddHandlerAddClicked(@AddClicked);
562	568		end;
563	569
564	570		destructor TYourDesignerExtension.Destroy;
565	571		begin
566	572		// 删除你的处理程序
567	573		GlobalDesignHook.RemoveHandlerAddClicked(@AddClicked);
568	574		end;
569	575
570	576		function TYourDesignerExtension.AddClicked(ADesigner: TIDesigner;
571	577		MouseDownComponent: TComponent; Button: TMouseButton;
572	578		Shift: TShiftState; X, Y: Integer;
573	579		var AComponentClass: TComponentClass;
574	580		var NewParent: TComponent): boolean of object;
575	581		begin
576	582		// 在此示例中，TYourControl 是一个带有 ChildControl 的自定义控件。
577	583		// 每当用户删除 TYourControl 上的控件而不是将新控件添加到 TYourControl 时，新控件将被添加为 ChildControl 的子控件。
578	584		// 已创建
579	585		if MouseDownComponent is TYourControl then
580	586		NewParent:=TYourControl(MouseDownComponent).ChildControl;
581	587		Result:=true;
582	588		end;
583	589		```
584	590
585	591		### 禁用设计器鼠标处理程序
586	592
587	593		通常，设计人员会捕获组件的所有鼠标事件。如果您的自定义控件应该处理鼠标事件句柄，您可以设置 csDesignInteractive 控件样式，也可以通过控件中的消息 CM_DESIGNHITTEST 对其进行精确控制：
588	594
589	595		``` pascal
590	596		type
591	597		TYourControl = class(TCustomControl)
592	598		protected
593	599		procedure CMDesignHitTest(var Message: TLMessage); message CM_DESIGNHITTEST;
594	600		end;
595	601		...
596	602		procedure TYourControl.CMDesignHitTest(var Message: TLMessage);
597	603		var
598	604		p: TSmallPoint;
599	605		aShiftState: TShiftState;
600	606		begin
601	607		aShiftState:=KeysToShiftState(PtrUInt(Message.WParam));
602	608		p:=TSmallPoint(longint(Message.LParam));
603	609		debugln(['TForm1.CMDesignHitTest ShiftState=',dbgs(aShiftState),' x=',p.x,' y=',p.y]);
604	610		if SkipDesignerMouseHandler then
605	611		Message.Result:=1; // 现在设计器调用了正常的 MouseUp、MouseMove 和 MouseDown 方法。
606	612		end;
607	613		```
608	614
609	615		## 在修改设计器窗体时收到通知
610	616
611	617		每个设计的 LCL 表格都有一个 TIDesigner 类型的设计器。IDE 将创建在 IDEIntf 单元组件中定义的 TComponentEditorDesigner 类型的设计器。例如：
612	618
613	619		``` pascal
614	620		procedure TYourAddOn.OnDesignerModified(Sender: TObject);
615	621		var
616	622		IDEDesigner: TComponentEditorDesigner;
617	623		begin
618	624		IDEDesigner:=TComponentEditorDesigner(Sender);
619	625		...
620	626		end;
621	627
622	628		procedure TYourAddOn.ConnectDesignerForm(Form1: TCustomForm);
623	629		var
624	630		IDEDesigner: TComponentEditorDesigner;
625	631		begin
626	632		IDEDesigner:=TComponentEditorDesigner(Form1.Designer);
627	633		IDEDesigner.AddHandlerModified(@OnDesignerModified);
628	634		end;
629	635		```
630	636
631	637		## 项目事件
632	638
633	639		这些事件在单元 LazIDEIntf 中定义。
634	640
635	641		- LazarusIDE.AddHandlerOnProjectClose：在项目关闭之前调用
636	642		- LazarusIDE.AddHandlerOnProjectOpened：在项目完全打开后调用（例如，加载了所有必需的包，在源代码编辑器中打开了单元）
637	643		- LazarusIDE.AddHandlerOnSavingAll：在 IDE 保存所有内容之前调用
638	644		- LazarusIDE.AddHandlerOnSavedAll：在 IDE 保存所有内容后调用
639	645		- LazarusIDE.AddHandlerOnProjectBuilding：在 IDE 构建项目之前调用
640	646		- LazarusIDE.AddHandlerOnProjectDependenciesCompiling：在 IDE 编译项目的包依赖项之前调用
641	647		- LazarusIDE.AddHandlerOnProjectDependenciesCompiled：在 IDE 编译包项目依赖项后调用
642	648		- LazarusIDE.AddHandlerOnProjectBuildingFinished：在 IDE 构建项目后调用（成功与否）（自 1.5 起）
643	649
644	650		## 其他 IDE 事件
645	651
646	652		uses LazIDEIntf;
647	653
648	654		在包的注册过程中调用这些：
649	655
650	656		- LazarusIDE.AddHandlerOnIDERestoreWindows：在 IDE 恢复其窗口时调用（在打开第一个项目之前）
651	657		- LazarusIDE.AddHandlerOnIDEClose：在 IDE 关闭时调用（在 closequery 之后调用，因此不再进行交互）
652	658		- LazarusIDE.AddHandlerOnQuickSyntaxCheck：执行菜单项或快速语法检查的快捷方式时调用
653	659		- LazarusIDE.AddHandlerOnLazarusBuilding：// 在 IDE 构建 Lazarus IDE 之前调用（从 1.5 开始）
654	660		- LazarusIDE.AddHandlerOnLazarusBuildingFinished：// 在 IDE 构建 Lazarus IDE 后调用（自 1.5 起）
655	661		- LazarusIDE.AddHandlerGetFPCFrontEndParams：// 当 IDE 获取 'fpc' 前端工具的参数时调用（自 1.5 起）
656	662		- LazarusIDE.AddHandlerGetFPCFrontEndPath：// 当 IDE 获取 'fpc' 前端工具的路径时调用（从 1.5 开始）
657	663		- LazarusIDE.AddHandlerOnUpdateIDEComponentPalette：？
658	664		- LazarusIDE.AddHandlerOnUpdateComponentPageControl :?
659	665		- LazarusIDE.AddHandlerOnShowDesignerFormOfSource：// 在显示代码编辑器的设计器表单后调用（AEditor 可以是 nil！）（自 1.5 起）
660	666		- LazarusIDE.AddHandlerOnShowSourceOfActiveDesignerForm：// 显示设计器表单代码后调用（自 1.5 起）
661	667		- LazarusIDE.AddHandlerOnChangeToolStatus：// 在 IDEToolStatus 发生变化时调用（例如 itNone-\> itBuilder 等）（自 1.5 起）
662	668
663	669		在您的某个单元的初始化部分中调用它们：
664	670
665	671		- AddBootHandler
666	672		- AddBootHandler(libhTransferMacrosCreated, @YourProc)：创建 IDEMacros 后调用（自 1.3 起）
667	673		- AddBootHandler(libhEnvironmentOptionsLoaded, @YourProc)：加载环境选项后调用（自 1.3 起）
668	674
669	675		# 项目
670	676
671	677		## 当前的项目
672	678
673	679		目前的主要项目可以通过 LazarusIDE.ActiveProject 获得。（单元 LazIDEIntf）
674	680
675	681		## 当前项目的所有单元
676	682
677	683		请注意，术语“项目单元”是不明确的。
678	684
679	685		- 项目检查器显示 .lpi 文件的列表。该项目可能不会在所有平台上使用所有这些单元，也许开发人员忘记添加所有使用过的单元。
680	686		- 使用过的包中的单元不是项目单元。
681	687
682	688		### 项目检查员的所有单元
683	689
684	690		要遍历项目检查器中列出的所有 pascal 单元，您可以使用例如：
685	691
686	692		``` pascal
687	693		uses
688	694		LCLProc, FileUtil, LazIDEIntf, ProjectIntf;
689	695
690	696		procedure ListProjectUnits;
691	697		var
692	698		LazProject: TLazProject;
693	699		i: Integer;
694	700		LazFile: TLazProjectFile;
695	701		begin
696	702		LazProject:=LazarusIDE.ActiveProject;
697	703		if LazProject<>nil then
698	704		for i:=0 to LazProject.FileCount-1 do
699	705		begin
700	706		LazFile:=LazProject.Files[i];
701	707		if LazFile.IsPartOfProject
702	708		and FilenameIsPascalUnit(LazFile.Filename)
703	709		then
704	710		debugln(LazFile.Filename);
705	711		end;
706	712		end;
707	713		```
708	714
709	715		### 所有用过的项目单元
710	716
711	717		要查找项目 / 包的所有当前使用单元，您可以使用以下内容。请注意，IDE 需要解析所有单元，因此可能需要一些时间。
712	718
713	719		``` pascal
714	720		uses
715	721		LazLoggerBase, LazIDEIntf, ProjectIntf;
716	722
717	723		procedure ListProjectUnits;
718	724		var
719	725		LazProject: TLazProject;
720	726		i: Integer;
721	727		begin
722	728		LazProject:=LazarusIDE.ActiveProject;
723	729		if LazProject<>nil then
724	730		begin
725	731		Units:=LazarusIDE.FindUnitsOfOwner(LazProject,[fuooListed,fuooUsed]); // 添加 fuooPackages 以包含包中的单位
726	732		try
727	733		for i:=0 to Units.Count-1 do
728	734		debugln('Filename=',Units[i]);
729	735		finally
730	736		Units.Free;
731	737		end;
732	738		end;
733	739		end;
734	740		```
735	741
736	742		## 项目的 .lpr、.lpi 和 .lps 文件
737	743
738	744		``` pascal
739	745		uses
740	746		LCLProc, FileUtil, ProjectIntf, LazIDEIntf;
741	747		var
742	748		LazProject: TLazProject;
743	749		begin
744	750		LazProject:=LazarusIDE.ActiveProject;
745	751		// 每个项目都有一个 .lpi 文件：
746	752		DebugLn(['Project'' lpi file: ',LazProject.ProjectInfoFile]);
747	753
748	754		// 如果项目会话信息存储在单独的 .lps 文件中：
749	755		if LazProject.SessionStorage<>pssNone then
750	756		DebugLn(['Project'' lps file: ',LazProject.ProjectSessionFile]);
751	757
752	758		// 如果项目有 .lpr 文件，那么它是主要的源文件：
753	759		if (LazProject.MainFile<>nil)
754	760		and (CompareFileExt(LazProject.MainFile.Filename,'lpr')=0) then
755	761		DebugLn(['Project has lpr file: ',LazProject.MainFile.Filename]);
756	762		end;
757	763		```
758	764
759	765		## 项目的可执行文件 / 目标文件名
760	766
761	767		有一个宏 \$(TargetFile)，可用于路径和外部工具。您可以在代码中查询宏：
762	768
763	769		``` pascal
764	770		uses MacroIntf;
765	771
766	772		function MyGetProjectTargetFile: string;
767	773		begin
768	774		Result:='$(TargetFile)';
769	775		if not IDEMacros.SubstituteMacros(Result) then
770	776		raise Exception.Create('unable to retrieve target file of project');
771	777		end;
772	778		```
773	779
774	780		有关更多宏的信息，请参阅此处：[[IDE Macros in paths and filenames]]。
775	781
776	782		## 添加您自己的项目类型
777	783
778	784		您可以在“新建 ...”对话框中添加项目：
779	785
780	786		- 请参阅 IDEIntf 包的单元 ProjectIntf。
781	787		- 请参阅项目模板
782	788
783	789		## 添加您自己的文件类型
784	790
785	791		您可以在“新建 ...”对话框中添加项目：
786	792
787	793		- 请参阅 IDEIntf 包的单元 ProjectIntf。
788	794		- 为普通单元选择基类 TFileDescPascalUnit，为新表单 / 数据模块选择 TFileDescPascalUnitWithResource。
789	795
790	796		## 添加新文件类型
791	797
792	798		``` pascal
793	799		uses ProjectIntf;
794	800		...
795	801		{ TFileDescText }
796	802
797	803		TFileDescMyText = class(TProjectFileDescriptor)
798	804		public
799	805		constructor Create; override;
800	806		function GetLocalizedName: string; override;
801	807		function GetLocalizedDescription: string; override;
802	808		end;
803	809		...
804	810
805	811		procedure Register;
806	812
807	813		implementation
808	814
809	815		procedure Register;
810	816		begin
811	817		RegisterProjectFileDescriptor(TFileDescMyText.Create,FileDescGroupName);
812	818		end;
813	819
814	820		{ TFileDescMyText }
815	821
816	822		constructor TFileDescMyText.Create;
817	823		begin
818	824		inherited Create;
819	825		Name:='MyText'; // 不要翻译这个
820	826		DefaultFilename:='text.txt';
821	827		AddToProject:=false;
822	828		end;
823	829
824	830		function TFileDescText.GetLocalizedName: string;
825	831		begin
826	832		Result:='My Text'; // 用 resourcestring 替换它
827	833		end;
828	834
829	835		function TFileDescText.GetLocalizedDescription: string;
830	836		begin
831	837		Result:='An empty text file';
832	838		end;
833	839		```
834	840
835	841		### 添加新表单类型
836	842
837	843		``` pascal
838	844		uses ProjectIntf;
839	845
840	846		...
841	847		TFileDescPascalUnitWithMyForm = class(TFileDescPascalUnitWithResource)
842	848		public
843	849		constructor Create; override;
844	850		function GetInterfaceUsesSection: string; override;
845	851		function GetLocalizedName: string; override;
846	852		function GetLocalizedDescription: string; override;
847	853		end;
848	854		...
849	855
850	856		procedure Register;
851	857
852	858		implementation
853	859
854	860		procedure Register;
855	861		begin
856	862		RegisterProjectFileDescriptor(TFileDescPascalUnitWithMyForm.Create,FileDescGroupName);
857	863		end;
858	864
859	865		{ TFileDescPascalUnitWithMyForm }
860	866
861	867		constructor TFileDescPascalUnitWithMyForm.Create;
862	868		begin
863	869		inherited Create;
864	870		Name:='MyForm'; // 不要翻译这个
865	871		ResourceClass:=TMyForm;
866	872		UseCreateFormStatements:=true;
867	873		end;
868	874
869	875		function TFileDescPascalUnitWithMyForm.GetInterfaceUsesSection: string;
870	876		begin
871	877		Result:='Classes, SysUtils, MyWidgetSet';
872	878		end;
873	879
874	880		function TFileDescPascalUnitWithForm.GetLocalizedName: string;
875	881		begin
876	882		Result:='MyForm'; // 用 resourcestring 替换它
877	883		end;
878	884
879	885		function TFileDescPascalUnitWithForm.GetLocalizedDescription: string;
880	886		begin
881	887		Result:='Create a new MyForm from example package NotLCLDesigner';
882	888		end;
883	889		```
884	890
885	891		## 以 lpi/lps 存储自定义值
886	892
887	893		您可以通过 CustomData 和 CustomSessionData 中的键值对存储您自己的数据。
888	894
889		-	~~` LazarusIDE.ActiveProject.CustomData['Name'] := Value ; // 存储在 lpi-x-platform 中，共享数据`\~~
890		-	~~` LazarusIDE.ActiveProject.CustomSessionData['Name'] := Value ; // 存储在 lps 中 - 只有本机`~~
	895	+	``` pascal
	896	+	LazarusIDE.ActiveProject.CustomData['Name'] := Value ; // 存储在 lpi-x-platform 中，共享数据
	897	+	LazarusIDE.ActiveProject.CustomSessionData['Name'] := Value ; // 存储在 lps 中 - 只有本机
	898	+	```
891	899
892	900		# 包
893	901
894	902		您可以使用 Packages 执行各种操作：
895	903
896	904		## 搜索所有包
897	905
898	906		迭代 IDE 中加载的所有包（自 0.9.29 起）。
899	907
900	908		``` pascal
901	909		uses PackageIntf;
902	910		...
903	911		for i:=0 to PackageEditingInterface.GetPackageCount-1 do
904	912		writeln(PackageEditingInterface.GetPackages(i).Name);
905	913		```
906	914
907	915		## 搜索包含名称的包
908	916
909	917		``` pascal
910	918		uses PackageIntf;
911	919		...
912	920		var
913	921		Pkg: TIDEPackage;
914	922		begin
915	923		Pkg:=PackageEditingInterface.FindPackageWithName('LCL');
916	924		if Pkg<>nil then
917	925		...
918	926		end;
919	927		```
920	928
921	929		注意：FindPackageWithName 不会打开包编辑器。为此使用 DoOpenPackageWithName。
922	930
923	931		## 获取已安装软件包的 lpk 文件名
924	932
925	933		``` pascal
926	934		uses PackageIntf;
927	935		...
928	936		var
929	937		Pkg: TIDEPackage;
930	938		begin
931	939		Pkg:=PackageEditingInterface.FindPackageWithName('LCL');
932	940		if Pkg<>nil then
933	941		LPKFilename:=Pkg.Filename;
934	942		end;
935	943		```
936	944
937	945		## 安装包
938	946
939	947		注意：仅安装带有 IDE 插件的软件包。安装其他软件包可能会使 IDE 不稳定。
940	948
941	949		``` pascal
942	950		uses PackageIntf, contnrs;
943	951		...
944	952		PkgList:=TObjectList.create(true);
945	953		try
946	954		Pkg:=TLazPackageID.Create;
947	955		Pkg.Name:='Cody';
948	956		PkgList.Add(Pkg);
949	957		// 检查 IDE 是否可以找到 cody.lpk 和所有依赖项
950	958		// 如果看起来很奇怪，IDE 会提示一些警告 / 确认。
951	959		if not PackageEditingInterface.CheckInstallPackageList(PkgList,[]) then
952	960		exit;
953	961		// 在这个例子中我们已经检查过，所以跳过警告并重建 IDE
954	962		if PackageEditingInterface.InstallPackages(PkgList,[piiifSkipChecks,piiifRebuildIDE])<>mrOK then
955	963		exit;
956	964		finally
957	965		PkgList.Free;
958	966		end;
959	967		```
960	968
961	969		## 打开包文件（lpk）
962	970
963	971		``` pascal
964	972		uses PackageIntf, FileUtil;
965	973		...
966	974		var
967	975		pkg: TIDEPackage;
968	976		begin
969	977		if PackageEditingInterface.DoOpenPackageFile(LPKFilename,[pofAddToRecent],false)<>mrOk then
970	978		exit;
971	979		Pkg:=PackageEditingInterface.FindPackageWithName(ExtractFilenameOnly(LPKFilename));
972	980		...
973	981		end;
974	982		```
975	983
976	984		> Warning: IDE 会在空闲时自动关闭未使用的软件包。永远不要引用 TIDEPackage。
977	985
978	986		## 找到一个单元的包裹
979	987
980	988		你有一个单元的文件名，例如 '/home/user/unit.pas'，你想知道它属于哪个包和项目使用这个：
981	989
982	990		``` pascal
983	991		uses Classes, PackageIntf, ProjectIntf;
984	992		...
985	993		var
986	994		Owners: TFPList;
987	995		i: Integer;
988	996		o: TObject;
989	997		begin
990	998		Owners:=PackageEditingInterface.GetPossibleOwnersOfUnit('/full/path/of/unit.pas',[]);
991	999		if Owners=nil then begin
992	1000		// 单元与项目 / 包没有直接关联
993	1001		// 也许单元出于某种原因没有添加，但可以访问
994	1002		// 搜索所有项目 / 包的所有单元路径
995	1003		// 注意：这会导致错误命中
996	1004		Owners:=PackageEditingInterface.GetPossibleOwnersOfUnit('/full/path/of/unit.pas',
997	1005		[piosfExcludeOwned,piosfIncludeSourceDirectories]);
998	1006		end;
999	1007		if Owners=nil then exit;
1000	1008		try
1001	1009		for i:=0 to Owners.Count-1 do begin
1002	1010		o:=TObject(Owners[i]);
1003	1011		if o is TIDEPackage then begin
1004	1012		writeln('Owner is package ',TIDEPackage(o).Name);
1005	1013		end else if o is TLazProject then begin
1006	1014		writeln('Owner is project ',TLazProject(o).ProjectInfoFile);
1007	1015		end;
1008	1016		end;
1009	1017		finally
1010	1018		Owners.Free;
1011	1019		end;
1012	1020		```
1013	1021
1014	1022		## 查找项目 / 包所需的包
1015	1023
1016	1024		您有一个项目或包，并且您想知道需要哪个包，使用：
1017	1025
1018	1026		``` pascal
1019	1027		uses Classes, PackageIntf, ProjectIntf;
1020	1028		...
1021	1029		var
1022	1030		lPkgList: TFPList;
1023	1031		i: Integer;
1024	1032		begin
1025	1033		PackageEditingInterface.GetRequiredPackages(LazarusIDE.ActiveProject, lPkgList, [pirNotRecursive]);
1026	1034		try
1027	1035		for i := 0 to lPkgList.Count - 1 do begin
1028	1036		writeln('required package is ' + TIDEPackage(lPkgList[i]).Filename);
1029	1037		end;
1030	1038		finally
1031	1039		lPkgList.Free;
1032	1040		end;
1033	1041		...
1034	1042		```
1035	1043
1036	1044		# 窗口（Windows）
1037	1045
1038	1046		基本上有四种类型的 IDE 窗口。
1039	1047
1040	1048		- 主 IDE 栏是 Application.MainForm。它始终存在。
1041	1049		- 浮动 / 可停靠窗口，如源代码编辑器，对象检查器和消息。
1042	1050		- 模态表单，如查找对话框，选项对话框和问题。
1043	1051		- 提示和完成表格
1044	1052
1045	1053		## 添加新的可停靠 IDE 窗口
1046	1054
1047	1055		什么是可停靠的 IDE 窗口：像源代码编辑器或对象检查器这样的 Windows 是浮动窗口，如果安装了扩展包，则可以停靠它，并在下次 IDE 启动时存储和恢复其状态，位置和大小。为了恢复窗口，IDE 需要在 IDEIntf 包的单元 IDEWindowIntf 中定义的创建者。每个可停靠窗口必须具有唯一名称。不要使用像 'FileBrowser' 这样的通用名称，因为这很容易与其他包冲突。并且不要使用像“XYZ”这样的短名称，因为创建者负责以此名称开头的所有表单。
1048	1056
1049	1057		### 如何注册可停靠的 IDE 窗口
1050	1058
1051	1059		请记住选择一个有效的 pascal 标识符的长唯一名称。您的窗口可以包含您想要的任何标题。
1052	1060
1053	1061		``` pascal
1054	1062		uses SysUtils, IDEWindowIntf;
1055	1063		...
1056	1064		var MyIDEWindow: TMyIDEWindow = nil;
1057	1065
1058	1066		procedure CreateMyIDEWindow(Sender: TObject; aFormName: string; var AForm: TCustomForm; DoDisableAutoSizing: boolean);
1059	1067		begin
1060	1068		// 检查名称
1061	1069		if CompareText(aFormName,MyIDEWindowName)<>0 then exit;
1062	1070		// 如果尚未创建表单并禁用自动调整大小
1063	1071		IDEWindowCreators.CreateForm(MyIDEWindow,TMyIDEWindowm,DoDisableAutosizing,Application);
1064	1072		... init the window ...
1065	1073		AForm:=MyIDEWindow;
1066	1074		end;
1067	1075
1068	1076		procedure Register;
1069	1077		begin
1070	1078		IDEWindowCreators.Add('MyIDEWindow',@CreateMyIDEWindow,nil,'100','50%','+300','+20%');
1071	1079		// 表单的默认边界是：
1072	1080		// Left=100, Top=Screen.Height div 2, Width=300, Height=Screen.Height div 5
1073	1081		// 当 IDE 需要此窗口的实例时，它会调用 CreateMyIDEWindow 过程。
1074	1082		end;
1075	1083		```
1076	1084
1077	1085		### 显示 IDE 窗口
1078	1086
1079	1087		不要使用 Show。使用：
1080	1088
1081	1089		``` pascal
1082	1090		IDEWindowCreators.ShowForm(MyIDEWindow,false);
1083	1091		```
1084	1092
1085	1093		这将适用于对接。对接系统可以将表格包裹到对接站点中。BringToFront 参数告诉对接系统使表单及其所有父站点可见，并将顶层站点放在前面。
1086	1094
1087	1095		### 有关 IDEWindowCreators 和 SimpleLayoutStorage 的注释
1088	1096
1089	1097		IDEWindowCreators.SimpleLayoutStorage 只存储曾经打开过的所有表单的 BoundsRect 和 WindowState。如果没有安装 dockmaster，它将用作后备。即使安装了 DockMaster，它也会存储状态，因此在卸载 dockmaster 时，将恢复表单边界。
1090	1098
1091	1099		所有可停靠表单都使用 IDEWindowCreators 来注册自己并显示表单。在显示表单时，Creator 会检查是否安装了 IDEDockMaster，并将显示委托给它。如果没有安装 IDEDockMaster，它只显示表单。IDEDockMaster 可以使用 IDEWindowCreators 中的信息按名称创建表单，并在第一次显示表单时了解放置表单的位置。有关更多详细信息，请参阅包 AnchorDockingDsgn 和 EasyDockMgDsgn。
1092	1100
1093	1101		# 代码工具
1094	1102
1095	1103		CodeTools 是一个包，提供了大量的功能来解析、搜索和更改 pascal 源代码以及其他语言的一些基本功能。您也可以在没有 IDE 的情况下使用它们。在 IDE 中使用它们之前，建议您首先阅读 [[Codetools]]。
1096	1104
1097	1105		在调用 IDE 中的任何 CodeTools 函数之前，您应该将源代码编辑器的当前更改提交到 CodeTools 缓冲区：
1098	1106
1099	1107		``` pascal
1100	1108		uses LazIDEIntf;
1101	1109		...
1102	1110		// 将源代码编辑器中的更改保存到 codetools
1103	1111		LazarusIDE.SaveSourceEditorChangesToCodeCache(-1); // -1：提交所有源代码编辑器
1104	1112		```
1105	1113
1106	1114		## 将资源指令添加到文件中
1107	1115
1108	1116		这为 pascal 单元添加 {\$R example.res}：
1109	1117
1110	1118		``` pascal
1111	1119		procedure AddResourceDirectiveToPascalSource(const Filename: string);
1112	1120		var
1113	1121		ExpandedFilename: String;
1114	1122		CodeBuf: TCodeBuffer;
1115	1123		begin
1116	1124		// 确保修剪文件名并包含完整路径
1117	1125		ExpandedFilename:=CleanAndExpandFilename(Filename);
1118	1126
1119	1127		// 将源代码编辑器中的更改保存到 codetools
1120	1128		LazarusIDE.SaveSourceEditorChangesToCodeCache(-1);
1121	1129
1122	1130		// 加载文件
1123	1131		CodeBuf:=CodeToolBoss.LoadFile(ExpandedFilename,true,false);
1124	1132
1125	1133		// 添加资源指令
1126	1134		if not CodeToolBoss.AddResourceDirective(CodeBuf,'example.res') then
1127	1135		LazarusIDE.DoJumpToCodeToolBossError;
1128	1136		end;
1129	1137		```
1130	1138
1131	1139		codetools 还提供 FindResourceDirective 和 RemoveDirective 等函数。
1132	1140
1133	1141		## 获取单元和包含文件的搜索路径
1134	1142
1135	1143		IDE 中有许多不同的搜索路径来自项目，包，fpc 和 lazarus 目录，并且有许多类型的路径：在解析宏之前或之后，有或没有继承的搜索路径，作为相对路径或绝对路径。目录中的所有文件共享同一组搜索路径。您可以通过询问 codetools 来完全解析每个目录的搜索路径：
1136	1144
1137	1145		``` pascal
1138	1146		uses CodeToolManager;
1139	1147		...
1140	1148
1141	1149		Dir:=''; // 空目录用于新文件，并且具有与项目目录相同的设置
1142	1150
1143	1151		// 获取包含文件的搜索路径：
1144	1152		Path:=CodeToolBoss.GetIncludePathForDirectory(Dir);
1145	1153
1146	1154		// 获取单元的搜索路径：
1147	1155		// 此搜索路径将传递给编译器。
1148	1156		// 它包含包输出目录，但不包含包源目录。
1149	1157		Path:=CodeToolBoss.GetUnitPathForDirectory(Dir);
1150	1158
1151	1159		// 只能为 IDE 提供额外的单元搜索路径（不传递给编译器）
1152	1160		Path:=CodeToolBoss.GetSrcPathForDirectory(Dir);
1153	1161
1154	1162		// 完整的搜索路径还包含单元的所有包源路径：
1155	1163		Path:=CodeToolBoss.GetCompleteSrcPathForDirectory(Dir);
1156	1164		```
1157	1165
1158	1166		# 源代码编辑
1159	1167
1160	1168		## 激活源代码编辑器
1161	1169
1162	1170		``` pascal
1163	1171		uses SrcEditorIntf;
1164	1172		...
1165	1173		Editor:=SourceEditorManagerIntf.ActiveEditor;
1166	1174		if Editor=nil then exit;
1167	1175		Filename:=Editor.FileName;
1168	1176		ScreenPos:=Editor.CursorScreenXY;
1169	1177		TextPos:=Editor.CursorTextXY;
1170	1178		```
1171	1179
1172	1180		# SynEdit
1173	1181
1174	1182		## 获取 TSynEdit 的设置
1175	1183
1176	1184		当您使用 TSynEdit 进行对话时，如果要使用与源代码编辑器相同的字体和设置，请使用：
1177	1185
1178	1186		``` pascal
1179	1187		uses SrcEditorIntf;
1180	1188		...
1181	1189		SourceEditorManagerIntf.GetEditorControlSettings(ASynEdit);
1182	1190		```
1183	1191
1184	1192		## 获取 SynEdit 的高亮设置
1185	1193
1186	1194		如果您有一个带有高亮的 TSynEdit 的对话框，并且您希望使用与源代码编辑器高亮相同的颜色来使用此语言：
1187	1195
1188	1196		使
1189	1197
1190	1198		``` pascal
1191	1199		uses SrcEditorIntf;
1192	1200		...
1193	1201		SourceEditorManagerIntf.GetHighlighterSettings(ASynHighlighter);
1194	1202		```
1195	1203
1196	1204		请参阅示例：[SQLStringsPropertyEditorDlg](http://svn.freepascal.org/svn/lazarus/trunk/components/sqldb/sqlstringspropertyeditordlg.pas) 单元中的 TSQLStringsPropertyEditorDlg.Create。
1197	1205
1198	1206		# 帮助
1199	1207
1200	1208		## 添加源的帮助
1201	1209
1202	1210		首先创建一个 THelpDatabase：
1203	1211
1204	1212		``` pascal
1205	1213		HelpDB := TFPDocHTMLHelpDatabase(
1206	1214		HelpDatabases.CreateHelpDatabase('ANameOfYourChoiceForTheDatabase',
1207	1215		TFPDocHTMLHelpDatabase,true));
1208	1216		HelpDB.DefaultBaseURL := 'http://your.help.org/';
1209	1217
1210	1218		FPDocNode := THelpNode.CreateURL(HelpDB,
1211	1219		'Package1 - A new package',
1212	1220		'file://index.html');
1213	1221		HelpDB.TOCNode := THelpNode.Create(HelpDB,FPDocNode);// 一次作为 TOC
1214	1222		DirectoryItem := THelpDBISourceDirectory.Create(FPDocNode,'$(PkgDir)/lcl',
1215	1223		'.pp;.pas',false);// 一次作为正常页面
1216	1224		HelpDB.RegisterItem(DirectoryItem);
1217	1225		```
1218	1226
1219	1227		## 在消息窗口中添加行
1220	1228
1221	1229		``` pascal
1222	1230		unit IDEMsgIntf;
1223	1231		...
1224	1232		var Dir: String;
1225	1233		begin
1226	1234		Dir:=GetCurrentDir;
1227	1235		IDEMessagesWindow.BeginBlock;
1228	1236		IDEMessagesWindow.AddMsg('unit1.pas(30,4) Error: Identifier not found "a"',Dir,0);
1229	1237		IDEMessagesWindow.EndBlock;
1230	1238		end;
1231	1239		```
1232	1240
1233	1241		# IDE 选项框架
1234	1242
1235	1243		## 打开特定框架中的选项
1236	1244
1237	1245		``` pascal
1238	1246		uses LazIDEIntf;
1239	1247		...
1240	1248		LazarusIDE.DoOpenIDEOptions(TYourIDEOptionsFrame);
1241	1249		```
1242	1250
1243	1251		# 其它
1244	1252
1245	1253		## 添加宏
1246	1254
1247	1255		您可以添加自己的 IDE 宏：
1248	1256
1249	1257		``` pascal
1250	1258		uses MacroIntf, MacroDefIntf;
1251	1259
1252	1260		procedure Register;
1253	1261		begin
1254	1262		// 注册具有固定值的宏：
1255	1263		IDEMacros.Add(TTransferMacro.Create('MyMacro1','Value','Description',nil,[]));
1256	1264		end;
1257	1265
1258	1266		// 使用动态值注册宏需要一个对象的方法
1259	1267		procedure TForm1.Init;
1260	1268		begin
1261	1269		IDEMacros.Add(TTransferMacro.Create('MyMacro','Value','Description',@OnResolveMyMacro,[]));
1262	1270		end;
1263	1271
1264	1272		function TForm1.OnResolveMyMacro(const s: string; const Data: PtrInt;
1265	1273		var Abort: boolean): string;
1266	1274		// s 是参数。例如 $MyMacro(parameter)
1267	1275		// 数据是查询实例。可以是零。
1268	1276		// 如果有错误设置 Abort 为 true。
1269	1277		// 结果字符串可以包含宏。例如 Result:='$(FPCVer)/$(TargetOS)';
1270	1278		begin
1271	1279		Result:='MyValue';
1272	1280		end;
1273	1281		```
1274	1282
1275	1283		## 调试 IDE
1276	1284
1277	1285		- 像往常一样编译 IDE，例如通过 Tools/Build Lazarus。确保设置调试标志，如 -g 或 -gw2。最好是使用配置文件“Debug IDE”，其中包含许多用于调试的标志。
1278	1286		- 打开 ide \\ lazarus.lpi 项目。您无法直接编译此项目。
1279	1287		- 根据需要设置断点等运行项目。
1280	1288
1281	1289		## 另请参见
1282	1290
1283	1291		- [[Creating IDE Help]]
1284	1292		- [[Help protocol]]
1285	1293		- [[How To Write Lazarus Component]]
1286	1294
1287	1295		---
1288	1296		From the Free Pascal wiki, page "Extending the IDE/zh CN", as it stood on 2020-02-14 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