FMXTutorial6
Contents page Previous  Next

Tutorial 6  Working with Series
Contents
Series Types
The TChartSeries component is the common ancestor for all Series types.
Series Class structure
As a little background on the structure of the TeeChart Component Library, here follows an explanation of the Series Components and their structure. The diagram below shows the relationship between TeeChart Series classes. All classes derive from the generic "TChartSeries" class and thus share "Series" properties and methods. Several other generic Classes derive from Series (CustomSeries, CustomBarSeries and CircledSeries), these are highlighted in green and their components are not directly accessible for programming, their characteristics are inherited by their descendant Series types. All derived Series (in red) are accessible in the TeeChart gallery for inclusion in your Chart. TeeChart Series, derived in this way, allow programmable access via a common index structure (collection).
TeeChart Pro's internal Series Class hierarchy 
It's easier to use the TChart Editor to add Series at design time but you can also create and add new and differing Series types to the same Chart at runtime.
//You could add the Series at runtime procedure TForm1.Button2Click(Sender: TObject); var tmpAreaSeries:TAreaSeries; begin tmpAreaSeries:=TAreaSeries.Create(self); With tmpAreaSeries do begin ParentChart:=Chart1; FillSampleValues(10); end; end;
All AreaSeries properties and methods are available for the new Series as for any Series created at design time.
Choosing a Series Type
Choosing a Series Type for a Chart will very much depend on your own requirements for the Chart. There are occasions, however, where the choice of Chart depends on which Series types support the number of input variables because of the high number of variables to plot. The following table shows the number of variables allowed by some different Series types. For the brevity of this tutorial we haven't included all the possible Series types offered with TeeChart.
Series Type 
No. of variables 
Datasource Properties 
Standard  
Line 
2 
XValues, YValues, XLabel 
Bar 
2 
XValues, YValues (called Bar), XLabel 
HorizBar 
2 
XValues, YValues (called Bar), XLabel 
Area 
2 
XValues, YValues, XLabel 
Point 
2 
Xvalues, YValues, XLabel 
Pie 
1 
PieValues, XLabel 
Fast Line 
2 
XValues, YValues, XLabel 
Horiz. Line 
2 
XValues, YValues, YLabel 
Horiz. Area 
2 
XValues, YValues, XLabel 
Shape 
4 
X0 (Top), Y0 (Bottom), X1 (Left), Y1 (Right) 
Bubble 
3 
Xvalues, YValues, XLabel, RadiusValues 
Gantt 
3 
StartValues, EndValues, AY (Y axis level), AXLabel (Label optionally shown on Yaxis or as mark) 
Extended  
Arrow 
4 
StartXValues, StartYValues, XLabel, EndXValues, EndYValues 
Polar 
2 
XValues, YValues, Labels (Polar has Angle and Radius) 
Radar 
2 
XValues, YValues, Labels (Radar has Angle and Radius) 
Bezier 
2 
XValues, YValues, XLabel 
Donut 
2 
Angle, YValue, Labels 
Smith 
2 
Resistance, Reactance, Labels 
Pyramid 
3 
XValues, YValues, XLabel, ErrorValues 
Financial  
Candle 
5 
OpenValues, CloseValues, HighValues, LowValues, DateValues 
Point & Figure 
5 
OpenValues, CloseValues, HighValues, LowValues, DateValues 
Volume 
2 
XValues, YValues (VolumeValues), XLabel 
Stats 

Histogram 
2 
Xvalues, YValues, XLabel 
Error Bar 
3 
XValues, YValues, XLabel, StdErrorValues 
Error 
3 
XValues, YValues, XLabel, StdErrorValues 
HighLow 
3 
XValues, YValues, XLabel, LowValues 
Box Plot 
3 
XValues, SamplesValues, Label 
Horizontal Box Plot 
3 
XValues, SamplesValues, Label 
Funnel 
3 
XValues, QuoteValues, OpportunityValues, XLabel 
3D 

Surface 
3 
Xvalues, YValues, ZValues 
Contour 
3 
XValues, YValues, ZValues, XLabel 
Waterfall 
3 
Xvalues, YValues, ZValues 
ColorGrid 
3 
XValues, YValues, ZValues 
Tower 
3 
XValues, YValues, XLabel, ZValues 
Point3D 
3 
XValues, YValues, XLabel, ZValues 
Triangle Surf. 
3 
Xvalues, YValues, ZValues 
Other 

