Difference between revisions of "TAChart documentation/ru"

From Lazarus wiki
Jump to navigationJump to search
Line 422: Line 422:
 
Каждый случайный источник использует свой собственный независимый генератор случайных чисел, чтобы гарантировать стабильность его значений.
 
Каждый случайный источник использует свой собственный независимый генератор случайных чисел, чтобы гарантировать стабильность его значений.
  
=== User-defined source ===
+
=== Предопределенный пользователем источник ===
  
This source may be used if you already have your data in memory, but in a format
+
Этот источник можно использовать, если у вас уже есть данные в памяти, но в формате
different from the data items used in TAChart.
+
отличается от элементов данных, используемых в TAChart.
With user-defined source you can access your data directly instead of first moving it all into a list source.
+
С помощью источника, определяемого пользователем, вы можете напрямую обращаться к своим данным, вместо того, чтобы сначала перемещать их все в список источника.
In some cases this may improve performance or reduce memory consumption.
+
В некоторых случаях это может улучшить производительность или снизить потребление памяти.
You can of course also generate, filter or modify data with the user-defined source.
+
Конечно, вы также можете генерировать, фильтровать или изменять данные с помощью пользовательского источника.
  
The number of data items in the source is determined by <code>PointsNumber</code> property.
+
Количество элементов данных в источнике определяется свойством <code>PointsNumber</code>.
Items themselves must be returned by the <code>OnGetChartDataItem</code> event handler.
+
Сами элементы должны быть возвращены обработчиком события <code>OnGetChartDataItem</code>.
You should call <code>Reset</code> method to notify the chart about changes in the data.
+
Вы должны вызвать метод <code>Reset</code>, чтобы уведомить диаграмму об изменениях данных.
(Other sources detect changes and perform notification automatically).
+
(Другие источники обнаруживают изменения и автоматически отправляют уведомление).
  
Note that if the <code>Sorted</code> property is set to true, it is the responsibility
+
Обратите внимание: если для свойства <code>Sorted</code> установлено значение <code>true</code>, это ответственность
of the event handler to provide actually sorted data.
+
обработчика событий для предоставления фактически отсортированных данных.
  
 
=== Database source ===
 
=== Database source ===

Revision as of 20:58, 24 January 2021

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

Обзор

TAChart - это пакет для рисования графиков, схем и других диаграмм. Он сопоставим по функциям, но не полностью совместим с Delphi'йским TeeChart. Одно существенное отличие состоит в том, что некоторые функции (например, источники данных и преобразования осей) реализуются через отдельные компоненты, а не через простые свойства диаграммы. Такая конструкция обеспечивает повышенную гибкость и возможность повторного использования кода, но за счет немного более сложного API.

Этот документ предоставляет краткий, но всесторонний обзор концепций, функций и компонентов TAChart. Пошаговое изучение см. в TAChart Tutorial: Getting started и других учебных пособиях.

В документации описан пакет TAChart, который можно найти в последней версии Lazarus для разработки. Некоторые функции могут быть недоступны в официальной версии Lazarus. Мы рекомендуем вам использовать эту последнюю версию документа, поскольку в ней исправлены и улучшены более старые описания в предыдущих версиях, а также тот факт, что в нее включены сведения о новейших функциях.

Тем не менее, вы можете посмотреть старую версию этого документа, чтобы увидеть состояние документации на момент выпуска Lazarus 1.0.

Серии

series hierarchy.png

Серии (графики, диаграммы) являются центральной частью TAChart. Их иерархия проиллюстрирована на рисунке. Серии, наследуемые от TCustomChartSeries, представляют данные, взятые из ChartSource графическим способом, таким как линии или столбцы; другие серии получают свои данные по-другому.

Диаграмма со сплошной линией

Это самый простой тип графика, представляющий «бесконечную» вертикальную или горизонтальную линию. Его можно использовать в качестве «центральной оси» в графиках функций или в качестве перетаскиваемой линии маркера.

Кроме того, установив Active = true, Pen.Style = psClear и UseBounds = true и соответствующий AxisIndexX, он становится «расширителем оси», гарантируя, что данное значение Position всегда будет включена в диапазон оси.

Основные виды диаграмм

Основные виды графиков используются наиболее часто и включают в себя line, bar и area серии. Все основные серии могут быть «сложены» с помощью источников со множеством значений. Также все базовые серии полностью поддерживают вращение и 3-D рисунок.

Line-диаграмма

TLineSeries можно использовать для рисования заданного набора точек, опционально помечая каждую точку данных символом и/или соединяя точки данных линией. Цвет ряда линий определяется свойством SeriesColor.

ColorEach позволяет управлять окраской отдельных точек данных и смежных сегментов линии (цвет точки данных предоставляется источником диаграммы):

  • ceNone - нет отдельной окраски, даже если цвета назначаются элементу данных диаграммы.
  • cePoint - раскрасить только символ точки данных, но не отрезок.
  • ceLineAfter - применить цвет точки данных к сегменту линии, следующему за точкой данных
  • ceLineBefore - применить цвет точки данных к сегменту перед точкой данных
  • cePointAndLineAfter, cePointAndLineBefore - как и раньше, но раскрашивает и символ точки данных.

Вы можете получить «пошаговый» вид, установив для свойства LineType значение ltStepXY или ltStepYX.

Используя источник со множеством значений, TLineSeries может обрабатывать несколько значений y для каждого значения x. Если для свойства Stacked установлено значение true, то отдельные значения y отображаются в виде ряда, то есть второе значение y добавляется к первому, а третье значение y ко второму значению и т.д. Обратите внимание, однако, что в отличие от серий bar или area, может быть неясно, что значения данных сгруппированы, и поэтому укладка в виде рядов обычно не рекомендуется в сериях line.

Fast lines

Некоторые графические пакеты включают в себя специальный график "fast line" для быстрого рисования серии линий из чрезвычайно больших наборов данных (более 10000 точек). TAChart, напротив, содержит оптимизированный быстрый путь внутри стандартного кода серии строк, который обеспечивает сопоставимую скорость рисования.

Серия линий будет нарисована очень быстро, если все следующее верно:

  • Нет отметок.
  • Нет указателей.
  • LineType не установлено в значение ltFromOrigin.

Некоторые операционные системы/наборы виджетов могут дополнительно требовать, чтобы свойствам были установлены следующие значения LinePen.Style=psSolid и LinePen.Width=1.

Дополнительного быстродействия можно добиться, если установить Source.Sorted=true.

Вы можете измерить скорость рисования линий на вашей платформе с помощью демо «line».

Point-диаграмма

TLineSeries можно нарисовать как «серию точек», показывающую только символы в позиции точек данных и скрывающую соединительные линии, установив для ShowPoints значение True и LineType для ltNone. Обратите внимание, что SeriesColor применяется только к соединительным линиям; чтобы указать цвет точек, измените Pointer.Brush.Color для заливки и/или Pointer.Pen.Color для цвета линии границы. Свойство Pointer также предоставляет доступ к фигурам (круг, рамка и т.д.) символов (Style).

Bar-диаграмма

TBarSeries представляет данные в виде набора полос, простирающихся от ZeroLevel до точек данных.

Вы можете контролировать ширину полосы с помощью свойства BarWidthPercent. Обратите внимание, что оно измеряется относительно соседних полос. Если значения X не равноудалены, полосы будут иметь различную ширину. Чтобы предотвратить это, установите BarWidthStyle=bwPercentMin.

Вы можете рисовать несколько полос бок о бок, используя свойство BarOffsetPercent.

Используйте несколько значений Y для создания ряда полос с накоплением (Stacked=true). Начиная с Lazarus 2.0, несколько значений Y также могут отображаться в расположении рядом (Stacked=false).

В дополнение к прямоугольным полосам данные могут быть представлены альтернативными формами: цилиндр, шестиугольная призма, пирамида или конус - см. свойство BarShape, которое поддерживает следующие значения: bsRectangular, bsCylindrical, bsHexPrism, bsPyramid, bsConical. Кроме того, событие OnCustomDrawBar позволяет рисовать столбцы любым заданным пользователем способом.

Area-диаграмма

TAreaSeries представляет данные в виде многоугольника, продолжающегося вниз от точек данных, либо до линии ZeroLevel, либо к бесконечности (если UseZeroLevel=false).

Вы можете получить «пошаговый» вид, задав свойство ConnectType.

Как и TBarSeries и TLineSeries, ряд областей может принимать несколько значений Y для одного и того же X из источника данных со множеством значений. Эти значения y отображаются в стопке, если для свойства Stacked установлено значение True (его значение по умолчанию). Используйте компонент ChartStyles, чтобы определить внешний вид отдельных слоев. (Обратите внимание, что в версиях Lazarus 1.8.x или более ранних ChartStyles не окрашивают последовательно перекрывающиеся слои).

Свойство Banded (доступно в Lazarus v2.0 +), если установлено в true, подавляет рисование самого низкого уровня стека. Таким образом, полоса значений данных может быть выделена: используйте источник диаграмм с двумя значениями Y - установите первое значение Y на минимум, а второе значение Y на максимальный уровень диапазона. В качестве альтернативы, ширина полосы может быть указана во втором значении Y, если оба свойства Banded и Stacked установлены в true.

Поддержку нескольких значений Y следует применять с осторожностью: при суммировании НЕположительных значений могут получаться графики, которые трудно понять, а ряд непакетированных областей (Stacked=false) может пострадать от того, что данные покрываются другими значениями Y. Кроме того, ZeroLevel следует включать только в самый низкий уровень стека, чтобы избежать необычных результатов.

Трехмерное представление серии может быть получено, если для Depth установлено положительное значение, например, 10 или 20. Обратите внимание, что алгоритм рисования очень прост и, скорее всего, даст неправильно отображение при пересечении кривых, или при отключенных свойствах укладки и объединения.

Диаграмма со множеством значений

Для графика со множеством значений требуется источник данных со множеством значений и использование дополнительных значений X и/или Y в качестве дополнительных параметров для рисования сложных фигур.


Bubble-диаграмма

TBubbleSeries представляет данные в виде окружностей переменного радиуса с центром в точках данных. Для этой серии требуется источник с YCount не менее 2, и в качестве радиуса пузырька используется первое дополнительное значение Y.

Свойство OverrideColor позволяет установить цвет внутренней части или края каждого пузырька в отдельности.

Диаграмма Box-and-whiskers

TBoxAndWhiskerSeries представляет данные в виде прямоугольников с центральной линией и двумя Т-образными формами, выступающими в обоих направлениях. Хотя в статистике ящик с усами (диаграмма размаха) должен основываться на конкретных квартилях данных, TAChart не применяет это, позволяя пользователям рисовать произвольные графики.

