TAChart Tutorial: Getting started: 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/2/2f/Tachart_getting_started_step6.png)
4	4
5	5		If you want to add a plot or a chart to your Lazarus form you should have a look at [[TAChart]]. This is the standard Lazarus package for drawing plots and charts.
6	6
7	7		In this tutorial we will draw some elemental mathematical functions by TAChart. We will create a chart with three line series for the functions
8	8
9	9		- y=cos(x),
10	10		- y=sin(x), and
11	11		- y=cos(x)*sin(x).
12	12
13	13		Maybe it is necessary to expain the words "series" and "chart" here: the entire diagram is the "chart", and each of the functions will be displayed as a curve called "series". We will connect the data points by line sections, therefore, we will use the "line series". TAChart, of course, allows to use many other types of series, for example bar series, area series, pie series, or even advanced types like spline or fit series.
14	14
15	15		## What is needed?
16	16
17	17		This guide will be very elemental. Of course, you'll need basic knowledge of the [[Object Pascal]] language and the Lazarus [[IDE]].
18	18
19	19		TAChart is included in Lazarus, so there is no need for seeking this package somewhere in the internet. However, don't use a too-old version of Lazarus since TAChart is being actively developed and some features may change from version to version.
20	20
21	21		It is best if you follow this tutorial step by step. But if you want you can use the [[Source code\|source code]] of the finished project at the end of this article.
22	22
23	23		## A new project
24	24
25	25		![](/wiki-images/9/95/TAChart_component_palette.png)
26	26
27	27		To begin with, we create a new project in Lazarus and, in the [[Component Palette\|component palette]] we select the page [[Chart tab\|"Chart"]]. Click on the left-most icon, the [[TChart]] component, and add it to the form. You will see an empty diagram with standardized x and y axes.
28	28
29	29		![](/wiki-images/6/63/TAChart_GettingStarted_Step1.png)
30	30
31	31		## Adding series
32	32
33	33		Now let's add series. For this purpose, double-click on the chart (or right-click, and select "Edit series" from the context menu). The TAChart series editor appears. It is still empty, but when you select "Add" you will see a menu with all the series types available within the TAChart package. Select the "line series". Repeat two times to create, in total, three line series that are assigned to the chart. They are not yet displayed in the chart, because they do not yet have any data. No data - no display. We will fix that in a minute.
34	34
35	35		![](/wiki-images/6/6f/TAChart_GettingStarted_Step1a.png)
36	36
37	37		Before we do that let us have a look at the object inspector tree. TAChart uses a quite complex architecture of classes and containers, so it is important to understand the object tree. In the current state of our project we see the TChart component and its children, the three line series and the AxisList with Left and Bottom axes as children again. The series names are constructed according to `Chart<number><SeriesType><Number>`.
38	38
39	39		![](/wiki-images/c/ce/Tachart_getting_started_object_tree.png)
40	40
41	41		Why don't we give them more descriptive names, like `SinSeries`, `CosSeries`, and `SinCosSeries`? For this purpose, click on each series, and change the series `Name` in the corresponding field of the object inspector below.
42	42
43	43		## Adding data
44	44
45	45		Now it's time to add data. The easiest option is to create the data along with the form, i.e. we write a handler for the forms's `OnCreate` event. Of course, in a "real" project, you will add data at other occasions, for example after a button click which might initiate a calculation or read data from a file.
46	46
47	47		``` pascal
48	48		procedure TForm1.FormCreate(Sender: TObject);
49	49		const
50	50		N = 100;
51	51		MIN = -10;
52	52		MAX = 10;
53	53		var
54	54		i: Integer;
55	55		x: Double;
56	56		begin
57	57		for i:=0 to N-1 do begin
58	58		x := MIN + (MAX - MIN) * i /(N - 1);
59	59		SinSeries.AddXY(x, sin(x));
60	60		CosSeries.AddXY(x, cos(x));
61	61		SinCosSeries.AddXY(x, sin(x)*cos(x));
62	62		end;
63	63		end;
64	64		```
65	65
66	66		This [[Procedure\|procedure]] creates 100 data points for each series. The x values are calculated to be equidistant between `MIN` and `MAX`, i.e. -10 and 10. The important lines are the calls to the `AddXY` [[Method\|method]] of each series. This method takes the x and y coordinates of each data point and adds them to an internal list. There are also overloaded versions of this method where you can also pass a text label for each data point, as well as an individual color, but we don't need this feature here.
67	67
68	68		The mentioned list is a so-called chart source - this is a [[Class\|class]] which provides the data for plotting. You can use the built-in chart source, or you can link the series to a separate one. There is a variety of chart sources in the component palette, like
69	69
70	70		- `TListChartSource` which stores the data in a list (this type is used by our series internally)
71	71		- `TDBChartSource` which interfaces to the records and fields in a database
72	72		- `TUserDefinedChartSource` which gives a very general access to data, for example, stored in an array of user-defined records
73	73		- `TCalculatedChartSource` which allows to analyze one series and display the results in another one.
74	74
75	75		But enough on chart sources - the built-in source is sufficient for this introductory project.
76	76
77	77		![](/wiki-images/b/b8/Tachart_getting_started_step2.png)
78	78
79	79		Ok, let's compile the program. We see the three curves, and the x axis automatically covers our data range between -10 and 10. Well - not too bad, but far from being perfect: The diagram is very confusing, we cannot distinguish between the individual lines, and we cannot tell which series belongs to which function.
80	80
81	81		## Formatting the series
82	82
83	83		Why don't we change the color of each series? To do this select each series in the object tree and, in the object inspector below, change the [[Property\|property]] `SeriesColor` as you want it to be - `SeriesColor` is the color of the lines connecting the data points.
84	84
85	85		When you recompile you will see the series colored. But we still cannot distinguish between the different functions. What we need is a legend.
86	86
87	87		## Adding a legend
88	88
89	89		Highlight the chart and, in the object inspector, scroll down to `Legend` and open the sub-properties. At the end, there is `Visible` which is `false` by default - so, set it to `true`, and recompile.
90	90
91	91		![](/wiki-images/2/2e/Tachart_getting_started_step3.png)
92	92
93	93		Well, it's getting better. What is missing, is an explanatory text for each series, like `y = sin(x)`. For this purpose each series has a property `Title` - this is the text which will appear in the legend for each entry along with the symbol for the corresponding series. Therefore you have to go through all series again and use the object inspector to set `Title` to `y=sin(x)`, `y=cos(x)`, and `y=sin(x)*cos(x)`, respectively.
94	94
95	95		![](/wiki-images/5/5f/Tachart_getting_started_step4.png) ![](/wiki-images/2/20/Tachart_getting_started_step4a.png)
96	96
97	97		Now when you recompile, the chart is almost perfect. Almost - because the legend is quite large, and the diagram is squeezed into the remaining space. Of course, we could increase the size of the form. But can we also put the legend underneath the diagram? No problem: go back to the chart's property `Legend` and set `Alignment` to `laBottomCenter`. You should also set `ColumnCount` to `3`, otherwise the legend items will be in a column instead of in a row.
98	98
99	99		![](/wiki-images/3/37/Tachart_getting_started_step5.png)
100	100
101	101		Ah! -- the third legend entry is truncated because the window is not wide enough. Align the chart to `alClient` and increase the width of the window a bit.
102	102
103	103		## Fine-tuning
104	104
105	105		A few more things can still be improved: The axes should have a title, like "x axis" and "y axis", respectively, and there should also be a title above the chart.
106	106
107	107		To set the title for the x axis select in the object tree the item `Bottom` of the AxisList child component of TChart, or go to `Bottom axis` in the object inspector. Open the sub-properties where you'll find `Title` which has sub-properties again. The text in the field `Caption` will be displayed as a title above the chart. Don't forget to set `Visible` to `true`. You may also want to set the font style of the title to bold - you find that property under `LabelFont`. Repeat the same with `Left axis`.
108	108
109	109		Essentially the same procedure can be used to set the chart title: Scroll to the chart's property `Title`, enter the title in the field `Text` (you may even use a multi-line text here), and set `Visible` to `true` again.
110	110
111	111		And finally, you might prefer to use a white background of the chart area, this is changed by the property `BackColor` of TChart. And maybe the grid should be less emphasized, i.e. it might look better with color `clSilver`. Use the left and bottom axes property `Grid.Color` to change that.
112	112
113	113		## Finished!
114	114
115	115		In the end, our chart looks like this. Neat, isn't it? And it was not difficult at all...
116	116
117	117		If you want to learn more about TAChart have a look at the official [[TAChart documentation]], and study some of the many demos that come with TAChart. They can be found in the folder `components\tachart\demo` of your Lazarus installation.
118	118
119	119		![](/wiki-images/2/2f/Tachart_getting_started_step6.png)
120	120
121	121		## Source code
122	122
123	123		The source code of this tutorial project can be found in the folder tutorials/getting_started of trunk TAChart installations.
124	124
125	125		### Project file
126	126
127	127		``` pascal
128	128		program project1;
129	129
130	130		{$mode objfpc}{$H+}
131	131
132	132		uses
133	133		{$IFDEF UNIX}{$IFDEF UseCThreads}
134	134		cthreads,
135	135		{$ENDIF}{$ENDIF}
136	136		Interfaces, // this includes the LCL widgetset
137	137		Forms, Unit1, tachartlazaruspkg
138	138		{ you can add units after this };
139	139
140	140		{$R *.res}
141	141
142	142		begin
143	143		RequireDerivedFormResource := True;
144	144		Application.Initialize;
145	145		Application.CreateForm(TForm1, Form1);
146	146		Application.Run;
147	147		end.
148	148		```
149	149
150	150		### Unit1.pas
151	151
152	152		``` pascal
153	153		unit Unit1;
154	154
155	155		{$mode objfpc}{$H+}
156	156
157	157		interface
158	158
159	159		uses
160	160		Classes, SysUtils, FileUtil, TAGraph, TASeries, Forms, Controls, Graphics,
161	161		Dialogs;
162	162
163	163		type
164	164
165	165		{ TForm1 }
166	166
167	167		TForm1 = class(TForm)
168	168		Chart1: TChart;
169	169		SinSeries: TLineSeries;
170	170		CosSeries: TLineSeries;
171	171		SinCosSeries: TLineSeries;
172	172		procedure FormCreate(Sender: TObject);
173	173		private
174	174		{ private declarations }
175	175		public
176	176		{ public declarations }
177	177		end;
178	178
179	179		var
180	180		Form1: TForm1;
181	181
182	182		implementation
183	183
184	184		{$R *.lfm}
185	185
186	186		{ TForm1 }
187	187
188	188		procedure TForm1.FormCreate(Sender: TObject);
189	189		const
190	190		N = 100;
191	191		MIN = -10;
192	192		MAX = 10;
193	193		var
194	194		i: Integer;
195	195		x: Double;
196	196		begin
197	197		for i:=0 to N - 1 do begin
198	198		x := MIN + (MAX - MIN) * i / (N - 1);
199	199		SinSeries.AddXY(x, sin(x));
200	200		CosSeries.AddXY(x, cos(x));
201	201		SinCosSeries.AddXY(x, sin(x)*cos(x));
202	202		end;
203	203
204	204		end;
205	205
206	206		end.
207	207		```
208	208
209	209		### Unit.lfm
210	210
211		-	~~``` pascal~~
	211	+	``` lfm
