Difference between revisions of "TAChart documentation"

From Lazarus wiki
(Sources)
Line 19: Line 19:
 
Data can gen into a chart from various sources.
 
Data can gen into a chart from various sources.
 
They are implemented as a set of components derived from <code>TCustomChartSource</code>.
 
They are implemented as a set of components derived from <code>TCustomChartSource</code>.
 +
 
To assign source to a series, you can set <code>Source</code> property.
 
To assign source to a series, you can set <code>Source</code> property.
 
If the property is left unassigned, series will use its own built-in list source.
 
If the property is left unassigned, series will use its own built-in list source.
 +
Methods like <code>AddXY</code> are delegated to the current series source.
 +
Note that the list source is the only editable source, so after you assign,
 +
for example, random chart source to the series, call to <code>AddXY</code> will raise an exception.
  
 
Each data item has the following fields: X, Y, Color, Text.
 
Each data item has the following fields: X, Y, Color, Text.
Line 26: Line 30:
 
=== List source ===
 
=== List source ===
  
List source is a basic chart source, storing chart data inside itself.
+
<code>TListChartSource</code> is a basic chart source, storing chart data inside itself.
 
As such, you can use <code>Add</code> and <code>Delete</code> function change source data.
 
As such, you can use <code>Add</code> and <code>Delete</code> function change source data.
  
Line 37: Line 41:
 
=== Random source ===
 
=== Random source ===
  
This source generates random data in the given range and is intended mostly to use in demos.
+
<code>TRandomChartSource</code> source generates random data in the given range and is intended mostly to use in demos.
 
You can also use it as design-time replacement for you actual data source.
 
You can also use it as design-time replacement for you actual data source.
 
This will let you see and change the look of your chart without having to run the application.
 
This will let you see and change the look of your chart without having to run the application.
 +
 +
Each random source uses it's own independent random number generator to guarantee stability of it's values.
  
 
=== User-defined source ===
 
=== User-defined source ===
Line 49: Line 55:
  
 
You can of course also use user-defined source to generate, filter or modify data.
 
You can of course also use user-defined source to generate, filter or modify data.
 +
 +
=== Database source ===
 +
 +
<code>TDbChartSource</code> takes data directly from the database.
 +
 +
=== Efficiency notes ===
 +
 +
Primary data source API allows random access. Nevertheless, many sources, in particular random, database and calculated,
 +
may exhibit quadratic or worse behavior if actually accessed randomly.
 +
TAChart itself takes care to only use sequential access (although may it require several passes).
 +
Sources optimize sequential access by using internal state.
 +
User code should be careful not to reset this state during chart drawing from event handlers or custom series code.
 +
 +
Notable exception is list source, which is guaranteed to provide fast random access.
 +
It may be used to cache slow sources with the help of <code>CopyForm</code> procedure.
  
 
== Coordinates and axises ==
 
== Coordinates and axises ==

Revision as of 06:59, 29 July 2011

English (en) русский (ru) українська (uk) 中文(中国大陆)‎ (zh_CN)

Overview

TAChart is a package for drawing graphs, charts and other diagrams. It is comparable in features, but not specifically compatible, with Delphi TeeChart package. One substantial difference is that some features (e.g. data sources and axis transformations) are implemented via separate components instead of just properties. This leads to increased flexibility and opportunity for code re-use, but at the cost of some additional API complexity.

Series

Series are the central part of TAChart. Most of the series represent data taken from data sources in graphical ways, such as lines or bars.

Sources

Data can gen into a chart from various sources. They are implemented as a set of components derived from TCustomChartSource.

To assign source to a series, you can set Source property. If the property is left unassigned, series will use its own built-in list source. Methods like AddXY are delegated to the current series source. Note that the list source is the only editable source, so after you assign, for example, random chart source to the series, call to AddXY will raise an exception.

Each data item has the following fields: X, Y, Color, Text.

List source

TListChartSource is a basic chart source, storing chart data inside itself. As such, you can use Add and Delete function change source data.