Иногда можно использовать серии блоков и усов, чтобы представить другие диаграммы другого значения, но схожего внешнего вида, такие как диаграммы Гантта.

Для этой серии требуется источник с YCount не менее 5, и используются значения Y следующим образом:

Index Usage
0 Нижний ус
1 Нижняя граница ящика
2 Центральная линия
3 Верхняя граница ящика
4 Верхний ус

Диаграмма Open-high-low-close

TOpenHighLowCloseSeries представляет данные в виде вертикальных линий с двумя галочками, как описано здесь.

Обычно требуется YCount не менее 4 и используются значения Y следующим образом:

Свойство По умолчанию Использование
YIndexLow 0 Нижняя точка линии
YIndexOpen 1 Положение галочки слева
YIndexClose 2 Положение галочки справа
YIndexHigh 3 Верхняя точка линии
Light bulb  Примечание: хотя предполагается, что значения Y упорядочены в порядке возрастания по приведенной выше таблице, ряды сами упорядочивания не сделают и будут отображать любые предоставленные данные.

Field-диаграмма

TFieldSeries отображает вектор в каждой точке данных. Вектор рисуется как отрезок с необязательной стрелкой. Линия центрируется по координатам X,Y, хранящимся в источнике диаграммы, ее направление задается дополнительными значениями, хранящимися в XList и YList источника диаграммы. Следовательно, для этого типа серии требуется источник с двумя значениями X и Y:

Поле элемента данных источника Использование
X X координата центра линии
Y Y координата центра линии
XList[0] X координата направления линии
YList[0] Y координата направления линии

Метод AddVector(x,y: Double; vectorx, vectory: Double; ALabel: String = ''; AColor: TColor = clTAColor) помогает правильно назначить все значения внутреннему списку источника.

Чтобы избежать наложения векторов, вызовите метод Normalize Vector(Length: Double),дабы нормализовать их длины так, чтобы самый длинный вектор имел указанную длину.

Параметры стрелки понимаются как проценты от длины вектора, то есть стрелка становится меньше для более коротких векторов.

Круговые диаграммы

Радиальные серии игнорируют преобразования осей. Вы можете увидеть примеры радиальных рядов в demo "radial".

Pie-диаграмма

TPieSeries рисует круговые диаграммы.

Для каждой точки данных круговая серия интерпретирует значение Y как относительный размер среза, а значение X как расстояние среза от центра круговой диаграммы (только если свойство Exploded имеет значение true).

Начиная с StartAngle, круговая диаграмма вращается против часовой стрелки по всему кругу.

Радиус круга можно установить вручную с помощью свойства FixedRadius или рассчитать автоматически, чтобы вся серия, включая все метки, точно соответствовала родительской диаграмме.

Кольцо можно нарисовать вместо кругового фрагмента, задав свойству InnerRadiusPercent значение больше 0, но меньше 100 - это определяет радиус внутреннего круга в процентах от общего радиуса.

Цвета кусочка определяются полем Color элементов данных или жестко закодированной палитрой. Контуры срезов отрисовываются с использованием свойства EdgePen.

Существует несколько опций для позиционирования метки, управляемых свойством MarkPositions:

  • pmpAround -- отметки рисуются вне круговой диаграммы на продолжении или радиус-векторе для каждого кусочка
  • pmpInside --отметки нарисованы внутри каждого кусочка
  • pmpLeftRight -- отметки рисуются непосредственно слева или справа от кусочка

MarkDistance определяет расстояние между начальной точкой метки и меткой. Начальная точка определяется MarkPositionCentered как периметр круговой диаграммы (false) или центр (true). MarkDistancePercent, если установлено значение true, интерпретирует Marks.Distance как процент от радиуса круговой диаграммы. В противном случае оно интерпретируется в единицах изображения.

Если RotateLabels имеет значение true, каждая метка дополнительно поворачивается, чтобы (если LabelFont.Orientation=0) она была параллельна радиус-вектору своего кусочка.

Если для значения Y элемента данных установлено значение NaN, он станет скрытым элементом. Если значение X установлено в NaN, элемент не рисуется, но место для него все еще зарезервировано. Это позволяет рисовать «частичные» круговые диаграммы.

Круговые диаграммы имеют ограниченную поддержку для трехмерного рисования. Свойство Depth определяет толщину круга. Orientation дополняет нормальный вид (poNormal) скошенным видом наклонной (poHorHorizontal) и вертикальной (poVertical ) круговой серии, последние две управляются свойством ViewAngle в градусах от 0 до 89. Поскольку TAChart не реализует алгоритм истинной скрытой линии/скрытой поверхности, в некоторых комбинациях могут быть некоторые изменения артефактов рисования параметров.

Polar-диаграмма

TPolarSeries представляет данные в виде точек в полярной системе координат.

Начало полярной системы координат определяется в координатах графа свойствами OriginX и OriginY.

Для каждой точки данных значение X интерпретируется как угол в радианах, а значение Y - как расстояние от центра.

TPolarSeries не поддерживает преобразования осей.

Некоторые дополнительные свойства:

  • CloseCircle: если имеет значение true, последняя точка связана с первой.
  • Filled: если имеет зачение true, то многоугольник точек серии заполняется с использованием текущего значения Brush. Если CloseCircle равно false, заливка отправляется в начало координат.
  • ShowPoints: если имеет значение true, то указатель серии рисуется в позиции каждой точки данных.

Диаграммы с пользовательской отрисовкой

Предоставляет события OnDraw и OnGetBounds, чтобы разрешить произвольную пользовательскую отрисовку на TChart. Обратите внимание, что использование TChart.Canvas напрямую крайне нежелательно и часто не будет работать должным образом.

Диаграммы функций

Диаграммы функций - это рекомендуемый способ рисования функциональных графиков, в отличие, например, от предварительного вычисления данных функций и использования line-диаграмм. Они обеспечивают независимый от масштаба контроль плавности и скорости рисования.

Вы можете увидеть примеры функциональных серий в демо "func".

Диаграммы функций

TFuncSeries представляет одномерную функцию, определенную событием OnCalculate. Функция рассчитывается для каждого свойства Step пикселя изображения, поэтому вы можете использовать его для увеличения «гладкости» или скорости рисования.

Свойство Extent можно использовать для установки экстентов x и y с целью вычисления полного экстента диаграммы. Однако во время рисования это свойство игнорируется, и функция будет отображаться в соответствии с текущим экстентом.

Свойство DomainExclusion позволяет исключить некоторые интервалы из функциональной области. TFuncSeries правильно рисует точки разрыва, установленные DomainExclusion. В настоящее время DomainExclusion можно установить только во время выполнения, вызвав процедуры AddRange или AddPoint. Интервалы, определенные DomainExclusion, по умолчанию закрыты, то есть содержат конечные точки; это означает, что функция не рассчитывается в конечных точках. Если исключение домена должно содержать конечные точки (при необходимости для функции y=sqrt(x)) вызовите AddRange с соответствующим элементом набора TIntervalOptions=(ioOpenStart,ioOpenEnd) в качестве необязательного третьего параметра.

Свойство DomainExclusion.Epsilon контролирует расстояние между конечной точкой и последней нарисованной точкой (конечно, в случае открытого интервала кривая начинается непосредственно в конечной точке). Epsilon можно настроить в тех редких случаях, когда значение по умолчанию 1E-6 не дает правильных результатов.

Диаграммы метаматических выражений

TExpressionSeries аналогичен TFuncSeries, но функция указана в виде строки математического выражения, например 'sin(1.23456*x)' ( свойство Expression). Диаграмма создает экземпляр FPExpressionParser для анализа строки и вычисления значений функции. Таким образом, функции могут быть нанесены на график во время разработки.

Свойство Params позволяет определять параметры для термина функции; в инспекторе объектов он открывает редактор коллекций, в котором каждый параметр может быть указан его именем (как используется в выражении) и его значением. Если, например, параметр f определен со значением 1.23456, то приведенное выше выражение также можно записать как 'sin(f*x)'.

Аналогично TFuncSeries, исключения доменов поддерживаются для определения областей, в которых функция не может быть рассчитана. Но в соответствии с математическими соглашениями TExpressionSeries требует в свойстве Domain задавать регион, в котором функция определена (дополнение к исключениям домена). Регион задается строкой, такой как 'x >= 0'. Если существует несколько условий, они должны быть разделены двоеточием, например 'x < -1; x > 1'. Двоеточие имеет функцию логического выражения ИЛИ. Интервал определяется как '-1 < x < 1'. Постоянные части условий также могут быть математическими выражениями - в следующем примере точка pi/2 исключается из вычисления значений функции: 'x <> pi/2'. Десятичные числа должны вводиться с точкой в ​​качестве десятичного разделителя, независимо от того, как он определен в системных настройках языка операционной системы.

Light bulb  Примечание: Параметры и домены должны быть определены до начала ввода выражения, в противном случае парсер сообщит об ошибке.

Диаграммы B-spline

TBSplineSeries рисует B-сплайн с заданным свойством Degree, используя Алгоритм Де Бора.

Сегменты сплайнов короче пикселей Step представлены прямыми линиями.

Диаграмма Cubic spline

TCubicSplineSeries рисует кривую данных как кубический сплайн, используя стандартный пакет FPC NumLib.

В Lazarus v2.0+ свойство SplineType позволяет выбирать между сплайнами natural и monotone Hermite, при этом последний избегает превышения интерполяции.

Функция сплайна рассчитывается для каждого Step пикселя изображения, поэтому вы можете использовать это свойство для увеличения «сглаживания» или скорости рисования.

Источник данных должен содержать не менее двух точек и строго увеличивать координаты X (старые версии Lazarus до версии 2.0 требуют, как минимум, 4 точки данных; для меньшего количества точек вместо сплайна рисуется многоугольник, с использованием свойства BadDataPen>, если установлена опция csoDrawFewPoints.)

Если значения X не упорядочены и установлена опция csoDrawUnorderedX, сплайн будет отрисован без учета проблемных точек с использованием BadDataPen.

Параметры csoExtrapolateLeft и csoExtrapolateRight позволяют задавать естественную экстраполяцию слева и справа соответственно.

Fit-диаграммы

TFitSeries выполняет подгонку методом наименьших квадратов, используя процедуры вычисления, содержащиеся в стандартном пакете Numlib из FPC. Основным соединительным элементом является TAFitLib, который является автономным и может применяться также без TAChart.

