TAChart Tutorial: Userdefined ChartSource: 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		![](/wiki-images/4/40/TAChart_Population6.png)
4	4
5	5		In this tutorial we use [[TAChart]] to plot the age distribution of world population. In doing this, you will learn
6	6
7	7		- how to work with an [[TAChart documentation\|area series]]
8	8		- and, most of all, how to apply a [[TAChart documentation\|user-defined chart source]]
9	9
10	10		As usual, we assume that you are familiar with Lazarus and the [[Object Pascal]] language and have some basic knowledge of the TAChart package that you would acquire by working through the [[TAChart Tutorial: Getting started\|Getting Started]] tutorial.
11	11
12	12		## Preparation
13	13
14	14		### Data
15	15
16	16		The site [www.census.gov](http://www.census.gov) contains a wealth of demographic data. This [link](http://www.census.gov/population/international/data/worldpop/tool_population.php) leads you directly to the data that we want to plot: world population as a function of age and gender.
17	17
18	18		Go to that page, select a year and click "submit". In the lower part of the window, you will see a table with the columns "Age", "Both Sexes Population", "Male population", "Female population", and "Sex ratio". Use the mouse to select the data in the table (including header) and copy them to the clipboard. Paste the data into a text editor and save as "population.txt".
19	19
20	20		Open Lazarus and create a new project. At first we have to load the data to make them available for plotting.
21	21
22	22		We define a `TPopulationRecord` and an [[Array\|array]] of type `TPopulationArray` to hold the data of the population table:
23	23
24	24		``` pascal
25	25		type
26	26		TPopulationRecord = record
27	27		Age: Integer;
28	28		Total: Double;
29	29		Male: Double;
30	30		Female: Double;
31	31		Ratio: Double;
32	32		end;
33	33
34	34		TPopulationArray = array of TPopulationRecord;
35	35		```
36	36
37	37		Now let's read the file. Have a look at the [[Unit\|unit]] `population.pas` in the [[TAChart Tutorial: Userdefined ChartSource\|Source Code]] section of this tutorial. You will find there a
38	38
39	39		``` pascal
40	40		procedure LoadPopulationData(const AFilename:string; var Data:TPopulationArray)
41	41		```
42	42
43	43		which does the file reading and stores the data in a `TPopulationArray`.
44	44
45	45		Just include the unit `population` in your [[Uses\|uses]] list to get access to this [[Procedure\|procedure]]. Add a [[Variable\|variable]] `PopulationData` of type `TPopulationArray` to the [[Private\|private]] section of the main form. Now we have everything ready to call `LoadPopulationData` from the form's OnCreate event handler. This will read our data file into the array `PopulationData`.
46	46
47	47		``` pascal
48	48		uses
49	49		..., population;
50	50
51	51		type
52	52		TForm1 = class(TForm)
53	53		// ...
54	54		private
55	55		PopulationData : TPopulationArray;
56	56		// ...
57	57		end;
58	58
59	59		const
60	60		POPULATION_FILE = 'population.txt';
61	61
62	62		procedure TForm1.FormCreate(Sender: TObject);
63	63		begin
64	64		LoadPopulationData(POPULATION_FILE, PopulationData);
65	65		end;
66	66		```
67	67
68	68		Compile to check for obvious errors. You may get a [[runtime error]] on that the data file cannot be found. This is because our data file is assumed to reside in the same directory as the exe file. To fix this, either change the [[Constant\|constant]] `POPULATION_FILE` to the correct storage location, or copy "population.txt" to the exe folder. Now the program should run fine, you will see an unspectacularly empty form, though.
69	69
70	70		### Combobox as category selector
71	71
72	72		The file contains various categories: total, male, and femal population, as well as male-to-female ratio. Why not display these data in our chart?
73	73
74	74		To prepare for this,
75	75
76	76		- add a [[TPanel\|panel]] to the form, align it to `alTop`, and delete its caption.
77	77		- Add a [[TComboBox\|combobox]] to this panel, set its `Style` to `csDropdownList`, add the strings "Total population", "Male population", "Female population", and "Ratio male/female (%)" to the `Items` [[Property\|property]], and set `ItemIndex` to 0.
78	78
79	79		### Preparing TChart
80	80
81	81		Now we are finished with preparations, and it's time for charting...
82	82
83	83		- Add a `TChart` component to the form, align it to `alClient`.
84	84		- Set the chart's `BackColor` to `clWhite` and the `Grid.Color` of each axis to `clSilver`.
85	85		- Get axis titles shown by setting `LeftAxis.Visible` and `BottomAxis.Visible` to `true`.
86	86		- Set the caption of the bottom axis to "Age", and that of the left axis to "Total population" (or leave it empty - we will later replace it at [[runtime]] by the selected item of the combobox).
87	87		- Use the text "World population" as the chart's title.
88	88		- Set these font styles to `fsBold`.
89	89		- Maybe it is a good idea to display our data reference in the [[TAChart documentation\|footer]] - the chart property `Foot` can be used for that. Note that the property editor of `Foot.Text` (as well as that of `Title.Text`) allows to enter linefeeds for multi-lined titles.
90	90
91	91		![](/wiki-images/6/61/TAChart_Population2.png)
92	92
93	93		## Creating an area series
94	94
95	95		This time, we want to display our data as an [area series](https://en.wikipedia.org/wiki/Area_chart). This type of series connects the data points as in a line series, but also fills the area underneath by a given color. It is very common to display demographic data, like a [population pyramid](https://en.wikipedia.org/wiki/Population_pyramid), in this way.
96	96
97	97		So, add a [[TAChart documentation\|TAreaSeries]] to the chart. As usual, you don't see it at this time because it does not yet have any data. But we can prepare some properties:
98	98
99	99		- Set its `SeriesColor` to `clSkyBlue`. This is the fill color of the area series.
100	100		- Hide the vertical connecting lines by setting the `AreaLinesPen` to `psClear`.
101	101		- If you want you can also change `ConnectType` to `ctStepXY` or `ctStepYX` to get a step effect.
102	102
103	103		Later, when the series has data, you should play around with these and other properties to see what they do.
104	104
105	105		## User-defined chart source
106	106
107	107		Now, how do we get our data to the area series?
108	108
109	109		The first idea might be iterate through our `PopulationData` array and copy the data to the series by means of `AddXY` calls, like this:
110	110
111	111		``` pascal
112	112		var
113	113		i: Integer;
114	114		begin
115	115		for i:=0 to High(PopulationData) do
116	116		Chart1AreaSeries1.AddXY(PopulationData[i].Age, PopulationData[i].Total);
117	117		end;
118	118		```
119	119
120	120		The disadvantage of this approach is that we would have the data in memory twice: in the `PopulationData` array and in the series - not so good: we would be wasting memory, and we would have to synchronize both storages when data points are added, deleted or edited.
121	121
122	122		![](/wiki-images/e/e0/TAChart_Population3.png) To avoid this, we add a [[TAChart documentation\|TUserDefinedChartSource]] to the form, it is the third or fourth icon from the left in the [[Chart tab\|Chart component palette]]. This chart source is made to interface to any kind of data storage, the source itself does not store any data. You just have to write an event handler for `OnGetChartDataItem` in order to transfer the data. For this purpose, the event takes a [[Variable parameter\|var parameter]] `AItem` of type `TChartDataItem` that is defined as follows (with elements omitted that are not needed here):
123	123
124	124		``` pascal
125	125		type
126	126		TChartDataItem = object
127	127		X, Y: Double;
128	128		// ...
129	129		end;
130	130		```
131	131
132	132		The fields `X` and `Y` are the coordinates of the data point.
133	133
134	134		Now we write the event handler for `OnGetChartDataItem`:
135	135
136	136		``` pascal
137	137		procedure TForm1.UserDefinedChartSource1GetChartDataItem(
138	138		ASource: TUserDefinedChartSource; AIndex: Integer; var AItem: TChartDataItem);
139	139		begin
140	140		AItem.X := PopulationData[AIndex].Age;
141	141		case Combobox1.ItemIndex of
142	142		0: AItem.Y := PopulationData[AIndex].Total;
143	143		1: AItem.Y := PopulationData[AIndex].Male;
144	144		2: AItem.Y := PopulationData[AIndex].Female;
145	145		3: AItem.Y := PopulationData[AIndex].Ratio;
146	146		end;
147	147		end;
148	148		```
149	149
150	150		`AIndex` is the index of the datapoint which is queried. Since both chart source and our `PopulationData` array begin at index 0 we just look into our data array at this index and copy the data to the corresponding elements of the `AItem`. Note that we pick the y coordinate according to what is selected in the combobox. In this way, the UserDefinedChartSource can provide a multitude of data.
151	151
152	152		There are still some important things to do:
153	153
154	154		- Tell the series to use the UserDefinedChartSource instead of the built-in source. For this purpose, we point the series' property `Source` to `UserDefinedChartSource1`.
155	155		- Tell the UserDefinedChartSource how many data points the external data array contains. We have to enter this number in the property `PointsNumber` of the UserDefinedChartSource. The data count is known after our procedure `LoadPopulationData` has finished. So we add a line which sets `PointsNumber` correctly to the `FormCreate` method after `LoadPopulationData` is called.
156	156		- Since the UserDefinedChartSource does not know anything about the structure of the external data we have to notify it whenever data are available or have been changed. We do this by calling `UserDefinedChartSource1.Reset` at an appropriate place. Sometimes you are lucky that some other method may have done this already. But keep in mind that whenever a chart with a UserDefinedChartSource does not behave as you expect there is a chance that you may have forgotten to call `Reset`. To see what happens let's "forget" to call `Reset` for the moment.
157	157
158	158		## Fine-tuning
159	159
160	160		![](/wiki-images/4/48/TAChart_Population4.png)
161	161
162	162		Compile the project in this stage. Not too bad, some flaws, though.
163	163
164	164		- The labels of the y axis are strange. Why do they jump from 80000000 to 1, and then to 12? This seems to be due to a bug of the `Format` function for large numbers in some FPC versions. If you have that issue as well, simply change the property `LeftAxis.Marks.Format`. This string is passed to the `Format` function to convert numbers to strings. The format specifier "%.0n" for example avoids that conversion error and, additionally, adds nice thousand separators to the labels which makes them much more readable. However, be aware that the "0" cuts off any decimals. Therefore, you should use this format specifier only for large numbers.
165	165		- There is a small gap between the y axis and the filled area series. Similarly, the filled area reaches a bit below the x axis. This is caused by the property `Margins` of the chart. This property is usually quite helpful to create an empty area near the plot axes, free from overlapping symbols and marks labels. But here, it is unfavorable. So just set `Chart.Margins.Left` and `Chart.Margins.Bottom` to 0.
166	166		- Ah, and the combobox is not working yet. We need to assign a handler for its `OnSelect` event. What does it have to do? Well, when another combobox item has been selected the UserDefinedChartSource reports a different y value to the series - that's what we want. But how we get the `OnGetChartDataItem` being called? Just by redrawing the chart! When the series is redrawn it always has to query the data from the chart source, so it will get the updated data automatically. OK - let's call `Chart1.Invalidate`:
167	167
168	168		``` pascal
169	169		procedure TForm1.ComboBox1Select(Sender: TObject);
170	170		begin
171	171		Chart1.Invalidate;
172	172		end;
173	173		```
174	174
175	175		When you compile and select another combobox item you will find that the series does nicely update to the selected category. But the axis is frozen, it should rescale automatically. Is this a bug?
176	176
177	177		No. A few lines above, it was said that whenever a chart with a UserDefinedChartSource does not behave as expected there is a chance that you may have forgotten to call `UserDefinedChartSource.Reset`. That's it: we replace the `Invalidate` by the `Reset`.
178	178
179	179		And we can fix another issue: the caption of the y axis should change whenever a different category is selected. For this, we copy the text of the selected combobox item to the chart's `LeftAxis.Title.Caption`. We add a corresponding line the the combobox OnSelect event handler:
180	180
181	181		``` pascal
182	182		procedure TForm1.ComboBox1Select(Sender: TObject);
183	183		begin
184	184		Chart1.LeftAxis.Title.Caption := Combobox1.Items[Combobox1.ItemIndex];
185	185		UserDefinedChartSource1.Reset;
186	186		end;
187	187		```
188	188
189	189		Now switching of data categories by the combobox is working fine.
190	190
191	191		A minor flaw left: Since our y data do not contain a 0 the y axis does not begin at 0 due to the automatic axis scaling. But it would be nice if there were a zero. For this, we must partially turn off automatic axis scaling. The `Chart.Extent` defines a rectangle for the minimum and maximum x and y values. When we set `Chart.Extent.UseYMin` to `true`, the y axis minimum is taken from the value of `Chart.Extent.YMin`, and this is 0 by default. Therefore, we have our zero back.
192	192
193	193		![](/wiki-images/1/13/TAChart_Population5.png)
194	194
195	195		But there is another small problem now: the lowest grid line is drawn on top of the x axis. First of all, the black lines that we see as axes are not the axes themselves, but belong to the frame drawn around the plotting area by default. You can test this by setting `Chart1.Frame.Visible` temporarily to `false`. For the axes, there is a property `AxisPen` where the "true" axis line can be turned on by `AxisPen.Visible = true`. After after doing this, the x axis is still a dashed line. This is caused by the drawing sequence. By default, the y axis, along with its grid, is drawn after the x axis. If you want to have the x axis drawn first you go to the object tree and drag the x axis above the y axis.
196	196
197	197		When you compile the chart is perfect.
198	198
199	199		![](/wiki-images/4/40/TAChart_Population6.png)
200	200
201	201		![](/wiki-images/f/fc/TAChart_Population7.png)
202	202
203	203		## Source code
204	204
205	205		For Lazarus v2.1+ you can find the [[Source code\|source code]] of this tutorial project in folder components/tachart/tutorials/population1 of your Lazarus installation. For older versions, copy and paste the following code to the corresponding files.
206	206
207	207		### Project file
208	208
209	209		``` pascal
210	210		program project1;
211	211
212	212		{$mode objfpc}{$H+}
213	213
214	214		uses
215	215		{$IFDEF UNIX}{$IFDEF UseCThreads}
216	216		cthreads,
217	217		{$ENDIF}{$ENDIF}
218	218		Interfaces, // this includes the LCL widgetset
219	219		Forms, Unit1, tachartlazaruspkg, population
220	220		{ you can add units after this };
221	221
222	222		{$R *.res}
223	223
224	224		begin
225	225		RequireDerivedFormResource := True;
226	226		Application.Initialize;
227	227		Application.CreateForm(TForm1, Form1);
228	228		Application.Run;
229	229		end.
230	230		```
231	231
232	232		### population.pas
233	233
234	234		``` pascal
235	235		unit population;
236	236
237	237		{$mode objfpc}{$H+}
238	238
239	239		interface
240	240
241	241		uses
242	242		Classes, SysUtils;
243	243
244	244		type
245	245		TPopulationRecord = record
246	246		Age: Integer;
247	247		Total: Double;
248	248		Male: Double;
249	249		Female: Double;
250	250		Ratio: Double;
251	251		end;
252	252
253	253		type
254	254		TPopulationArray = array of TPopulationRecord;
255	255
256	256		procedure LoadPopulationData(const AFileName: String; var Data: TPopulationArray);
257	257
258	258		implementation
259	259
260	260		procedure LoadPopulationData(const AFileName: String; var Data: TPopulationArray);
261	261
262	262		function StripThousandSep(const s: String): String;
263	263		var
264	264		i: Integer;
265	265		begin
266	266		Result := s;
267	267		for i:=Length(Result) downto 1 do
268	268		if Result[i] = ',' then
269	269		Delete(Result, i, 1);
270	270		end;
271	271
272	272		var
273	273		List1, List2: TStringList;
274	274		i, j, n: Integer;
275	275		s: String;
276	276		ds: char;
277	277		begin
278	278		ds := FormatSettings.DecimalSeparator;
279	279		List1 := TStringList.Create;
280	280		try
281	281		List1.LoadFromFile(AFileName);
282	282		n := List1.Count;
283	283		SetLength(Data, n-2);
284	284		FormatSettings.DecimalSeparator := '.';
285	285		List2 := TStringList.Create;
286	286		try
287	287		List2.Delimiter := #9;
288	288		List2.StrictDelimiter := true;
289	289		j := 0;
290	290		for i:=2 to n-1 do begin
291	291		List2.DelimitedText := List1[i];
292	292		s := List1[i];
293	293		with Data[j] do begin
294	294		if i < n-1 then
295	295		Age := StrToInt(trim(List2[0]))
296	296		else
297	297		Age := 100;
298	298		Total := StrToFloat(StripThousandSep(trim(List2[1])));
299	299		Male := StrToFloat(StripThousandSep(trim(List2[2])));
300	300		Female := StrToFloat(StripThousandSep(trim(List2[3])));
301	301		Ratio := StrToFloat(trim(List2[4]));
302	302		end;
303	303		inc(j);
304	304		end;
305	305		finally
306	306		List2.Free;
307	307		end;
308	308		finally
309	309		FormatSettings.DecimalSeparator := ds;
310	310		List1.Free;
311	311		end;
312	312		end;
313	313
314	314		end.
315	315		```
316	316
317	317		### Unit1.pas
318	318
319	319		``` pascal
320	320		unit Unit1;
321	321
322	322		{$mode objfpc}{$H+}
323	323
324	324		interface
325	325
326	326		uses
327	327		Classes, SysUtils, FileUtil, TAGraph, TASources, TASeries, Forms, Controls,
328	328		Graphics, Dialogs, ExtCtrls, StdCtrls, population, TACustomSource;
329	329
330	330		type
331	331
332	332		{ TForm1 }
333	333
334	334		TForm1 = class(TForm)
335	335		Chart1: TChart;
336	336		Chart1AreaSeries1: TAreaSeries;
337	337		ComboBox1: TComboBox;
338	338		Panel1: TPanel;
339	339		UserDefinedChartSource1: TUserDefinedChartSource;
340	340		procedure ComboBox1Select(Sender: TObject);
341	341		procedure FormCreate(Sender: TObject);
342	342		procedure UserDefinedChartSource1GetChartDataItem(
343	343		ASource: TUserDefinedChartSource; AIndex: Integer;
344	344		var AItem: TChartDataItem);
345	345		private
346	346		{ private declarations }
347	347		PopulationData: TPopulationArray;
348	348		public
349	349		{ public declarations }
350	350		end;
351	351
352	352		var
353	353		Form1: TForm1;
354	354
355	355		implementation
356	356
357	357		{$R *.lfm}
358	358
359	359		const
360	360		POPULATION_FILE = 'population.txt';
361	361
362	362		{ TForm1 }
363	363
364	364		procedure TForm1.FormCreate(Sender: TObject);
365	365		begin
366	366		LoadPopulationData(POPULATION_FILE, PopulationData);
367	367		UserDefinedChartSource1.PointsNumber := Length(PopulationData);
368	368		Chart1.LeftAxis.Title.Caption := Combobox1.Items[Combobox1.ItemIndex];
369	369		end;
370	370
371	371		procedure TForm1.ComboBox1Select(Sender: TObject);
372	372		begin
373	373		Chart1.LeftAxis.Title.Caption := Combobox1.Items[Combobox1.ItemIndex];
374	374		UserDefinedChartSource1.Reset;
375	375		end;
376	376
377	377		procedure TForm1.UserDefinedChartSource1GetChartDataItem(
378	378		ASource: TUserDefinedChartSource; AIndex: Integer; var AItem: TChartDataItem);
379	379		begin
380	380		AItem.X := PopulationData[AIndex].Age;
381	381		case Combobox1.ItemIndex of
382	382		0: AItem.Y := PopulationData[AIndex].Total;
383	383		1: AItem.Y := PopulationData[AIndex].Male;
384	384		2: AItem.Y := PopulationData[AIndex].Female;
385	385		3: AItem.Y := PopulationData[AIndex].Ratio;
386	386		end;
387	387		end;
388	388
389	389		end.
390	390		```
391	391
392	392		### Unit1.lfm
393	393
394		-	~~``` pascal~~
	394	+	``` lfm
395	395		object Form1: TForm1
396	396		Left = 342
397	397		Height = 360
398	398		Top = 128
399	399		Width = 480
400	400		Caption = 'World population'
401	401		ClientHeight = 360
402	402		ClientWidth = 480
403	403		OnCreate = FormCreate
404	404		Position = poScreenCenter
405	405		LCLVersion = '1.1'
406	406		object Panel1: TPanel
407	407		Left = 0
408	408		Height = 36
409	409		Top = 0
410	410		Width = 480
411	411		Align = alTop
412	412		ClientHeight = 36
413	413		ClientWidth = 480
414	414		TabOrder = 0
415	415		object ComboBox1: TComboBox
416	416		Left = 12
417	417		Height = 23
418	418		Top = 5
419	419		Width = 196
420	420		ItemHeight = 15
421	421		ItemIndex = 0
422	422		Items.Strings = (
423	423		'Total population'
424	424		'Male population'
425	425		'Female population'
426	426		'Ratio male/female (%)'
427	427		)
428	428		OnSelect = ComboBox1Select
429	429		Style = csDropDownList
430	430		TabOrder = 0
431	431		Text = 'Total population'
432	432		end
433	433		end
434	434		object Chart1: TChart
435	435		Left = 0
436	436		Height = 324
437	437		Top = 36
438	438		Width = 480
439	439		AxisList = <
440	440		item
441	441		Grid.Visible = False
442	442		Alignment = calRight
443	443		AxisPen.Visible = True
444	444		Marks.Visible = False
445	445		Minors = <>
446	446		end
447	447		item
448	448		Grid.Color = clSilver
449	449		Alignment = calBottom
450	450		AxisPen.Visible = True
451	451		Minors = <>
452	452		Title.LabelFont.Style = [fsBold]
453	453		Title.Visible = True
454	454		Title.Caption = 'Age'
455	455		end
456	456		item
457	457		Grid.Color = clSilver
458	458		AxisPen.Visible = True
459	459		Marks.Format = '%.0n'
460	460		Marks.Style = smsCustom
461	461		Minors = <>
462	462		Title.LabelFont.Orientation = 900
463	463		Title.LabelFont.Style = [fsBold]
464	464		Title.Visible = True
465	465		end>
466	466		BackColor = clWhite
467	467		Extent.UseYMin = True
468	468		Foot.Alignment = taLeftJustify
469	469		Foot.Brush.Color = clBtnFace
470	470		Foot.Font.Color = clBlue
471	471		Foot.Text.Strings = (
472	472		'Source:'
473	473		'http://www.census.gov/population/international/data/worldpop/tool_population.php'
474	474		)
475	475		Foot.Visible = True
476	476		Margins.Left = 0
477	477		Margins.Right = 0
478	478		Margins.Bottom = 0
479	479		Title.Brush.Color = clBtnFace
480	480		Title.Font.Color = clBlue
481	481		Title.Font.Style = [fsBold]
482	482		Title.Text.Strings = (
483	483		'World population'
484	484		)
485	485		Title.Visible = True
486	486		Align = alClient
487	487		ParentColor = False
488	488		object Chart1AreaSeries1: TAreaSeries
489	489		AreaBrush.Color = clSkyBlue
490	490		AreaLinesPen.Style = psClear
491	491		Source = UserDefinedChartSource1
492	492		end
493	493		end
494	494		object UserDefinedChartSource1: TUserDefinedChartSource
495	495		OnGetChartDataItem = UserDefinedChartSource1GetChartDataItem
496	496		left = 552
497	497		top = 152
498	498		end
499	499		end
500	500		```
501	501
502	502		---
503	503		From the Free Pascal wiki, page "TAChart Tutorial: Userdefined ChartSource", as it stood on 2019-11-16 after a change by Djzepi, 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