How To Write Lazarus Component: what changed

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

Old	New		Line
1	1		This is a guide on how to build components.
2	2
3	3		## Step 1: Create the package
4	4
5	5		- On the Lazarus IDE menu, click Package \> New Package to run the Package Manager.
6	6
7	7		![](/wiki-images/7/7c/Package_menu.png)
8	8
9	9		- A Save file dialog will appear. Chose a folder and a file name and press save. If the IDE prompts for using lowercase filenames press 'yes'.
10	10
11	11		- Congratulations: You have just created your first package!
12	12
13	13		![](/wiki-images/3/37/How_to_write_lazarus_component_package_maker.png)
14	14
15	15		## Step 2: Create the unit
16	16
17	17		You can create a new unit or use an existing file. Both options are described below.
18	18
19	19		### Create a new unit
20	20
21	21		- Use the Add button \> New component.
22	22
23	23		![](/wiki-images/5/56/Package_new_component.png)
24	24
25	25		- Choose a component like TComboBox.
26	26		- Choose customcontrol1.pas as Unit File Name and CustomControl1 as Unit Name.
27	27		- You can now give to the component a icon and determine on which palette the component should appear later in the Lazarus-IDE.
28	28		- Click Create New Component.
29	29
30	30		``` pascal
31	31		unit CustomControl1;
32	32
33	33		{$mode objfpc}{$H+}
34	34
35	35		interface
36	36
37	37		uses
38	38		Classes, SysUtils, LResources, Forms, Controls, Graphics, Dialogs, StdCtrls;
39	39
40	40		type
41	41		TCustomControl1 = class(TComboBox)
42	42		private
43	43		{ Private declarations }
44	44		protected
45	45		{ Protected declarations }
46	46		public
47	47		{ Public declarations }
48	48		published
49	49		{ Published declarations }
50	50		end;
51	51
52	52		procedure Register;
53	53
54	54		implementation
55	55
56	56		procedure Register;
57	57		begin
58	58		RegisterComponents('Standard', [TCustomControl1]);
59	59		end;
60	60
61	61		end.
62	62		```
63	63
64	64		- Now add the code for your component. Resist the temptation to install the new component into the IDE at this early stage. It is very likely that the new component is still buggy. Since the new component will become a part of the IDE it can crash the IDE, it may even be possible that the IDE does not start any more. Test your component excessively.
65	65		- When the component is tested as much as possible install the package by clicking opening the package in "Package" \> "Install/uninstall packages", click the "Compile" button at the top of the package editor, and then Use -\> Install:
66	66
67	67		![](/wiki-images/3/36/Package_install.png)
68	68
69	69		- Now the IDE will ask you, if the IDE should be rebuilt. Say yes.
70	70
71	71		![](/wiki-images/9/9b/Package_rebuild.png)
72	72
73	73		- Lazarus automatically restarts and you can see your new component in the component palette. Congratulations: you have just installed your first package with your first package component.
74	74
75	75		![](/wiki-images/3/35/Package_installed.png)
76	76
77	77		> Note: If you do not see your new component in the component palette, it is most likely that you are not running the re-compiled version of Lazarus. You can set where Lazarus builds to using Tools -\> Options -\> Files -\> Lazarus directory.
78	78		>
79	79		> Instead of calling Lazarus directly, you also can use startlazarus, which starts the newly created Lazarus, for example the Lazarus executable in the ~/.lazarus directory, if you don't have write access to the directory Lazarus was installed into.
80	80
81	81		> Note: If things go wrong because the new component is still buggy and Lazarus cannot be started again you delete the new lazarus.exe and rename the backup copy of the previous version, lazarus.old.exe, back to lazarus.exe.
82	82
83	83		### Add an existing unit
84	84
85	85		If you already had a unit you can add it to the package:
86	86
87	87		![](/wiki-images/1/11/Package_existing_unit.png)
88	88
89	89		- Click the Add button, go to the Add Files tab. At the Unit file name, browse to your existing file. Click Add files to package. If the package manager complains that the unit is not in the unit path, click yes to add the directory to the unit path.
90	90		- Click the Add button again, go to the Add Files tab, browse to the .lrs file and click OK (See Step 3 about creating this icon file).
91	91		- Click the Add button again, go to the New Requirement tab. In the Package name select LCL and click OK.
92	92
93	93		The end result should look like this:
94	94
95	95		![](/wiki-images/d/d9/How_to_write_lazarus_component_package_maker_done.png)
96	96
97	97		- Click under the Files tree in the Package Manager. In the File Properties, make sure Register unit is checked.
98	98		- Click the Options button. Select the IDE Integration tab. In Package Type, make sure Designtime and Runtime is selected.
99	99		- Click the Compile button to check to see that the files compile without errors.
100	100		- Click the Install button. Lazarus will rebuild and restart automatically.
101	101
102	102		The component is created and ready to be used:
103	103
104	104		![](/wiki-images/3/3c/How_to_write_lazarus_component_created.png)
105	105
106	106		## Step 3: Create icons for the package
107	107
108	108		Each component which should have an icon on the component palette requires images files packaged to a resource file. It is highly recommended to create the images as PNG files with alpha channel. The images should be 24x24 pixels in size. However, since Lazarus 1.8+ supports scaling of the icons at higher screen resolutions, you should also create images at 36x36 and 48x48 pixels which will be displayed at 150% and 200% resolutions, respectively). All images must have the same filename as the component, and the for extra-resolution images the appendices "_150" and "_200" must be added to the base filename to indicate the scaling factor. As an example, if your component is called `TMySuperEdit` you should prepare images named as `tmysuperedit.png`, `tmysuperedit_150.png`, and `tmysuperedit_200.png`. To simplify art work, it is recommended to draw the images as SVG vector images from which the destination sizes can be exported.
109	109
110	110		FPC is capable of using standard resource files `.rc` or compiled resources `.res` since fpc version 2.6. See [[Lazarus Resources\|Lazarus_Resources#FPC_resources]]
111	111
112	112		The `.lrs`: see below.
113	113
114	114		### Using the Lazarus Image Editor
115	115
116	116		You can use [[Lazarus Image Editor]] to create the icons in .lrs format.
117	117
118	118		### Using lazres
119	119
120	120		`lazres` is usually located in the Lazarus tools directory.
121	121
122	122		You may need to compile [[lazres]] at first use. Simply open the lazres.lpi in the IDE and click run \> build in the menu.
123	123
124	124		Create lrs file
125	125
126	126		To create the lrs file run:
127	127
128	128		`~/lazarus/tools/lazres samplepackage.lrs TMyCom.png`
129	129
130	130		or, if high-resolution images are available
131	131
132	132		`~/lazarus/tools/lazres samplepackage.lrs TMyCom.png TMyCom_150.pgn TMyCom_200.png`
133	133
134	134		Where
135	135
136	136		- samplepackage is the name of your package
137	137		- TMyCom is the name of your component! The name of the image must match the name of your component!
138	138
139	139		You can add more than one image to the lrs file by appending the image file name at the end. Eg. ~/lazarus/tools/lazres samplepackage.lrs TMyCom.png TMyOtherCom.png ...
140	140
141	141		Sample
142	142
143	143		Following is a sample of the resulting samplepackage.lrs file.
144	144
145	145		LazarusResources.Add('TMyCom','PNG',[
146	146		#137'PNG'#13#10#26#10#0#0#0#13'IHDR'#0#0#0#24#0#0#0#24#8#2#0#0#0'o'#21#170#175
147	147		+#0#0#0#4'gAMA'#0#0#177#143#11#252'a'#5#0#0#0'\|IDAT8O'#237#212#209#10#192' '#8
148	148		+#5'P'#247#231#251's'#215#138#133#164#166'\'#220#195'`'#209'c'#157'L'#173#131
149	149		+#153#169'd4'#168'dP'#137'r_'#235'5'#136'@Zmk'#16'd9'#144#176#232#164'1'#247
150	150		+'I'#8#160'IL'#206'C'#179#144#12#199#140'.'#134#244#141'~'#168#247#209'S~;'#29
151	151		+'V+'#196#201'^'#10#15#150'?'#255#18#227#206'NZ>42'#181#159#226#144#15'@'#201
152	152		+#148#168'e'#224'7f<@4'#130'u_YD'#23#213#131#134'Q]'#158#188#135#0#0#0#0'IEND'
153	153		+#174'B`'#130
154	154		]);
155	155
156	156		Make sure to include your resource file in your new component source by adding the following at the bottom your component's unit and including "LResources" in the uses clause
157	157
158	158		``` pascal
159	159		initialization
160	160		{$I samplepackage.lrs}
161	161		```
162	162
163	163		Create res file
164	164
165	165		lazres can also create a compiled resource file, just specify a file with the .res extension, e.g.:
166	166
167	167		`~/lazarus/tools/lazres samplepackage.``res`` TMyCom.png`
168	168
169	169		or, with high-res icons:
170	170
171	171		`~/lazarus/tools/lazres samplepackage.``res`` TMyCom.png TMyCom_150.png TMyCom_200.png`
172	172
173	173		In this case, instead of including the lrs file in the initialization section, just include the resource file anywhere in your component source file
174	174
175	175		``` pascal
176	176		{$R samplepackage.res}
177	177		```
178	178
179	179		### Using glazres
180	180
181	181		GLazRes is the graphical version of `lazres` that can assemble files into a Lazarus resource file (.lrs). It can be found in the tools directory of a Lazarus installation.
182	182
183	183		## Recompiling Packages
184	184
185	185		You need to rebuild the package every time you make changes to the mycom.pas file. To rebuild the package, open the samplepackage.lpk file in the Package Manager and click the Install button.
186	186
187	187		## Removing Packages
188	188
189	189		- To remove installed components: on the IDE menu, click Package \> Configure installed packages. The following image shows the Installed Packages tool.
190	190
191		-	~~![`Installed Components`](/wiki-images/0/0e/How_to_write_lazarus_component_installed_components.png)~~
	191	+	```text
	192	+	Installed Components
	193	+	```
192	194
193	195		- Select the package you want to uninstall and click Uninstall selection.
194	196
195	197		If something goes wrong with a package (e.g. package directory is deleted without first uninstalling it), Lazarus may not allow you to uninstall packages. To fix the problem, at the IDE menu click Tools \> Build Lazarus. Lazarus will rebuild all packages and restart. You should now be able to uninstall problematic packages.
196	198
197	199		## Enhancing mycom.pas
198	200
199	201		- The code in mycom.pas above gives you the basics on what you need to create a component. The following is an enhanced version with some tips on how to write procedures and events for components.
200	202		- The OnChange2 shows how to create events
201	203		- The OnSample shows how to create custom events
202	204		- MyText and MyText2 shows different ways to write properties.
203	205		- You can use TComboBox instead of TCustomComboBox as the base class, which publishes all properties as TComboBox.
204	206		- If TCustomComboBox is used as the base class, you'll notice a lot of properties and events will be missing in the IDE Object Inspector. To add those properties and events, just copy and paste the properties as listed below // properties from TComboBox. These list of properties can be got from the TComboBox declaration in the StdCtrls unit. Omit any property which you want to handle yourself.
205	207
206	208		``` pascal
207	209		unit mycom;
208	210
209	211		{$mode objfpc}{$H+}
210	212
211	213		interface
212	214
213	215		uses
214	216		Classes, SysUtils, StdCtrls, Forms, Dialogs,
215	217		LCLType,LCLIntf,lresources,LCLProc;
216	218
217	219		type
218	220
219	221		TSampleEvent = procedure(MyText: String) of Object;
220	222
221	223		TMyCom = class (TCustomComboBox)
222	224		private
223	225		FMyText: String;
224	226		FOnChange2: TNotifyEvent;
225	227		FOnSample: TSampleEvent;
226	228		public
227	229		constructor Create(TheOwner: TComponent); override;
228	230		procedure CreateWnd; override;
229	231		procedure Change; override;
230	232		protected
231	233		function GetMyText2: String;
232	234		procedure SetMyText2(MyText: String);
233	235		published
234	236		property MyText: String read FMyText write FMyText;
235	237		property MyText2: String read GetMyText2 write SetMyText2;
236	238		property OnChange2: TNotifyEvent read FOnChange2 write FOnChange2;
237	239		property OnSample: TSampleEvent read FOnSample write FOnSample;
238	240
239	241		// properties from TComboBox
240	242		property Align;
241	243		property Anchors;
242	244		property ArrowKeysTraverseList;
243	245		property AutoComplete;
244	246		property AutoCompleteText;
245	247		property AutoDropDown;
246	248		property AutoSelect;
247	249		property AutoSize;
248	250		property BidiMode;
249	251		property BorderSpacing;
250	252		property CharCase;
251	253		property Color;
252	254		property Ctl3D;
253	255		property Constraints;
254	256		property DragCursor;
255	257		property DragMode;
256	258		property DropDownCount;
257	259		property Enabled;
258	260		property Font;
259	261		property ItemHeight;
260	262		property ItemIndex;
261	263		property Items;
262	264		property ItemWidth;
263	265		property MaxLength;
264	266		property OnChange;
265	267		property OnChangeBounds;
266	268		property OnClick;
267	269		property OnCloseUp;
268	270		property OnContextPopup;
269	271		property OnDblClick;
270	272		property OnDragDrop;
271	273		property OnDragOver;
272	274		property OnDrawItem;
273	275		property OnEndDrag;
274	276		property OnDropDown;
275	277		property OnEditingDone;
276	278		property OnEnter;
277	279		property OnExit;
278	280		property OnGetItems;
279	281		property OnKeyDown;
280	282		property OnKeyPress;
281	283		property OnKeyUp;
282	284		property OnMeasureItem;
283	285		property OnMouseDown;
284	286		property OnMouseMove;
285	287		property OnMouseUp;
286	288		property OnStartDrag;
287	289		property OnSelect;
288	290		property OnUTF8KeyPress;
289	291		property ParentBidiMode;
290	292		property ParentColor;
291	293		property ParentCtl3D;
292	294		property ParentFont;
293	295		property ParentShowHint;
294	296		property PopupMenu;
295	297		property ReadOnly;
296	298		property ShowHint;
297	299		property Sorted;
298	300		property Style;
299	301		property TabOrder;
300	302		property TabStop;
301	303		property Text;
302	304		property Visible;
303	305		end;
304	306
305	307		procedure Register;
306	308
307	309		implementation
308	310
309	311		procedure Register;
310	312		begin
311	313		RegisterComponents('Sample',[TMyCom]);
312	314		end;
313	315
314	316		constructor TMyCom.Create(TheOwner: TComponent);
315	317		begin
316	318		inherited Create(TheOwner);
317	319		Self.Style := csDropDownList;
318	320		end;
319	321
320	322		procedure TMyCom.CreateWnd;
321	323		begin
322	324		inherited CreateWnd;
323	325		Items.Assign(Screen.Fonts);
324	326		end;
325	327
326	328		procedure TMyCom.Change;
327	329		begin
328	330		inherited;
329	331		if Assigned(FOnChange2) then FOnChange2(Self);
330	332		if Assigned(FOnSample) then FOnSample(FMyText);
331	333		end;
332	334
333	335		function TMyCom.GetMyText2: String;
334	336		begin
335	337		Result:=FMyText;
336	338		end;
337	339
338	340		procedure TMyCom.SetMyText2(MyText: String);
339	341		begin
340	342		FMyText:=MyText;
341	343		end;
342	344
343	345		initialization
344	346		{$I samplepackage.lrs}
345	347
346	348		end.
347	349		```
348	350
349	351		Also you will notice that some undeclared and possibly unwanted elements exist in the IDE Object Inspector. To remove those of them, which you do not need, you can redeclare them in the Published section as simple variables. For example:
350	352
351	353		``` pascal
352	354		Published
353	355		...
354	356		property Height: Integer;
355	357		property Width: Integer;
356	358		...
357	359		```
358	360
359	361		## Using embedded (visual) components
360	362
361	363		It's possible to use standard components embedded in your own components (look for example at TLabeledEdit or TButtonPanel).
362	364
363	365		Let's say you want to create a custom panel with a TLabel on it. With the steps described above the base package and source files can be created. Now do the following to add a TLabel to the component:
364	366
365	367		- Add a private attribute for the label component (FEmbeddedLabel: TLabel;).
366	368		- Add a published read-only property for the label component (property EmbeddedLabel: TLabel read FEmbeddedLabel;)
367	369		- Create the label in the component's (overridden) constructor (FEmbeddedLabel := TLabel.Create(self); )
368	370		- Set the parent of the component (FEmbeddedLabel.Parent := self;)
369	371		- If the component to be embedded is not a 'subcomponent' by default (like TBoundLabel, TPanelBitBtn etc) then add the call to SetSubComponent. This is necessary for the IDE so it knows that it has to store the properties of the embedded component as well. TLabel is not a subcomponent by default so the call to the method must be added (FEmbeddedLabel.SetSubComponent(true);).
370	372
371	373		To sum it up you would get something like this (only the essential parts are shown):
372	374
373	375		``` pascal
374	376		TEnhancedPanel = class(TCustomControl)
375	377		private
376	378		{ The new attribute for the embedded label }
377	379		FEmbeddedLabel: TLabel;
378	380
379	381		public
380	382		{ The constructor must be overriden so the label can be created }
381	383		constructor Create(AOwner: TComponent); override;
382	384
383	385		published
384	386		{ Make the label visible in the IDE }
385	387		property EmbeddedLabel: TLabel read FEmbeddedLabel;
386	388		end;
387	389
388	390		implementation
389	391
390	392		constructor TEnhancedPanel.Create(AOwner: TComponent);
391	393		begin
392	394		inherited Create(AOwner);
393	395
394	396		// Set default width and height
395	397		with GetControlClassDefaultSize do
396	398		SetInitialBounds(0, 0, CX, CY);
397	399
398	400		// Add the embedded label
399	401		FEmbeddedLabel := TLabel.Create(Self); // Add the embedded label
400	402		FEmbeddedLabel.Parent := self; // Show the label in the panel
401	403		FEmbeddedLabel.SetSubComponent(true); // Tell the IDE to store the modified properties
402	404		FLabel.Name := 'EmbeddedLabel';
403	405		FLabel.Caption := 'Howdy World!';
404	406
405	407		// Make sure the embedded label can not be selected/deleted within the IDE
406	408		FLabel.ControlStyle := FLabel.ControlStyle - [csNoDesignSelectable];
407	409
408	410		// Set other properties if necessary
409	411		//...
410	412
411	413		end;
412	414		```
413	415
414	416		The reference for Delphi (Embarcadero): [Creating a Styled FireMonkey Component by Extending an Existing Component](https://docwiki.embarcadero.com/RADStudio/Alexandria/en/Creating_a_Styled_FireMonkey_Component_by_Extending_an_Existing_Component)
415	417
416	418		## Using custom paint procedure
417	419
418	420		You can always subclass a component inside your program. For example, this implements a custom Paint procedure to a TLabel:
419	421
420	422		``` pascal
421	423		type
422	424		TMyLabel = class(TLabel)
423	425		protected
424	426		procedure Paint; override;
425	427		end;
426	428		{...}
427	429		implementation
428	430		{...}
429	431		procedure TMyLabel.Paint;
430	432		begin
431	433		// your code to implement Paint, for example
432	434		Canvas.TextOut(0,0,Caption);
433	435		end;
434	436		```
435	437
436	438		Now you can create a MyLabel inside your program, at run time, with that overridden Paint procedure instead of the standard one.
437	439
438	440		For most components, and for most methods, it would be recommendable to call inherited procedure inside it:
439	441
440	442		``` pascal
441	443		procedure TMyLabel.Paint;
442	444		begin
443	445
444	446		inherited Paint; /////////////////////
445	447
446	448		// your code to implement Paint, for example
447	449		Canvas.TextOut(0,0,Caption);
448	450		end;
449	451		```
450	452
451	453		However, inherited behavior is not desirable in this case, since the second writing action would overlap the first (inherited) one.
452	454
453	455		## Integrating the component with the IDE
454	456
455	457		### Property editors
456	458
457	459		Property editors provide custom dialogs to edit properties in the object inspector. For most properties, like strings, string lists, images, enumerated types and others, there are already default property editors, but if a custom component has a special kind of property it may require a custom dialog to edit the property.
458	460
459	461		Each property editor is a class, which should descend from TPropertyEditor or one of its descendents and implement methods from this base class. They should be registered in the 'Register' procedure by using the function RegisterPropertyEditor from the unit PropEdits. It is a standard to name property editors with the property name followed by 'Property', for example TFieldProperty for the property editor of the TField property.
460	462
461	463		``` pascal
462	464		TPropertyEditor = class
463	465		public
464	466		function AllEqual: Boolean; Virtual;
465	467		function AutoFill: Boolean; Virtual;
466	468		procedure Edit; Virtual; // Activated by double-clicking the property value
467	469		procedure ShowValue; Virtual; // Activated by control-clicking the property value
468	470		function GetAttributes: TPropertyAttributes; Virtual;
469	471		function GetEditLimit: Integer; Virtual;
470	472		function GetName: ShortString; Virtual;
471	473		procedure GetProperties(Proc: TGetPropEditProc); Virtual;
472	474		function GetHint(HintType: TPropEditHint; x, y: integer): String; Virtual;
473	475		function GetDefaultValue: AnsiString; Virtual;
474	476		procedure GetValues(Proc: TGetStrProc); Virtual;
475	477		procedure SetValue(const NewValue: AnsiString); Virtual;
476	478		procedure UpdateSubProperties; Virtual;
477	479		function SubPropertiesNeedsUpdate: Boolean; Virtual;
478	480		function IsDefaultValue: Boolean; Virtual;
479	481		function IsNotDefaultValue: Boolean; Virtual;
480	482		// ... shortened
481	483		end;
482	484		```
483	485
484	486		A good example for a property editor is the TFont property editor.
485	487
486	488		One of the most common cases for property editors is properties which are classes. Because classes have many fields and can have a variety of formats, it's not possible for Lazarus to have the object inspector edit field able to edit it, like is done for strings and numeric types.
487	489
488	490		For classes, a convention is to have the value field show permanently the name of the class in parentheses, for example "(TFont)" and the "..." button shows a dialog to edit this class. This behaviour, except for the dialog, is implemented by a standard property editor for classes called TClassPropertyEditor, which can be inherited from when writing property editors for classes:
489	491
490	492		``` pascal
491	493		TClassPropertyEditor = class(TPropertyEditor)
492	494		public
493	495		constructor Create(Hook: TPropertyEditorHook; APropCount: Integer); Override;
494	496		function GetAttributes: TPropertyAttributes; Override;
495	497		procedure GetProperties(Proc: TGetPropEditProc); Override;
496	498		function GetValue: AnsiString; Override;
497	499		property SubPropsTypeFilter: TTypeKinds Read FSubPropsTypeFilter
498	500		Write SetSubPropsTypeFilter
499	501		Default tkAny;
500	502		end;
501	503		```
502	504
503	505		Going back to the TFont example, inheriting from TClassPropertyEditor already offers part of the desired behavior and then the TFontPropertyEditor class only needs to implement showing the dialog in the Edit method and set the attributes for the editor:
504	506
505	507		``` pascal
506	508		TFontPropertyEditor = class(TClassPropertyEditor)
507	509		public
508	510		procedure Edit; Override;
509	511		function GetAttributes: TPropertyAttributes; Override;
510	512		end;
511	513
512	514		procedure TFontPropertyEditor.Edit;
513	515		var
514	516		FontDialog: TFontDialog;
515	517		begin
516	518		FontDialog := TFontDialog.Create(NIL);
517	519		try
518	520		FontDialog.Font := TFont(GetObjectValue(TFont));
519	521		FontDialog.Options := FontDialog.Options + [fdShowHelp, fdForceFontExist];
520	522		if FontDialog.Execute then SetPtrValue(FontDialog.Font);
521	523		finally
522	524		FontDialog.Free;
523	525		end;
524	526		end;
525	527
526	528		function TFontPropertyEditor.GetAttributes: TPropertyAttributes;
527	529		begin
528	530		Result := [paMultiSelect, paSubProperties, paDialog, paReadOnly];
529	531		end;
530	532		```
531	533
532	534		The reference for Delphi (Embarcadero): [Creating a Component Editor and a Property Editor for FireMonkey Components](https://docwiki.embarcadero.com/RADStudio/Alexandria/en/Creating_a_Component_Editor_and_a_Property_Editor_for_FireMonkey_Components)
533	535
534	536		### Component editors
535	537
536	538		Component editors control the behavior of right-clicking and double clicking components in the form designer.
537	539
538	540		Each component editor is a class, which should descend from TComponentEditor or one of its descendents and implement methods from this base class. They should be registered in the 'Register' procedure by using the function RegisterComponentEditor from the unit ComponentEditors. It is a standard to name component editors with the component name followed by 'Editor', for example TStringGridComponentEditor for the property editor of the TStringGrid component. Although user component editors should be based in TComponentEditor, most of its methods are actually from an ancestor, so it is necessary to also know TBaseComponentEditor:
539	541
540	542		``` pascal
541	543		TBaseComponentEditor = class
542	544		protected
543	545		public
544	546		constructor Create(AComponent: TComponent;
545	547		ADesigner: TComponentEditorDesigner); Virtual;
546	548		procedure Edit; Virtual; Abstract;
547	549		procedure ExecuteVerb(Index: Integer); Virtual; Abstract;
548	550		function GetVerb(Index: Integer): String; Virtual; Abstract;
549	551		function GetVerbCount: Integer; Virtual; Abstract;
550	552		procedure PrepareItem(Index: Integer; const AnItem: TMenuItem); Virtual; Abstract;
551	553		procedure Copy; Virtual; Abstract;
552	554		function IsInInlined: Boolean; Virtual; Abstract;
553	555		function GetComponent: TComponent; Virtual; Abstract;
554	556		function GetDesigner: TComponentEditorDesigner; Virtual; Abstract;
555	557		function GetHook(out Hook: TPropertyEditorHook): Boolean; Virtual; Abstract;
556	558		procedure Modified; Virtual; Abstract;
557	559		end;
558	560		```
559	561
560	562		The most important method of a component editor is Edit, which is called when the component is double clicked. When the context menu for the component is invoked the GetVerbCount and GetVerb methods are called to build the menu. If one of the verbs (which means menu items in this case) are selected, ExecuteVerb is called. There is a default component editor (TDefaultEditor) which implements Edit to search the properties of the component for the most appropriate one to be edited. It usually chooses an event, which is edited by adding it's skeleton code in the code editor and setting the cursor to be in place to add code for it.
561	563
562	564		Other important methods from TBaseComponentEditor are:
563	565
564	566		- ExecuteVerb(Index) - Executes one of the extra menu items placed on the right-click popup menu;
565	567		- GetVerb – To return the name of each extra popup menu item. Note that it is the responsibility of the component editor to place special menu item caption characters like & to create a keyboard accelerator and "-" to create a separator;
566	568		- GetVerbCount – Returns the amount of items to be added to the popup menu. The index for the routines GetVerb and ExecuteVerb is zero based, going from 0 to GetVerbCount – 1;
567	569		- PrepareItem – Called for each verb after the menu item was created. Allows the menu item to be customized such as by adding subitems, adding a checkbox or even hiding it by setting Visible to false;
568	570		- Copy - Called when the component is being copied to the clipboard. The component data for use by Lazarus will always be added and cannot be modified. This method is instead for adding a different kind of clipboard information to paste the component in other applications, but which won't affect the Lazarus paste.
569	571
570	572		A simple and interesting example is the TCheckListBox component editor which creates a dialog to edit. More convenient than implementing all methods from TBaseComponentEditor is inheriting from TComponentEditor, and this is what TCheckListBoxEditor does. This base class adds empty implementations for most methods and some default ones for others. For Edit it calls ExecuteVerb(0), so if the first item will be identical to the double-click action, which is a convention for editor, there is no need to implement Edit. This basic action for the double-click and first menu item is often a dialog, and for TCheckListBox this is also done:
571	573
572	574		``` pascal
573	575		TCheckListBoxComponentEditor = class(TComponentEditor)
574	576		protected
575	577		procedure DoShowEditor;
576	578		public
577	579		procedure ExecuteVerb(Index: Integer); override;
578	580		function GetVerb(Index: Integer): String; override;
579	581		function GetVerbCount: Integer; override;
580	582		end;
581	583
582	584		procedure TCheckGroupComponentEditor.DoShowEditor;
583	585		var
584	586		Dlg: TCheckGroupEditorDlg;
585	587		begin
586	588		Dlg := TCheckGroupEditorDlg.Create(NIL);
587	589		try
588	590		// .. shortened
589	591		Dlg.ShowModal;
590	592		// .. shortened
591	593		finally
592	594		Dlg.Free;
593	595		end;
594	596		end;
595	597
596	598		procedure TCheckGroupComponentEditor.ExecuteVerb(Index: Integer);
597	599		begin
598	600		case Index of
599	601		0: DoShowEditor;
600	602		end;
601	603		end;
602	604
603	605		function TCheckGroupComponentEditor.GetVerb(Index: Integer): String;
604	606		begin
605	607		Result := 'CheckBox Editor...';
606	608		end;
607	609
608	610		function TCheckGroupComponentEditor.GetVerbCount: Integer;
609	611		begin
610	612		Result := 1;
611	613		end;
612	614		```
613	615
614	616		## Design-time component debugging
615	617
616	618		To catch design-time-errors in a (newly created) dbgcomponent:
617	619
618	620		- open project `C:\lazarus\ide\lazarus.lpi`;
619	621		- run project;
620	622		- set breakpoint in dbgcomponent in main (1st) app;
621	623		- use dbgcomponent pascal code in second app;
622	624		- step through design-time component code in debug-session; do whatever is necessary;
623	625
624	626		## See also
625	627
626	628		- [[Extending the IDE]]
627	629		- [[Lazarus Packages]] - A guide for creating a package under Lazarus
628	630		- [[Components and Code examples]]
629	631		- [[Lazarus Components]]
630	632		- [[IDE Window: Add to Package]]
631	633		- [[IDE Window: Create new package component]]
632	634
633	635		You can post questions regarding this page [here](http://forum.lazarus.freepascal.org/index.php/topic,5789.0.html)
634	636
635	637		---
636	638		From the Free Pascal wiki, page "How To Write Lazarus Component", as it stood on 2023-11-07 after a change by Ernesto, 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).
637	639		Category: Code
638	640		Category: Component Creation
639	641		Category: Lazarus
640	642		Category: Packages
641	643		Category: Tutorials

Back to history