212	212		object Form1: TForm1
213	213		Left = 14
214	214		Height = 244
215	215		Top = 137
216	216		Width = 347
217	217		Caption = 'Form1'
218	218		ClientHeight = 244
219	219		ClientWidth = 347
220	220		OnCreate = FormCreate
221	221		LCLVersion = '1.1'
222	222		object Chart1: TChart
223	223		Left = 0
224	224		Height = 244
225	225		Top = 0
226	226		Width = 347
227	227		AxisList = <
228	228		item
229	229		Grid.Color = clSilver
230	230		Minors = <>
231	231		Title.LabelFont.Orientation = 900
232	232		Title.LabelFont.Style = [fsBold]
233	233		Title.Visible = True
234	234		Title.Caption = 'y axis'
235	235		end
236	236		item
237	237		Grid.Color = clSilver
238	238		Alignment = calBottom
239	239		Minors = <>
240	240		Title.LabelFont.Style = [fsBold]
241	241		Title.Visible = True
242	242		Title.Caption = 'x axis'
243	243		end>
244	244		BackColor = clWhite
245	245		Foot.Brush.Color = clBtnFace
246	246		Foot.Font.Color = clBlue
247	247		Legend.Alignment = laBottomCenter
248	248		Legend.ColumnCount = 3
249	249		Legend.Visible = True
250	250		Title.Brush.Color = clBtnFace
251	251		Title.Font.Color = clBlue
252	252		Title.Font.Style = [fsBold]
253	253		Title.Text.Strings = (
254	254		'My first chart'
255	255		)
256	256		Title.Visible = True
257	257		Align = alClient
258	258		ParentColor = False
259	259		object SinSeries: TLineSeries
260	260		Title = 'y=sin(x)'
261	261		LinePen.Color = clRed
262	262		end
263	263		object CosSeries: TLineSeries
264	264		Title = 'y=cos(x)'
265	265		LinePen.Color = clBlue
266	266		end
267	267		object SinCosSeries: TLineSeries
268	268		Title = 'y=sin(x)*cos(x)'
269	269		LinePen.Color = clGreen
270	270		end
271	271		end
272	272		end
273	273		```
274	274
275	275		---
276	276		From the Free Pascal wiki, page "TAChart Tutorial: Getting started", as it stood on 2023-04-12 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