Функция подбора выбирается через свойство FitEquation:

  • fePolynomial: y = b0 + b1x + b2x2 + … + bnxn, где значение n контроллируется свойством ParamCount (ParamCount = n + 1).
  • feLinear: y = a + bx
  • feExp: y = a * ebx
  • fePower: y = a * xb
  • feCustom: y = b0X0(x) + b1X1(x) + b2X2(x) + … + bnXn(x) где значение n контроллируется свойством ParamCount (ParamCount = n + 1), и Xi(x), i = 0..n, являются «базовыми функциями», которые определяются методом SetFitBasisFunc(AIndex: TFitFuncIndex; AFitFunc: TFitFunc; AFitFuncName: String).
    • AIndex - индекс i базовой функции, 1..MaxInt.
    • AFitFuncName - текстовое представление функции, используемой для легенды по умолчанию.
    • AFitFunc - адрес базовой функции Xi(x), которая имеет сигнатуру function(x: ArbFloat; Param: Integer): ArbFloat с ArbFloat, являющимся общим типом данных с плавающей точкой в FPC Numlib (unit typ). Некоторые базовые функции легко доступны в модуле TAFitLib:
function FitBaseFunc_Const(x: ArbFloat; Param: Integer): ArbFloat;   // константа
function FitBaseFunc_Linear(x: ArbFloat; Param: Integer): ArbFloat;  // линейный член (x)
function FitBaseFunc_Square(x: ArbFloat; Param: Integer): ArbFloat;  // квадратный член (x^2)
function FitBaseFunc_Cube(x: ArbFloat; Param: Integer): ArbFloat;    // кубический член (x^3)
function FitBaseFunc_Poly(x: ArbFloat; Param: Integer): ArbFloat;    // power term (x^Param)
function FitBaseFunc_Sin(x: ArbFloat; Param: Integer): ArbFloat;     // sin(x*Param) 
function FitBaseFunc_Cos(x: ArbFloat; Param: Integer): ArbFloat;     // cos(x*Param)

По умолчанию параметры b0, b1, ..., a, b варьируются в процессе подбора так, что среднее значение квадратичного отклонения между данными и подобранными кривыми было сведено к минимуму. Однако также возможно поддерживать один или несколько параметров подгонки постоянными, например, чтобы заставить подобранную прямую линию проходить через начало координат. Для этого значения постоянных параметров должны быть указаны в ';' или '|' для разграничения списка строковых значений свойства FixedParams. Порядок значений должен соответствовать порядку подгоночных параметров. Параметры переменных можно оставить пустыми или заменить нечисловой строкой.

Пример: FixedParams='var;2' (или короче: ';2') означает, что первый подходящий параметр является переменной, но второй параметр остается постоянным со значением 2; если имеется более 2 параметров, остальные также считаются переменными.

Диапазон подгонки обычно определяется экстентом диаграммы, но может быть установлен вручную через свойство FitRange. Функция подгонки рисуется по всей оси, если только DrawFitRangeOnly=true.

Когда подгонка завершена, ErrCode диаграммы устанавливается так, чтобы показать, был ли расчет успешным или нет:

  • fitOK: успешно
  • fitDimError: расчет был прерван, потому что размеры массивов данных (x, y, полоса ошибок y) не совпадают.
  • fitMoreParamsThanValues: расчет не удался, потому что есть больше подгоночных параметров, чем значений данных.
  • fitNoFitParams: расчет прерван, потому что параметры подгонки не указаны. Это может произойти случайно, если все параметры подгонки будут исправлены в свойстве FixedParams.
  • fitSingular: матрица дизайна задачи подгонки оказывается (почти) единственной.
  • fitNoBaseFunction: для случая FitEquation=feCustom указано недостаточно базовых функций подгонки.

Метод ErrorMsg создаст текст для сообщения об ошибке из текущего ErrCode.

Событие OnFitComplete вызывается после того, как найдено уравнение подгонки, но до начала рисования. Это хорошее место для запроса результатов процедуры подбора:

  • Param[AIndex] является наиболее подходящим значением для параметра с указанным индексом, AIndex = 0..ParamCount-1.
  • ParamError[AIndex] сообщает неопределенность ("standard error" (стандартная ошибка) в статистическом выражении) соответствующего параметра подгонки.
  • Процедура GetConfidenceLimits(AIndex: Integer; out ALower, AUpper: Double) возвращает диапазон между ALower и AUpper, в пределах которого ожидается наилучшее соответствие того, что параметр будет найден с вероятностью, указанной в ConfidenceLevel (по умолчанию: 0.95, т.е. 95%).
  • Param_tValue[AIndex] возвращает значение t-статистики для соответствующего параметра подгонки. Это соотношение стоимости, деленное на стандартную ошибку. Для точного параметра значение t должно быть намного больше 1.
  • Param_pValue[AIndex] - это вероятность того, что любое значение t, столь же высокое, как Param_tValue, будет случайно получено для данных степеней свободы. Чтобы «доверять» подобранному значению с уверенностью, заданной ConfidenceLevel, значение p должно быть меньше, чем 1 - ConfidenceLevel, по умолчанию 0,05.
  • FitStatistics сообщает о других статистических параметрах, полезных для проверки достоверности подобранной модели или для дальнейших статистических расчетов. Эти данные доступны как свойства или функции этого класса:
    • N (integer): количество точек данных, используемых для подгонки. Обратите внимание, что это может быть меньше точек данных, предоставленных источником диаграммы, поскольку он может содержать значения NaN, которые пропускаются.
    • M (integer): количество подгоночных параметров. Обычно это значение ParamCount, но если определенные параметры вынуждены быть постоянными (FixedParams), их количество вычитается.
    • DOF (integer): "degrees of freedom" (cтепени свободы) - это разница N - M, важный параметр в статистическом анализе результатов подбора.
    • SST: "total sum of squares" (общая сумма квадратов) - это сумма квадратов члена (y[i] - ymean)/dy[i] по всем точкам данных. Здесь y[i] - это значение y точки данных с индексом i, dy[i] размера ее полосы ошибок (стандартное отклонение) - или 1, если недоступно, а ymean - это среднее значение y[i]/dy[i]. Количество определяет общее изменение точек данных вокруг их среднего значения.
    • SSE: "error sum of squares" (сумма ошибок квадратов) - изменение точек данных вокруг подогнаной кривой, т.е. сумма ((y[i] - ycalc(x[i])/dy[i])^2); здесь ycalc(x[i]) - вычисленное значение подгоночной кривой в точке x[i].
    • SSR: "regression sum of squares" (сумма квадратов регрессии) - изменение только подогнанной кривой, то есть сумма ((ycalc(x[i]) - ymean)/dy[i])^2.
    • xBar: среднее значение координат x всех используемых точек данных.
    • SSx: изменение координат x точек данных, то есть сумма (x[i] - xbar)^2.
    • VarCovar[i, j: Integer]: Double: является элементом матрицы дисперсии-ковариации для параметров подгонки при данных индексах.
    • R2: "коэффициент детерминации". Это - соотношение SSR/SSE, и описывает, насколько сильно разброс данных объясняется подобранной кривой. Значение 1 для идеальной подгонки и 0 для абсолютной без соглашения.
    • AdjR2: был введен для компенсации эффекта, который обычно увеличивается R2, добавляя все больше и больше подходящих параметров.
    • Chi2: другое слово для SSE. По сути, это статистическая величина, которая минимизируется во время процедуры подбора. Данное значение является минимальным найденным значением.
    • ReducedChi2: это Chi2 (или: SSE), которое нормализовано по степеням свободы, то есть изменению данных вокруг подобранной кривой на степень свободы. Должно быть "маленьким" для хорошей подгонки.
    • ResidualStdError: общая стандартная ошибка подгонки. Должно быть "маленьким".
    • pValue: (дробная) вероятность того, что остаточный разброс точек данных вокруг подобранной кривой является случайным. Должно быть высоким, на практике несколько десятков, хотя иногда значения до 0,001 по-прежнему принимаются. Если в подбор не включены никакие полосы ошибок, иногда p оказывается равным 0 или 1 - такие значения следует игнорировать.
  • Процедуры GetLowerConfidenceInterval(const Ax: Double; out AY: Double), GetUpperConfidenceInterval, GetLowerPredictionInterval и GetUpperPredictionInterval могут быть подключены к событию OnCalculate TFuncSeries, чтобы построить границы нижнего и верхнего доверительных интервалов и интервалов прогнозирования вокруг подобранной кривой. Эти пределы определяют области вокруг подобранной кривой, в пределах которых можно ожидать общую подгоночную кривую (доверительный интервал) или отдельные точки данных (интервал прогнозирования) на основе вероятности, заданной ConfidenceLevel.
  • Примечание: все эти статистические данные предполагают, что остаточные ошибки соответствуют нормальному распределению и что столбцы ошибок были оценены надлежащим образом.

EquationText возвращает интерфейс IEquationText, который позволяет построить строку, представляющую уравнение соответствия. Вы можете переопределить имена переменных x и y, числовой формат и, наконец, получить строку из функции Get. Обратите внимание, что преобразование из IEquationText в String определено, поэтому обычно нет необходимости явно вызывать Get.

Legend.Format-свойство fit series поддерживает дополнительный аргумент формата ('%2:s'), указывающий на текст уравнения по умолчанию.

После изменения параметров TFitSeries уравнение будет пересчитано на следующем отрисовке диаграммы. Чтобы немедленно пересчитать его, вызовите процедуру ExecFit. Используйте свойство State, чтобы проверить правильность текущего уравнения.

Диаграмма цветовых карт

TColorMapSeries представляет собой двумерную функцию, определенную событием OnCalculate как поле пикселей, цвет которого зависит от значения функции.

Диаграмма отображается в виде набора прямоугольников размером StepX с помощью StepY пикселей. Функция вызывается один раз для каждого прямоугольника.

Цветовые значения определяются одной из встроенных палитр (свойство BuiltinPalette = cmpHot, cmpCold, cmpRainbow, cmpMonochrome). Диапазон значений, сопоставленных с цветами палитры, должен быть указан в BuiltinPaletteMax и BuiltinPaletteMin, иначе результаты не будут предсказуемыми.

Альтернативно, внешний ChartSource может быть назначен свойству ColorSource, которое должно быть отсортировано. Каждая точка данных источника диаграммы интерпретируется как имеющая значение X, соответствующая значению Color. Если фактическое значение попадает между уровнями цвета, оно может быть либо линейно интерполировано (если Interpolate равно true), либо округлено до ближайшего уровня.

В случае, когда Legend.Multiplicity=lmPoint, диаграмма цветовых карт будет отображать уровни цвета в Легенде.

Диаграмма цветовых карт выражения

аналогична диаграмме цветовых карт с тем отличием, что двумерная функция определяется не событием, а математическим выражением, таким как x^2+y^2, как и в TExpressionSeries, но теперь с двумя переменными x и y. Переменные могут быть переименованы с помощью свойств VariableNameX и VariableNameY. Аналогично TExpressionSeries также можно вводить параметры (свойство Params). Домены, однако, не поддерживаются, функция должна быть определена во всем видимом диапазоне x/y.

