Lazarus Nongraphical Visual Component Example Code: what changed

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

Old	New		Line
1	1		### Introduction
2	2
3	3		There are many property types in Lazarus, and when writing a descendent of TComponent it is not always straightforward how to implement some of them. After searching many sources I have written a component template that includes most property types.
4	4
5	5		The code below is a working component that could be packaged and compiled in the IDE, but its purpose is to serve as a source of copy/paste snippets.
6	6
7	7		Here's what it looks like in the Lazarus Object Inspector:
8	8
9		-	~~<figure>~~
10		-	~~<img src="myvisualcomponent_properties11.png" title="myvisualcomponent_properties11.png" />~~
11		-	~~<figcaption>myvisualcomponent_properties11.png</figcaption>~~
12		-	~~</figure>~~
	9	+	![](/wiki-images/3/3f/Myvisualcomponent_properties11.png)
13	10
14	11		### Code to copy and paste
15	12
16	13		``` pascal
17	14		unit MyCustomControl;
18	15
19	16		{
20	17		= Example of a generic non-graphical component for Lazarus 1.x
21	18		= - example code for various types of properties and events to show and act correctly in the Object Inspector
22	19		= - including a custom 'About' dialog property editor
23	20		=
24	21		= Although this unit will compile as written, the purpose is to provide template code
25	22		= for various property types and events that can be copy/pasted into your own component
26	23		=
27	24		= Example Property types:
28	25		= 1) Bitmap
29	26		= 2) Font
30	27		= 3) Icon
31	28		= 4) Stringlist
32	29		= 5) Options expandable true/false list
33	30		= 6) User type drop-down list
34	31		= 7) Simple String
35	32		= 8) String with pre and post-processing
36	33		= 9) String Array with indexed properties
37	34		= 10) String with default value
38	35		= 11) Integer with default value
39	36		= 12) Overridden (custom) Tag property
40	37		= 13) Inherited drop-down list of types
41	38		= 14) Custom dialog
42	39		= 15) Custom events
43	40		= 16) Property hidden from the Object Inspector
44	41		= 17) Filename property with custom properties for the OpenDialog
45	42		=
46	43		= Author: minesadorada@charcodelvalle.com
47	44		= Date: May 2014
48	45		= License: LGPL
49	46		=
50	47		}
51	48		{$mode objfpc}{$H+}
52	49
53	50		interface
54	51
55	52		uses
56	53		Classes, SysUtils, Forms, Controls, Graphics, Buttons,
57	54		LCLIntf, LCLType, LResources,
58	55		ExtCtrls, StdCtrls, Dialogs, PropEdits;
59	56
60	57		const
61	58		C_VERSION = '1.1'; // Remember to co-ordinate with the Package manager VersionInfo
62	59
63	60		C_ERRORMESSAGE = '%s error:' + LineEnding + '%s';
64	61		// Used with Exception.CreateFmt
65	62
66	63		type
67	64		// Drop-down list in Object Inspector
68	65		tmcType = (mcType1, mcType2, mcType3);
69	66
70	67		// Expandable list of Options in Object Inspector
71	68		tOptions = (Opt1, Opt2, Opt3);
72	69		tOptionsFlags = set of tOptions;
73	70
74	71		tAboutString = string; // Unique string type used in 'About' property editor
75	72		tFilenameString = string; // Unique string type used in MyFilename property editor
76	73
77	74		TSampleEvent = procedure(MyText: string) of object; // Custom Event type
78	75
79	76		TMyVisualComponent = class(TComponent) // Non-graphical ancestor
80	77		private
81	78		{ Private declarations }
82	79		fAboutString: string; // Dummy string for 'About' property
83	80		fFileNameString: tFilenameString; // Filename
84	81		fmcType: tmcType; // Type defined above
85	82		fSimpleString: string; // Direct read and write (no methods)
86	83		fProcessedString: string; // Methods used to read and write the property
87	84		fStringWithDefault: string; // Object Inspector shows default
88	85		fIntegerWithDefault: integer; // Object Inspector shows default
89	86		fTag: string; // Property overrides normal Tag property
90	87		fOptions: tOptionsFlags; // Variable of Set type. * If Opt1 IN fOptions then...
91	88		fIcon: TIcon; // Assigned to Application Icon by default
92	89		fFont: TFont; // Assigned only if MyFont property set
93	90		fBitMap: TBitMap; // Assigned only if MyBitmap property set
94	91		fSizeConstraints: TSizeConstraintsOptions;
95	92		// Built-in set (part of TSizeConstraints object)
96	93		fStringArray: array[0..3] of string;
97	94		// Stores values of String1,String2,String3 and String4 properties
98	95		fStringList: TStrings; // Holds MyStringList property values
99	96		fVersion: string; // Holds read-only version property
100	97		FOnSample: TSampleEvent; // Custom event
101	98
102	99		fHiddenString: string; // Hidden property
103	100		fOnChangeHiddenString: TNotifyEvent; // Custom event
104	101
105	102		{ Private methods }
106	103
107	104		procedure SetProcessedString(AValue: string);
108	105		function GetProcessedString: string;
109	106		// Read and Write procedures for property ProcessedString
110	107
111	108		procedure SetTag(AValue: string); // Write procedure for overridden property 'Tag'
112	109
113	110		function GetStringValue(const AIndex: integer): string;
114	111		// Indexed Get Method
115	112		procedure SetStringValue(const AIndex: integer; AValue: string);
116	113		// Indexed Set method
117	114
118	115		procedure SetStrings(const AValue: TStrings);
119	116		// Needed to use a TStrings property. FStringList also needs to be created in the Constructor
120	117
121	118		procedure SetFont(const AValue: TFont);
122	119		// Needed to use a Font property. fFont also needs to be created in the Constructor
123	120
124	121		procedure SetBitMap(const AValue: TBitmap);
125	122		// Needed to use a BitMap property. fBitMap also needs to be created in the Constructor
126	123
127	124		// Sets the HiddenString property
128	125		procedure SetHiddenString(const AValue: string);
129	126		protected
130	127		{ Protected declarations }
131	128		// Can be used if you plan to subclass this component
132	129		public
133	130		{ Public declarations }
134	131		constructor Create(AOwner: TComponent); override; // Constructor must be public
135	132		destructor Destroy; override; // Destructor must be public
136	133
137	134		{ Public properties }
138	135		// This section used for properties you don't want to display in the Object Inspector (or array properties)
139	136		property HiddenString: string read fHiddenString write SetHiddenString;
140	137		// Public property hidden from the Object Inspector. * SetHiddenString method can trigger custom event OnChangeHiddenString
141	138		published
142	139		{
143	140		Published declarations (Displayed in the Object Inspector)
144	141		Note: Comments immediately above the property declarations are displayed in the Lazarus Object Inspector lower pane
145	142		}
146	143
147	144		// The custom property editor TAboutPropertyEditor is used in the Object Inspector
148	145		property About: tAboutString read fAboutString; // Example of custom 'About' dialog
149	146
150	147		// Example of drop-down list in the Object Inspector
151	148		// Default is displayed in different font and is set in Constructor
152	149		property MyTypeList: tmcType read fmcType write fmcType default mcType2;
153	150
154	151		// Direct access read + write
155	152		property SimpleString: string read fSimpleString write fSimpleString;
156	153
157	154		// Example of using Read and Write methods
158	155		property ProcessedString: string read GetProcessedString write SetProcessedString;
159	156
160	157		// Example of pseudo-default property of a string (value is set in Constructor)
161	158		property StringWithDefault: string read fStringWithDefault write fStringWithDefault;
162	159
163	160		// Example of an expandable list of booleans in the Object Inspector
164	161		property Options: tOptionsFlags read fOptions write fOptions;
165	162
166	163		// Browse for Icon dialog in the Object Inspector. * No need to Create fIcon in constructor
167	164		property MyIcon: TIcon read fIcon write fIcon;
168	165
169	166		// Browse for Font dialog in the Object Inspector. * fFont needs to be created in Constructor
170	167		property MyFont: TFont read fFont write SetFont; // * Note the SetFont method
171	168
172	169		// * Note the SetBitmap method
173	170		// Browse for Bitmap dialog in the Object Inspector. * fBitmap needs to be created in Constructor
174	171		property MyBitMap: TBitmap read fBitMap write SetBitmap;
175	172
176	173		// Showing a built-in list of booleans in the Object Inspector
177	174		property MySizeConstraints: TSizeConstraintsOptions
178	175		read fSizeConstraints write fSizeConstraints;
179	176
180	177		// Default is displayed in different font but has to be set to the value 2 in Constructor
181	178		property IntegerWithDefault: integer read fIntegerWithDefault
182	179		write fIntegerWithDefault default 2; // Example of integer default
183	180
184	181		// The method is passed the index as a parameter
185	182		// Example of using an indexed read and write method to store strings in an array
186	183		property String1: string index 1 read GetStringValue write SetStringValue;
187	184		// Example of using an indexed read and write method to store strings in an array
188	185		property String2: string index 2 read GetStringValue write SetStringValue;
189	186		// Example of using an indexed read and write method to store strings in an array
190	187		property String3: string index 3 read GetStringValue write SetStringValue;
191	188		// Example of using an indexed read and write method to store strings in an array
192	189		property String4: string index 4 read GetStringValue write SetStringValue;
193	190
194	191		// Dialog shows in the Object Inspector. * fStringlist must be Created in the constructor. * Note the SetStrings override
195	192		// String list example.
196	193		property MyStringList: TStrings read fStringList write SetStrings;
197	194
198	195		// Example of a file open dialog property
199	196		property MyFilename: tFilenameString read fFilenameString write fFilenameString;
200	197
201	198		// Tag property will now only accept a single alpha character
202	199		// Example of overriding an ancestor (TComponent's) Tag property
203	200		property Tag: string read fTag write SetTag;
204	201
205	202		// No need to specify type, read method or write method
206	203		// Example of publishing a public property from an ancestor (TComponent)
207	204		property ComponentState;
208	205
209	206		// ReadOnly property
210	207		property Version: string read fVersion;
211	208
212	209		// Example of Custom Event that does nothing
213	210		property OnSample: TSampleEvent read FOnSample write FOnSample;
214	211
215	212		// This custom event is always triggered by a change in the value of HiddenString property
216	213		property OnChangeHiddenString: TNotifyEvent
217	214		read fOnChangeHiddenString write fOnChangeHiddenString;
218	215		end;
219	216		// Declaration for the 'About' property editor
220	217		TAboutPropertyEditor = class(TClassPropertyEditor)
221	218		public
222	219		procedure Edit; override;
223	220		function GetAttributes: TPropertyAttributes; override;
224	221		function GetValue: string; override;
225	222		end;
226	223		// Declaration for 'MyFilename' property editor
227	224		// (See PropEdits unit for a list of property editors to modify)
228	225		TMyFileNamePropertyEditor = class(TFileNamePropertyEditor)
229	226		public
230	227		// Override the Edit method for total control
231	228		function GetFilter: string; override;
232	229		function GetDialogOptions: TOpenOptions; override;
233	230		function GetDialogTitle: string; override;
234	231		end;
235	232
236	233		procedure Register; // Must be declared here just before implementation
237	234
238	235		implementation
239	236
240	237		procedure Register;
241	238		begin
242	239		{$I myvisualcomponent_icon.lrs}
243	240		// Register this component into the IDE on the 'Additional' component palette
244	241		RegisterComponents('Additional', [TMyVisualComponent]);
245	242
246	243		// Register the custom property editor for the 'About' property
247	244		RegisterPropertyEditor(TypeInfo(tAboutString),
248	245		TMyVisualComponent, 'About', TAboutPropertyEditor);
249	246		// Register the custom property editor for the 'MyFilename' property
250	247		RegisterPropertyEditor(TypeInfo(tFilenameString),
251	248		TMyVisualComponent, 'MyFilename', TMyFileNamePropertyEditor);
252	249
253	250		// Note the TypeInfo parameter is made into a unique string type
254	251		// (defined earlier in this unit)
255	252		// so that the regular property editors in other components don't get confused
256	253		// You could simply use TypeInfo(String)
257	254		end;
258	255
259	256		constructor TMyVisualComponent.Create(AOwner: TComponent);
260	257		// Called when form is loaded into the IDE
261	258		begin
262	259		inherited Create(AOwner);
263	260		// Initialisation goes here
264	261		// Set any properties to their defaults and intialise objects
265	262		fmcType := mcType2; // because this was the default value specified
266	263		fStringWithDefault := 'Default String'; // Unspecified default
267	264		fIntegerWithDefault := 2; // Default value specified
268	265		fTag := 'A'; // Unspecified default
269	266		fIcon := Application.Icon; // Unspecified default
270	267		fFont := TFont.Create; // Needs to be created here for Object Inspector to show options
271	268		fBitmap := TBitMap.Create;
272	269		// Needs to be created here for Object Inspector to show the bitmap dialog
273	270		fStringList := TStringList.Create;
274	271		// Needs to be created here for Object Inspector to show dialog
275	272		fVersion := C_VERSION;
276	273		// Assign read-only property
277	274		end;
278	275
279	276		destructor TMyVisualComponent.Destroy;
280	277		begin
281	278		// Clean-up code goes here
282	279		// FreeandNil any user-created objects here
283	280		FreeAndNil(fBitmap);
284	281		FreeAndNil(fStringList);
285	282		FreeAndNil(fFont);
286	283		inherited Destroy;
287	284		end;
288	285
289	286		// == START PROPERTY EDITOR CODE ==
290	287		procedure TAboutPropertyEditor.Edit;
291	288		// Shows a dialog when About property is double-clicked
292	289		var
293	290		tAboutForm: TForm;
294	291		OKbutton: TBitBtn;
295	292		lbl_Description: TLabel;
296	293		sz: string;
297	294		begin
298	295		// Make up message string
299	296		sz := 'My component for Lazarus' + LineEnding + 'by email@domain.com' +
300	297		LineEnding + LineEnding;
301	298		sz += 'Methods:' + LineEnding;
302	299		sz += 'MyVisualComponent.Method1' + LineEnding;
303	300		sz += 'MyVisualComponent.Method2' + LineEnding;
304	301		sz += LineEnding + 'Version: ' + C_VERSION + LineEnding;
305	302		sz += 'License: LGPL';
306	303		// Create a new dialog
307	304		tAboutForm := TForm.CreateNew(nil);
308	305		try //.. finally FreeAndNil everything
309	306		with tAboutForm do
310	307		begin
311	308		// Set Form properties
312	309		position := poScreenCenter;
313	310		borderstyle := bsToolWindow;
314	311		Caption := 'About My Component';
315	312		formstyle := fsSystemStayOnTop;
316	313		color := clSkyBlue;
317	314		Height := 240;
318	315		Width := 320;
319	316		// Create a BitBtn button
320	317		okbutton := TBitBtn.Create(tAboutForm);
321	318		// Set BitBtn properties
322	319		okbutton.Kind := bkClose;
323	320		okbutton.left := (Width div 2) - okbutton.Width div 2;
324	321		okbutton.top := Height - okbutton.Height - 10;
325	322		okbutton.parent := tAboutForm;
326	323		// Create a label control
327	324		lbl_Description := Tlabel.Create(tAboutForm);
328	325		// Set label properties
329	326		lbl_Description.left := 8;
330	327		lbl_Description.Top := 30;
331	328		lbl_Description.Width := 304;
332	329		lbl_Description.Height := 200;
333	330		lbl_Description.Autosize := False;
334	331		lbl_Description.Alignment := taCenter;
335	332		lbl_Description.Caption := sz;
336	333		lbl_Description.parent := tAboutForm;
337	334		// Display the dialog modally
338	335		ShowModal;
339	336		end;
340	337		finally
341	338		// Free all resources
342	339		FreeAndNil(lbl_Description);
343	340		FreeAndNil(okbutton);
344	341		FreeAndNil(tAboutForm);
345	342		end;
346	343		end;
347	344
348	345		function TAboutPropertyEditor.GetAttributes: TPropertyAttributes;
349	346		// Show the ellipsis
350	347		begin
351	348		Result := [paDialog];
352	349		end;
353	350
354	351		function TAboutPropertyEditor.GetValue: string;
355	352		// Override standard string read method
356	353		begin
357	354		Result := '(Double-click)';
358	355		end;
359	356
360	357		function TMyFileNamePropertyEditor.GetFilter: string;
361	358		begin
362	359		Result := 'All Files\|.\|Bitmaps\|.bmp\|JPegs\|.jpg';
363	360		end;
364	361
365	362		function TMyFileNamePropertyEditor.GetDialogOptions: TOpenOptions;
366	363		begin
367	364		// To see the full list, drop an OpenDialog onto a form and see the Options property
368	365		Result := [ofFileMustExist, ofPathMustExist];
369	366		end;
370	367
371	368		function TMyFileNamePropertyEditor.GetDialogTitle: string;
372	369		begin
373	370		Result := 'My Custom Title';
374	371		end;
375	372		// == END PROPERTY EDITOR CODE ==
376	373
377	374		// == PROPERTY GET/SETS ==
378	375		procedure TMyVisualComponent.SetProcessedString(AValue: string);
379	376		begin
380	377		// Check to see if a change is necessary
381	378		// Avalue can be amended before it is assigned to fProcessedString
382	379		if (fProcessedString <> AValue) then
383	380		fProcessedString := UpperCase(AValue);
384	381		end;
385	382
386	383		function TMyVisualComponent.GetProcessedString: string;
387	384		begin
388	385		// Do any error-checking or processing of fProcessedString here.
389	386		Result := fProcessedString;
390	387		end;
391	388
392	389		procedure TMyVisualComponent.SetTag(AValue: string);
393	390		// Overridden Tag property will only accept letters
394	391		// If changed via Object Inspector to a non-alpha string, then show custom error message
395	392		begin
396	393		if (fTag <> AValue) and (Length(AValue) > 0) then
397	394		if AValue[1] in ['A'..'Z'] + ['a'..'z'] then
398	395		fTag := AValue[1]
399	396		else
400	397		if ComponentState = [csDesigning] then
401	398		raise Exception.CreateFmt(C_ERRORMESSAGE,
402	399		[Name, 'You can only set the tag property to an alpha value']);
403	400		// 'Name' is the Name property of this TComponent instance
404	401		end;
405	402
406	403		function TMyVisualComponent.GetStringValue(const AIndex: integer): string;
407	404		begin
408	405		// Example of an indexed property Get method
409	406		// Retrieve from private string Array
410	407		Result := fStringArray[AIndex - 1];
411	408		end;
412	409
413	410		procedure TMyVisualComponent.SetStringValue(const AIndex: integer; AValue: string);
414	411		// Example of an indexed property Set method
415	412		// Value is stored in private string array
416	413		begin
417	414		if (fStringArray[AIndex - 1] <> AValue) then
418	415		fStringArray[AIndex - 1] := AValue;
419	416		end;
420	417
421	418		procedure TMyVisualComponent.SetStrings(const AValue: TStrings);
422	419		begin
423	420		// this is correct statement
424	421		FStringList.Assign(AValue);
425	422		// this is not correct
426	423		// FStrings := AValue;
427	424		end;
428	425
429	426		procedure TMyVisualComponent.SetFont(const AValue: TFont);
430	427		begin
431	428		// this is correct statement
432	429		fFont.Assign(AValue);
433	430		// this is not correct
434	431		// fFont := AValue;
435	432		end;
436	433
437	434		procedure TMyVisualComponent.SetBitMap(const AValue: TBitmap);
438	435		begin
439	436		// this is correct statement
440	437		fBitmap.Assign(AValue);
441	438		// this is not correct
442	439		// fBitmap := AValue;
443	440		end;
444	441
445	442		procedure TMyVisualComponent.SetHiddenString(const AValue: string);
446	443		// If value is changed then triggers the custom events OnChangeHiddenString and OnSample
447	444		begin
448	445		if (fHiddenString <> AValue) then
449	446		begin
450	447		fHiddenString := AValue;
451	448		// Trigger custom events
452	449		if Assigned(fOnChangeHiddenString) then
453	450		OnChangeHiddenString(Self);
454	451		if Assigned(fOnSample) then
455	452		OnSample(AValue);
456	453		end;
457	454		end;
458	455		// Sample application code that uses the Custom Events as coded
459	456		// Both are triggered by changing the HiddenString property in SetHiddenString
460	457		{
461	458		procedure TForm1.MyVisualComponent1ChangeHiddenString(Sender: TObject);
462	459		begin
463	460		ShowMessage('Hidden String was changed to something new');
464	461		end;
465	462
466	463		procedure TForm1.MyVisualComponent1Sample(MyText: String);
467	464		begin
468	465		ShowMessageFmt('Hidden String was changed to "%s"',[MyText]);
469	466		end;
470	467
471	468		procedure TForm1.Button1Click(Sender: TObject);
472	469		begin
473	470		MyVisualComponent1.HiddenString:='Hello World';
474	471		end;
475	472		}
476	473		end.
477	474		```
478	475
479	476		### Download
480	477
481	478		You can download this code as a package ready to install and play with [here](http://www.charcodelvalle.com/myvisualcomponent/myvisualcomponent_code.zip)
482	479
483	480		### Author
484	481
485	482		minesadorada@charcodelvalle.com
486	483
487	484		### License
488	485
489	486		All code is released under the LGPL license
490	487
491	488		## See also
492	489
493	490		- [[Components and Code examples\|Components and code examples]]
494	491		- [[How To Write Lazarus Component\|How to write a Lazarus component]]
495	492		- [[Object Oriented Programming with FreePascal and Lazarus\|Object-oriented programming with FreePascal and Lazarus]]
496	493
497	494		---
498	495		From the Free Pascal wiki, page "Lazarus Nongraphical Visual Component Example Code", as it stood on 2020-02-18 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).
499	496		Category: Code Snippets
500	497		Category: Component Creation
501	498		Category: Object-oriented development
502	499		Category: Tutorials

Back to history