TAChart documentation/ru: what changed

Revision 2 to 3. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## Обзор
2	2
3	3		[[TAChart/ru\|TAChart]] - это пакет для рисования графиков, схем и других диаграмм. Он [[Comparing TAChart with Delphi's TeeChart Standard\|сопоставим по функциям]], но не полностью [[TAChart documentation\|совместим]] с Delphi'йским TeeChart. Одно существенное отличие состоит в том, что некоторые функции (например, источники данных и преобразования осей) реализуются через отдельные компоненты, а не через простые свойства диаграммы. Такая конструкция обеспечивает повышенную гибкость и возможность повторного использования кода, но за счет немного более сложного API.
4	4
5	5		Этот документ предоставляет краткий, но всесторонний обзор концепций, функций и компонентов TAChart. Пошаговое изучение см. в [[TAChart Tutorial: Getting started]] и [[TAChart\|других учебных пособиях]].
6	6
7	7		В документации описан пакет TAChart, который можно найти в последней версии Lazarus для разработки. Некоторые функции могут быть недоступны в официальной версии Lazarus. Мы рекомендуем вам использовать эту последнюю версию документа, поскольку в ней исправлены и улучшены более старые описания в предыдущих версиях, а также тот факт, что в нее включены сведения о новейших функциях.
8	8
9	9		Тем не менее, вы можете посмотреть \[ старую версию\] этого документа, чтобы увидеть состояние документации на момент выпуска Lazarus 1.0.
10	10
11	11		## Серии
12	12
13	13		![](/wiki-images/5/56/Series_hierarchy.png)Серии (графики, диаграммы) являются центральной частью TAChart. Их иерархия проиллюстрирована на рисунке. Серии, наследуемые от TCustomChartSeries, представляют данные, взятые из [[TAChart documentation/ru\|ChartSource]] графическим способом, таким как линии или столбцы; другие серии получают свои данные по-другому.
14	14
15	15		### Диаграмма со сплошной линией
16	16
17	17		Это самый простой тип графика, представляющий «бесконечную» вертикальную или горизонтальную линию. Его можно использовать в качестве «центральной оси» в графиках функций или в качестве перетаскиваемой линии маркера.
18	18
19	19		Кроме того, установив `Active` = true, `Pen.Style = psClear` и `UseBounds = true` и соответствующий `AxisIndexX`, он становится «расширителем оси», гарантируя, что данное значение `Position` всегда будет включена в диапазон оси.
20	20
21	21		### Основные виды диаграмм
22	22
23	23		Основные виды графиков используются наиболее часто и включают в себя [[TAChart documentation/ru\|line]], [[TAChart documentation/ru\|bar]] и [[TAChart documentation/ru\|area]] серии. Все основные серии могут быть «сложены» с помощью [[TAChart documentation/ru\|источников со множеством значений]]. Также все базовые серии полностью поддерживают вращение и 3-D рисунок.
24	24
25	25		#### Line-диаграмма
26	26
27	27		`TLineSeries` можно использовать для рисования заданного набора точек, опционально помечая каждую точку данных символом и/или соединяя точки данных линией. Цвет ряда линий определяется свойством `SeriesColor`.
28	28
29	29		`ColorEach` позволяет управлять окраской отдельных точек данных и смежных сегментов линии (цвет точки данных предоставляется источником диаграммы):
30	30
31	31		- `ceNone` - нет отдельной окраски, даже если цвета назначаются элементу данных диаграммы.
32	32		- `cePoint` - раскрасить только символ точки данных, но не отрезок.
33	33		- `ceLineAfter` - применить цвет точки данных к сегменту линии, следующему за точкой данных
34	34		- `ceLineBefore` - применить цвет точки данных к сегменту перед точкой данных
35	35		- `cePointAndLineAfter, cePointAndLineBefore` - как и раньше, но раскрашивает и символ точки данных.
36	36
37	37		Вы можете получить «пошаговый» вид, установив для свойства `LineType` значение `ltStepXY` или `ltStepYX`.
38	38
39	39		Используя [[TAChart documentation/ru\|источник со множеством значений]], `TLineSeries` может обрабатывать несколько значений y для каждого значения x. Если для свойства `Stacked` установлено значение `true`, то отдельные значения y отображаются в виде ряда, то есть второе значение y добавляется к первому, а третье значение y ко второму значению и т.д. Обратите внимание, однако, что в отличие от серий bar или area, может быть неясно, что значения данных сгруппированы, и поэтому укладка в виде рядов обычно не рекомендуется в сериях line.
40	40
41	41		##### Fast lines
42	42
43	43		Некоторые графические пакеты включают в себя специальный график "fast line" для быстрого рисования серии линий из чрезвычайно больших наборов данных (более 10000 точек). TAChart, напротив, содержит оптимизированный быстрый путь внутри стандартного кода серии строк, который обеспечивает сопоставимую скорость рисования.
44	44
45	45		Серия линий будет нарисована очень быстро, если все следующее верно:
46	46
47	47		- Нет отметок.
48	48		- Нет указателей.
49	49		- `LineType` не установлено в значение `ltFromOrigin`.
50	50
51	51		Некоторые операционные системы/наборы виджетов могут дополнительно требовать, чтобы свойствам были установлены следующие значения `LinePen.Style=psSolid` и `LinePen.Width=1`.
52	52
53	53		Дополнительного быстродействия можно добиться, если установить `Source.Sorted=true`.
54	54
55	55		Вы можете измерить скорость рисования линий на вашей платформе с помощью демо «line».
56	56
57	57		##### Point-диаграмма
58	58
59	59		`TLineSeries` можно нарисовать как «серию точек», показывающую только символы в позиции точек данных и скрывающую соединительные линии, установив для `ShowPoints` значение `True` и `LineType` для `ltNone`. Обратите внимание, что `SeriesColor` применяется только к соединительным линиям; чтобы указать цвет точек, измените `Pointer.Brush.Color` для заливки и/или `Pointer.Pen.Color` для цвета линии границы. Свойство `Pointer` также предоставляет доступ к фигурам (круг, рамка и т.д.) символов (`Style`).
60	60
61	61		#### Bar-диаграмма
62	62
63	63		`TBarSeries` представляет данные в виде набора полос, простирающихся от `ZeroLevel` до точек данных.
64	64
65	65		Вы можете контролировать ширину полосы с помощью свойства `BarWidthPercent`. Обратите внимание, что оно измеряется относительно соседних полос. Если значения X не равноудалены, полосы будут иметь различную ширину. Чтобы предотвратить это, установите `BarWidthStyle=bwPercentMin`.
66	66
67	67		Вы можете рисовать несколько полос бок о бок, используя свойство `BarOffsetPercent`.
68	68
69	69		Используйте несколько значений Y для создания ряда полос с накоплением (`Stacked=true`). Начиная с Lazarus 2.0, несколько значений Y также могут отображаться в расположении рядом (`Stacked=false`).
70	70
71	71		В дополнение к прямоугольным полосам данные могут быть представлены альтернативными формами: цилиндр, шестиугольная призма, пирамида или конус - см. свойство `BarShape`, которое поддерживает следующие значения: `bsRectangular, bsCylindrical, bsHexPrism, bsPyramid, bsConical`. Кроме того, событие `OnCustomDrawBar` позволяет рисовать столбцы любым заданным пользователем способом.
72	72
73	73		#### Area-диаграмма
74	74
75	75		`TAreaSeries` представляет данные в виде многоугольника, продолжающегося вниз от точек данных, либо до линии `ZeroLevel`, либо к бесконечности (если `UseZeroLevel=false`).
76	76
77	77		Вы можете получить «пошаговый» вид, задав свойство `ConnectType`.
78	78
79	79		Как и `TBarSeries` и `TLineSeries`, ряд областей может принимать несколько значений `Y` для одного и того же `X` из [[TAChart documentation/ru\|источника данных со множеством значений]]. Эти значения y отображаются в стопке, если для свойства `Stacked` установлено значение `True` (его значение по умолчанию). Используйте компонент ChartStyles, чтобы определить внешний вид отдельных слоев. (Обратите внимание, что в версиях Lazarus 1.8.x или более ранних ChartStyles не окрашивают последовательно перекрывающиеся слои).
80	80
81	81		Свойство `Banded` (доступно в Lazarus v2.0 +), если установлено в true, подавляет рисование самого низкого уровня стека. Таким образом, полоса значений данных может быть выделена: используйте источник диаграмм с двумя значениями Y - установите первое значение Y на минимум, а второе значение Y на максимальный уровень диапазона. В качестве альтернативы, ширина полосы может быть указана во втором значении Y, если оба свойства `Banded` и `Stacked` установлены в true.
82	82
83	83		Поддержку нескольких значений Y следует применять с осторожностью: при суммировании НЕположительных значений могут получаться графики, которые трудно понять, а ряд непакетированных областей (`Stacked=false`) может пострадать от того, что данные покрываются другими значениями Y. Кроме того, `ZeroLevel` следует включать только в самый низкий уровень стека, чтобы избежать необычных результатов.
84	84
85	85		Трехмерное представление серии может быть получено, если для `Depth` установлено положительное значение, например, 10 или 20. Обратите внимание, что алгоритм рисования очень прост и, скорее всего, даст неправильно отображение при пересечении кривых, или при отключенных свойствах укладки и объединения.
86	86
87	87		### Диаграмма со множеством значений
88	88
89	89		Для графика со множеством значений требуется [[TAChart documentation/ru\|источник данных со множеством значений]] и использование дополнительных значений X и/или Y в качестве дополнительных параметров для рисования сложных фигур.
90	90
91	91		#### Bubble-диаграмма
92	92
93	93		`TBubbleSeries` представляет данные в виде окружностей переменного радиуса с центром в точках данных. Для этой серии требуется источник с `YCount` не менее 2, и в качестве радиуса пузырька используется первое дополнительное значение Y.
94	94
95	95		Свойство `OverrideColor` позволяет установить цвет внутренней части или края каждого пузырька в отдельности.
96	96
97	97		#### Диаграмма Box-and-whiskers
98	98
99	99		`TBoxAndWhiskerSeries` представляет данные в виде прямоугольников с центральной линией и двумя Т-образными формами, выступающими в обоих направлениях. Хотя в статистике [ящик с усами (диаграмма размаха)](https://ru.wikipedia.org/wiki/%D0%AF%D1%89%D0%B8%D0%BA_%D1%81_%D1%83%D1%81%D0%B0%D0%BC%D0%B8) должен основываться на конкретных квартилях данных, TAChart не применяет это, позволяя пользователям рисовать произвольные графики.
100	100
101	101		Иногда можно использовать серии блоков и усов, чтобы представить другие диаграммы другого значения, но схожего внешнего вида, такие как [диаграммы Гантта](https://ru.wikipedia.org/wiki/%D0%94%D0%B8%D0%B0%D0%B3%D1%80%D0%B0%D0%BC%D0%BC%D0%B0_%D0%93%D0%B0%D0%BD%D1%82%D1%82%D0%B0).
102	102
103	103		Для этой серии требуется источник с `YCount` не менее 5, и используются значения Y следующим образом:
104	104
105	105		\| Index \| Usage \|
106	106		\|-------\|-----------------------\|
107	107		\| 0 \| Нижний ус \|
108	108		\| 1 \| Нижняя граница ящика \|
109	109		\| 2 \| Центральная линия \|
110	110		\| 3 \| Верхняя граница ящика \|
111	111		\| 4 \| Верхний ус \|
112	112		\| \| \|
113	113
114	114		#### Диаграмма Open-high-low-close
115	115
116	116		`TOpenHighLowCloseSeries` представляет данные в виде вертикальных линий с двумя галочками, как описано [здесь](https://en.wikipedia.org/wiki/Open-high-low-close_chart).
117	117
118	118		Обычно требуется `YCount` не менее 4 и используются значения Y следующим образом:
119	119
120	120		\| Свойство \| По умолчанию \| Использование \|
121	121		\|-------------\|--------------\|--------------------------\|
122	122		\| YIndexLow \| 0 \| Нижняя точка линии \|
123	123		\| YIndexOpen \| 1 \| Положение галочки слева \|
124	124		\| YIndexClose \| 2 \| Положение галочки справа \|
125	125		\| YIndexHigh \| 3 \| Верхняя точка линии \|
126	126		\| \| \| \|
127	127
128	128		> Note: хотя предполагается, что значения Y упорядочены в порядке возрастания по приведенной выше таблице, ряды сами упорядочивания не сделают и будут отображать любые предоставленные данные.
129	129
130	130		#### Field-диаграмма
131	131
132	132		`TFieldSeries` отображает вектор в каждой точке данных. Вектор рисуется как отрезок с необязательной стрелкой. Линия центрируется по координатам X,Y, хранящимся в источнике диаграммы, ее направление задается дополнительными значениями, хранящимися в XList и YList источника диаграммы. Следовательно, для этого типа серии требуется источник с двумя значениями X и Y:
133	133
134	134		\| Поле элемента данных источника \| Использование \|
135	135		\|--------------------------------\|--------------------------------\|
136	136		\| X \| X координата центра линии \|
137	137		\| Y \| Y координата центра линии \|
138	138		\| XList\[0\] \| X координата направления линии \|
139	139		\| YList\[0\] \| Y координата направления линии \|
140	140		\| \| \|
141	141
142	142		Метод `AddVector(x,y: Double; vectorx, vectory: Double; ALabel: String = ''; AColor: TColor = clTAColor)` помогает правильно назначить все значения внутреннему списку источника.
143	143
144	144		Чтобы избежать наложения векторов, вызовите метод `Normalize Vector(Length: Double)`,дабы нормализовать их длины так, чтобы самый длинный вектор имел указанную длину.
145	145
146	146		Параметры стрелки понимаются как проценты от длины вектора, то есть стрелка становится меньше для более коротких векторов.
147	147
148	148		### Круговые диаграммы
149	149
150	150		Радиальные серии игнорируют преобразования осей. Вы можете увидеть примеры радиальных рядов в demo "radial".
151	151
152	152		#### Pie-диаграмма
153	153
154	154		`TPieSeries` рисует круговые диаграммы.
155	155
156	156		Для каждой точки данных круговая серия интерпретирует значение Y как относительный размер среза, а значение X как расстояние среза от центра круговой диаграммы (только если свойство `Exploded` имеет значение true).
157	157
158	158		Начиная с `StartAngle`, круговая диаграмма вращается против часовой стрелки по всему кругу.
159	159
160	160		Радиус круга можно установить вручную с помощью свойства `FixedRadius` или рассчитать автоматически, чтобы вся серия, включая все метки, точно соответствовала родительской диаграмме.
161	161
162	162		Кольцо можно нарисовать вместо кругового фрагмента, задав свойству `InnerRadiusPercent` значение больше 0, но меньше 100 - это определяет радиус внутреннего круга в процентах от общего радиуса.
163	163
164	164		Цвета кусочка определяются полем `Color` элементов данных или жестко закодированной палитрой. Контуры срезов отрисовываются с использованием свойства `EdgePen`.
165	165
166	166		Существует несколько опций для позиционирования метки, управляемых свойством `MarkPositions`:
167	167
168	168		- `pmpAround` -- отметки рисуются вне круговой диаграммы на продолжении или радиус-векторе для каждого кусочка
169	169		- `pmpInside` --отметки нарисованы внутри каждого кусочка
170	170		- `pmpLeftRight` -- отметки рисуются непосредственно слева или справа от кусочка
171	171
172	172		`MarkDistance` определяет расстояние между начальной точкой метки и меткой. Начальная точка определяется `MarkPositionCentered` как периметр круговой диаграммы (`false`) или центр (`true`). `MarkDistancePercent`, если установлено значение `true`, интерпретирует `Marks.Distance` как процент от радиуса круговой диаграммы. В противном случае оно интерпретируется в единицах изображения.
173	173
174	174		Если `RotateLabels` имеет значение true, каждая метка дополнительно поворачивается, чтобы (если `LabelFont.Orientation=0`) она была параллельна радиус-вектору своего кусочка.
175	175
176	176		Если для значения Y элемента данных установлено значение NaN, он станет [[TAChart documentation/ru\|скрытым]] элементом. Если значение X установлено в NaN, элемент не рисуется, но место для него все еще зарезервировано. Это позволяет рисовать «частичные» круговые диаграммы.
177	177
178	178		Круговые диаграммы имеют ограниченную поддержку для трехмерного рисования. Свойство `Depth` определяет толщину круга. `Orientation` дополняет нормальный вид (`poNormal`) скошенным видом наклонной (`poHorHorizontal`) и вертикальной (`poVertical` ) круговой серии, последние две управляются свойством `ViewAngle` в градусах от 0 до 89. Поскольку TAChart не реализует алгоритм истинной скрытой линии/скрытой поверхности, в некоторых комбинациях могут быть некоторые изменения артефактов рисования параметров.
179	179
180	180		#### Polar-диаграмма
181	181
182	182		`TPolarSeries` представляет данные в виде точек в [полярной системе координат](https://ru.wikipedia.org/wiki/%D0%9F%D0%BE%D0%BB%D1%8F%D1%80%D0%BD%D0%B0%D1%8F_%D1%81%D0%B8%D1%81%D1%82%D0%B5%D0%BC%D0%B0_%D0%BA%D0%BE%D0%BE%D1%80%D0%B4%D0%B8%D0%BD%D0%B0%D1%82).
183	183
184	184		Начало полярной системы координат определяется в координатах графа свойствами `OriginX` и `OriginY`.
185	185
186	186		Для каждой точки данных значение X интерпретируется как угол в радианах, а значение Y - как расстояние от центра.
187	187
188	188		TPolarSeries не поддерживает преобразования осей.
189	189
190	190		Некоторые дополнительные свойства:
191	191
192	192		- `CloseCircle`: если имеет значение `true`, последняя точка связана с первой.
193	193		- `Filled`: если имеет зачение `true`, то многоугольник точек серии заполняется с использованием текущего значения `Brush`. Если `CloseCircle` равно false, заливка отправляется в начало координат.
194	194		- `ShowPoints`: если имеет значение `true`, то указатель серии рисуется в позиции каждой точки данных.
195	195
196	196		### Диаграммы с пользовательской отрисовкой
197	197
198	198		Предоставляет события `OnDraw` и `OnGetBounds`, чтобы разрешить произвольную пользовательскую отрисовку на TChart. Обратите внимание, что использование `TChart.Canvas` напрямую крайне нежелательно и часто не будет работать должным образом.
199	199
200	200		### Диаграммы функций
201	201
202	202		Диаграммы функций - это рекомендуемый способ рисования функциональных графиков, в отличие, например, от предварительного вычисления данных функций и использования [[TAChart documentation/ru\|line-диаграмм]]. Они обеспечивают независимый от масштаба контроль плавности и скорости рисования.
203	203
204	204		Вы можете увидеть примеры функциональных серий в демо "func".
205	205
206	206		#### Диаграммы функций
207	207
208	208		`TFuncSeries` представляет одномерную функцию, определенную событием `OnCalculate`. Функция рассчитывается для каждого свойства `Step` пикселя изображения, поэтому вы можете использовать его для увеличения «гладкости» или скорости рисования.
209	209
210	210		Свойство `Extent` можно использовать для установки экстентов x и y с целью вычисления [[TAChart documentation/ru\|полного экстента]] диаграммы. Однако во время рисования это свойство игнорируется, и функция будет отображаться в соответствии с текущим экстентом.
211	211
212	212		Свойство `DomainExclusion` позволяет исключить некоторые интервалы из функциональной области. TFuncSeries правильно рисует точки разрыва, установленные `DomainExclusion`. В настоящее время `DomainExclusion` можно установить только во время выполнения, вызвав процедуры `AddRange` или `AddPoint`. Интервалы, определенные `DomainExclusion`, по умолчанию закрыты, то есть содержат конечные точки; это означает, что функция не рассчитывается в конечных точках. Если исключение домена должно содержать конечные точки (при необходимости для функции `y=sqrt(x)`) вызовите `AddRange` с соответствующим элементом набора `TIntervalOptions=(ioOpenStart,ioOpenEnd)` в качестве необязательного третьего параметра.
213	213
214	214		Свойство `DomainExclusion.Epsilon` контролирует расстояние между конечной точкой и последней нарисованной точкой (конечно, в случае открытого интервала кривая начинается непосредственно в конечной точке). `Epsilon` можно настроить в тех редких случаях, когда значение по умолчанию 1E-6 не дает правильных результатов.
215	215
216	216		#### Диаграммы метаматических выражений
217	217
218	218		`TExpressionSeries` аналогичен `TFuncSeries`, но функция указана в виде строки математического выражения, например `'sin(1.23456*x)'` ( свойство `Expression`). Диаграмма создает экземпляр [[How To Use TFPExpressionParser\|FPExpressionParser]] для анализа строки и вычисления значений функции. Таким образом, функции могут быть нанесены на график во время разработки.
219	219
220	220		Свойство `Params` позволяет определять параметры для термина функции; в инспекторе объектов он открывает редактор коллекций, в котором каждый параметр может быть указан его именем (как используется в выражении) и его значением. Если, например, параметр `f` определен со значением `1.23456`, то приведенное выше выражение также можно записать как `'sin(f*x)'`.
221	221
222	222		Аналогично `TFuncSeries`, исключения доменов поддерживаются для определения областей, в которых функция не может быть рассчитана. Но в соответствии с математическими соглашениями `TExpressionSeries` требует в свойстве `Domain` задавать регион, в котором функция определена (дополнение к исключениям домена). Регион задается строкой, такой как `'x >= 0'`. Если существует несколько условий, они должны быть разделены двоеточием, например `'x < -1; x > 1'`. Двоеточие имеет функцию логического выражения ИЛИ. Интервал определяется как `'-1 < x < 1'`. Постоянные части условий также могут быть математическими выражениями - в следующем примере точка pi/2 исключается из вычисления значений функции: `'x <> pi/2'`. Десятичные числа должны вводиться с точкой в качестве десятичного разделителя, независимо от того, как он определен в системных настройках языка операционной системы.
223	223
224	224		> Note: Параметры и домены должны быть определены до начала ввода выражения, в противном случае парсер сообщит об ошибке.
225	225
226	226		#### Диаграммы B-spline
227	227
228	228		`TBSplineSeries` рисует [B-сплайн](https://ru.wikipedia.org/wiki/B-%D1%81%D0%BF%D0%BB%D0%B0%D0%B9%D0%BD) с заданным свойством `Degree`, используя [Алгоритм Де Бора](https://en.wikipedia.org/wiki/De_Boor's_algorithm).
229	229
230	230		Сегменты сплайнов короче пикселей `Step` представлены прямыми линиями.
231	231
232	232		#### Диаграмма Cubic spline
233	233
234	234		`TCubicSplineSeries` рисует кривую данных как [кубический сплайн](https://ru.wikipedia.org/wiki/%D0%9A%D1%83%D0%B1%D0%B8%D1%87%D0%B5%D1%81%D0%BA%D0%B8%D0%B9_%D1%81%D0%BF%D0%BB%D0%B0%D0%B9%D0%BD), используя стандартный пакет FPC NumLib.
235	235
236	236		В Lazarus v2.0+ свойство `SplineType` позволяет выбирать между сплайнами [natural](https://en.wikipedia.org/wiki/Spline_interpolation) и [monotone Hermite](https://en.wikipedia.org/wiki/Monotone_cubic_interpolation), при этом последний избегает превышения интерполяции.
237	237
238	238		Функция сплайна рассчитывается для каждого `Step` пикселя изображения, поэтому вы можете использовать это свойство для увеличения «сглаживания» или скорости рисования.
239	239
240	240		Источник данных должен содержать не менее двух точек и строго увеличивать координаты X (старые версии Lazarus до версии 2.0 требуют, как минимум, 4 точки данных; для меньшего количества точек вместо сплайна рисуется многоугольник, с использованием свойства `BadDataPen`\>, если установлена опция `csoDrawFewPoints`.)
241	241
242	242		Если значения X не упорядочены и установлена опция `csoDrawUnorderedX`, сплайн будет отрисован без учета проблемных точек с использованием `BadDataPen`.
243	243
244	244		Параметры `csoExtrapolateLeft` и `csoExtrapolateRight` позволяют задавать естественную экстраполяцию слева и справа соответственно.
245	245
246	246		#### Fit-диаграммы
247	247
248	248		`TFitSeries` выполняет подгонку [методом наименьших квадратов](https://ru.wikipedia.org/wiki/%D0%9C%D0%B5%D1%82%D0%BE%D0%B4_%D0%BD%D0%B0%D0%B8%D0%BC%D0%B5%D0%BD%D1%8C%D1%88%D0%B8%D1%85_%D0%BA%D0%B2%D0%B0%D0%B4%D1%80%D0%B0%D1%82%D0%BE%D0%B2), используя процедуры вычисления, содержащиеся в стандартном пакете [[numlib\|Numlib]] из FPC. Основным соединительным элементом является TAFitLib, который является автономным и может применяться также без TAChart.
249	249
250	250		Функция подбора выбирается через свойство `FitEquation`:
251	251
252	252		- `fePolynomial`: y = b<sub>0</sub> + b<sub>1</sub>x + b<sub>2</sub>x<sup>2</sup> + … + b<sub>n</sub>x<sup>n</sup>, где значение n контроллируется свойством `ParamCount` (`ParamCount = n + 1`).
253	253		- `feLinear`: y = a + bx
254	254		- `feExp`: y = a * e<sup>bx</sup>
255	255		- `fePower`: y = a * x<sup>b</sup>
256	256		- `feCustom`: y = b<sub>0</sub>X<sub>0</sub>(x) + b<sub>1</sub>X<sub>1</sub>(x) + b<sub>2</sub>X<sub>2</sub>(x) + … + b<sub>n</sub>X<sub>n</sub>(x) где значение n контроллируется свойством `ParamCount` (`ParamCount = n + 1`), и X<sub>i</sub>(x), i = 0..n, являются «базовыми функциями», которые определяются методом `SetFitBasisFunc(AIndex: TFitFuncIndex; AFitFunc: TFitFunc; AFitFuncName: String)`.
257	257		- `AIndex` - индекс i базовой функции, `1..MaxInt`.
258	258		- `AFitFuncName` - текстовое представление функции, используемой для легенды по умолчанию.
259	259		- `AFitFunc` - адрес базовой функции X<sub>i</sub>(x), которая имеет сигнатуру `function(x: ArbFloat; Param: Integer): ArbFloat` с `ArbFloat`, являющимся общим типом данных с плавающей точкой в FPC [[numlib\|Numlib]] (unit typ). Некоторые базовые функции легко доступны в модуле TAFitLib:
260	260
261	261		``` pascal
262	262		function FitBaseFunc_Const(x: ArbFloat; Param: Integer): ArbFloat; // константа
263	263		function FitBaseFunc_Linear(x: ArbFloat; Param: Integer): ArbFloat; // линейный член (x)
264	264		function FitBaseFunc_Square(x: ArbFloat; Param: Integer): ArbFloat; // квадратный член (x^2)
265	265		function FitBaseFunc_Cube(x: ArbFloat; Param: Integer): ArbFloat; // кубический член (x^3)
266	266		function FitBaseFunc_Poly(x: ArbFloat; Param: Integer): ArbFloat; // power term (x^Param)
267	267		function FitBaseFunc_Sin(x: ArbFloat; Param: Integer): ArbFloat; // sin(x*Param)
268	268		function FitBaseFunc_Cos(x: ArbFloat; Param: Integer): ArbFloat; // cos(x*Param)
269	269		```
270	270
271	271		По умолчанию параметры `b`<sub>`0`</sub>`, b`<sub>`1`</sub>`, ..., a, b` варьируются в процессе подбора так, что среднее значение квадратичного отклонения между данными и подобранными кривыми было сведено к минимуму. Однако также возможно поддерживать один или несколько параметров подгонки постоянными, например, чтобы заставить подобранную прямую линию проходить через начало координат. Для этого значения постоянных параметров должны быть указаны в ';' или '\\|' для разграничения списка строковых значений свойства `FixedParams`. Порядок значений должен соответствовать порядку подгоночных параметров. Параметры переменных можно оставить пустыми или заменить нечисловой строкой.
272	272
273	273		Пример: `FixedParams='var;2'` (или короче: `';2'`) означает, что первый подходящий параметр является переменной, но второй параметр остается постоянным со значением 2; если имеется более 2 параметров, остальные также считаются переменными.
274	274
275	275		Диапазон подгонки обычно определяется экстентом диаграммы, но может быть установлен вручную через свойство `FitRange`. Функция подгонки рисуется по всей оси, если только `DrawFitRangeOnly=true`.
276	276
277	277		Когда подгонка завершена, `ErrCode` диаграммы устанавливается так, чтобы показать, был ли расчет успешным или нет:
278	278
279	279		- `fitOK`: успешно
280	280		- `fitDimError`: расчет был прерван, потому что размеры массивов данных (x, y, полоса ошибок y) не совпадают.
281	281		- `fitMoreParamsThanValues`: расчет не удался, потому что есть больше подгоночных параметров, чем значений данных.
282	282		- `fitNoFitParams`: расчет прерван, потому что параметры подгонки не указаны. Это может произойти случайно, если все параметры подгонки будут исправлены в свойстве `FixedParams`.
283	283		- `fitSingular`: матрица дизайна задачи подгонки оказывается (почти) единственной.
284	284		- `fitNoBaseFunction`: для случая `FitEquation=feCustom` указано недостаточно базовых функций подгонки.
285	285
286	286		Метод `ErrorMsg` создаст текст для сообщения об ошибке из текущего `ErrCode`.
287	287
288	288		Событие `OnFitComplete` вызывается после того, как найдено уравнение подгонки, но до начала рисования. Это хорошее место для запроса результатов процедуры подбора:
289	289
290	290		- `Param[AIndex]` является наиболее подходящим значением для параметра с указанным индексом, `AIndex = 0..ParamCount-1`.
291	291		- `ParamError[AIndex]` сообщает неопределенность ("standard error" (стандартная ошибка) в статистическом выражении) соответствующего параметра подгонки.
292	292		- Процедура `GetConfidenceLimits(AIndex: Integer; out ALower, AUpper: Double)` возвращает диапазон между `ALower` и `AUpper`, в пределах которого ожидается наилучшее соответствие того, что параметр будет найден с вероятностью, указанной в `ConfidenceLevel` (по умолчанию: `0.95`, т.е. 95%).
293	293		- `Param_tValue[AIndex]` возвращает значение [t-статистики](https://en.wikipedia.org/wiki/T-statistic) для соответствующего параметра подгонки. Это соотношение стоимости, деленное на стандартную ошибку. Для точного параметра значение t должно быть намного больше 1.
294	294		- `Param_pValue[AIndex]` - это вероятность того, что любое значение `t`, столь же высокое, как `Param_tValue`, будет случайно получено для данных степеней свободы. Чтобы «доверять» подобранному значению с уверенностью, заданной `ConfidenceLevel`, значение p должно быть меньше, чем `1 - ConfidenceLevel`, по умолчанию 0,05.
295	295		- `FitStatistics` сообщает о других статистических параметрах, полезных для проверки достоверности подобранной модели или для дальнейших статистических расчетов. Эти данные доступны как свойства или функции этого класса:
296	296		- `N` (integer): количество точек данных, используемых для подгонки. Обратите внимание, что это может быть меньше точек данных, предоставленных источником диаграммы, поскольку он может содержать значения NaN, которые пропускаются.
297	297		- `M` (integer): количество подгоночных параметров. Обычно это значение `ParamCount`, но если определенные параметры вынуждены быть постоянными (`FixedParams`), их количество вычитается.
298	298		- `DOF` (integer): "degrees of freedom" (cтепени свободы) - это разница `N - M`, важный параметр в статистическом анализе результатов подбора.
299	299		- `SST`: "total sum of squares" (общая сумма квадратов) - это сумма квадратов члена `(y[i] - ymean)/dy[i]` по всем точкам данных. Здесь `y[i]` - это значение `y` точки данных с индексом `i`, `dy[i]` размера ее полосы ошибок (стандартное отклонение) - или 1, если недоступно, а `ymean` - это среднее значение `y[i]/dy[i]`. Количество определяет общее изменение точек данных вокруг их среднего значения.
300	300		- `SSE`: "error sum of squares" (сумма ошибок квадратов) - изменение точек данных вокруг подогнаной кривой, т.е. сумма `((y[i] - ycalc(x[i])/dy[i])^2)`; здесь `ycalc(x[i])` - вычисленное значение подгоночной кривой в точке `x[i]`.
301	301		- `SSR`: "regression sum of squares" (сумма квадратов регрессии) - изменение только подогнанной кривой, то есть сумма `((ycalc(x[i]) - ymean)/dy[i])^2`.
302	302		- `xBar`: среднее значение координат `x` всех используемых точек данных.
303	303		- `SSx`: изменение координат `x` точек данных, то есть сумма `(x[i] - xbar)^2`.
304	304		- `VarCovar[i, j: Integer]: Double`: является элементом матрицы дисперсии-ковариации для параметров подгонки при данных индексах.
305	305		- `R2`: "коэффициент детерминации". Это - соотношение `SSR/SSE`, и описывает, насколько сильно разброс данных объясняется подобранной кривой. Значение 1 для идеальной подгонки и 0 для абсолютной без соглашения.
306	306		- `AdjR2`: был введен для компенсации эффекта, который обычно увеличивается `R2`, добавляя все больше и больше подходящих параметров.
307	307		- `Chi2`: другое слово для `SSE`. По сути, это статистическая величина, которая минимизируется во время процедуры подбора. Данное значение является минимальным найденным значением.
308	308		- `ReducedChi2`: это `Chi2` (или: `SSE`), которое нормализовано по степеням свободы, то есть изменению данных вокруг подобранной кривой на степень свободы. Должно быть "маленьким" для хорошей подгонки.
309	309		- `ResidualStdError`: общая стандартная ошибка подгонки. Должно быть "маленьким".
310	310		- `pValue`: (дробная) вероятность того, что остаточный разброс точек данных вокруг подобранной кривой является случайным. Должно быть высоким, на практике несколько десятков, хотя иногда значения до 0,001 по-прежнему принимаются. Если в подбор не включены никакие полосы ошибок, иногда p оказывается равным 0 или 1 - такие значения следует игнорировать.
311	311		- Процедуры `GetLowerConfidenceInterval(const Ax: Double; out AY: Double)`, `GetUpperConfidenceInterval`, `GetLowerPredictionInterval` и `GetUpperPredictionInterval` могут быть подключены к событию `OnCalculate` TFuncSeries, чтобы построить границы нижнего и верхнего доверительных интервалов и интервалов прогнозирования вокруг подобранной кривой. Эти пределы определяют области вокруг подобранной кривой, в пределах которых можно ожидать общую подгоночную кривую (доверительный интервал) или отдельные точки данных (интервал прогнозирования) на основе вероятности, заданной `ConfidenceLevel`.
312	312		- Примечание: все эти статистические данные предполагают, что остаточные ошибки соответствуют нормальному распределению и что столбцы ошибок были оценены надлежащим образом.
313	313
314	314		`EquationText` возвращает интерфейс `IEquationText`, который позволяет построить строку, представляющую уравнение соответствия. Вы можете переопределить имена переменных x и y, числовой формат и, наконец, получить строку из функции `Get`. Обратите внимание, что преобразование из IEquationText в String определено, поэтому обычно нет необходимости явно вызывать `Get`.
315	315
316	316		Legend.Format-свойство fit series поддерживает дополнительный аргумент формата ('%2:s'), указывающий на текст уравнения по умолчанию.
317	317
318	318		После изменения параметров `TFitSeries` уравнение будет пересчитано на следующем отрисовке диаграммы. Чтобы немедленно пересчитать его, вызовите процедуру `ExecFit`. Используйте свойство `State`, чтобы проверить правильность текущего уравнения.
319	319
320	320		#### Диаграмма цветовых карт
321	321
322	322		`TColorMapSeries` представляет собой двумерную функцию, определенную событием `OnCalculate` как поле пикселей, цвет которого зависит от значения функции.
323	323
324	324		Диаграмма отображается в виде набора прямоугольников размером `StepX` с помощью `StepY` пикселей. Функция вызывается один раз для каждого прямоугольника.
325	325
326	326		Цветовые значения определяются одной из встроенных палитр (свойство `BuiltinPalette = cmpHot, cmpCold, cmpRainbow, cmpMonochrome`). Диапазон значений, сопоставленных с цветами палитры, должен быть указан в `BuiltinPaletteMax` и `BuiltinPaletteMin`, иначе результаты не будут предсказуемыми.
327	327
328	328		Альтернативно, внешний ChartSource может быть назначен свойству `ColorSource`, которое должно быть отсортировано. Каждая точка данных источника диаграммы интерпретируется как имеющая значение X, соответствующая значению Color. Если фактическое значение попадает между уровнями цвета, оно может быть либо линейно интерполировано (если `Interpolate` равно `true`), либо округлено до ближайшего уровня.
329	329
330	330		В случае, когда `Legend.Multiplicity=lmPoint`, диаграмма цветовых карт будет отображать уровни цвета в [[TAChart documentation/ru\|Легенде]].
331	331
332	332		#### Диаграмма цветовых карт выражения
333	333
334	334		аналогична диаграмме цветовых карт с тем отличием, что двумерная функция определяется не событием, а математическим выражением, таким как `x^2+y^2`, как и в TExpressionSeries, но теперь с двумя переменными `x` и `y`. Переменные могут быть переименованы с помощью свойств `VariableNameX` и `VariableNameY`. Аналогично TExpressionSeries также можно вводить параметры (свойство `Params`). Домены, однако, не поддерживаются, функция должна быть определена во всем видимом диапазоне x/y.
335	335
336	336		## Источники
337	337
338	338		![](/wiki-images/7/72/Chartsource_hierarchy.png)Данные могут попасть в график из разных источников. Они реализованы как набор компонентов, производных от `TCustomChartSource`.
339	339
340	340		Чтобы назначить источник диаграмме, вы можете задать свойство `Source`. Если свойство оставлено неназначенным, диаграмма будет использовать свой собственный встроенный список источников. Такие методы, как `AddXY`, делегируются текущему источнику диаграммы. Обратите внимание, что список источника является единственным редактируемым источником, поэтому после назначения, например, случайного источника диаграммы для серии, вызов `AddXY` вызовет исключение.
341	341
342	342		Каждый элемент данных имеет следующие поля: `X`, `Y`, `XList`, `YList`, `Color`, `Text`.
343	343
344	344		### Отсортированные источники
345	345
346	346		Если известно, что значения X источника возрастают, возможны некоторые дополнительные оптимизации, такие как бинарный поиск. Таким образом, все источники имеют свойство `IsSorted`, которое помогает определить это.
347	347
348	348		В Lazarus 2.1+ [[TAChart documentation/ru\|TListChartSource]] можно отсортировать по нескольким критериям:
349	349
350	350		- `SortBy` = `sbX`, `sbY`, `sbText`, `sbColor`, `sbCustom`: сортировка по значению X или Y, тексту, цвету или определенным пользователем способом соответственно. В последнем случае должен быть предоставлен обработчик для события `OnCompare`.
351	351		- `SortIndex`: индекс значений X или Y, используемый для сортировки.
352	352		- `SortDir` = `sdAscending`, `sdDescending`: сортировка в порядке возрастания или убывания.
353	353
354	354		Когда источник сортируется по чему-либо, кроме x, это влияет только на порядок отрисовки связанных рядов, и возможно, что на диаграмме ничего не изменится. Визуальный эффект заметен для
355	355
356	356		- [[TAChart documentation/ru\|TPieSeries]] потому что порядок точек данных определяет порядок срезов по кругу
357	357		- [[TAChart documentation/ru\|TBubbleSeries]] когда пузырьки перекрываются. Используйте сочетание `SortBy=sbY`, `SortIndex=1` и `SortDir=sdDescending`, чтобы избежать покрытия пузырьков, потому что сначала появляются большие пузырьки, а маленькие - последними.
358	358		- все серии унаследованы от [[TAChart documentation/ru\|TBasicPointSeries]], когда `XCount` связанного источника диаграммы равен 0: в этом случае значение X источника игнорируется и заменяется индексом точки данных. Поскольку индекс точек данных изменяется при сортировке, точки данных будут автоматически переставлены в отсортированном порядке - см. Пример sort_demo в папке demo.
359	359
360	360		### Источники с множеством значений
361	361
362	362		Источники могут содержать несколько значений Y для каждого значения X. Эти значения хранятся в поле `YList` исходного элемента данных. Количество значений Y определяется свойством `YCount`. Обратите внимание, что первое значение Y в любом случае сохраняется в поле Y, поэтому `YCount=3` означает, что значения хранятся в `Y`, `YList[0]` и `YList[1]`.
363	363
364	364		Дополнительные значения могут использоваться в различных сериях - например, столбчатые диаграммы с накоплением или пузырьковые диаграммы.
365	365
366	366		Более того, также возможно сохранять несколько значений X для одной и той же точки данных. Это требуется для `TFieldSeries`. Эти дополнительные значения X хранятся в `XList` исходного элемента данных. Как и в случае со значениями Y, общее количество значений X задается свойством `XCount`, которое содержит "обычное" значение X плюс длину массива `XList`.
367	367
368	368		### Пропуск исходных элементов
369	369
370	370		Можно указать TAChart пропустить рисование некоторых исходных элементов, не удаляя их из источника. Это может быть полезно как для оптимизации, так и для пользовательского интерфейса.
371	371
372	372		Чтобы пропустить элемент, присвойте [NaN](http://www.freepascal.org/docs-html/rtl/math/nan.html) либо значению X, либо одному из значений Y. Точный эффект пропуска зависит от серии, но обычно установка X в NaN означает пропуск всего элемента, в то время как установка Y или некоторого элемента YList означает пропуск только этого значения Y, при этом все еще отрисовывая другие.
373	373
374	374		Также обратите внимание, что если вы установите NaN только для одной координаты, другая все равно будет участвовать в вычислении экстента.
375	375
376	376		В случае составных серий неясно, как следует обрабатывать отсутствующее значение, когда к нему добавляются следующие уровни. В Lazarus v2.1 + есть свойство `StackedNaN`, которое можно выбрать как
377	377
378	378		- `snReplaceByZero` - отсутствующее значение считается нулевым; это как Excel обрабатывает этот случай.
379	379		- `snDoNotDraw` - пропускает всю точку данных со всеми уровнями стека.
380	380
381	381		Вы можете увидеть примеры пропуска элементов в демо "nan".
382	382
383	383		### Планки погрешностей
384	384
385	385		`TLineSeries`, `TBSplineSeries`, `TCubicSplineSeries` и `TFitSeries` могут отображать планки погрешностей(error bars) в каждой точке данных. Размер планок погрешностей в направлениях `x` и `y` определяется параметрами в свойствах `XErrorBarData` и `YErrorBarData` соответственно:
386	386
387	387		- `Kind: TChartErrorBarKind`: определяет, как интерпретируются следующие данные
388	388		- `ebkNone`: игнорировать - планки погрешностей отображаться не будут
389	389		- `ebkConst`: все точки данных имеют одинаковую планку погрешности, заданную `ValuePlus` и `ValueMinus`.
390	390		- `ebkPercent`: значения `ValuePlus` и `ValueMinus` понимаются как процент от значений данных.
391	391		- `ebkChartSource`: каждая точка данных может иметь отдельную планку погрешности. Длина планок погрешностей сохраняется в XList или YList источника многозначной диаграммы. Индекс среди всех значений x и y задается `IndexPlus` и `IndexMinus` для положительной и отрицательной планки погрешности соответственно.
392	392		- `ValuePlus` и `ValueMinus`: длина столбцов положительных и отрицательных погрешностей соответственно. В зависимости от настройки `Kind` предполагается, что значение является постоянным для всех точек данных (`Kind = ebkConst`, единицы оси) или в процентах от значения точки данных (`Kind = ebkPercent`). Оба значения должны быть положительными числами, за исключением `ValueMinus = -1`, который указывает, что отрицательная планка погрешности должна быть равна положительной планке погрешности.
393	393		- `IndexPlus` и `IndexMinus` используются, когда `Kind` равен `ebkChartSource` и указывают индекс x или y в многозначном chartsource, из которого можно получить длину планки погрешности для отдельных точек данных. Предположим, что источник диаграммы содержит два значения x (`XCount = 2`) и `XErrorBarData.ValuePlus` равно 1, тогда второе значение x (хранящееся в `XList[0]`) используется для положительной длины планки погрешности. Если `IndexMinus` равно -1, то предполагается, что длина отрицательной планки погрешности равна длине положительной планки погрешности без необходимости предоставления явного значения в источнике диаграммы.
394	394
395	395		> Note: Использование нескольких значений `y` для других целей, кроме отдельных планок погрешностей, не рекомендуется в этом контексте, поскольку настоящая реализация может отображать планки погрешности только для значения `y` с индексом 0.
396	396
397	397		Каждый тип серии, поддерживающий планки погрешностей, имеет дополнительные свойства `XErrorBars` и `YErrorBars`, которые определяют, как планки погрешностей будут отображаться:
398	398
399	399		- `Visible` можно использовать для отключения планок погрешностей, даже если их размер указан в источнике диаграммы.
400	400		- `Width` - это длина перекладины, нарисованной в конце планки погрешностей. Значение по умолчанию -1 означает, что его длина будет равна соответствующему размеру `Pointer` серии.
401	401		- `Pen` определяет параметр пера, используемый для рисования планок погрешностей. Обычно для `Pen.Color` устанавливается цвет серии.
402	402
403	403		### Список источников
404	404
405	405		`TListChartSource` - это базовый источник диаграммы, хранящий данные диаграммы внутри себя. Таким образом, вы можете использовать функции `Add` и `Delete` для изменения исходных данных.
406	406
407	407		Свойство `Item` возвращает указатель непосредственно на базовое хранилище, поэтому вы можете напрямую изменять поля элемента. Однако это не приведет к автоматическому обновлению диаграммы, а также сделает недействительным некоторое внутреннее состояние списка источника.
408	408
409	409		Рекомендуется:
410	410
411	411		- Чтобы изменить отдельный элемент, используйте процедуры Set{Color\\|Text\\|XValue\\|YValue\\|YList}.
412	412		- Чтобы изменить многие элементы в чувствительном ко времени коде, вызовите `BeginUpdate`, затем измените элементы напрямую, потом вызовите `EndUpdate`.
413	413
414	414		Источник также имеет свойство `DataPoints`, позволяющее задавать данные во время разработки. Это свойство - TStringList, где каждая строка представляет точку данных. Строка состоит из значений X, Y, необязательных значений YList, Color и Text, разделенных символом `\|`(вертикальная черта). Обратите внимание, что свойство `DataPoints` предназначено в первую очередь для создания образцов кода и демок. Оно очень неэффективно, и вы не должны использовать его для добавления точек данных из кода.
415	415
416	416		Вы можете управлять сортировкой значений X, задав свойство `Sorted`. Обратите внимание, когда для параметра `Sorted` установлено значение `true`, список источника сортирует данные и сохраняет их отсортированными после вставки новых точек. Если вставленные точки не отсортированы, это может привести к квадратичному времени выполнения. Вы должны либо установить для `Sorted` значение `true` только после вставки, либо предварительно отсортировать данные, чтобы избежать этого.
417	417
418	418		### Случайный источник
419	419
420	420		Источник `TRandomChartSource` генерирует случайные данные в заданном диапазоне и предназначен в основном для использования в демках. Вы также можете использовать его как замену времени разработки для вашего фактического источника данных. Это позволит вам видеть и изменять внешний вид вашей диаграммы без необходимости запускать приложение.
421	421
422	422		Каждый случайный источник использует свой собственный независимый генератор случайных чисел, чтобы гарантировать стабильность его значений.
423	423
424	424		### Предопределенный пользователем источник
425	425
426	426		Этот источник можно использовать, если у вас уже есть данные в памяти, но в формате отличается от элементов данных, используемых в TAChart. С помощью источника, определяемого пользователем, вы можете напрямую обращаться к своим данным, вместо того, чтобы сначала перемещать их все в список источника. В некоторых случаях это может улучшить производительность или снизить потребление памяти. Конечно, вы также можете генерировать, фильтровать или изменять данные с помощью пользовательского источника.
427	427
428	428		Количество элементов данных в источнике определяется свойством `PointsNumber`. Сами элементы должны быть возвращены обработчиком события `OnGetChartDataItem`. Вы должны вызвать метод `Reset`, чтобы уведомить диаграмму об изменениях данных. (Другие источники обнаруживают изменения и автоматически отправляют уведомление).
429	429
430	430		Обратите внимание: если для свойства `Sorted` установлено значение `true`, это ответственность обработчика событий для предоставления фактически отсортированных данных.
431	431
432	432		### Источник из базы данных
433	433
434	434		`TDbChartSource` берет данные прямо из базы данных. Он содержится в отдельном модуле, чтобы не вводить зависимость компонента с учетом базы данных. в каждый проект с помощью TAChart.
435	435
436	436		Следующие свойства содержат имена полей базы данных для полей элементов данных:
437	437
438	438		\| Свойство \| Метод доступа \|
439	439		\|--------------\|-----------------------------------------------------------\|
440	440		\| `FieldX` \| AsFloat (или AsDateTime, если задана опция dcsoDateTimeX) \|
441	441		\| `FieldY` \| AsFloat (или AsDateTime, если задана опция dcsoDateTimeY) \|
442	442		\| `FieldColor` \| AsInteger \|
443	443		\| `FieldText` \| AsString \|
444	444		\| \| \|
445	445
446	446		Если свойство `FieldX` пусто, вместо него используется RecNo. `NULL` значения кода в полях координат переводятся в [[TAChart documentation/ru\|NaNs]].
447	447
448	448		Чтобы получить источник со множеством значений, задайте для свойства `FieldY` список имен полей, разделенных запятыми. Обратите внимание, что `YCount` будет задан автоматически - попытка задать его вручную вызовет исключение.
449	449
450	450		### Вычисляемый источник
451	451
452	452		`TCalculatedChartSource` - это источник, используемый для управления данными, взятыми из источника `Origin`. Этот источник выполняет преобразования в следующем порядке:
453	453
454	454		- Изменение порядка Y - значения Y источника со множественными значениями могут быть дублированы, удалены или заменены в соответствии со свойством `ReorderYList`, которое представляет собой разделенный запятыми список исходных индексов значений Y. Шаг пропускается, если `ReorderYList` пуст.
455	455		- Накопление - заменяется значения Y каждого элемента функцией соседних значений.
456	456		- Процент - заменяется каждое значение Y на процент от общего количества всех значений Y для этого элемента. Полезно для рисования "столбчатых диаграмм" и диаграмм с областями. Шаг пропускается, если свойство `Percentage` имеет значение `false`.
457	457
458	458		Накопление контролируется несколькими свойствами:
459	459
460	460		`AccumulationRange` контролирует количество элементов для накопления, считая текущий элемент, поэтому `AccumulationRange = 1` отключает накопление. `AccumulationRange = 0` интерпретируется как «бесконечный» диапазон, т.е. запрос на накопление по всем имеющимся данным. Это в основном полезно в сочетании с методом `camSum` для создания совокупных сумм.
461	461
462	462		Обратите внимание, что фактическое количество элементов может быть меньше для точек около начала или конца источника.
463	463
464	464		`AccumulationDirection`:
465	465
466	466		- cadBackward - использовать предыдущие значения из источника,
467	467		- cadForward - использовать следующие значения из источника,
468	468		- cadCenter - используйте предыдущие и следующие значения для общего числа до `2 * AccumulationRange - 1`.
469	469
470	470		`AccumulationMethod`:
471	471
472	472		- camNone - пропустить шаг накопления,
473	473		- camSum - сумма последнего элемента `AccumulationRange`,
474	474		- camAverage - среднее значение последнего элемента `AccumulationRange`,
475	475		- camDerivative - производная конечных разностей, рассчитанная с использованием последнего элемента `AccumulationRange`. Обратите внимание, что метод расчета предполагает эквидистантные значения X и может потерять точность, если расстояние X существенно меняется.
476	476		- camSmoothDerivative - сглаженная производная конечных разностей, более устойчивая к случайным ошибкам измерения в данных.
477	477
478	478		### Интервальный источник
479	479
480	480		`TIntervalChartSource` может предоставить произвольное количество точек в заданном интервале, контролируемом различными свойствами источника. Этот источник является встроенным по умолчанию источником для меток осей. Если вы хотите установить одинаковые [[TAChart documentation/ru\|параметры интервала осей]] для нескольких осей, Вы можете назначить один компонент `TIntervalChartSource` для `Marks.Source` каждой из этих осей.
481	481
482	482		### Источник интервала даты и времени
483	483
484	484		`TDateTimeIntervalChartSource` похож на [[TAChart documentation/ru\|TIntervalChartSource]], но предоставляет метки в формате [[TAChart documentation/ru\|значения даты/времени]]. Этот источник автоматически выбирает подходящий календарный интервал (например, неделя или час) в зависимости от масштаба оси.
485	485
486	486		Обратите внимание, что значения X предоставленных элементов данных - это значения `TDateTime` и значения `Label` содержат отформатированные строки даты и времени. Если вы хотите использовать `TDateTimeIntervalChartSource` в качестве источника меток оси, вам, вероятно, следует установить свойства `Marks.Format` или `Marks.Style`, чтобы использовать предоставленные метки.
487	487
488	488		Если задано свойство `DateTimeFormat`, оно используется для форматирования всех меток. Форматирование выполняется стандартной [SysUtils.FormatDateTime](http://www.freepascal.org/docs-html/rtl/sysutils/formatdatetime.html). Если `DateTimeFormat` пуст, формат выбирается автоматически в зависимости от масштаба.
489	489
490	490		`TDateTimeIntervalChartSource` определяется в модуле [TAIntervalSources](https://github.com/alrieckert/lazarus/blob/master/components/tachart/taintervalsources.pas).
491	491
492	492		### Примечания по оптимизации источников
493	493
494	494		API первичного источника данных допускает произвольный доступ. Тем не менее, многие источники, в частности рандомные, из базы данных и вычисляемые, могут проявлять квадратичное или худшее поведение при случайном доступе. Сам TAChart заботится об использовании только последовательного доступа (хотя может потребоваться несколько проходов). Источники оптимизируют последовательный доступ с помощью внутреннего состояния. Код пользователя должен быть аккуратен, чтобы не сбросить это состояние во время рисования диаграммы из обработчиков событий или кода пользовательской серии.
495	495
496	496		Заметным исключением является [[TAChart documentation/ru\|списочный источник]], который гарантированно обеспечивает быстрый произвольный доступ. Его можно использовать для кеширования медленных источников с помощью процедуры `CopyFrom`.
497	497
498	498		Также обратите внимание, что указатель, возвращаемый функцией `GetItem`, может указывать на внутренний буфер, который будет перезаписан следующим вызовом `GetItem`. Опять же, списочный источник не имеет этого ограничения.
499	499
500	500		## Координаты и оси
501	501
502	502		- Координаты оси (известные в некоторых других приложениях как координаты объекта) — это «сырые» значения координат, полученные из данных. Как следует из названия, координаты оси интерпретируются в терминах конкретной оси — одно и то же значение координаты может иметь разное значение в зависимости от оси, к которой оно применяется.
503	503		- Координаты графика (также известные как мировые координаты) преобразуются из координат оси с использованием преобразования оси, например логарифмического масштаба. Координаты графика общие для всех объектов на графике.
504	504		- Координаты изображения (также известные как координаты экрана) преобразуются из координат графика на основе области просмотра диаграммы. Это преобразование всегда является линейным, и на него могут влиять такие инструменты диаграммы, как масштабирование и панорамирование.
505	505		- Координаты устройства обычно равны координатам экрана, но могут быть скорректированы в соответствии с бэкендом чертежа, чтобы приспособиться к различным физическим разрешениям (значениям DPI). См., например, [[TAChart documentation/ru\|отрисовщик принтера]].
506	506
507	507		Вы можете добавить или удалить произвольное количество осей, отредактировав свойство `AxisList`. По умолчанию диаграмма имеет две оси: одну горизонтальную и одну вертикальную. Они доступны через свойства `BottomAxis` и `LeftAxis`. Обратите внимание, что эти свойства являются псевдонимами для кода `AxisList[0]` и `AxisList[1]`, поэтому, если вы удалите эти оси по умолчанию, доступ к `BottomAxis` и `LeftAxis` вернет `nil`.
508	508
509	509		Визуально ось состоит из осевой линии (нарисованной `AxisPen`), линий сетки (нарисованной `GridPen`), делений, меток и стрелки.
510	510
511	511		Каждая ось рисуется внутри собственного прямоугольника, определяемого размером меток и делений. Назначив нескольким осям один и тот же положительный `Group` номер, вы можете сделать так, чтобы они разделяли одну и ту же прямоугольную область. Сгруппированные оси можно использовать для создания «панелей», когда несколько рядов рисуются на разных участках одного и того же графика.
512	512
513	513		Оси с одинаковым выравниванием, но разными группами, укладываются рядом друг с другом. Вы можете использовать свойство `Margin` для управления расстоянием между такими осями.
514	514
515	515		### Преобразования осей
516	516
517	517		Преобразования осей сгруппированы в компоненте `TChartAxisTransformations`. Он содержит список преобразований, которые применяются в указанном порядке. (Например, выполнение масштабирования до и после логарифмирования даст разные результаты).
518	518
519	519		Чтобы преобразования возымели эффект, следует:
520	520
521	521		- Убедиться, что свойство `Enabled` имеет значение true для всех преобразований.
522	522		- Назначить компонент преобразований свойству `Transformations` хотя бы одной оси.
523	523		- Назначить свойства `AxisIndexX` и/или `AxisIndexY` ряда соответствующему индексу оси.
524	524
525	525		Обратите внимание, что по умолчанию `AxisIndexX` иcode\>AxisIndexY имеют специальное значение -1, что означает «игнорировать преобразования осей». Также обратите внимание, что если вы добавите или удалите оси, индексы могут измениться. Вы можете повернуть серию, назначив `AxisIndexX` вертикальной оси и `AxisIndexY` горизонтальной оси.
526	526
527	527		#### Линейное и логарифмическое преобразование
528	528
529	529		Это простые арифметические преобразования.
530	530
531	531		#### Трансформация с автоматическим масштабированием
532	532
533	533		Чтобы отобразить несколько серий с независимым масштабированием, назначьте их двум или более осям и примените `TAutoScaleAxisTransform` к каждой оси. См. демку "axistransf", страница "Linear", флажок "Auto scale".
534	534
535	535		Используя свойства `MinValue` и `MaxValue`, вы можете управлять координатами на графике автоматически масштабируемого ряда. Например, задав одному преобразованию диапазон от 0 до 1, а другому — диапазон от 1 до 2, вы ограничите все ряды, использующие первое преобразование, верхней половиной диаграммы, а все ряды, использующие второе преобразование в нижнюю половину (при условии, что не осталось неназначенных рядов).
536	536
537	537		#### Совокупное преобразование нормального распределения
538	538
539	539		Используйте `TCumulNormDistrAxisTransform`, чтобы установить [кумулятивное нормальное распределение](https://ru.wikipedia.org/wiki/%D0%A4%D1%83%D0%BD%D0%BA%D1%86%D0%B8%D1%8F_%D1%80%D0%B0%D1%81%D0%BF%D1%80%D0%B5%D0%B4%D0%B5%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F) как преобразование оси. Это может быть полезно при составлении статистических графиков.
540	540
541	541		Обратите внимание, что результат этого преобразования находится в диапазоне от 0 до 1. Рекомендуется соответствующим образом ограничить диапазон осей.
542	542
543	543		См. пример на странице «Нормальное распределение» демки «axistransf».
544	544
545	545		#### Пользовательское преобразование
546	546
547	547		Вы можете создать свою собственную трансформацию либо путем наследования от `TAxisTransform`, или, если вы предпочитаете «визуальное» программирование, используйте `TUserDefinedAxisTransform`. В любом случае есть два основных требования:
548	548
549	549		- функции `AxisToGraph` и `GraphToAxis` должны быть определены везде в диапазоне данных и обратны друг другу (например, теперь избегайте только деления, а также умножения на ноль).
550	550		- Функции должны быть монотонными.
551	551
552	552		### Оси даты и времени
553	553
554	554		Использование значений даты/времени для меток оси является распространенным требованием. Правильный способ сделать это зависит от точного характера ваших данных даты/времени:
555	555
556	556		- Если данные являются актуальными значениями `TDateTime`, используйте его как координату X в пунктах, назначьте [[TAChart documentation/ru\|TDateTimeIntervalChartSource]] `Marks.Source` соответствующей оси, а `Marks.Style` измените на `smsLabel`. `TDateTimeIntervalChartSource` обеспечивает автоматическую маркировку в зависимости от масштаба в широком диапазоне -- от столетий до миллисекунд.
557	557		- Если данные представлены в физических единицах, но вне диапазона значений `TDateTime`, таких как астрономические или микроэлектронные тайминги, используйте их как обычную координату X с пользовательским `Marks.Format`.
558	558		- Если данные представлены в календарных единицах, таких как месяцы и годы, что характерно для финансовых данных, у вас есть несколько вариантов:
559	559		- Если единицы даты «равноудалены» при интерпретации как числа (например, простые числа года), назначьте один и тот же источник данных как для серий, так и для меток осей, а затем используйте пользовательский `Marks.Format`, событие `Axis.OnMarkToText` или поле `Text` элементов данных для форматирования дат в соответствии с вашими требованиями.
560	560		- Если единицы даты не «равноудалены» (например, числа в формате ГГГГММ или даже строки-даты), вместо этого используйте суррогатную координату X (обычно просто точечный индекс) и отображайте даты, используя методы, описанные выше.
561	561		- Предварительно преобразуйте координаты в значения `TDateTime`, затем используйте `TDateTimeIntervalChartSource`, как описано выше.
562	562
563	563		### Диапазоны осей
564	564
565	565		Диапазон оси измеряется в осевых единицах и определяет протяженность ряда, прикрепленного к этой оси. Обычно диапазон осей равен объединению всех экстентов серии, но его можно переопределить с помощью свойства `Range`.
566	566
567	567		Метки осей отображаются внутри диапазона меток осей, который определяется как пересечение:
568	568
569	569		- Логический экстент (преобразованный в координаты оси)
570	570		- Суммарный экстент всех рядов данных этой оси, если `Marks.AtDataOnly = true`
571	571		- Свойство `Marks.Range`.
572	572
573	573		### Интервалы осей
574	574
575	575		Метки осей располагаются вдоль оси через равные промежутки, выбранные графиком. На выбор интервалов можно повлиять с помощью свойства `Intervals`. Это свойство имеет несколько подсвойств, которые применяются в следующем порядке:
576	576
577	577		- Свойство `Options` содержит набор флагов, управляющих использованием других параметров. Если флаг не установлен, соответствующий параметр игнорируется.
578	578		- `NiceSteps` — это строка, содержащая последовательность «множителей шага» — значений с плавающей запятой в диапазоне от 0 до 1, исключая 0. Если это свойство применяется, шаг оси будет равен степени десяти, умноженной на одно из предоставленных значений. Если можно использовать несколько множителей, будет выбран крайний левый. Множители разделяются вертикальной чертой (\\|).
579	579		- Если `NiceSteps` игнорируется или TAChart не может найти подходящий шаг, диапазон оси будет разделен на равные интервалы независимо от количества знаков после запятой в представлении значений меток. В этом случае рекомендуется уменьшить количество видимых цифр в `Marks.Format`.
580	580		- свойства `MinLength` и `MaxLength` устанавливают пределы длины интервала «в единицах изображения» (обычно в пикселях).
581	581		- Свойство `Count` — желаемое количество меток оси. Среди всех шагов оценки, прошедших предыдущие тесты, TChart выбирает тот, который дает количество оценок, ближайшее к `Count`. Если свойство `Count` игнорируется или есть несколько шагов с одинаковым количеством меток, выбирается самый длинный шаг.
582	582		- Свойство `Tolerance` устанавливает максимальное расстояние «в единицах изображения», на которое может быть перемещена метка, чтобы уменьшить длину ее десятичного представления. Это помогает избежать большого количества бессмысленных цифр в заголовках меток, когда предыдущие шаги по какой-то причине не привели к созданию «хороших» меток. Обратите внимание, что на этом этапе игнорируются все предыдущие ограничения, поэтому большие значения`Tolerance` могут привести к значительным искажениям. Часто бывает достаточно установки `Tolerance = 1`.
583	583
584	584		Обратите внимание, что если вы устанавливаете источник диаграммы вручную, свойство `Intervals` может применяться только частично или не применяться вовсе. Например, [[TAChart documentation/ru\|список источника]] не может гарантировать максимальную длину интервала, так как он имеет только конечное число точек. См. также [[TAChart documentation/ru\|интервальный источник диаграммы]].
585	585
586	586		### Положение оси
587	587
588	588		По умолчанию ось выравнивается по стороне диаграммы, соответствующей свойству `Alignment`. Вы можете позиционировать ось по-разному, задав свойства `Position` и `PositionUnits`.
589	589
590	590		Допускаются следующие значения свойства `PositionUnits`:
591	591
592	592		- `cuPercent` -- процент отсечения прямоугольника.
593	593		- `cuGraph` -- абсолютная позиция в координатах графика.
594	594		- `cuPixels` -- позиция в единицах экрана относительно координат по умолчанию.
595	595
596	596		Примечание 1: Если положение оси отличается от значения по умолчанию (`Position = 0` и `PositionUnits = cuPercent`), он будет исключен из расчета полей, поэтому будет казаться, что он перекрывает серию.
597	597
598	598		Примечание 2: `Alignment` влияет не только на положение самой оси, но и на соответствующие метки. Таким образом, если две оси имеют `Position = 50` и `PositionUnits = cuPercent`, но одна имеет `Alignment = calLeft`, а другая `Alignment = calRight`, они будут отображать общую линию оси с метками на разных стороны.
599	599
600	600		См. пример на странице "Position" демку "axis".
601	601
602	602		### Названия осей
603	603
604	604		Если свойство `TextFormat` переключено на `tfHTML`, то HTML-объекты и теги могут быть встроены для специального форматирования заголовков осей, таких как подстрочные/надстрочные индексы или греческие символы. Подробнее см. [[TAChart documentation/ru\|HTML]].
605	605
606	606		### Размер LabelSize
607	607
608	608		Начиная с Lazarus v1.4 оси диаграммы имеют новое свойство `LabelSize`, которое, если оно отличается от `0`, переопределяет автоматический расчет пространства, необходимого для меток осей. `LabelSize` приблизительно определяет пиксели между линией оси и заголовком оси, независимо от размера меток оси. Эту функцию можно использовать для выравнивания линий осей нескольких диаграмм, которые расположены друг над другом или рядом.
609	609
610	610		См. демку «axisalign» и [[TAChart documentation/ru\|графическое объяснение]] для примера.
611	611
612	612		> Note: Если (ненулевое) значение `LabelSize` слишком маленькое, метки осей могут доходить до заголовка оси или даже обрезаться на границе диаграммы.
613	613
614	614		## Экстенты и поля
615	615
616	616		### Экстенты
617	617
618	618		Экстент диаграммы представляет собой прямоугольник в [[TAChart documentation/ru\|координатах графа]].
619	619
620	620		TChart определяет несколько экстентов:
621	621
622	622		- Full extent (полный) -- обычно определяется автоматически как область, охватывающая все данные из рядов и диапазонов осей. Возвращается функцией `GetFullExtent`.
623	623		- Fixed extent(фиксированный) -- определяется свойством `TChart.Extent`. Может частично или полностью переопределить расчет полного экстента.
624	624		- `LogicalExtent` -- запрошенный пользователем экстент для отображения на изображении диаграммы. Запись в это свойство является официальным способом изменения экстента диаграммы с помощью внешнего кода. Например, `LogicalExtent := GetFullExtent` (почти) эквивалентен вызову процедуры `ZoomFull`.
625	625		- `CurrentExtent` -- экстент, фактически отображаемый пользователю. Может отличаться от `LogicalExtent` из-за необходимости резервирования места для ряда [[TAChart documentation/ru\|метки]], внутренней диаграммы [[TAChart documentation/ru\|поля]] и т.д.
626	626
627	627		Значение минимального экстента не может быть больше значения максимального экстента. При попытке установить такие значения будет сгенерировано исключение. Для предотвращения исключений можно использовать процедуру `.Extent.FixTo(aBounds: TDoubleRect)` для установки логических экстентов. Значения в `TDoubleRect` упорядочены следующим образом: \[xmin, ymin, xmax, ymax\].
628	628
629	629		Чтобы инвертировать экстенты, свойство `Inverted` оси (левой, нижней и т.д.) должно быть установлено в `True`.
630	630
631	631		Важно: установка логических экстентов будет работать должным образом, только если для всех `Margins` диаграммы установлено значение 0 (значение по умолчанию — 4), а для параметра `Series.Marks.AutoMargins` для всех рядов диаграммы установлено значение `False` (по умолчанию — `True`). В противном случае запрошенный экстент будет увеличен, чтобы включить в него также `Margins` диаграммы и `Marks` серии.
632	632
633	633		### Extent limits
634	634
635	635		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.
636	636
637	637		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.
638	638
639	639		Extent limits are expressed in graph units.
640	640
641	641		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.
642	642
643	643		### Linked extents
644	644
645	645		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.
646	646
647	647		This is useful for simulating multi-pane chart layouts. See "panes" demo for an example.
648	648
649	649		### Поля
650	650
651	651		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:
652	652
653	653		- Internal (`Margins` property) -- applied after axis drawing. Are also influenced by series marks and series themselves.
654	654		- External (`MarginsExternal` property) -- applied before axis drawing. Are also influenced by axis marks and arrows.
655	655
656	656		Other chart elements, such as legend, title, footer and labels, have margins, too.
657	657
658	658		### Optimization notes
659	659
660	660		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.
661	661
662	662		### Графическое объяснение
663	663
664	664		![](/wiki-images/8/80/TAChart_Margins.png)
665	665
666	666		## Tools
667	667
668	668		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.
669	669
670	670		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.
671	671
672	672		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+).
673	673
674	674		In each user action, tools in the toolset are processed in order, and for each tool:
675	675
676	676		- If `Enabled=false`, the tool is ignored.
677	677		- If `Shift` is not equal to the current shift state, the tool is ignored.
678	678		- Tool is requested to process the action.
679	679		- 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.
680	680		- 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.
681	681
682	682		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.
683	683
684	684		Some tools publish the `EscapeCancels` property which, if set to `true`, cancels the tool operation if the user pressed the ESC key.
685	685
686	686		### Keyboard handling in tools
687	687
688	688		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.
689	689
690	690		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.
691	691
692	692		### Drawing mode
693	693
694	694		Some tools, such as zoom drag or crosshair, display moving shapes over the chart with the mouse movement.
695	695
696	696		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.
697	697
698	698		The display method is controlled by the `DrawingMode` property with the following values:
699	699
700	700		- `tdmXor` -- use XOR method;
701	701		- `tdmNormal` -- use full chart redraw;
702	702		- `tdmDefault` -- use XOR method on widgetsets where it is known to work (Windows and Gtk) and full redraw on others.
703	703
704	704		### Extent tools
705	705
706	706		Extent tools modify the chart's logical extent.
707	707
708	708		Zooming tools can be animated by setting `AnimationSteps` to a value greater then 1 and specifying an appropriate `AnimationInterval` in milliseconds.
709	709
710	710		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.
711	711
712	712		#### Zoom drag tool
713	713
714	714		`TZoomDragTool` allows the user to zoom in by drawing a rectangle with the mouse. The rectangle then becomes the new logical extent.
715	715
716	716		Restoration of the zooming to the full extent can be achieved by several actions, controlled by the `RestoreExtentOn` property:
717	717
718	718		- `zreDragTopLeft`, `zreDragTopRight`, `zreDragBottomLeft`, `zreDragBottomRight` -- dragging in the specified direction,
719	719		- `zreClick` -- clicking without dragging,
720	720		- `zreDifferentDrag` -- dragging in a direction different from the one used to zoom in.
721	721
722	722		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.
723	723
724	724		To get a behavior compatible with earlier versions of Delphi's TeeChart, specify `RestoreExtentOn = [zreDragTopLeft, zreDragTopRight, zreDragBottomLeft]`.
725	725
726	726		To get a behavior compatible with newer versions of TeeChart, specify `RestoreExtentOn = [zreDifferentDrag]`.
727	727
728	728		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.
729	729
730	730		#### Zoom click tool
731	731
732	732		`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".
733	733
734	734		`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`.
735	735
736	736		- 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.
737	737		- 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.
738	738		- 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.
739	739
740	740		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.
741	741
742	742		#### Zoom mouse-wheel tool
743	743
744	744		`TZoomMouseWheelTool` allows the user to zoom in and out with the mouse wheel. Its properties are identical to the zoom click tool.
745	745
746	746		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.
747	747
748	748		#### Pan drag tool
749	749
750	750		`TPanDragTool` allows the user to move the logical extent by dragging the mouse in the directions indicated by the `Directions` property.
751	751
752	752		Use the `MinDragRadius` property to distinguish dragging from clicking.
753	753
754	754		#### Pan click tool
755	755
756	756		`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.
757	757
758	758		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.
759	759
760	760		#### Pan mouse wheel tool
761	761
762	762		`TPanMouseWheelTool` allows the user to move the logical extent by scrolling the mouse wheel.
763	763
764	764		The extent is moved in `WheelUpDirection` when the wheel is scrolled up and in the opposite direction when the wheel is scrolled down.
765	765
766	766		The movement speed is controlled by `Step` property.
767	767
768	768		### Data tools
769	769
770	770		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.
771	771
772	772		When a data tool is activated, it determines the nearest point of the affected series which is located inside of the `GrabRadius` (in pixels).
773	773
774	774		Using the set `Targets: TNearestPointTargets` it can be controlled which part of a complex series must be hit:
775	775
776	776		- `nptPoint`: The tool must hit the data point at (x, y).
777	777		- `nptXList`: If the series' source has several x values the tool must hit any of the values in the XList.
778	778		- `nptYList`: If the series' source has several y values the tool must hit any of the values in the YList.
779	779		- `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.
780	780
781	781		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.
782	782
783	783		For large series, the efficiency can be improved by using a sorted source, a small `GrabRadius` and a `DistanceMode<>cdmOnlyY`.
784	784
785	785		#### Data point drag tool
786	786
787	787		`TDataPointDragTool` allows the user to change data values by dragging the data point. Requires the series' data source to be a list source.
788	788
789	789		You can use the `OnDrag` and `OnDragStart` events to limit drag direction or grab area.
790	790
791	791		See "dragdrop" demo for an example.
792	792
793	793		#### Data point click tool
794	794
795	795		`TDataPointClickTool` allows you to assign an `OnPointClick` event handler, which will be called when the user clicks on the data point.
796	796
797	797		#### Data point hint tool
798	798
799	799		`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.
800	800
801	801		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`.
802	802
803	803		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`).
804	804
805	805		#### Data point crosshair tool
806	806
807	807		`TDataPointCrosshairTool` displays a cross-hair centered on the data point. It replaces the "reticule" found in older versions of TAChart.
808	808
809	809		#### Data point distance tool
810	810
811	811		`TDataPointDistanceTool` allows to measure and display a distance between two points on the chart.
812	812
813	813		### Chart element tools
814	814
815	815		#### Axis click tool
816	816
817	817		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:
818	818
819	819		- `ahtTitle`: click on the axis title
820	820		- `ahtLine`: click on the axis line (allowed tolerance defined by the tool's `GrabRadius` or the axis' `TickLength` and `InnerTickLength` whichever is greater).
821	821		- `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.
822	822		- `ahtAxisStart`: the click on the line or label area occured in the first quarter of the axis length
823	823		- `ahtAxisCenter`: the click on the line or label area occured in the center part (two quarters) of the axis length
824	824		- `ahtAxisEnd`: the click on the line or label area occured in the last quarter of the axis length.
825	825
826	826		#### Title/footer click tool
827	827
828	828		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.
829	829
830	830		#### Legend click tool
831	831
832	832		Generates an `OnClick` event when a click on the chart's legend has occured. The event has the legend as a parameter.
833	833
834	834		### User defined tool
835	835
836	836		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.
837	837
838	838		Call the `Handled` method of the tool to indicate that no further processing of the event should be done.
839	839
840	840		## Decorative elements
841	841
842	842		### Title and footer
843	843
844	844		Chart title and footer are multi-line texts appearing above and below the chart correspondingly. They support various rotations and alignments.
845	845
846	846		#### HTML
847	847
848	848		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.
849	849
850	850		- 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>.\
851	851		Example: The text `sin 2α = 2 sin α cos α` is displayed as "sin 2α = 2 sin α cos α"
852	852		- `<sub>...</sub>` displays the enclosed text as subscript.\
853	853		Example: `H<sub>2</sub>O` is shown in the chart as "H<sub>2</sub>O"
854	854		- `<sup>...</sup>` displays the enclosed text as superscript.\
855	855		Example: `cm<sup>2</sup>` is shown in the chart as "cm<sup>2</sup>"
856	856		- `<b>...</b>` displays the enclosed text with bold type face. \
857	857		Likewise, the tags \<i\>...\</i\>, \<u\>...\</u\>, \<s\>...;\</s\> can be used to format portions of the text as italic, underlined, and strike-out\
858	858		Example: `Plot of <b>x</b> <i>vs.</i> <b>y</b>` is shown in the chart as "Plot of x vs. y"
859	859		- The `<font>...</font>` tags can be used to modify the font of the enclosed text:
860	860		- 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.
861	861		- The font name can be specified by the `name` attribute.
862	862		- 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.
863	863		- Example: This code adds a two-line footer in which the 2nd line is in blue, 8-pt, underlined Times New Roman:
864	864
865	865		``` pascal
866	866		Chart.Foot.Text.Clear;
867	867		Chart.Foot.Text.Add('Reference:');
868	868		Chart.Font.Text.Add('<font name="Times New Roman" size="8pt" color="blue"><u>www.freepascal.org/</u></font>');
869	869		```
870	870
871	871		> Warning: 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
872	872
873	873		The demo application in folder demo/html of the Lazarus installation heavily makes use of embedded HTML codes.
874	874
875	875		### Легенда
876	876
877	877		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.
878	878
879	879		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.
880	880
881	881		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.
882	882
883	883		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.
884	884
885	885		Legend items are sorted as following:
886	886
887	887		- By group index, items without group (`GroupIndex=-1`) going first to avoid confusion with the last group.
888	888		- By `Order` property, items without explicit order (`Order=-1`) going last.
889	889		- By creation order of series.
890	890		- For multiple items per series, by generation order (for standard series it is the order of points).
891	891
892	892		Sorted items are then added to the legend table in either by rows or by columns depending on the `ItemFillOrder` property.
893	893
894	894		#### Legend item text
895	895
896	896		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`](http://www.freepascal.org/docs-html/rtl/sysutils/format.html) function, with the second argument containing following data items:
897	897
898	898		- For per-series multiplicity:
899	899		- 0: Series `Title`
900	900		- 1: Series `Index`
901	901		- For per-point multiplicity:
902	902		- Same as mark labels
903	903
904	904		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.
905	905
906	906		#### User-defined legend items
907	907
908	908		Arbitrary legend items can be generated by overriding `OnCreate` and `OnDraw` events of series `Legend` property.
909	909
910	910		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.
911	911
912	912		### Arrows
913	913
914	914		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.
915	915
916	916		Arrowhead shape is determined by `Width`, `Length` and `BaseLength` properties, for example:
917	917
918	918		- Thin wedge: `BaseLength = 0`
919	919		- Triangle: `BaseLength = Length`
920	920		- Rhombus: `BaseLength = 2 * Length`
921	921		- Inverted Triangle: `BaseLength > 0`, `Length = 0`
922	922
923	923		This image shows these arrows created for `Length=10` and `Width=5`.![](/wiki-images/b/be/TAChart_Arrows.png)\
924	924
925	925		### Transparency
926	926
927	927		`Transparency` property of the series represents a level of transparency from 0 (fully opaque) to 255 (fully transparent -- i.e. invisible).
928	928
929	929		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.
930	930
931	931		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.
932	932
933	933		### ChartStyles
934	934
935	935		`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.
936	936
937	937		## Метки
938	938
939	939		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.
940	940
941	941		You can see examples in the "labels" demo.
942	942
943	943		### Mark labels
944	944
945	945		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`](http://www.freepascal.org/docs-html/rtl/sysutils/format.html) function, with the second argument containing following data items:
946	946
947	947		- 0: Y
948	948		- 1: Y as a percentage of the Y total
949	949		- 2: Text
950	950		- 3: Y total
951	951		- 4: X
952	952
953	953		Where "Y total" is the sum of all Y values for this source. Note that not all sources supply all the items above.
954	954
955	955		Some pre-defined formats can be set via the `Style` property.
956	956
957	957		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.
958	958
959	959		The text is rendered using the `LabelFont`. Note in particular that TAChart supports arbitrary font `Orientation`.
960	960
961	961		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`.
962	962
963	963		#### Multi-line marks
964	964
965	965		If the mark text contains [`LineEnding`](http://www.freepascal.org/docs-html/rtl/system/lineending.html) character sequence, it is split into several lines. Lines of different length are aligned according to `Alignment` property.
966	966
967	967		#### HTML codes in marks
968	968
969	969		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.
970	970
971	971		### Mark positions and attachment
972	972
973	973		The mark position relative to the marked point is determined by the marks owner (series or axis).
974	974
975	975		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.
976	976
977	977		Additionally, basic chart series have a property `MarkPositions` specifying the direction of labels' offsets relative to series data points as following:
978	978
979	979		- 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.
980	980		- lmpPositive -- positive direction of series' Y axis
981	981		- lmpNegative -- negative direction of series' Y axis
982	982		- lmpInside -- towards the center of the data points cloud; for TBarSeries and TAreaSeries: towards the ZeroLevel
983	983
984	984		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`.
985	985
986	986		### Rotation of marks
987	987
988	988		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.
989	989
990	990		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:
991	991
992	992		- raCenter -- default setting, i.e. rotation occurs around the text center
993	993		- raLeft -- the rotation center is at the left edge of the label.
994	994		- raRight -- the rotation center is at the right edge of the text.
995	995		- 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.
996	996
997	997		## Drawers
998	998
999	999		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.
1000	1000
1001	1001		These classes are called drawing back-ends or drawers for short.
1002	1002
1003	1003		### Отрисовщик TCanvas
1004	1004
1005	1005		`TCanvasDrawer` — это отрисовщик по умолчанию, используемый для отображения диаграммы в TCanvas. Это включает в себя экран и различные форматы растровых изображений. Изображение, созданное этим ящиком, используется в качестве эталона при разработке и отладке других серверных частей.
1006	1006
1007	1007		### TFPCanvas drawer
1008	1008
1009	1009		`TFPCanvasDrawer` is similar to TCanvas drawer, but based on `TFPCanvas` (which is a `TCanvas` analog implemented in the FCL instead of the LCL).
1010	1010
1011	1011		See the "nogui" demo for an example.
1012	1012
1013	1013		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.
1014	1014
1015	1015		### SVG drawer
1016	1016
1017	1017		`TSVGDrawer` produces text stream with the image of the chart in [SVG](https://en.wikipedia.org/wiki/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.
1018	1018
1019	1019		See "save" demo for an example.
1020	1020
1021	1021		For this drawer, image unit is an SVG canvas unit instead of a pixel.
1022	1022
1023	1023		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.
1024	1024
1025	1025		### OpenGL drawer
1026	1026
1027	1027		`TOpenGLDrawer` draws chart on the current [OpenGL](https://en.wikipedia.org/wiki/OpenGL) context. It is suitable to be used in games and other OpenGL-only applications.
1028	1028
1029	1029		OpenGL drawer expects, but does not set by itself, an orthogonal projection. See "opengl" demo for an example.
1030	1030
1031	1031		Note that, like in OpenGL itself, `TOpenGLDrawer` font support is extremely limited.
1032	1032
1033	1033		### Отрисовщик принтера
1034	1034
1035	1035		TPrinterDrawer рисует диаграмму на холсте принтера. Он не очищает страницу.
1036	1036
1037	1037		Хотя холст принтера является потомком `TCanvas`, и поэтому печать может выполняться с использованием [[TAChart documentation/ru\|отрисовщика по умолчанию]], `TPrinterDrawer` выполняет правильное масштабирование координат изображения в соответствии с DPI принтера и экрана.
1038	1038
1039	1039		Вы можете использовать этот отрисовщик для экспорта диаграммы в формат PDF с помощью одного из доступных продуктов для записи PDF.
1040	1040
1041	1041		См. пример демку 'print'.
1042	1042
1043	1043		Обратите внимание, что этот отрисовщик находится в отдельном пакете TAChartPrint.
1044	1044
1045	1045		### AggPas drawer
1046	1046
1047	1047		`TAggPasDrawer` draws chart using [AggPas library](http://www.crossgl.com/aggpas).
1048	1048
1049	1049		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.
1050	1050
1051	1051		Note that this drawer is located in a separate TAChartAggPas package.
1052	1052
1053	1053		### BGRABitmap drawer
1054	1054
1055	1055		`TBGRADrawer` draws chart using [[BGRABitmap]] library.
1056	1056
1057	1057		BGRABitmap is recently created and actively developed graphics library, offering, in particular, anti-aliasing and rich selection of gradients.
1058	1058
1059	1059		Currently BGRABitmap supports all TAChart features, but is somewhat slower then other drawing methods.
1060	1060
1061	1061		Note that this drawer is located in a separate TAChartBGRA package, which depends on external `bgrabitmappack` package.
1062	1062
1063	1063		### FPVectorial drawer
1064	1064
1065	1065		`TFPVectorialDrawer` draws chart using [[fpvectorial]] library. FPVectorial offers exporting to various vector formats, including SVG, PDF, CorelDraw and even instructions for metal cutting machines.
1066	1066
1067	1067		It currently has some limitations in TAChart support, but is actively developed.
1068	1068
1069	1069		Note that this drawer is located in a separate `TAChartFPVectorial` package, which depends on `fpvectorialpkg` package.
1070	1070
1071	1071		### WMF drawer
1072	1072
1073	1073		`TWindowsMetafileDrawer` draws chart into a [Windows Metafile](https://en.wikipedia.org/wiki/Windows_Metafile).
1074	1074
1075	1075		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.
1076	1076
1077	1077		## Navigation
1078	1078
1079	1079		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.
1080	1080
1081	1081		Moving extent (but not visualizing it) is possible by using panning tools.
1082	1082
1083	1083		You can see examples in the "navigation" demo.
1084	1084
1085	1085		### Scroll bars
1086	1086
1087	1087		`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.
1088	1088
1089	1089		Setting `AutoPageSize = true` lets `TChartNavScrollBar` to pick page size proportional to the logical extent.
1090	1090
1091	1091		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.
1092	1092
1093	1093		Also note that `TChartNavScrollBar` does not automatically align or attach itself to a chart, so it can be arbitrarily positioned on the form.
1094	1094
1095	1095		### Navigation panel
1096	1096
1097	1097		`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`.
1098	1098
1099	1099		If `MiniMap = true`, the panel additionally displays the chart series.
1100	1100
1101	1101		`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.
1102	1102
1103	1103		## Additional components
1104	1104
1105	1105		### Legend panel
1106	1106
1107	1107		`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.
1108	1108
1109	1109		### Chart listbox
1110	1110
1111	1111		`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.
1112	1112
1113	1113		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.
1114	1114
1115	1115		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.
1116	1116
1117	1117		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.
1118	1118
1119	1119		### Chart image list
1120	1120
1121	1121		`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.
1122	1122
1123	1123		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)`.
1124	1124
1125	1125		In Laz 2.1+ the `TChartImageList` can be used also at designtime. It stores only those images not assigned to a series.
1126	1126
1127	1127		### Chart combobox
1128	1128
1129	1129		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.
1130	1130
1131	1131		The combobox is not linked to a particular chart. Use the `OnChange` event to transfer the modified property to the series.
1132	1132
1133	1133		## TeeChart compatibility
1134	1134
1135	1135		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.
1136	1136
1137	1137		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 [[Comparing TAChart with Delphi&\|comparison page]] for more detailed info.
1138	1138
1139	1139		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.
1140	1140
1141	1141		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.
1142	1142
1143	1143		## Technical details
1144	1144
1145	1145		### Drawing order
1146	1146
1147	1147		Chart drawing consists of three stages:
1148	1148
1149	1149		1. Preparation: At this stage, various internal data structures are initialized.
1150	1150		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.
1151	1151		3. Drawing: At this stage, the actual chart image is displayed.
1152	1152
1153	1153		There also exists an ordering among various chart elements:
1154	1154
1155	1155		1. Background (using `TChart.Color` property).
1156	1156		2. Back-wall (using `TChart.BackColor` property).
1157	1157		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.
1158	1158		4. Legend.
1159	1159		5. Tools.
1160	1160
1161	1161		Note that `ZPosition` works for both 2-D and 3-D charts, so you can overlay series and axes in arbitrary order.
1162	1162
1163	1163		### Coding style
1164	1164
1165	1165		Historically FPC, Lazarus and LCL sources contain a mix of coding styles, with the general rule being "be consistent with the surrounding code".
1166	1166
1167	1167		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.
1168	1168
1169	1169		#### Spaces
1170	1170
1171	1171		- No double spaces anywhere.
1172	1172		- Spaces after: operations, comma, semicolon, assignment, closing parenthesis in expressions (not in function calls).
1173	1173		- Spaces before: operations, assignment, opening parenthesis in expressions (not in function calls).
1174	1174
1175	1175		#### Lines
1176	1176
1177	1177		- No double empty lines anywhere.
1178	1178		- Empty lines between procedures, classes, unit sections. Rare empty lines inside procedure bodies to separate logical blocks.
1179	1179		- Line length below 80 characters, with rare exceptions.
1180	1180		- Single statement per line, except if ... then {exit\\|break\\|continue} and some rare cases of mass assignment.
1181	1181		- 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.
1182	1182
1183	1183		#### Indentation and blocks
1184	1184
1185	1185		- Always two spaces, both for blocks and continuation lines.
1186	1186		- begin on the same line as the control statement, end aligned with the control statement.
1187	1187		- end always alone on the line. In particular, write end else begin on two lines.
1188	1188		- Put then or do on a separate line to separate a complex condition from the statement body:
1189	1189
1190		-	~~` ``while`\~~
1191		-	~~` long condition or`\~~
1192		-	~~` another long condition`\~~
1193		-	~~` ``do`\~~
1194		-	~~` loop body`~~
	1190	+	```text
	1191	+	while
	1192	+	long condition or
	1193	+	another long condition
	1194	+	do
	1195	+	loop body
	1196	+	```
1195	1197
1196	1198		- Use begin/end only when necessary (i. e. not for single statements).
1197	1199
1198	1200		#### Comments
1199	1201
1200	1202		- Put a license header at the beginning of every file.
1201	1203		- Single-line comments everywhere except the license header and auto-generated class headers in implementation section.
1202	1204		- Use only full sentences in comments, starting with a capital letter and ending with a full stop.
1203	1205		- Comments should be placed before commented code, except in rare cases where a comment fits at the end of the same line.
1204	1206		- 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.
1205	1207
1206	1208		#### Names
1207	1209
1208	1210		- Constants use ALL_CAPS_WITH_UNDERSCORE, everything else use CamelCase.
1209	1211		- 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\`\`).
1210	1212		- Class fields start with 'F', arguments start with 'A', types start with 'T', TAChart units start with 'TA'.
1211	1213
1212	1214		#### Variable declarations
1213	1215
1214	1216		- Initialize when possible.
1215	1217		- Local variables after nested procedures unless used by them.
1216	1218		- Group variables by type.
1217	1219
1218	1220		#### Classes and methods
1219	1221
1220	1222		- 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'.
1221	1223		- 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.
1222	1224		- Use strict private/strict protected visibility where possible.
1223	1225
1224	1226		#### Hints and warnings
1225	1227
1226	1228		- Code should compile with zero hints and warnings.
1227	1229		- Silence any "unused parameter" warning with the \`\`Unused\`\` procedure from the TAChartUtils unit, or use the {%H-} Lazarus IDE directive.
1228	1230
1229	1231		#### Control flow
1230	1232
1231	1233		- Use exit or raise to abort method execution in case of a violated pre-condition.
1232	1234		- Use enumerators where possible.
1233	1235		- Use with carefully, and only where its use significantly saves code size and in the minimal possible range.
1234	1236		- Limit all procedures to 50-60 lines, and use nested procedures liberally.
1235	1237
1236	1238		---
1237	1239		From the Free Pascal wiki, page "TAChart documentation/ru", as it stood on 2022-10-18 after a change by Zoltanleo, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).

Back to history