The source also has DataPoints property to allow setting data at design time. This property is a TStringList, with each line representing a data point. Line consists of X, Y, Color and Text values separated by | (vertical bar) character. Note that DataPoints property is designed primarily for sample and demo code. It is very inefficient, and you should not use if to add data points from the code.

Random source

TRandomChartSource source generates random data in the given range and is intended mostly to use in demos. You can also use it as design-time replacement for you actual data source. This will let you see and change the look of your chart without having to run the application.

Each random source uses it's own independent random number generator to guarantee stability of it's values.

User-defined source

This source may be used if you already have your data in memory, but in the format different from the data items used in TAChart. Using user-defined source to access your data directly instead of first moving it all into a list source may (or may not) be beneficial for speed.

You can of course also use user-defined source to generate, filter or modify data.

Database source

TDbChartSource takes data directly from the database.

Efficiency notes

Primary data source API allows random access. Nevertheless, many sources, in particular random, database and calculated, may exhibit quadratic or worse behavior if actually accessed randomly. TAChart itself takes care to only use sequential access (although may it require several passes). Sources optimize sequential access by using internal state. User code should be careful not to reset this state during chart drawing from event handlers or custom series code.

Notable exception is list source, which is guaranteed to provide fast random access. It may be used to cache slow sources with the help of CopyForm procedure.

Coordinates and axises

TAChart uses three coordinate systems:

  • Axis coordinates (known in some other applications as object coordinates) -- this is the "raw" coordinate values obtained from the data. As the name implies, axis coordinates are interpreted in therms of specific axis -- the same coordinate value may have different meaning depending on the axis it is applied to.
  • Graph coordinates (aka world coordinates) are converted from the axis coordinates using axis transformation, such as logarithmic scale. Graph coordinates are common for all objects in the chart.
  • Image coordinates (aka screen coordinates) are converted from graph coordinates based on the chart viewport. This transformation is always linear and can be influenced by chart tools such as zooming and panning.

You can add or remove arbitrary number of axises by editing AxisList property. By default, chart have two axises: one horizontal and one vertical. They are accessible via BottomAxis and LeftAxis properties. Note that those properties are aliases to AxisList[0] and AxisList[1], so if you remove those default axises, accessing BottomAxis and LeftAxis will return nil.

Axis transformations

Axis transformations are grouped in TChartAxisTransformations component. It contains a list of transformations which are applied in the order given. (For example, performing scale before and after logarithm will yield different results).

For transformations to have an effect, you should:

  • Make sure Enabled property is true for all transformations.
  • Assign transformations component to Transformations property of at least one axis.
  • Assign AxisIndexX and/or AxisIndexY properties of the series to the appropriate axis index.

Note that by default, AxisIndexX and AxisIndexY have a special value of -1, which means "ignore axis transformations". Also note that if you add or remove axises, the indexes may change. You can rotate the series by assigning both AxisIndexX to vertical axis and AxisIndexY to the horizontal axis.

Linear and logarithmic transformation

Those are simple arithmetic transformations.

Auto-scaling transformation

To display several independently scaled series, assign them to two or more axises and apply TAutoScaleAxisTransform to each axis. See "axistransf" demo, page "Linear", checkbox "Auto scale".

By using MinValue and MaxValue properties you can control the in graph coordinates of the auto-scaled series. For example, by setting one transformation to a range from 0 to 1, and another to a range from 1 to 2, you will confine all the series using the first transformation to the upper half of the chart, and all the series using the second transformation to the lower half (assuming there are no unassigned series left).

User-defined transformation

You can create you own transformation either by inheriting from TAxisTransform, or, if you prefer "visual" programming, by using TUserDefinedAxisTransform. In either case there are two basic requirements:

  • AxisToGraph and GraphToAxis functions should be defined everywhere in data range and inverse of each other (for example, avoid now only dividing, but also multiplying by zero).
  • functions should be monotonic.

Tools

TODO

Legend

TODO

Marks

TODO

Drawers

TODO

Navigation

TODO