Источники

chartsource hierarchy.png

Данные могут попасть в график из разных источников. Они реализованы как набор компонентов, производных от TCustomChartSource.

Чтобы назначить источник диаграмме, вы можете задать свойство Source. Если свойство оставлено неназначенным, диаграмма будет использовать свой собственный встроенный список источников. Такие методы, как AddXY, делегируются текущему источнику диаграммы. Обратите внимание, что список источника является единственным редактируемым источником, поэтому после назначения, например, случайного источника диаграммы для серии, вызов AddXY вызовет исключение.

Каждый элемент данных имеет следующие поля: X, Y, XList, YList, Color, Text.

Отсортированные источники

Если известно, что значения X источника возрастают, возможны некоторые дополнительные оптимизации, такие как бинарный поиск. Таким образом, все источники имеют свойство IsSorted, которое помогает определить это.

В Lazarus 2.1+ TListChartSource можно отсортировать по нескольким критериям:

  • SortBy = sbX, sbY, sbText, sbColor, sbCustom: сортировка по значению X или Y, тексту, цвету или определенным пользователем способом соответственно. В последнем случае должен быть предоставлен обработчик для события OnCompare.
  • SortIndex: индекс значений X или Y, используемый для сортировки.
  • SortDir = sdAscending, sdDescending: сортировка в порядке возрастания или убывания.

Когда источник сортируется по чему-либо, кроме x, это влияет только на порядок отрисовки связанных рядов, и возможно, что на диаграмме ничего не изменится. Визуальный эффект заметен для

  • TPieSeries потому что порядок точек данных определяет порядок срезов по кругу
  • TBubbleSeries когда пузырьки перекрываются. Используйте сочетание SortBy=sbY, SortIndex=1 и SortDir=sdDescending, чтобы избежать покрытия пузырьков, потому что сначала появляются большие пузырьки, а маленькие - последними.
  • все серии унаследованы от TBasicPointSeries, когда XCount связанного источника диаграммы равен 0: в этом случае значение X источника игнорируется и заменяется индексом точки данных. Поскольку индекс точек данных изменяется при сортировке, точки данных будут автоматически переставлены в отсортированном порядке - см. Пример sort_demo в папке demo.

Источники с множеством значений

Источники могут содержать несколько значений Y для каждого значения X. Эти значения хранятся в поле YList исходного элемента данных. Количество значений Y определяется свойством YCount. Обратите внимание, что первое значение Y в любом случае сохраняется в поле Y, поэтому YCount=3 означает, что значения хранятся в Y, YList[0] и YList[1].

Дополнительные значения могут использоваться в различных сериях - например, столбчатые диаграммы с накоплением или пузырьковые диаграммы.

Более того, также возможно сохранять несколько значений X для одной и той же точки данных. Это требуется для TFieldSeries. Эти дополнительные значения X хранятся в XList исходного элемента данных. Как и в случае со значениями Y, общее количество значений X задается свойством XCount, которое содержит "обычное" значение X плюс длину массива XList.

Пропуск исходных элементов

Можно указать TAChart пропустить рисование некоторых исходных элементов, не удаляя их из источника. Это может быть полезно как для оптимизации, так и для пользовательского интерфейса.

Чтобы пропустить элемент, присвойте NaN либо значению X, либо одному из значений Y. Точный эффект пропуска зависит от серии, но обычно установка X в NaN означает пропуск всего элемента, в то время как установка Y или некоторого элемента YList означает пропуск только этого значения Y, при этом все еще отрисовывая другие.

Также обратите внимание, что если вы установите NaN только для одной координаты, другая все равно будет участвовать в вычислении экстента.

В случае составных серий неясно, как следует обрабатывать отсутствующее значение, когда к нему добавляются следующие уровни. В Lazarus v2.1 + есть свойство StackedNaN, которое можно выбрать как

  • snReplaceByZero - отсутствующее значение считается нулевым; это как Excel обрабатывает этот случай.
  • snDoNotDraw - пропускает всю точку данных со всеми уровнями стека.

Вы можете увидеть примеры пропуска элементов в демо "nan".

Планки погрешностей

TLineSeries, TBSplineSeries, TCubicSplineSeries и TFitSeries могут отображать планки погрешностей(error bars) в каждой точке данных. Размер планок погрешностей в направлениях x и y определяется параметрами в свойствах XErrorBarData и YErrorBarData соответственно:

  • Kind: TChartErrorBarKind: определяет, как интерпретируются следующие данные
    • ebkNone: игнорировать - планки погрешностей отображаться не будут
    • ebkConst: все точки данных имеют одинаковую планку погрешности, заданную ValuePlus и ValueMinus.
    • ebkPercent: значения ValuePlus и ValueMinus понимаются как процент от значений данных.
    • ebkChartSource: каждая точка данных может иметь отдельную планку погрешности. Длина планок погрешностей сохраняется в XList или YList источника многозначной диаграммы. Индекс среди всех значений x и y задается IndexPlus и IndexMinus для положительной и отрицательной планки погрешности соответственно.
  • ValuePlus и ValueMinus: длина столбцов положительных и отрицательных погрешностей соответственно. В зависимости от настройки Kind предполагается, что значение является постоянным для всех точек данных (Kind = ebkConst, единицы оси) или в процентах от значения точки данных (Kind = ebkPercent). Оба значения должны быть положительными числами, за исключением ValueMinus = -1, который указывает, что отрицательная планка погрешности должна быть равна положительной планке погрешности.
  • IndexPlus и IndexMinus используются, когда Kind равен ebkChartSource и указывают индекс x или y в многозначном chartsource, из которого можно получить длину планки погрешности для отдельных точек данных. Предположим, что источник диаграммы содержит два значения x (XCount = 2) и XErrorBarData.ValuePlus равно 1, тогда второе значение x (хранящееся в XList[0]) используется для положительной длины планки погрешности. Если IndexMinus равно -1, то предполагается, что длина отрицательной планки погрешности равна длине положительной планки погрешности без необходимости предоставления явного значения в источнике диаграммы.
Light bulb  Примечание: Использование нескольких значений y для других целей, кроме отдельных планок погрешностей, не рекомендуется в этом контексте, поскольку настоящая реализация может отображать планки погрешности только для значения y с индексом 0.

Каждый тип серии, поддерживающий планки погрешностей, имеет дополнительные свойства XErrorBars и YErrorBars, которые определяют, как планки погрешностей будут отображаться:

  • Visible можно использовать для отключения планок погрешностей, даже если их размер указан в источнике диаграммы.
  • Width - это длина перекладины, нарисованной в конце планки погрешностей. Значение по умолчанию -1 означает, что его длина будет равна соответствующему размеру Pointer серии.
  • Pen определяет параметр пера, используемый для рисования планок погрешностей. Обычно для Pen.Color устанавливается цвет серии.

Список источников

TListChartSource - это базовый источник диаграммы, хранящий данные диаграммы внутри себя. Таким образом, вы можете использовать функции Add и Delete для изменения исходных данных.

Свойство Item возвращает указатель непосредственно на базовое хранилище, поэтому вы можете напрямую изменять поля элемента. Однако это не приведет к автоматическому обновлению диаграммы, а также сделает недействительным некоторое внутреннее состояние списка источника.

Рекомендуется:

  • Чтобы изменить отдельный элемент, используйте процедуры Set{Color|Text|XValue|YValue|YList}.
  • Чтобы изменить многие элементы в чувствительном ко времени коде, вызовите BeginUpdate, затем измените элементы напрямую, потом вызовите EndUpdate.

Источник также имеет свойство DataPoints, позволяющее задавать данные во время разработки. Это свойство - TStringList, где каждая строка представляет точку данных. Строка состоит из значений X, Y, необязательных значений YList, Color и Text, разделенных символом |(вертикальная черта). Обратите внимание, что свойство DataPoints предназначено в первую очередь для создания образцов кода и демок. Оно очень неэффективно, и вы не должны использовать его для добавления точек данных из кода.

Вы можете управлять сортировкой значений X, задав свойство Sorted. Обратите внимание, когда для параметра Sorted установлено значение true, список источника сортирует данные и сохраняет их отсортированными после вставки новых точек. Если вставленные точки не отсортированы, это может привести к квадратичному времени выполнения. Вы должны либо установить для Sorted значение true только после вставки, либо предварительно отсортировать данные, чтобы избежать этого.

Случайный источник

Источник TRandomChartSource генерирует случайные данные в заданном диапазоне и предназначен в основном для использования в демках. Вы также можете использовать его как замену времени разработки для вашего фактического источника данных. Это позволит вам видеть и изменять внешний вид вашей диаграммы без необходимости запускать приложение.

Каждый случайный источник использует свой собственный независимый генератор случайных чисел, чтобы гарантировать стабильность его значений.

Предопределенный пользователем источник

Этот источник можно использовать, если у вас уже есть данные в памяти, но в формате отличается от элементов данных, используемых в TAChart. С помощью источника, определяемого пользователем, вы можете напрямую обращаться к своим данным, вместо того, чтобы сначала перемещать их все в список источника. В некоторых случаях это может улучшить производительность или снизить потребление памяти. Конечно, вы также можете генерировать, фильтровать или изменять данные с помощью пользовательского источника.

Количество элементов данных в источнике определяется свойством PointsNumber. Сами элементы должны быть возвращены обработчиком события OnGetChartDataItem. Вы должны вызвать метод Reset, чтобы уведомить диаграмму об изменениях данных. (Другие источники обнаруживают изменения и автоматически отправляют уведомление).

Обратите внимание: если для свойства Sorted установлено значение true, это ответственность обработчика событий для предоставления фактически отсортированных данных.

Database source

TDbChartSource takes data directly from a database. It is contained in a separate unit to avoid introducing a db-aware component dependency into every project using TAChart.

The following properties contain database field names for data item fields:

Property Access method
FieldX AsFloat (or AsDateTime, if option dcsoDateTimeX is set)
FieldY AsFloat (or AsDateTime, if option dcsoDateTimeY is set)
FieldColor AsInteger
FieldText AsString

If FieldX property is empty, RecNo is used instead. NULL values in coordinate fields are translated into NaNs.

To get multi-valued source, set FieldY property to a comma-separated list of field names. Note that YCount will be set automatically -- trying to set it by hand will raise an exception.

Calculated source