Clock 
2 
Angle, YValues, Labels 
Line Point 
2 
XValues, YValues, XLabel 
Bar Join 
2 
Xvalues, YValues, XLabel 
Bar3D 
3 
XValues, YValues, YStartPoint, XLabel 
WindRose 
2 
Angle, YValues, Labels 
Calendar 
2 
XValues, YValues, Labels 
Gauges 

Gauge 
1 
Value 
Labelling can be used to extend the value of a 2 variable Series Type. See the example below that uses 3 instances of the Bar Series type in the same Chart.
Example
Uses Bar Series types
Product code  Month  Quantity produced 
10  Jan  300 
10  Feb  325 
10  Mar  287 
12  Jan  175 
12  Feb  223 
12  Mar  241 
14  Jan  461 
14  Feb  470 
14  Mar  455 
In its simplest form, the data produces the following Chart, grouping the information by month:
or (grouping by product):
We have added new values to the table above (Stock).
Product code  Month  Quantity produced  Stock level 
10  Jan  300  600 
10  Feb  325  715 
10  Mar  287  676 
12  Jan  175  245 
12  Feb  223  270 
12  Mar  241  315 
14  Jan  461  800 
14  Feb  470  755 
14  Mar  455  835 
The values of stock are generally higher than those of monthly production so displaying them gives the following chart (2D this time). The Chart uses Line Series to differentiate Stocks.
Adding data to a Series
Most Series types (other than ODBC datasources Tutorial 8 and Functions Tutorial 7) use the Add and ADDXY methods for adding data. There are some exceptions, see the following table for examples of how they can differ:
Series Type  Add Series points  Delete Series points 
Standard Series types  
Line 
Series.Add 
Series.Delete 
Horiz Line 
Series.Add 
Series.Delete] 
Fast Line 
Series.Add 
Series.Delete 
Bar 
Series.Add 
Series.Delete 
HorizBar 
Series.Add 
Series.Delete 
Area 
Series.Add 
Series.Delete 
Point 
Series.Add 
Series.Delete 
Pie 
Series.Add 
Series.Delete 
Arrow 
ArrowSeries.AddArrow 
Series.Delete 
Bubble 
BubbleSeries.AddBubble 
Series.Delete 
Gantt 
GanttSeries.AddGantt 
Series.Delete 
Shape 
ShapeSeries.X0, 
TChart.RemoveSeries (TCustomAxisPanel) 
Colour
Colour may be manually added for a point when adding the point
Example
Series1.Add(46, 'My first value', clYellow);
Alternatively use the TeeChart constant clTeeColor, telling TeeChart to allocate a colour. TeeChart will choose one of up to 16 unique and as yet unused colours for each new Series.
Example
Series1.Add(46, 'My first value', clTeeColor);
Deleting data points from a Series
Use Series.Delete to delete a point from a Series.
Example
Series1.Delete(7); //(8th point  Points index start at zero)
Series.Clear clears all points from a Series.
Adding Null points to a Series
See the table [#AddToSeries Adding data to a Series] for a list of Series Types that support the AddNull method. As the name suggests, AddNull will add a Null point to the Series allowing you to define a label for the point but leaving a break in the Series at that point. In the case of a Line Series, the last point before the break will not join to the first point after the break. See [Javascript:CallHelp('TChartSeries.AddNull','Tc2013') Series.AddNull].
example
Series1.AddNull('my null value');
Mixing Series Types on a Chart
TeeChart Pro offers an empty Chart Canvas as a backdrop to data Series. That means that no Chart types are predefined. You define the Chart type you require as a mix of the Series Types that you wish to display. Due to the specialised nature of some Series types it is impractical to mix a few of the Series types together on a Chart. TeeChart helps you by greying out unsuitable Series types in the Chart Gallery when you come to add a new Series. There is no practical limit to the number of Series that you can put in one Chart.
Adding New Series
Add a Series using the Chart Editor (see Tutorial 1) or by code.
Example
procedure TForm1.Button2Click(Sender: TObject); var tmpLineSeries:TLineSeries; begin tmpLineSeries:=TLineSeries.Create(self); Chart1.AddSeries(tmpLineSeries); tmpLineSeries.FillSampleValues(10); end;
Choose Axes for a Series
Series added to the Chart will automatically take the Left and Bottom axes as their reference axes. You may change the reference axes in the Chart Editor by selecting the Series General page for the relevant Series. There are 4 axes available, Top, Left, Bottom and Right. By code, changing the axes will look like this:
With Series1 do begin HorizAxis := aTopAxis; VertAxis := aRightAxis; end;
More than 1 Series may be associated with each Axis. TeeChart will decide the best scale to fit the Series matched to the Axis but you may change Axis scales yourself (See the Axis Tutorial). Additional axes may be added, they will copy the scales associated with their counterparts from the first 4 axes (see the Tutorial section Additional axes).
Connecting Series
You may use a Series as the datasource for another Series. This can be done with the Chart Editor by setting the datasource for the 2nd Series. Go to the Series tab, Datasource page. Select 'Function' as the datasource type. Two Listboxes will appear, available Series and Selected Series. Select the Series you wish to use as the datasource for the present Series, then, in the Combobox above, entitled Function:, select Copy as the function type. Note that any Series, in this way, may be defined as a function of other Series and the Function Type may be any in the list available in the Function combobox. To do the same by code see below:
procedure TForm1.BitBtn2Click(Sender: TObject); begin With Series2 do begin Datasource:=Series1; SetFunction(TAverageTeeFunction.Create(Self)); FunctionType.Period := 4; CheckDatasource; end end;
See tutorial 7  Working with Functions for more information about how to use TeeChart functions.
Changing Series order
Changing series order is very easy with the Chart Editor. Go to the front page of the Editor and highlight the Series that you wish to move. Use the arrow buttons on the right to move the Series up or down in the Series order. Series order will decide the relative display position of the Series in the Chart with respect to other Series. By code use the SeriesList property or the ExchangeSeries method.
Example
Chart1.ExchangeSeries(0, 1); //Change Series(0) with Series(1) in the index order
*Note. After exchanging Series, the index for the Series will be changed. Thus the line of code above will perpetually interchange the 2 Series '0' and '1' if the code is rerun, as 0 becomes 1 and 1 becomes 0.
Setting a Series to 'Active:=False' will hide the Series from the Chart but maintain its data content intact.
Series Value list
TeeChart Series store their values in a Valuelist accessible and modifiable via the [Javascript:CallHelp('TChartValuelist','Tc2013') TChartValueList component].
Accessing Series Values
You may access any value in the list:
Example
ShowMessage(FloatToStr(Series1.XValues[3])); //Displays value of 4th point (index starts at 0) in Series1
Values accessed in this way may be used to set trap conditions on Series data:
With Series1 do begin For t := 0 To Count  1 do begin If YValues[t] > 9 Then ShowMessage('Value: ' FloatToStr(XValues[t]) ', ' FloatToStr(YValues[t]) ' exceeds limit'); end; end;
The same value may be obtained via the point ValueIndex used by some Series methods and several Chart events.
Example
procedure TForm1.Series1Click(Sender: TChartSeries; ValueIndex: Integer; Button: TMouseButton; Shift: TShiftState; X, Y: Integer); begin Showmessage('ValueIndex is: ' IntToStr(ValueIndex)); Showmessage('Point''s Y value is: ' FloatToStr(Sender.YValues.Value[ValueIndex])); Chart1.CancelMouse:=True; //Use CancelMouse to prevent Zoom event activating end;
Note
When clicking on 3D Series, only clicks on the front plane will be recognised as Series clicks.
Example using Values
This code modifies the value of a BarSeries Bar according to the user's mouseclick.
Example
//Use the OnClickSeries or OnClickBackground event to determine where the user has clicked. procedure TForm1.Chart1ClickBackground(Sender: TCustomChart; Button: TMouseButton; Shift: TShiftState; X, Y: Integer); begin If (Int(Chart1.Axes.Bottom.CalcPosPoint(X)) > 1) Then Case Ord(Button) of 0 : UpdatePoint(Chart1.Axes.Bottom.CalcPosPoint(X), Chart1.Axes.Left.CalcPosPoint(Y)); end; end; procedure TForm1.Series1Click(Sender: TChartSeries; ValueIndex: Integer; Button: TMouseButton; Shift: TShiftState; X, Y: Integer); begin UpdatePoint(ValueIndex, Chart1.Axes.Left.CalcPosPoint(Y)); Chart1.CancelMouse:=True; //Use CancelMouse to prevent Zoom event activating end;
In both cases call the UpdatePoint Sub routine to modify the Bar's value:
Procedure TForm1.UpdatePoint(Bar, Y : Double); begin If Round(Bar) < Series1.Count Then begin Series1.YValues[Round(Bar)] := Int(Y); Chart1.refresh; end; end;


© 19982019 Steema Software SL. All rights reserved.