TCalculatedChartSource is the source used for manipulating data taken from the Origin source. This source performs transformations in the following order:

  • Y reordering -- Y values of multi-valued source can be duplicated, removed or exchanged according to ReorderYList property, which is a comma-separated list of original Y value indexes. Step skipped if ReorderYList is empty.
  • Accumulation -- replaces each item's Y values by a function of the neighboring values.
  • Percentage -- replace each Y value by the percentage of total of all Y values for that item. Useful for drawing "stacked percentage" bar and area charts. Step skipped if the Percentage property is false.

Accumulation is controlled by several properties:

AccumulationRange controls number of items to accumulate, counting the current item, so AccumulationRange = 1 disables accumulation. AccumulationRange = 0 is interpreted as "infinite" range, i.e. request to accumulate over all the available data. This is mostly useful in conjunction with camSum method to produce cumulative sums.

Note that the actual number of items may be lower for the points near the beginning or end of the source.

AccumulationDirection:

  • cadBackward -- use previous values from the source,
  • cadForward -- use next values from the source,
  • cadCenter -- use both previous and next values for a total number of up to 2 * AccumulationRange - 1.

AccumulationMethod:

  • camNone -- skip accumulation step,
  • camSum -- sum of the last AccumulationRange items,
  • camAverage -- average the last AccumulationRange items,
  • camDerivative -- finite differences derivative, calculated using the last AccumulationRange items. Note that the calculation method assumes equidistant X values, and may loose accuracy if the X distance varies substantially.
  • camSmoothDerivative -- smoothed finite differences derivative, more robust against random measurement errors in the data.

Interval source

TIntervalChartSource can supply arbitrarily many points in a given interval, controlled by various properties of the source. This source is the default built-in source for axis marks. If you want to set the same axis interval parameters for several axes, you can assign a single TIntervalChartSource component the Marks.Source of each of those axes.

Date-time interval source

TDateTimeIntervalChartSource is similar to the TIntervalChartSource, but provides marks formatted as date/time values. This source automatically selects appropriate calendar interval (such as week or hour) depending on the axis scale.

Note that X values of provided data items are TDateTime values, and Label values contain formatted date-time strings. If you want to use TDateTimeIntervalChartSource as the source of axis marks, you should probably set Marks.Format or Marks.Style properties to make use of provided labels.

If the DateTimeFormat property is set, it is used to format all labels. Formatting is performed with standard SysUtils.FormatDateTime function. If DateTimeFormat is empty, format is chosen automatically based on scale.

TDateTimeIntervalChartSource is defined in the TAIntervalSources unit.

Source optimization 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 it may 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.

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

Also note that the pointer returned by GetItem function may point to the internal buffer which will be overwritten by the next call to GetItem. Again the list source does not have this limitation.

Coordinates and axes

TAChart uses four 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 terms 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.
  • Device coordinates are usually equal to screen coordinates, but may be adjusted to the drawing back-end to accommodate different physical resolutions (DPI values). See, for example, printer drawer.

You can add or remove an arbitrary number of axes by editing AxisList property. By default, chart have two axes: 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 axes, accessing BottomAxis and LeftAxis will return nil.

Visually, axis consists of the axis line (drawn by AxisPen), grid lines (drawn by GridPen), ticks, marks and arrow.

Each axis is drawn inside its own rectangle, determined by the size of mark labels and ticks. By assigning several axes the same positive Group number, you can have them share the same rectangular area. Grouped axes can be used to achieve a "panes" look, when several series are drawn on different portions of the same graph.

Axes with the same alignment, but different groups, are stacked alongside each other. You can use the Margin property to control spacing between such axes.

Axis transformations

Axis transformations are grouped in the 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 axes, 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 axes and apply TAutoScaleAxisTransform to each axis. See "axistransf" demo, page "Linear", checkbox "Auto scale".

By using the 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).

Cumulative normal distribution transformation

Use TCumulNormDistrAxisTransform to set cumulative normal distribution as an axis transformation. This may be useful in statistical charting.

Note that this transformation result is in range from 0 to 1. It is recommended to restrict the axis range accordingly.

See the "Normal distribution" page of the "axistransf" demo for an example.

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.

Date and time axes

Using date/time values for axis marks is a common requirement. The correct way to do this depends on the exact nature of your date/time data:

  • If the data is actual TDateTime values, use it as an X coordinate in points, assign TDateTimeIntervalChartSource to the Marks.Source of the corresponding axis, and change Marks.Style to smsLabel. TDateTimeIntervalChartSource provides automatic labeling depending on the scale in wide range -- from centuries to milliseconds.
  • If the data is in physical units, but outside TDateTime values range, such as astronomical or micro-electronics timings, use it as a normal X coordinate with custom Marks.Format.
  • If the data is in calendar units, such as months and years, which is common for financial data, you have several options:
    • If date units are "equidistant" when interpreted as numbers (for example, simple year numbers), assign the same data source to both series and axis marks, then use custom Marks.Format, Axis.OnMarkToText event or Text field of the data items to format dates per your requirements.
    • If date units are not "equidistant" (for example, numbers in YYYYMM format or even date strings), use surrogate X coordinate (usually, simply a point index) instead and display dates using methods described above.
    • Convert coordinates to TDateTime values beforehand, then use TDateTimeIntervalChartSource as described above.

Axis ranges

Axis range is measured in axis units and determines the extent of series attached to this axis. Normally an axis range is equal to the union of all series extents, but may be overridden with the Range property.

Axis marks are displayed inside the axis marks range, which is determined as the intersection of:

  • Logical extent (converted to axis coordinates)
  • Combined extent of all data series of this axis, if Marks.AtDataOnly = true
  • Marks.Range property.

Axis intervals

Axis marks are located along the axis at equal intervals chosen by the chart. The choice of intervals can be influenced via Intervals property. This property has a few subproperties, which are applied in the following order:

  • Options property contains a set of flags controlling usage of other parameters. If the flag is not in the set, the corresponding parameter is ignored.
  • NiceSteps is a string containing a sequence of "step multipliers" -- floating point values in the range from 0 to 1, excluding 0. If this property is applied, the axis step will be a power of ten multiplied by one of the provided values. If several multipliers can be used, the leftmost one will be chosen. Multipliers are separated by the vertical bar (|) character.
  • If NiceSteps is ignored or TAChart fails to find appropriate step, the axis range will be divided into equal intervals without regard to the number of decimal digits in the representation of mark values. In this case, it is recommended to reduce the number of visible digits in Marks.Format.
  • MinLength and MaxLength properties set the limits of interval length in image units (usually pixels).
  • Count property is the desired number of axis marks. Among all mark steps passing the previous tests, TChart chooses the one which gives the number of marks nearest to the Count. If Count property is ignored, or there are several steps with equal number of marks, the longest step is chosen.
  • Tolerance property sets the maximum distance in image units by which the mark may be moved in order to reduce the length of its decimal representation. This helps to avoid a lot of meaningless digits in mark labels when previous steps have for some reason failed to generate "nice" marks. Note that this stage ignores all previous restrictions, so large Tolerance values may result in significant distortions. Setting Tolerance = 1 is often sufficient.

Note that if you set chart source manually, Intervals property may apply only partially or not apply at all. For example, list source is unable to guarantee maximum interval length, since it has only a finite number of points. See also interval chart source.

Axis position

By default, the axis is aligned to the side of the chart corresponding to the Alignment property. You can position an axis differently by setting the Position and PositionUnits properties.

The following values of the PositionUnits property are accepted:

  • cuPercent -- percentage of the clipping rectangle.
  • cuGraph -- absolute position in graph coordinates.
  • cuPixels -- position in screen units relative to the default coordinate.

Note 1: If the axis position is changed from default (Position = 0 and PositionUnits = cuPercent), it will be excluded from the margins calculation, so it will appear to overlap the series.

Note 2: The Alignment affects not only the position of the axis itself, but also of the corresponding labels. So, if two axes have both Position = 50 and PositionUnits = cuPercent, but one has Alignment = calLeft and another Alignment = calRight, they will diaplay a common axis line with labels on different sides.

See "Position" page of the "axis" demo for an example.

Axis titles

If the property TextFormat is switched to tfHTML then HTML entities and tags can be embedded for special formatting of axis titles, such as subscripts/superscripts or greek characters. See HTML for details.

Axis LabelSize

Since Lazarus v1.4 the chart axes have a new property LabelSize which - if different from 0 - overrides the automatic calculation of the space needed by the axis marks. The LabelSize, approximately, defines the pixels between axis line and axis title, independently of the size of the axis labels. This feature can be used to align the axis lines of several charts that are stacked above each other or placed side by side.

See the "axisalign" demo and Graphical explanation for an example.

Light bulb  Примечание: If the (non-zero) LabelSize value is too small then the axis labels may reach into the axis title or may even be truncated at the chart border.

Extents and margins

Экстенты

Chart extent is a rectangle in graph coordinates.

There are several extents defined by TChart:

  • Full extent -- usually determined automatically as the area encompassing all the data from series and axis ranges. Is returned by the GetFullExtent function.
  • Fixed extent -- determined by the TChart.Extent property. May override full extent calculation partially or fully.
  • LogicalExtent -- the extent requested by the user to be seen on the chart image. Writing to this property is the official way to change the chart extent by external code. For example, LogicalExtent := GetFullExtent is (almost) equivalent to calling the ZoomFull procedure.
  • CurrentExtent -- the extent actually displayed to the user. May differ from the LogicalExtent due to the need to reserve space for series marks, inner chart margins etc.

The value of the minimum extent cannot be greater than the value of the maximum extent. If an attempt is made to set such values an exception will be generated. To prevent exceptions, the procedure .Extent.FixTo(aBounds: TDoubleRect) can be used to set logical extents. The values in TDoubleRect are ordered in the following way: [xmin, ymin, xmax, ymax].

In order to invert the extents, the property Inverted' of the (left, bottom, etc) axis shall be set to True.

Important: Setting logical extents will work as required only if all the Margins of the chart are set to 0 (default value is 4) and Series.Marks.AutoMargins to all series in the chart is set to False (default is True). Otherwise, the requested extent will be enlarged to include also the chart's Margins as well as the series' Marks.

Extent limits

By default, TAChart allows arbitrary extents. However, for both usability and speed reasons it may be desirable to limit extent size. For example, setting the lower bound of the size may disallow extreme zoom levels, while setting the upper bound may force the user to only see a part of the very long series at any given time.

The extent can be limited with the ExtentSizeLimit property. Sub-properties MinX, MinY, UseMinX and UseMinY control the lower bounds of the extent, while sub-properties MaxX, MaxY, UseMaxX and UseMaxY control the upper bounds.

Extent limits are expressed in graph units.

Setting Proportional = true will enforce the current extent to have the shape of the plot area. This may be useful for cartographic or some math plots which require the same scale on both axes.

Linked extents

Using the TChartExtentLink component, you can ensure that the logical extents of several charts enumerated by the LinkedCharts property always stay the same. In Laz 2.1+ the component was extended to provide an additional property AlignSides which adjusts the LabelSize properties of aligned charts such that the corresponding sides of the plot area are aligned, too.

This is useful for simulating multi-pane chart layouts. See "panes" demo for an example.

Margins

Margin is a distance reserved around the edges of rectangular region. Margins are measured in image units (usually pixels). The chart itself has two kinds of margins:

  • Internal (Margins property) -- applied after axis drawing. Are also influenced by series marks and series themselves.
  • External (MarginsExternal property) -- applied before axis drawing. Are also influenced by axis marks and arrows.

Other chart elements, such as legend, title, footer and labels, have margins, too.

Optimization notes

Calculation of CurrentExtent and actual margins is a non-trivial iterative process (see TChart.PrepareAxis code for details). Although usually fast, in complex cases it can require multiple passes through chart sources.

Graphical explanation

TAChart Margins.png

Tools

Chart tools define how the chart reacts to various user actions, primarily mouse movements and clicks. You can see examples of tools usage in the "tools" or "barseriestools" demos.

Tools are grouped in a TChartToolset component, which should be assigned to the chart's Toolset property. The same toolset can be used in several charts.

If Toolset is unassigned, for compatibility reasons a built-in toolset consisting of zoom drag and pan drag tools is used; these builtin tools can be turned off individually by setting the chart properties AllowZoom and/or AllowPanning to false, respectively (the latter is available only after Lazarus v2.2+).

In each user action, tools in the toolset are processed in order, and for each tool:

  • If Enabled=false, the tool is ignored.
  • If Shift is not equal to the current shift state, the tool is ignored.
  • Tool is requested to process the action.
  • If the tool signals that the action is handled, processing is stopped, otherwise it continues to the next tool. This way, tools with the same Shift value may be differentiated based on special activation conditions. For example, some drag tools may be configured to not activate on a simple click, leaving the click event available for other actions.
  • Finally, if no suitable tool is found, the chart's event handler is called. Note that this means that chart event handlers will only work with all tools disabled. Generally it is recommended to use tools for interactivity, chart events are left mostly for compatibility.

In your application you can create, for example, a toolbar with each button enabling the corresponding tool in the toolset and disabling all others. Alternatively, by assigning different Shift values, you can enable several tools at once.

Some tools publish the EscapeCancels property which, if set to true, cancels the tool operation if the user pressed the ESC key.

Keyboard handling in tools

Besides mouse events, some tools may react on key presses -- for example, crosshair tool with Shift = [ssCtrl] will display crosshairs when the CTRL key is pressed, without mouse buttons. Unfortunately, the chart must be focused to receive keyboard events. This means that after the user interacted with other controls on the same form, the chart stops reacting on keyboard-only events.

To prevent this, you can either call the Chart.SetFocus method, or set Chart.AutoFocus = true, which will make a chart grab the focus when the mouse moves over it.

Drawing mode

Some tools, such as zoom drag or crosshair, display moving shapes over the chart with the mouse movement.

There are two ways to display those shapes: either simply draw them over the chart, fully redrawing the chart upon each mouse movement, or use pmXor pen mode to draw and erase the shape directly from the MouseMove event handler. The former method allows to use arbitrary pen color and style, but the latter is much more efficient. Additionally, some widgetsets ignore all drawing outside the Paint event, in such a case the latter method will not work at all.

The display method is controlled by the DrawingMode property with the following values:

  • tdmXor -- use XOR method;
  • tdmNormal -- use full chart redraw;
  • tdmDefault -- use XOR method on widgetsets where it is known to work (Windows and Gtk) and full redraw on others.

Extent tools

Extent tools modify the chart's logical extent.

Zooming tools can be animated by setting AnimationSteps to a value greater then 1 and specifying an appropriate AnimationInterval in milliseconds.

In the zooming tools, adapt the LimitToExtent property to restrict zooming to the chart's full extent on all or some directions. The same property is available also in the panning tools for the corresponding purpose when the viewport is panned.

Zoom drag tool

TZoomDragTool allows the user to zoom in by drawing a rectangle with the mouse. The rectangle then becomes the new logical extent.

Restoration of the zooming to the full extent can be achieved by several actions, controlled by the RestoreExtentOn property:

  • zreDragTopLeft, zreDragTopRight, zreDragBottomLeft, zreDragBottomRight -- dragging in the specified direction,
  • zreClick -- clicking without dragging,
  • zreDifferentDrag -- dragging in a direction different from the one used to zoom in.

By default, RestoreExtentOn = [zreClick, zreDragTopLeft, zreDragTopRight, zreDragBottomLeft] which means that the full extent is restored either by clicking or by drawing a rectangle in any direction except from top-left to bottom-right.

To get a behavior compatible with earlier versions of Delphi's TeeChart, specify RestoreExtentOn = [zreDragTopLeft, zreDragTopRight, zreDragBottomLeft].

To get a behavior compatible with newer versions of TeeChart, specify RestoreExtentOn = [zreDifferentDrag].

The enumerated property RatioLimit ((zrlNone, zrlProportional, zrlFixedX, zrlFixedY) lets you restrict zooming to one of the coordinates, or makes the zooming process keep the original proportions.

Zoom click tool

TZoomClickTool allows the user to zoom in or out by clicking on the chart with the mouse. ZoomFactor is the scaling multiplier applied by the tool where factors below 1 represent "zoom out", and factors above represent "zoom in".

ZoomRatio allows to create a non-proportional zooming effect by specifiying the ratio of X to Y scale. In other words, the X zoom factor is given by the property ZoomFactor, the Y zoom factor is the product ZoomFactor*ZoomRatio.

  • In particular, to zoom only horizontally, the Y zoom factor must be 1, i.e. ZoomFactor*ZoomRatio = 1 or ZoomRatio = 1/ZoomFactor. For example, when your ZoomFactor for the X axis is 1.1, then ZoomRatio must be 1/1.1 = 0.909.
  • Similarly, to zoom only vertically, the X factor must be 1, i.e. ZoomFactor = 1, and you can use ZoomRatio alone to determine the Y zoom factor.
  • And finally, in the normal case, when X and Y should zoom by the same ratio, keep ZoomRatio at 1 and determine the overall zoom factor by the ZoomFactor alone.

If FixedPoint is true, the location of the mouse click is used as a fixed point for zooming, otherwise the chart image center is used instead.

Zoom mouse-wheel tool

TZoomMouseWheelTool allows the user to zoom in and out with the mouse wheel. Its properties are identical to the zoom click tool.

The chart is scaled by ZoomFactor when the user scrolls the mouse wheel up, and by 1/ZoomFactor when the user scrolls the mouse wheel down.

Pan drag tool

TPanDragTool allows the user to move the logical extent by dragging the mouse in the directions indicated by the Directions property.

Use the MinDragRadius property to distinguish dragging from clicking.

Pan click tool

TPanClickTool allows the user to move the logical extent by clicking inside a range of Margins pixels from the corresponding border of the chart image.

The panning offset is determined by the distance from the edge of the chart (the nearer to the edge, the greater). Setting Interval in milliseconds will allow to continue panning with the given interval until the mouse button is up.

Pan mouse wheel tool

TPanMouseWheelTool allows the user to move the logical extent by scrolling the mouse wheel.

The extent is moved in WheelUpDirection when the wheel is scrolled up and in the opposite direction when the wheel is scrolled down.

The movement speed is controlled by Step property.

Data tools

Data tools are linked to specific data series via the AffectedSeries property, which is a string of comma-separated series indexes. Note that indexes may change if you add or remove series. Having AffectedSeries empty means that the tools operate on every series in the chart.

When a data tool is activated, it determines the nearest point of the affected series which is located inside of the GrabRadius (in pixels).

Using the set Targets: TNearestPointTargets it can be controlled which part of a complex series must be hit:

  • nptPoint: The tool must hit the data point at (x, y).
  • nptXList: If the series' source has several x values the tool must hit any of the values in the XList.
  • nptYList: If the series' source has several y values the tool must hit any of the values in the YList.
  • nptCustom: Meant for special effects depending on the series. In case of a bar series, for example, the function GetNearestPoint is overridden to accept hits inside series bars if this option is set.

All options are on by default. For further control, most series have the same set of Targets, named ToolTargets. An option must be included in the targets of both tool and series to be active. This way tools can be shared with series reacting differently on each option. See "barseriestools" demo as an example.

For large series, the efficiency can be improved by using a sorted source, a small GrabRadius and a DistanceMode<>cdmOnlyY .

Data point drag tool

TDataPointDragTool allows the user to change data values by dragging the data point. Requires the series' data source to be a list source.

You can use the OnDrag and OnDragStart events to limit drag direction or grab area.

See "dragdrop" demo for an example.

Data point click tool

TDataPointClickTool allows you to assign an OnPointClick event handler, which will be called when the user clicks on the data point.

Data point hint tool

TDataPointHintTool displays a hint when the user moves the mouse over the data point. The hint is either equal to the point label (if UseDefaultHintText=true) or determined by calling the OnHint event handler.

By default, this tool displays a separate hint window, independent from the application hint. To use a single hint window per application, you may set UseApplicationHint=true.

Note that the application-level hint does not work in combination with modifier keys and mouse buttons, so the hint is displayed only if no buttons are pressed (i.e. Shift property must be empty when UseApplicationHint=true).

Data point crosshair tool

TDataPointCrosshairTool displays a cross-hair centered on the data point. It replaces the "reticule" found in older versions of TAChart.

Data point distance tool

TDataPointDistanceTool allows to measure and display a distance between two points on the chart.

Chart element tools

Axis click tool

This tool fires an event OnClick when the user clicks on an axis or its title. The event has the clicked axis and a set of TAxisHitTest elements as parameters:

  • ahtTitle: click on the axis title
  • ahtLine: click on the axis line (allowed tolerance defined by the tool's GrabRadius or the axis' TickLength and InnerTickLength whichever is greater).
  • ahtLabels: click into the label area of the axis. It is not distinguished whether a label is clicked or the empty space between the labels.
  • ahtAxisStart: the click on the line or label area occured in the first quarter of the axis length
  • ahtAxisCenter: the click on the line or label area occured in the center part (two quarters) of the axis length
  • ahtAxisEnd: the click on the line or label area occured in the last quarter of the axis length.

Title/footer click tool

An OnClick event is created when the user clicks on the title or footer of a chart. The event has the clicked title/footer as parameter.

Legend click tool

Generates an OnClick event when a click on the chart's legend has occured. The event has the legend as a parameter.

User defined tool

To add your own tool, either inherit from TUserDefinedTool or use it directly, assigning one or more On{After,Before}{KeyDown,KeyUp,MouseDown,MouseMove,MouseUp,MouseWheelDown,MouseWheelUp} event handlers.

Call the Handled method of the tool to indicate that no further processing of the event should be done.

Decorative elements

Title and footer

Chart title and footer are multi-line texts appearing above and below the chart correspondingly. They support various rotations and alignments.

HTML

If the Lazarus version is 1.8 or newer then html entities and some html tags can be embedded into the title/footer texts for a variety of additional formatting options. This feature is turned on by switching the property TextFormat to tfHTML. In addition to header/footer texts it is available also for axis captions, axis marks, series marks and legend texts/series titles.

  • Non-standard charcters can be embedded using the corresponding html entities, i.e. as codes beginning with an ampersand (&), a standardized appreviation of the character name (or its hex or decimal unicode value), and ending with a semicolon (;). A list of all html entities can be found at http://unicode.e-workers.de/entities.php.
    Example: The text sin 2&alpha; = 2 sin &alpha; cos &alpha; is displayed as "sin 2α = 2 sin α cos α"
  • <sub>...</sub> displays the enclosed text as subscript.
    Example: H<sub>2</sub>O is shown in the chart as "H2O"
  • <sup>...</sup> displays the enclosed text as superscript.
    Example: cm<sup>2</sup> is shown in the chart as "cm2"
  • <b>...</b> displays the enclosed text with bold type face.
    Likewise, the tags <i>...</i>, <u>...</u>, <s>...;</s> can be used to format portions of the text as italic, underlined, and strike-out
    Example: Plot of <b>x</b> <i>vs.</i> <b>y</b> is shown in the chart as "Plot of x vs. y"
  • The <font>...</font> tags can be used to modify the font of the enclosed text:
    • Text color: The embedded This text is <font color="red">RED</font> displays the enclosed text in red color, i.e. like "This text is RED". Specify the color by the most typical color names or by the html hex color codes of rgb values, in the format #rrggbb or #rgb where r, g, b are hex bytes for the red, green and blue color components. The three-digit codes #rgb are equivalent to the six-digit codes #rrggbb where both digits of the same component are equal.
    • The font name can be specified by the name attribute.
    • The font size is controlled by the size attribute. It can take the values "x-small", "small", "medium", "large", "x-large", "xx-large" for font sizes 7, 10, 12, 14, 18, 24pt, respectively. Alternatively, the point or pixel size can be specified directly if "pt" or "px", respectively, is appended.
    • Example: This code adds a two-line footer in which the 2nd line is in blue, 8-pt, underlined Times New Roman:
  Chart.Foot.Text.Clear;
  Chart.Foot.Text.Add('Reference:');
  Chart.Font.Text.Add('<font name="Times New Roman" size="8pt" color="blue"><u>www.freepascal.org/</u></font>');
Warning-icon.png

Предупреждение: It is not recommended to switch font name and font size within the same line because TAChart drawers cannot exactly align the base line of characters in different fonts and font sizes

The demo application in folder demo/html of the Lazarus installation heavily makes use of embedded HTML codes.

Легенда

Chart legend is a table with each item containing an icon and a text line. Grid lines may be controlled by GridHorizontal and GridVertical properties.

Legend supports various alignments and can be located inside the chart or on the sidebar. Legend can be displayed in two or more columns by setting ColumnCount property. Setting ColumnCount to a very large value effectively creates "horizontal" legend.

Legend items are generated based on chart series which have both Active and ShowInLegend set to true. Depending on Legend.Multiplicity series can produce a single item or one item per point.

Legend items can be grouped together under sub-headers. Sub-headers are taken from GroupNames property, and each series can use Legend.GroupIndex property to indicate its group.

Legend items are sorted as following:

  • By group index, items without group (GroupIndex=-1) going first to avoid confusion with the last group.
  • By Order property, items without explicit order (Order=-1) going last.
  • By creation order of series.
  • For multiple items per series, by generation order (for standard series it is the order of points).

Sorted items are then added to the legend table in either by rows or by columns depending on the ItemFillOrder property.

Legend item text

The text of a legend item is generated by the corresponding series based on the Legend.Format property. This property is used as a first argument for the SysUtils.Format function, with the second argument containing following data items:

  • For per-series multiplicity:
    • 0: Series Title
    • 1: Series Index
  • For per-point multiplicity:

If the property TextFormat is switched to tfHTML then HTML entities and tags can be embedded for special formatting of legend texts. See HTML for details.

User-defined legend items

Arbitrary legend items can be generated by overriding OnCreate and OnDraw events of series Legend property.

Note that user-defined item count is controlled solely by UserItemsCount property and does not depend on Multiplicity. Also note that GroupIndex and Order properties are actually per-item, so you can totally override entire legend from a single (perhaps fictive) series.

Arrows

Arrowheads can be drawn at the end of axis lines, constant lines, mark links, etc. It is controlled by TChartAxis.Arrow, TConstantLine.Arrow, TChartMarks.Arrow correspondingly.

Arrowhead shape is determined by Width, Length and BaseLength properties, for example:

  • Thin wedge: BaseLength = 0
  • Triangle: BaseLength = Length
  • Rhombus: BaseLength = 2 * Length
  • Inverted Triangle: BaseLength > 0, Length = 0

This image shows these arrows created for Length=10 and Width=5.TAChart Arrows.png

Transparency

Transparency property of the series represents a level of transparency from 0 (fully opaque) to 255 (fully transparent -- i.e. invisible).

Compatibility note: FPVectorial and TFPCanvas drawers currently do not support transparency because of limitations of the underlying libraries. Printer and WMF drawers can not support transparency in principle.

Optimization note: Transparency support in the LCL is rudimentary, so current TCanvas drawer implementation may be slow with many transparent series and large charts. To improve efficiency, it is recommended to use as few different transparency levels as possible and to not interleave series with different transparencies. Alternatively, use BGRABitmap as back-end, since it has faster transparency implementation.

ChartStyles

TChartStyles can be employed to control the appearance of the "layers" of area, line, and bar series with multiple y values. They can also be used to colorize the regions between axis ticks in a banded way.

Marks

Marks annotate certain points of the chart. These points can be defined by a series or an axis. Typically, mark consists of some graphical element (such as an axis tick) and a text label. However, either of these elements can be omitted.

You can see examples in the "labels" demo.

Mark labels

The label text can be enclosed in a box, controlled by LabelBrush and Frame properties. The text itself is created based on the data source items, with the help of Format property. This property is used as a first argument for the SysUtils.Format function, with the second argument containing following data items:

  • 0: Y
  • 1: Y as a percentage of the Y total
  • 2: Text
  • 3: Y total
  • 4: X

Where "Y total" is the sum of all Y values for this source. Note that not all sources supply all the items above.

Some pre-defined formats can be set via the Style property.

If the source is mutli-valued, YIndex property determines which Y value is used. If YIndex = -1, a separate label is displayed for each Y value, which is useful for stacked series.

The text is rendered using the LabelFont. Note in particular that TAChart supports arbitrary font Orientation.

Mark labels are usually included in margins calculation to guarantee that all labels fit in the viewport. This behavior can be turned off by setting AutoMargins property to false.

Multi-line marks

If the mark text contains LineEnding character sequence, it is split into several lines. Lines of different length are aligned according to Alignment property.

HTML codes in marks

If the property TextFormat is switched to tfHTML then HTML entities and tags can be embedded for special formatting of marks. See HTML for details.

Mark positions and attachment

The mark position relative to the marked point is determined by the marks owner (series or axis).

Common mark properties include Distance, which measures the distance from the origin point to the attachment point in image units, and Attachment, which controls whether the attachment point is considered to be in the center or at the edge of the label box.

Additionally, basic chart series have a property MarkPositions specifying the direction of labels' offsets relative to series data points as following:

  • lmpOutside -- away from the center of the data points cloud; for TBarSeries and TAreaSeries it has a special meaning: away from the ZeroLevel defined for this series.
  • lmpPositive -- positive direction of series' Y axis
  • lmpNegative -- negative direction of series' Y axis
  • lmpInside -- towards the center of the data points cloud; for TBarSeries and TAreaSeries: towards the ZeroLevel

In Lazarus 2.0+, TBarSeries and TAreaSeries have an additional property MarkPositionCentered which allows to center the marks origins between data points and zero level. In order to place marks exactly at the center of the bars of a BarSeries or at the center of the drop line of an AreaSeries, the following properties must be changed additionally: Marks.Distance = 0, and Marks.Attachment = maCenter.

Rotation of marks

Marks can be rotated by any angle in a resolution of 1/10 degree by modifying the Orientation of their font; it is specified by the 10-fold value in degrees, i.e. the value 450 refers to an angle of 45°. 0° means horizontal orientation, the angle increases in the counter-clockwise direction.

The rotation normally occurs with respect to the center of the label. Axis and series marks additionally have a property RotationCenter to shift the center of rotation to an edge of the text:

  • raCenter -- default setting, i.e. rotation occurs around the text center
  • raLeft -- the rotation center is at the left edge of the label.
  • raRight -- the rotation center is at the right edge of the text.
  • raEdge -- ignored in case of series marks (will be replaced by raLeft). But in case of axis marks the center of rotation is automatically moved to the text start or end in order to avoid rotation of the label into the chart.

Drawers

For low-level drawing routines, TAChart uses special set of classes implementing IChartDrawer interface. This allows such features as printing charts and exporting them to SVG format.

These classes are called drawing back-ends or drawers for short.

TCanvas drawer

TCanvasDrawer is the default drawer used to display chart on TCanvas. This includes screen and various raster image formats. The image produced by this drawer is used as a reference when developing and debugging other back-ends.

TFPCanvas drawer

TFPCanvasDrawer is similar to TCanvas drawer, but based on TFPCanvas (which is a TCanvas analog implemented in the FCL instead of the LCL).

See the "nogui" demo for an example.

Although TFPCanvas and, correspondingly, TFPCanvasDrawer have a restricted implementation of some TAChart features, their important advantage is the possibility they offer of compiling an application with the nogui widgetset. This is particularly useful for Web applications, which can then generate raster chart images without any further graphic dependency, or a need to install X/Gtk/Qt on the server.

SVG drawer

TSVGDrawer produces text stream with the image of the chart in SVG format. Similarly to TFPCanvas drawer, it is independent of LCL and can be used in Web applications to generate vector charts in nogui widgetset.

See "save" demo for an example.

For this drawer, image unit is an SVG canvas unit instead of a pixel.

Note that due to the nature of SVG, there is no way to measure font dimensions, so they are approximated crudely. This may result in problems like label text not fitting in the mark rectangle, especially in browsers like Firefox that do not support textLength attribute.

OpenGL drawer

TOpenGLDrawer draws chart on the current OpenGL context. It is suitable to be used in games and other OpenGL-only applications.

OpenGL drawer expects, but does not set by itself, an orthogonal projection. See "opengl" demo for an example.

Note that, like in OpenGL itself, TOpenGLDrawer font support is extremely limited.

Printer drawer

TPrinterDrawer draws chart on the printer canvas. It does not flush the page.

Although printer canvas is a descendant of TCanvas, and so printing can be done using the default drawer, TPrinterDrawer does proper re-scaling of image coordinates according to printer vs screen DPI.

You can use this drawer to export chart to PDF format using one of the available PDF writer products.

See "print" demo for an example.

Note that this drawer is located in a separate TAChartPrint package.

AggPas drawer

TAggPasDrawer draws chart using AggPas library.

AggPas offers high-speed antialiased drawing and is included in Lazarus sources. Unfortunately, the library is currently not maintained and there are some limitations in TAChart support.

Note that this drawer is located in a separate TAChartAggPas package.

BGRABitmap drawer

TBGRADrawer draws chart using BGRABitmap library.

BGRABitmap is recently created and actively developed graphics library, offering, in particular, anti-aliasing and rich selection of gradients.

Currently BGRABitmap supports all TAChart features, but is somewhat slower then other drawing methods.

Note that this drawer is located in a separate TAChartBGRA package, which depends on external bgrabitmappack package.

FPVectorial drawer

TFPVectorialDrawer draws chart using fpvectorial library. FPVectorial offers exporting to various vector formats, including SVG, PDF, CorelDraw and even instructions for metal cutting machines.

It currently has some limitations in TAChart support, but is actively developed.

Note that this drawer is located in a separate TAChartFPVectorial package, which depends on fpvectorialpkg package.

WMF drawer

TWindowsMetafileDrawer draws chart into a Windows Metafile.

It uses WinAPI directly, and so will only work on Windows. WMF support has been added to fpvectorial which provides a cross-platform alternative to this package.

Navigation

Chart navigation consists of two parts: moving logical extent around without changing zoom factor, and visualizing the logical extent's position and size relative to the full extent.

Moving extent (but not visualizing it) is possible by using panning tools.

You can see examples in the "navigation" demo.

Scroll bars

TChartNavScrollBar is a TCustomScrollBar descendant with additional Chart property referencing the chart. TChartNavScrollBar synchronizes its position with chart extent in both directions. If the logical extent is equal to or larger than the full extent, navigation scroll bar does nothing.

Setting AutoPageSize = true lets TChartNavScrollBar to pick page size proportional to the logical extent.

Note that Min and Max properties are not changed automatically. It is recommended to set Min = 0 and Max to some fairly large integer value to avoid rounding issues.

Also note that TChartNavScrollBar does not automatically align or attach itself to a chart, so it can be arbitrarily positioned on the form.

Navigation panel

TChartNavPanel component displays logical and full extent of an assigned chart as differently colored rectangles, allowing user to drag the logical extent rectangle if AllowDragNavigation = true.

If MiniMap = true, the panel additionally displays the chart series.

TChartNavPanel can have arbitrary size, but it is recommended to keep height to width proportion the same as in the assigned chart. Setting Proportional = true will enforce the same proportions even if the above condition is not met, at the cost of some wasted space on the panel.

Additional components

Legend panel

TChartLegendPanel provides a legend which can be placed anywhere on the form. The legend is taken from the chart with is assigned to the property Chart of the LegendPanel. The chart’s own legend should be turned off.

Chart listbox

TChartListbox is a versatile legend replacement which displays an icon and the series title for each series of the chart attached to the property Chart of the listbox. But in addition to the standard legend, it also has checkboxes for each series. Unchecking a checkbox hides the associated series, checking it shows the series again. The listbox listens to changes in the associated chart and updates automatically.

The property CheckStyle can be used to switch the listbox from a checkbox-like behavior (cbsCheckbox, an arbitrary combination of series can be checked) to a radiobutton-like behavior (cbsRadioButton, only a single series can be checked). Depending on CheckStyle either a radiobutton or a checkbox state icon is displayed for each series.

Events are fired when the checkbox/radiobutton or the series title are clicked (OnCheckboxClick or OnItemClick, respectively), or when the series icon is double-clicked (OnSeriesIconDblClick). The latter event is thought to open a dialog for changing the series color, pointer style, series title etc.

The listbox items are collected in a different way than for a conventional legend. The populating process ignores the series property Legend.Visible which controls whether the series is to be shown in the legend or not. Instead of it, there is an event OnAddSeries in which the var parameter Skip should be set to true if the series passed as another argument should be excluded from the listbox. Every series is listed only with a single item, i.e. the series’ Multiplicity is ignored as well. Moveover, grouping of items is not supported either.

Chart image list

TChartImageList collects the icons displayed for each series in the legend and can be used for imagelist-aware controls, such as treeviews, listviews or menus to show icons for each series. The icons are extracted from the chart which is assigned to the Chart property of the component. The image list is notified of changes in the chart and updates its images automatically whenever something changes with a series. The event OnPopulate is fired if the image list is rebuilt.

Note that this kind of image list is volatile, i.e. its images are not stored in the form's lfm file. Nevertheless, at runtime, it can be used as a standard image list with other images. Just add these non-series images before assigning the chart to the image list. Use the property FirstSeriesIndex to get the image index of the first series contained in the image list. Alternatively, find the image index of a specific series by calling the function ImageIndexOfSeries(series).

In Laz 2.1+ the TChartImageList can be used also at designtime. It stores only those images not assigned to a series.

Chart combobox

The TChartCombobox is an extended combobox. Depending on the property Mode (ccmPointerStyle, ccmPenStyle, ccmPenWidth, ccmBrushStyle) it is populated with names and corresponding icons for pointer style, pen style, pen width or brush style selection. Therefore, it is useful for gui elements in which the user can modify the appearance of series and other chart objects.

The combobox is not linked to a particular chart. Use the OnChange event to transfer the modified property to the series.

TeeChart compatibility

TeeChart is a standard set of charting components used by Delphi. Although TAChart does not have a goal to to be compatible with TeeChart, basic feature set and names are very similar, so simple examples may work in both libraries equivalently.

More complex features -- in particular, multi-value series, series sources, multiple axes -- are implemented differently from TeeChart. This is by design and will not change. See comparison page for more detailed info.

To assist porting of TeeChart code to the TAChart, you can use TAChartTeeChart unit. It contains class helpers adding or emulating some TeeChart-specific properties and methods.

Note that it is NOT recommended to use this unit for normal development, since the emulation is only intended to simulate the subset of features implemented in TeeChart, and may not be reliable when used in conjunction with the full set of TAChart features.

Technical details

Drawing order

Chart drawing consists of three stages:

  1. Preparation: At this stage, various internal data structures are initialized.
  2. Measurement: At this stage, the chart calculates the sizes of all elements, and optimizes them for best presentation. Optimization may require several iterations, so the measurement stage is often the heaviest one both in terms of implementation complexity and running time.
  3. Drawing: At this stage, the actual chart image is displayed.

There also exists an ordering among various chart elements:

  1. Background (using TChart.Color property).
  2. Back-wall (using TChart.BackColor property).
  3. Series and axes according to ZPosition property. For each series and axis, graphic elements are drawn before marks. Note that this protects marks against hiding by the axis/series they belong to, but not by other axes/series.
  4. Legend.
  5. Tools.

Note that ZPosition works for both 2-D and 3-D charts, so you can overlay series and axes in arbitrary order.

Coding style

Historically FPC, Lazarus and LCL sources contain a mix of coding styles, with the general rule being "be consistent with the surrounding code".

However, since TAChart has many fewer contributors, it is feasible to adopt and maintain a consistent style across all TAChart code. If you want to contribute to TAChart, please format your code accordingly. Also remember that any coding style may be violated in certain situations when the reason is good enough, but please explain that reason if you do so.

Spaces

  • No double spaces anywhere.
  • Spaces after: operations, comma, semicolon, assignment, closing parenthesis in expressions (not in function calls).
  • Spaces before: operations, assignment, opening parenthesis in expressions (not in function calls).

Lines

  • No double empty lines anywhere.
  • Empty lines between procedures, classes, unit sections. Rare empty lines inside procedure bodies to separate logical blocks.
  • Line length below 80 characters, with rare exceptions.
  • Single statement per line, except if ... then {exit|break|continue} and some rare cases of mass assignment.
  • If the line is too long, line breaks may be inserted after at the following symbols, in order of decreasing priority: keywords, opening parenthesis, opening square bracket, semicolon, comma, operation.

Indentation and blocks

  • Always two spaces, both for blocks and continuation lines.
  • begin on the same line as the control statement, end aligned with the control statement.
  • end always alone on the line. In particular, write end else begin on two lines.
  • Put then or do on a separate line to separate a complex condition from the statement body:
 while
   long condition or
   another long condition
 do
   loop body
  • Use begin/end only when necessary (i. e. not for single statements).

Comments

  • Put a license header at the beginning of every file.
  • Single-line comments everywhere except the license header and auto-generated class headers in implementation section.
  • Use only full sentences in comments, starting with a capital letter and ending with a full stop.
  • Comments should be placed before commented code, except in rare cases where a comment fits at the end of the same line.
  • Comments should only include information not evident from the source. In particular, choose meaningful procedure and argument names in preference to adding comments describing their usage.

Names

  • Constants use ALL_CAPS_WITH_UNDERSCORE, everything else use CamelCase.
  • Local variables start with a lower-case letter, everything else starts with an upper-case letter, even when FPC library disagrees (e.g. ``Math``, not ``math``).
  • Class fields start with 'F', arguments start with 'A', types start with 'T', TAChart units start with 'TA'.

Variable declarations

  • Initialize when possible.
  • Local variables after nested procedures unless used by them.
  • Group variables by type.

Classes and methods

  • Methods are grouped per-class, methods inside class are sorted alphabetically both in interface and implementation. There should be zero Code Observer warnings about 'Unsorted members'.
  • If there is a need to group methods by topic, use visibility specifiers as topic separators. In particular, group overridden methods separately from the newly introduced ones.
  • Use strict private/strict protected visibility where possible.

Hints and warnings

  • Code should compile with zero hints and warnings.
  • Silence any "unused parameter" warning with the ``Unused`` procedure from the TAChartUtils unit, or use the {%H-} Lazarus IDE directive.

Control flow

  • Use exit or raise to abort method execution in case of a violated pre-condition.
  • Use enumerators where possible.
  • Use with carefully, and only where its use significantly saves code size and in the minimal possible range.
  • Limit all procedures to 50-60 lines, and use nested procedures liberally.