Обзор
editTAChart - это пакет для рисования графиков, схем и других диаграмм. Он сопоставим по функциям, но не полностью совместим с Delphi'йским TeeChart. Одно существенное отличие состоит в том, что некоторые функции (например, источники данных и преобразования осей) реализуются через отдельные компоненты, а не через простые свойства диаграммы. Такая конструкция обеспечивает повышенную гибкость и возможность повторного использования кода, но за счет немного более сложного API.
Этот документ предоставляет краткий, но всесторонний обзор концепций, функций и компонентов TAChart. Пошаговое изучение см. в TAChart Tutorial: Getting started и других учебных пособиях.
В документации описан пакет TAChart, который можно найти в последней версии Lazarus для разработки. Некоторые функции могут быть недоступны в официальной версии Lazarus. Мы рекомендуем вам использовать эту последнюю версию документа, поскольку в ней исправлены и улучшены более старые описания в предыдущих версиях, а также тот факт, что в нее включены сведения о новейших функциях.
Тем не менее, вы можете посмотреть старую версию этого документа, чтобы увидеть состояние документации на момент выпуска Lazarus 1.0.
Серии
edit
Серии (графики, диаграммы) являются центральной частью TAChart. Их иерархия проиллюстрирована на рисунке. Серии, наследуемые от TCustomChartSeries, представляют данные, взятые из ChartSource графическим способом, таким как линии или столбцы; другие серии получают свои данные по-другому.
Диаграмма со сплошной линией
editЭто самый простой тип графика, представляющий «бесконечную» вертикальную или горизонтальную линию. Его можно использовать в качестве «центральной оси» в графиках функций или в качестве перетаскиваемой линии маркера.
Кроме того, установив Active = true, Pen.Style = psClear и UseBounds = true и соответствующий AxisIndexX, он становится «расширителем оси», гарантируя, что данное значение Position всегда будет включена в диапазон оси.
Основные виды диаграмм
editОсновные виды графиков используются наиболее часто и включают в себя line, bar и area серии. Все основные серии могут быть «сложены» с помощью источников со множеством значений. Также все базовые серии полностью поддерживают вращение и 3-D рисунок.
Line-диаграмма
editTLineSeries можно использовать для рисования заданного набора точек, опционально помечая каждую точку данных символом и/или соединяя точки данных линией. Цвет ряда линий определяется свойством SeriesColor.
ColorEach позволяет управлять окраской отдельных точек данных и смежных сегментов линии (цвет точки данных предоставляется источником диаграммы):
ceNone- нет отдельной окраски, даже если цвета назначаются элементу данных диаграммы.cePoint- раскрасить только символ точки данных, но не отрезок.ceLineAfter- применить цвет точки данных к сегменту линии, следующему за точкой данныхceLineBefore- применить цвет точки данных к сегменту перед точкой данныхcePointAndLineAfter, cePointAndLineBefore- как и раньше, но раскрашивает и символ точки данных.
Вы можете получить «пошаговый» вид, установив для свойства LineType значение ltStepXY или ltStepYX.
Используя источник со множеством значений, TLineSeries может обрабатывать несколько значений y для каждого значения x. Если для свойства Stacked установлено значение true, то отдельные значения y отображаются в виде ряда, то есть второе значение y добавляется к первому, а третье значение y ко второму значению и т.д. Обратите внимание, однако, что в отличие от серий bar или area, может быть неясно, что значения данных сгруппированы, и поэтому укладка в виде рядов обычно не рекомендуется в сериях line.
Fast lines
editНекоторые графические пакеты включают в себя специальный график "fast line" для быстрого рисования серии линий из чрезвычайно больших наборов данных (более 10000 точек). TAChart, напротив, содержит оптимизированный быстрый путь внутри стандартного кода серии строк, который обеспечивает сопоставимую скорость рисования.
Серия линий будет нарисована очень быстро, если все следующее верно:
- Нет отметок.
- Нет указателей.
LineTypeне установлено в значениеltFromOrigin.
Некоторые операционные системы/наборы виджетов могут дополнительно требовать, чтобы свойствам были установлены следующие значения LinePen.Style=psSolid и LinePen.Width=1.
Дополнительного быстродействия можно добиться, если установить Source.Sorted=true.
Вы можете измерить скорость рисования линий на вашей платформе с помощью демо «line».
Point-диаграмма
editTLineSeries можно нарисовать как «серию точек», показывающую только символы в позиции точек данных и скрывающую соединительные линии, установив для ShowPoints значение True и LineType для ltNone. Обратите внимание, что SeriesColor применяется только к соединительным линиям; чтобы указать цвет точек, измените Pointer.Brush.Color для заливки и/или Pointer.Pen.Color для цвета линии границы. Свойство Pointer также предоставляет доступ к фигурам (круг, рамка и т.д.) символов (Style).
Bar-диаграмма
editTBarSeries представляет данные в виде набора полос, простирающихся от ZeroLevel до точек данных.
Вы можете контролировать ширину полосы с помощью свойства BarWidthPercent. Обратите внимание, что оно измеряется относительно соседних полос. Если значения X не равноудалены, полосы будут иметь различную ширину. Чтобы предотвратить это, установите BarWidthStyle=bwPercentMin.
Вы можете рисовать несколько полос бок о бок, используя свойство BarOffsetPercent.
Используйте несколько значений Y для создания ряда полос с накоплением (Stacked=true). Начиная с Lazarus 2.0, несколько значений Y также могут отображаться в расположении рядом (Stacked=false).
В дополнение к прямоугольным полосам данные могут быть представлены альтернативными формами: цилиндр, шестиугольная призма, пирамида или конус - см. свойство BarShape, которое поддерживает следующие значения: bsRectangular, bsCylindrical, bsHexPrism, bsPyramid, bsConical. Кроме того, событие OnCustomDrawBar позволяет рисовать столбцы любым заданным пользователем способом.
Area-диаграмма
editTAreaSeries представляет данные в виде многоугольника, продолжающегося вниз от точек данных, либо до линии ZeroLevel, либо к бесконечности (если UseZeroLevel=false).
Вы можете получить «пошаговый» вид, задав свойство ConnectType.
Как и TBarSeries и TLineSeries, ряд областей может принимать несколько значений Y для одного и того же X из источника данных со множеством значений. Эти значения y отображаются в стопке, если для свойства Stacked установлено значение True (его значение по умолчанию). Используйте компонент ChartStyles, чтобы определить внешний вид отдельных слоев. (Обратите внимание, что в версиях Lazarus 1.8.x или более ранних ChartStyles не окрашивают последовательно перекрывающиеся слои).
Свойство Banded (доступно в Lazarus v2.0 +), если установлено в true, подавляет рисование самого низкого уровня стека. Таким образом, полоса значений данных может быть выделена: используйте источник диаграмм с двумя значениями Y - установите первое значение Y на минимум, а второе значение Y на максимальный уровень диапазона. В качестве альтернативы, ширина полосы может быть указана во втором значении Y, если оба свойства Banded и Stacked установлены в true.
Поддержку нескольких значений Y следует применять с осторожностью: при суммировании НЕположительных значений могут получаться графики, которые трудно понять, а ряд непакетированных областей (Stacked=false) может пострадать от того, что данные покрываются другими значениями Y. Кроме того, ZeroLevel следует включать только в самый низкий уровень стека, чтобы избежать необычных результатов.
Трехмерное представление серии может быть получено, если для Depth установлено положительное значение, например, 10 или 20. Обратите внимание, что алгоритм рисования очень прост и, скорее всего, даст неправильно отображение при пересечении кривых, или при отключенных свойствах укладки и объединения.
Диаграмма со множеством значений
editДля графика со множеством значений требуется источник данных со множеством значений и использование дополнительных значений X и/или Y в качестве дополнительных параметров для рисования сложных фигур.
Bubble-диаграмма
editTBubbleSeries представляет данные в виде окружностей переменного радиуса с центром в точках данных. Для этой серии требуется источник с YCount не менее 2, и в качестве радиуса пузырька используется первое дополнительное значение Y.
Свойство OverrideColor позволяет установить цвет внутренней части или края каждого пузырька в отдельности.
Диаграмма Box-and-whiskers
editTBoxAndWhiskerSeries представляет данные в виде прямоугольников с центральной линией и двумя Т-образными формами, выступающими в обоих направлениях. Хотя в статистике ящик с усами (диаграмма размаха) должен основываться на конкретных квартилях данных, TAChart не применяет это, позволяя пользователям рисовать произвольные графики.
Иногда можно использовать серии блоков и усов, чтобы представить другие диаграммы другого значения, но схожего внешнего вида, такие как диаграммы Гантта.
Для этой серии требуется источник с YCount не менее 5, и используются значения Y следующим образом:
| Index | Usage |
|---|---|
| 0 | Нижний ус |
| 1 | Нижняя граница ящика |
| 2 | Центральная линия |
| 3 | Верхняя граница ящика |
| 4 | Верхний ус |
Диаграмма Open-high-low-close
editTOpenHighLowCloseSeries представляет данные в виде вертикальных линий с двумя галочками, как описано здесь.
Обычно требуется YCount не менее 4 и используются значения Y следующим образом:
| Свойство | По умолчанию | Использование |
|---|---|---|
| YIndexLow | 0 | Нижняя точка линии |
| YIndexOpen | 1 | Положение галочки слева |
| YIndexClose | 2 | Положение галочки справа |
| YIndexHigh | 3 | Верхняя точка линии |
хотя предполагается, что значения Y упорядочены в порядке возрастания по приведенной выше таблице, ряды сами упорядочивания не сделают и будут отображать любые предоставленные данные.
Field-диаграмма
editTFieldSeries отображает вектор в каждой точке данных. Вектор рисуется как отрезок с необязательной стрелкой. Линия центрируется по координатам X,Y, хранящимся в источнике диаграммы, ее направление задается дополнительными значениями, хранящимися в XList и YList источника диаграммы. Следовательно, для этого типа серии требуется источник с двумя значениями X и Y:
| Поле элемента данных источника | Использование |
|---|---|
| X | X координата центра линии |
| Y | Y координата центра линии |
| XList[0] | X координата направления линии |
| YList[0] | Y координата направления линии |
Метод AddVector(x,y: Double; vectorx, vectory: Double; ALabel: String = ''; AColor: TColor = clTAColor) помогает правильно назначить все значения внутреннему списку источника.
Чтобы избежать наложения векторов, вызовите метод Normalize Vector(Length: Double),дабы нормализовать их длины так, чтобы самый длинный вектор имел указанную длину.
Параметры стрелки понимаются как проценты от длины вектора, то есть стрелка становится меньше для более коротких векторов.
Круговые диаграммы
editРадиальные серии игнорируют преобразования осей. Вы можете увидеть примеры радиальных рядов в demo "radial".
Pie-диаграмма
editTPieSeries рисует круговые диаграммы.
Для каждой точки данных круговая серия интерпретирует значение Y как относительный размер среза, а значение X как расстояние среза от центра круговой диаграммы (только если свойство Exploded имеет значение true).
Начиная с StartAngle, круговая диаграмма вращается против часовой стрелки по всему кругу.
Радиус круга можно установить вручную с помощью свойства FixedRadius или рассчитать автоматически, чтобы вся серия, включая все метки, точно соответствовала родительской диаграмме.
Кольцо можно нарисовать вместо кругового фрагмента, задав свойству InnerRadiusPercent значение больше 0, но меньше 100 - это определяет радиус внутреннего круга в процентах от общего радиуса.
Цвета кусочка определяются полем Color элементов данных или жестко закодированной палитрой. Контуры срезов отрисовываются с использованием свойства EdgePen.
Существует несколько опций для позиционирования метки, управляемых свойством MarkPositions:
pmpAround-- отметки рисуются вне круговой диаграммы на продолжении или радиус-векторе для каждого кусочкаpmpInside--отметки нарисованы внутри каждого кусочкаpmpLeftRight-- отметки рисуются непосредственно слева или справа от кусочка
MarkDistance определяет расстояние между начальной точкой метки и меткой. Начальная точка определяется MarkPositionCentered как периметр круговой диаграммы (false) или центр (true). MarkDistancePercent, если установлено значение true, интерпретирует Marks.Distance как процент от радиуса круговой диаграммы. В противном случае оно интерпретируется в единицах изображения.
Если RotateLabels имеет значение true, каждая метка дополнительно поворачивается, чтобы (если LabelFont.Orientation=0) она была параллельна радиус-вектору своего кусочка.
Если для значения Y элемента данных установлено значение NaN, он станет скрытым элементом. Если значение X установлено в NaN, элемент не рисуется, но место для него все еще зарезервировано. Это позволяет рисовать «частичные» круговые диаграммы.
Круговые диаграммы имеют ограниченную поддержку для трехмерного рисования. Свойство Depth определяет толщину круга. Orientation дополняет нормальный вид (poNormal) скошенным видом наклонной (poHorHorizontal) и вертикальной (poVertical ) круговой серии, последние две управляются свойством ViewAngle в градусах от 0 до 89. Поскольку TAChart не реализует алгоритм истинной скрытой линии/скрытой поверхности, в некоторых комбинациях могут быть некоторые изменения артефактов рисования параметров.
Polar-диаграмма
editTPolarSeries представляет данные в виде точек в полярной системе координат.
Начало полярной системы координат определяется в координатах графа свойствами OriginX и OriginY.
Для каждой точки данных значение X интерпретируется как угол в радианах, а значение Y - как расстояние от центра.
TPolarSeries не поддерживает преобразования осей.
Некоторые дополнительные свойства:
CloseCircle: если имеет значениеtrue, последняя точка связана с первой.Filled: если имеет зачениеtrue, то многоугольник точек серии заполняется с использованием текущего значенияBrush. ЕслиCloseCircleравно false, заливка отправляется в начало координат.ShowPoints: если имеет значениеtrue, то указатель серии рисуется в позиции каждой точки данных.
Диаграммы с пользовательской отрисовкой
editПредоставляет события OnDraw и OnGetBounds, чтобы разрешить произвольную пользовательскую отрисовку на TChart. Обратите внимание, что использование TChart.Canvas напрямую крайне нежелательно и часто не будет работать должным образом.
Диаграммы функций
editДиаграммы функций - это рекомендуемый способ рисования функциональных графиков, в отличие, например, от предварительного вычисления данных функций и использования line-диаграмм. Они обеспечивают независимый от масштаба контроль плавности и скорости рисования.
Вы можете увидеть примеры функциональных серий в демо "func".
Диаграммы функций
editTFuncSeries представляет одномерную функцию, определенную событием OnCalculate. Функция рассчитывается для каждого свойства Step пикселя изображения, поэтому вы можете использовать его для увеличения «гладкости» или скорости рисования.
Свойство Extent можно использовать для установки экстентов x и y с целью вычисления полного экстента диаграммы. Однако во время рисования это свойство игнорируется, и функция будет отображаться в соответствии с текущим экстентом.
Свойство DomainExclusion позволяет исключить некоторые интервалы из функциональной области. TFuncSeries правильно рисует точки разрыва, установленные DomainExclusion. В настоящее время DomainExclusion можно установить только во время выполнения, вызвав процедуры AddRange или AddPoint. Интервалы, определенные DomainExclusion, по умолчанию закрыты, то есть содержат конечные точки; это означает, что функция не рассчитывается в конечных точках. Если исключение домена должно содержать конечные точки (при необходимости для функции y=sqrt(x)) вызовите AddRange с соответствующим элементом набора TIntervalOptions=(ioOpenStart,ioOpenEnd) в качестве необязательного третьего параметра.
Свойство DomainExclusion.Epsilon контролирует расстояние между конечной точкой и последней нарисованной точкой (конечно, в случае открытого интервала кривая начинается непосредственно в конечной точке). Epsilon можно настроить в тех редких случаях, когда значение по умолчанию 1E-6 не дает правильных результатов.
Диаграммы метаматических выражений
editTExpressionSeries аналогичен TFuncSeries, но функция указана в виде строки математического выражения, например 'sin(1.23456*x)' ( свойство Expression). Диаграмма создает экземпляр FPExpressionParser для анализа строки и вычисления значений функции. Таким образом, функции могут быть нанесены на график во время разработки.
Свойство Params позволяет определять параметры для термина функции; в инспекторе объектов он открывает редактор коллекций, в котором каждый параметр может быть указан его именем (как используется в выражении) и его значением. Если, например, параметр f определен со значением 1.23456, то приведенное выше выражение также можно записать как 'sin(f*x)'.
Аналогично TFuncSeries, исключения доменов поддерживаются для определения областей, в которых функция не может быть рассчитана. Но в соответствии с математическими соглашениями TExpressionSeries требует в свойстве Domain задавать регион, в котором функция определена (дополнение к исключениям домена). Регион задается строкой, такой как 'x >= 0'. Если существует несколько условий, они должны быть разделены двоеточием, например 'x < -1; x > 1'. Двоеточие имеет функцию логического выражения ИЛИ. Интервал определяется как '-1 < x < 1'. Постоянные части условий также могут быть математическими выражениями - в следующем примере точка pi/2 исключается из вычисления значений функции: 'x <> pi/2'. Десятичные числа должны вводиться с точкой в качестве десятичного разделителя, независимо от того, как он определен в системных настройках языка операционной системы.
Параметры и домены должны быть определены до начала ввода выражения, в противном случае парсер сообщит об ошибке.
Диаграммы B-spline
editTBSplineSeries рисует B-сплайн с заданным свойством Degree, используя Алгоритм Де Бора.
Сегменты сплайнов короче пикселей Step представлены прямыми линиями.
Диаграмма Cubic spline
editTCubicSplineSeries рисует кривую данных как кубический сплайн, используя стандартный пакет FPC NumLib.
В Lazarus v2.0+ свойство SplineType позволяет выбирать между сплайнами natural и monotone Hermite, при этом последний избегает превышения интерполяции.
Функция сплайна рассчитывается для каждого Step пикселя изображения, поэтому вы можете использовать это свойство для увеличения «сглаживания» или скорости рисования.
Источник данных должен содержать не менее двух точек и строго увеличивать координаты X (старые версии Lazarus до версии 2.0 требуют, как минимум, 4 точки данных; для меньшего количества точек вместо сплайна рисуется многоугольник, с использованием свойства BadDataPen>, если установлена опция csoDrawFewPoints.)
Если значения X не упорядочены и установлена опция csoDrawUnorderedX, сплайн будет отрисован без учета проблемных точек с использованием BadDataPen.
Параметры csoExtrapolateLeft и csoExtrapolateRight позволяют задавать естественную экстраполяцию слева и справа соответственно.
Fit-диаграммы
editTFitSeries выполняет подгонку методом наименьших квадратов, используя процедуры вычисления, содержащиеся в стандартном пакете Numlib из FPC. Основным соединительным элементом является TAFitLib, который является автономным и может применяться также без TAChart.
Функция подбора выбирается через свойство FitEquation:
fePolynomial: y = b0 + b1x + b2x2 + … + bnxn, где значение n контроллируется свойствомParamCount(ParamCount = n + 1).feLinear: y = a + bxfeExp: y = a * e*bx*fePower: y = a * xbfeCustom: y = b0X0(x) + b1X1(x) + b2X2(x) + … + bnXn(x) где значение n контроллируется свойствомParamCount(ParamCount = n + 1), и Xi(x), i = 0..n, являются «базовыми функциями», которые определяются методомSetFitBasisFunc(AIndex: TFitFuncIndex; AFitFunc: TFitFunc; AFitFuncName: String).AIndex- индекс i базовой функции,1..MaxInt.AFitFuncName- текстовое представление функции, используемой для легенды по умолчанию.AFitFunc- адрес базовой функции Xi(x), которая имеет сигнатуруfunction(x: ArbFloat; Param: Integer): ArbFloatсArbFloat, являющимся общим типом данных с плавающей точкой в FPC Numlib (unit typ). Некоторые базовые функции легко доступны в модуле TAFitLib:
function FitBaseFunc_Const(x: ArbFloat; Param: Integer): ArbFloat; // константа
function FitBaseFunc_Linear(x: ArbFloat; Param: Integer): ArbFloat; // линейный член (x)
function FitBaseFunc_Square(x: ArbFloat; Param: Integer): ArbFloat; // квадратный член (x^2)
function FitBaseFunc_Cube(x: ArbFloat; Param: Integer): ArbFloat; // кубический член (x^3)
function FitBaseFunc_Poly(x: ArbFloat; Param: Integer): ArbFloat; // power term (x^Param)
function FitBaseFunc_Sin(x: ArbFloat; Param: Integer): ArbFloat; // sin(x*Param)
function FitBaseFunc_Cos(x: ArbFloat; Param: Integer): ArbFloat; // cos(x*Param)
По умолчанию параметры b0, b1, ..., a, b варьируются в процессе подбора так, что среднее значение квадратичного отклонения между данными и подобранными кривыми было сведено к минимуму. Однако также возможно поддерживать один или несколько параметров подгонки постоянными, например, чтобы заставить подобранную прямую линию проходить через начало координат. Для этого значения постоянных параметров должны быть указаны в ';' или '|' для разграничения списка строковых значений свойства FixedParams. Порядок значений должен соответствовать порядку подгоночных параметров. Параметры переменных можно оставить пустыми или заменить нечисловой строкой.
Пример: FixedParams='var;2' (или короче: ';2') означает, что первый подходящий параметр является переменной, но второй параметр остается постоянным со значением 2; если имеется более 2 параметров, остальные также считаются переменными.
Диапазон подгонки обычно определяется экстентом диаграммы, но может быть установлен вручную через свойство FitRange. Функция подгонки рисуется по всей оси, если только DrawFitRangeOnly=true.
Когда подгонка завершена, ErrCode диаграммы устанавливается так, чтобы показать, был ли расчет успешным или нет:
fitOK: успешноfitDimError: расчет был прерван, потому что размеры массивов данных (x, y, полоса ошибок y) не совпадают.fitMoreParamsThanValues: расчет не удался, потому что есть больше подгоночных параметров, чем значений данных.fitNoFitParams: расчет прерван, потому что параметры подгонки не указаны. Это может произойти случайно, если все параметры подгонки будут исправлены в свойствеFixedParams.fitSingular: матрица дизайна задачи подгонки оказывается (почти) единственной.fitNoBaseFunction: для случаяFitEquation=feCustomуказано недостаточно базовых функций подгонки.
Метод ErrorMsg создаст текст для сообщения об ошибке из текущего ErrCode.
Событие OnFitComplete вызывается после того, как найдено уравнение подгонки, но до начала рисования. Это хорошее место для запроса результатов процедуры подбора:
Param[AIndex]является наиболее подходящим значением для параметра с указанным индексом,AIndex = 0..ParamCount-1.ParamError[AIndex]сообщает неопределенность ("standard error" (стандартная ошибка) в статистическом выражении) соответствующего параметра подгонки.- Процедура
GetConfidenceLimits(AIndex: Integer; out ALower, AUpper: Double)возвращает диапазон междуALowerиAUpper, в пределах которого ожидается наилучшее соответствие того, что параметр будет найден с вероятностью, указанной вConfidenceLevel(по умолчанию:0.95, т.е. 95%). Param_tValue[AIndex]возвращает значение t-статистики для соответствующего параметра подгонки. Это соотношение стоимости, деленное на стандартную ошибку. Для точного параметра значение t должно быть намного больше 1.Param_pValue[AIndex]- это вероятность того, что любое значениеt, столь же высокое, какParam_tValue, будет случайно получено для данных степеней свободы. Чтобы «доверять» подобранному значению с уверенностью, заданнойConfidenceLevel, значение p должно быть меньше, чем1 - ConfidenceLevel, по умолчанию 0,05.FitStatisticsсообщает о других статистических параметрах, полезных для проверки достоверности подобранной модели или для дальнейших статистических расчетов. Эти данные доступны как свойства или функции этого класса:N(integer): количество точек данных, используемых для подгонки. Обратите внимание, что это может быть меньше точек данных, предоставленных источником диаграммы, поскольку он может содержать значения NaN, которые пропускаются.M(integer): количество подгоночных параметров. Обычно это значениеParamCount, но если определенные параметры вынуждены быть постоянными (FixedParams), их количество вычитается.DOF(integer): "degrees of freedom" (cтепени свободы) - это разницаN - M, важный параметр в статистическом анализе результатов подбора.SST: "total sum of squares" (общая сумма квадратов) - это сумма квадратов члена(y[i] - ymean)/dy[i]по всем точкам данных. Здесьy[i]- это значениеyточки данных с индексомi,dy[i]размера ее полосы ошибок (стандартное отклонение) - или 1, если недоступно, аymean- это среднее значениеy[i]/dy[i]. Количество определяет общее изменение точек данных вокруг их среднего значения.SSE: "error sum of squares" (сумма ошибок квадратов) - изменение точек данных вокруг подогнаной кривой, т.е. сумма((y[i] - ycalc(x[i])/dy[i])^2); здесьycalc(x[i])- вычисленное значение подгоночной кривой в точкеx[i].SSR: "regression sum of squares" (сумма квадратов регрессии) - изменение только подогнанной кривой, то есть сумма((ycalc(x[i]) - ymean)/dy[i])^2.xBar: среднее значение координатxвсех используемых точек данных.SSx: изменение координатxточек данных, то есть сумма(x[i] - xbar)^2.VarCovar[i, j: Integer]: Double: является элементом матрицы дисперсии-ковариации для параметров подгонки при данных индексах.R2: "коэффициент детерминации". Это - соотношениеSSR/SSE, и описывает, насколько сильно разброс данных объясняется подобранной кривой. Значение 1 для идеальной подгонки и 0 для абсолютной без соглашения.AdjR2: был введен для компенсации эффекта, который обычно увеличиваетсяR2, добавляя все больше и больше подходящих параметров.Chi2: другое слово дляSSE. По сути, это статистическая величина, которая минимизируется во время процедуры подбора. Данное значение является минимальным найденным значением.ReducedChi2: этоChi2(или:SSE), которое нормализовано по степеням свободы, то есть изменению данных вокруг подобранной кривой на степень свободы. Должно быть "маленьким" для хорошей подгонки.ResidualStdError: общая стандартная ошибка подгонки. Должно быть "маленьким".pValue: (дробная) вероятность того, что остаточный разброс точек данных вокруг подобранной кривой является случайным. Должно быть высоким, на практике несколько десятков, хотя иногда значения до 0,001 по-прежнему принимаются. Если в подбор не включены никакие полосы ошибок, иногда p оказывается равным 0 или 1 - такие значения следует игнорировать.
- Процедуры
GetLowerConfidenceInterval(const Ax: Double; out AY: Double),GetUpperConfidenceInterval,GetLowerPredictionIntervalиGetUpperPredictionIntervalмогут быть подключены к событиюOnCalculateTFuncSeries, чтобы построить границы нижнего и верхнего доверительных интервалов и интервалов прогнозирования вокруг подобранной кривой. Эти пределы определяют области вокруг подобранной кривой, в пределах которых можно ожидать общую подгоночную кривую (доверительный интервал) или отдельные точки данных (интервал прогнозирования) на основе вероятности, заданнойConfidenceLevel. - Примечание: все эти статистические данные предполагают, что остаточные ошибки соответствуют нормальному распределению и что столбцы ошибок были оценены надлежащим образом.
EquationText возвращает интерфейс IEquationText, который позволяет построить строку, представляющую уравнение соответствия. Вы можете переопределить имена переменных x и y, числовой формат и, наконец, получить строку из функции Get. Обратите внимание, что преобразование из IEquationText в String определено, поэтому обычно нет необходимости явно вызывать Get.
Legend.Format-свойство fit series поддерживает дополнительный аргумент формата ('%2:s'), указывающий на текст уравнения по умолчанию.
После изменения параметров TFitSeries уравнение будет пересчитано на следующем отрисовке диаграммы. Чтобы немедленно пересчитать его, вызовите процедуру ExecFit. Используйте свойство State, чтобы проверить правильность текущего уравнения.
Диаграмма цветовых карт
editTColorMapSeries представляет собой двумерную функцию, определенную событием OnCalculate как поле пикселей, цвет которого зависит от значения функции.
Диаграмма отображается в виде набора прямоугольников размером StepX с помощью StepY пикселей. Функция вызывается один раз для каждого прямоугольника.
Цветовые значения определяются одной из встроенных палитр (свойство BuiltinPalette = cmpHot, cmpCold, cmpRainbow, cmpMonochrome). Диапазон значений, сопоставленных с цветами палитры, должен быть указан в BuiltinPaletteMax и BuiltinPaletteMin, иначе результаты не будут предсказуемыми.
Альтернативно, внешний ChartSource может быть назначен свойству ColorSource, которое должно быть отсортировано. Каждая точка данных источника диаграммы интерпретируется как имеющая значение X, соответствующая значению Color. Если фактическое значение попадает между уровнями цвета, оно может быть либо линейно интерполировано (если Interpolate равно true), либо округлено до ближайшего уровня.
В случае, когда Legend.Multiplicity=lmPoint, диаграмма цветовых карт будет отображать уровни цвета в Легенде.
Диаграмма цветовых карт выражения
editаналогична диаграмме цветовых карт с тем отличием, что двумерная функция определяется не событием, а математическим выражением, таким как x^2+y^2, как и в TExpressionSeries, но теперь с двумя переменными x и y. Переменные могут быть переименованы с помощью свойств VariableNameX и VariableNameY. Аналогично TExpressionSeries также можно вводить параметры (свойство Params). Домены, однако, не поддерживаются, функция должна быть определена во всем видимом диапазоне x/y.
Источники
edit
Данные могут попасть в график из разных источников. Они реализованы как набор компонентов, производных от TCustomChartSource.
Чтобы назначить источник диаграмме, вы можете задать свойство Source. Если свойство оставлено неназначенным, диаграмма будет использовать свой собственный встроенный список источников. Такие методы, как AddXY, делегируются текущему источнику диаграммы. Обратите внимание, что список источника является единственным редактируемым источником, поэтому после назначения, например, случайного источника диаграммы для серии, вызов AddXY вызовет исключение.
Каждый элемент данных имеет следующие поля: X, Y, XList, YList, Color, Text.
Отсортированные источники
editЕсли известно, что значения X источника возрастают, возможны некоторые дополнительные оптимизации, такие как бинарный поиск. Таким образом, все источники имеют свойство IsSorted, которое помогает определить это.
В Lazarus 2.1+ TListChartSource можно отсортировать по нескольким критериям:
SortBy=sbX,sbY,sbText,sbColor,sbCustom: сортировка по значению X или Y, тексту, цвету или определенным пользователем способом соответственно. В последнем случае должен быть предоставлен обработчик для событияOnCompare.SortIndex: индекс значений X или Y, используемый для сортировки.SortDir=sdAscending,sdDescending: сортировка в порядке возрастания или убывания.
Когда источник сортируется по чему-либо, кроме x, это влияет только на порядок отрисовки связанных рядов, и возможно, что на диаграмме ничего не изменится. Визуальный эффект заметен для
TPieSeriesпотому что порядок точек данных определяет порядок срезов по кругуTBubbleSeriesкогда пузырьки перекрываются. Используйте сочетаниеSortBy=sbY,SortIndex=1иSortDir=sdDescending, чтобы избежать покрытия пузырьков, потому что сначала появляются большие пузырьки, а маленькие - последними.- все серии унаследованы от
TBasicPointSeries, когдаXCountсвязанного источника диаграммы равен 0: в этом случае значение X источника игнорируется и заменяется индексом точки данных. Поскольку индекс точек данных изменяется при сортировке, точки данных будут автоматически переставлены в отсортированном порядке - см. Пример sort_demo в папке demo.
Источники с множеством значений
editИсточники могут содержать несколько значений Y для каждого значения X. Эти значения хранятся в поле YList исходного элемента данных. Количество значений Y определяется свойством YCount. Обратите внимание, что первое значение Y в любом случае сохраняется в поле Y, поэтому YCount=3 означает, что значения хранятся в Y, YList[0] и YList[1].
Дополнительные значения могут использоваться в различных сериях - например, столбчатые диаграммы с накоплением или пузырьковые диаграммы.
Более того, также возможно сохранять несколько значений X для одной и той же точки данных. Это требуется для TFieldSeries. Эти дополнительные значения X хранятся в XList исходного элемента данных. Как и в случае со значениями Y, общее количество значений X задается свойством XCount, которое содержит "обычное" значение X плюс длину массива XList.
Пропуск исходных элементов
editМожно указать TAChart пропустить рисование некоторых исходных элементов, не удаляя их из источника. Это может быть полезно как для оптимизации, так и для пользовательского интерфейса.
Чтобы пропустить элемент, присвойте NaN либо значению X, либо одному из значений Y. Точный эффект пропуска зависит от серии, но обычно установка X в NaN означает пропуск всего элемента, в то время как установка Y или некоторого элемента YList означает пропуск только этого значения Y, при этом все еще отрисовывая другие.
Также обратите внимание, что если вы установите NaN только для одной координаты, другая все равно будет участвовать в вычислении экстента.
В случае составных серий неясно, как следует обрабатывать отсутствующее значение, когда к нему добавляются следующие уровни. В Lazarus v2.1 + есть свойство StackedNaN, которое можно выбрать как
snReplaceByZero- отсутствующее значение считается нулевым; это как Excel обрабатывает этот случай.snDoNotDraw- пропускает всю точку данных со всеми уровнями стека.
Вы можете увидеть примеры пропуска элементов в демо "nan".
Планки погрешностей
editTLineSeries, TBSplineSeries, TCubicSplineSeries и TFitSeries могут отображать планки погрешностей(error bars) в каждой точке данных. Размер планок погрешностей в направлениях x и y определяется параметрами в свойствах XErrorBarData и YErrorBarData соответственно:
Kind: TChartErrorBarKind: определяет, как интерпретируются следующие данныеebkNone: игнорировать - планки погрешностей отображаться не будутebkConst: все точки данных имеют одинаковую планку погрешности, заданнуюValuePlusиValueMinus.ebkPercent: значенияValuePlusиValueMinusпонимаются как процент от значений данных.ebkChartSource: каждая точка данных может иметь отдельную планку погрешности. Длина планок погрешностей сохраняется в XList или YList источника многозначной диаграммы. Индекс среди всех значений x и y задаетсяIndexPlusиIndexMinusдля положительной и отрицательной планки погрешности соответственно.
ValuePlusиValueMinus: длина столбцов положительных и отрицательных погрешностей соответственно. В зависимости от настройкиKindпредполагается, что значение является постоянным для всех точек данных (Kind = ebkConst, единицы оси) или в процентах от значения точки данных (Kind = ebkPercent). Оба значения должны быть положительными числами, за исключениемValueMinus = -1, который указывает, что отрицательная планка погрешности должна быть равна положительной планке погрешности.IndexPlusиIndexMinusиспользуются, когдаKindравенebkChartSourceи указывают индекс x или y в многозначном chartsource, из которого можно получить длину планки погрешности для отдельных точек данных. Предположим, что источник диаграммы содержит два значения x (XCount = 2) иXErrorBarData.ValuePlusравно 1, тогда второе значение x (хранящееся вXList[0]) используется для положительной длины планки погрешности. ЕслиIndexMinusравно -1, то предполагается, что длина отрицательной планки погрешности равна длине положительной планки погрешности без необходимости предоставления явного значения в источнике диаграммы.
Использование нескольких значений y для других целей, кроме отдельных планок погрешностей, не рекомендуется в этом контексте, поскольку настоящая реализация может отображать планки погрешности только для значения y с индексом 0.
Каждый тип серии, поддерживающий планки погрешностей, имеет дополнительные свойства XErrorBars и YErrorBars, которые определяют, как планки погрешностей будут отображаться:
Visibleможно использовать для отключения планок погрешностей, даже если их размер указан в источнике диаграммы.Width- это длина перекладины, нарисованной в конце планки погрешностей. Значение по умолчанию -1 означает, что его длина будет равна соответствующему размеруPointerсерии.Penопределяет параметр пера, используемый для рисования планок погрешностей. Обычно дляPen.Colorустанавливается цвет серии.
Список источников
editTListChartSource - это базовый источник диаграммы, хранящий данные диаграммы внутри себя. Таким образом, вы можете использовать функции Add и Delete для изменения исходных данных.
Свойство Item возвращает указатель непосредственно на базовое хранилище, поэтому вы можете напрямую изменять поля элемента. Однако это не приведет к автоматическому обновлению диаграммы, а также сделает недействительным некоторое внутреннее состояние списка источника.
Рекомендуется:
- Чтобы изменить отдельный элемент, используйте процедуры Set{Color|Text|XValue|YValue|YList}.
- Чтобы изменить многие элементы в чувствительном ко времени коде, вызовите
BeginUpdate, затем измените элементы напрямую, потом вызовитеEndUpdate.
Источник также имеет свойство DataPoints, позволяющее задавать данные во время разработки. Это свойство - TStringList, где каждая строка представляет точку данных. Строка состоит из значений X, Y, необязательных значений YList, Color и Text, разделенных символом |(вертикальная черта). Обратите внимание, что свойство DataPoints предназначено в первую очередь для создания образцов кода и демок. Оно очень неэффективно, и вы не должны использовать его для добавления точек данных из кода.
Вы можете управлять сортировкой значений X, задав свойство Sorted. Обратите внимание, когда для параметра Sorted установлено значение true, список источника сортирует данные и сохраняет их отсортированными после вставки новых точек. Если вставленные точки не отсортированы, это может привести к квадратичному времени выполнения. Вы должны либо установить для Sorted значение true только после вставки, либо предварительно отсортировать данные, чтобы избежать этого.
Случайный источник
editИсточник TRandomChartSource генерирует случайные данные в заданном диапазоне и предназначен в основном для использования в демках.
Вы также можете использовать его как замену времени разработки для вашего фактического источника данных.
Это позволит вам видеть и изменять внешний вид вашей диаграммы без необходимости запускать приложение.
Каждый случайный источник использует свой собственный независимый генератор случайных чисел, чтобы гарантировать стабильность его значений.
Предопределенный пользователем источник
editЭтот источник можно использовать, если у вас уже есть данные в памяти, но в формате отличается от элементов данных, используемых в TAChart. С помощью источника, определяемого пользователем, вы можете напрямую обращаться к своим данным, вместо того, чтобы сначала перемещать их все в список источника. В некоторых случаях это может улучшить производительность или снизить потребление памяти. Конечно, вы также можете генерировать, фильтровать или изменять данные с помощью пользовательского источника.
Количество элементов данных в источнике определяется свойством PointsNumber.
Сами элементы должны быть возвращены обработчиком события OnGetChartDataItem.
Вы должны вызвать метод Reset, чтобы уведомить диаграмму об изменениях данных.
(Другие источники обнаруживают изменения и автоматически отправляют уведомление).
Обратите внимание: если для свойства Sorted установлено значение true, это ответственность
обработчика событий для предоставления фактически отсортированных данных.
Источник из базы данных
editTDbChartSource берет данные прямо из базы данных.
Он содержится в отдельном модуле, чтобы не вводить зависимость компонента с учетом базы данных.
в каждый проект с помощью TAChart.
Следующие свойства содержат имена полей базы данных для полей элементов данных:
| Свойство | Метод доступа |
|---|---|
FieldX |
AsFloat (или AsDateTime, если задана опция dcsoDateTimeX) |
FieldY |
AsFloat (или AsDateTime, если задана опция dcsoDateTimeY) |
FieldColor |
AsInteger |
FieldText |
AsString |
Если свойство FieldX пусто, вместо него используется RecNo.
NULL значения кода в полях координат переводятся в NaNs.
Чтобы получить источник со множеством значений, задайте для свойства FieldY список имен полей, разделенных запятыми.
Обратите внимание, что YCount будет задан автоматически - попытка задать его вручную вызовет исключение.
Вычисляемый источник
editTCalculatedChartSource - это источник, используемый для управления данными, взятыми из источника Origin.
Этот источник выполняет преобразования в следующем порядке:
- Изменение порядка Y - значения Y источника со множественными значениями могут быть дублированы, удалены или заменены в соответствии со свойством
ReorderYList, которое представляет собой разделенный запятыми список исходных индексов значений Y. Шаг пропускается, еслиReorderYListпуст. - Накопление - заменяется значения Y каждого элемента функцией соседних значений.
- Процент - заменяется каждое значение Y на процент от общего количества всех значений Y для этого элемента. Полезно для рисования "столбчатых диаграмм" и диаграмм с областями. Шаг пропускается, если свойство
Percentageимеет значениеfalse.
Накопление контролируется несколькими свойствами:
AccumulationRange контролирует количество элементов для накопления, считая текущий элемент,
поэтому AccumulationRange = 1 отключает накопление.
AccumulationRange = 0 интерпретируется как «бесконечный» диапазон, т.е. запрос на накопление по всем
имеющимся данным. Это в основном полезно в сочетании с методом camSum для создания
совокупных сумм.
Обратите внимание, что фактическое количество элементов может быть меньше для точек около начала или конца источника.
AccumulationDirection:
- cadBackward - использовать предыдущие значения из источника,
- cadForward - использовать следующие значения из источника,
- cadCenter - используйте предыдущие и следующие значения для общего числа до
2 * AccumulationRange - 1.
AccumulationMethod:
- camNone - пропустить шаг накопления,
- camSum - сумма последнего элемента
AccumulationRange, - camAverage - среднее значение последнего элемента
AccumulationRange, - camDerivative - производная конечных разностей, рассчитанная с использованием последнего элемента
AccumulationRange. Обратите внимание, что метод расчета предполагает эквидистантные значения X и может потерять точность, если расстояние X существенно меняется. - camSmoothDerivative - сглаженная производная конечных разностей, более устойчивая к случайным ошибкам измерения в данных.
Интервальный источник
editTIntervalChartSource может предоставить произвольное количество точек в заданном интервале, контролируемом различными свойствами источника.
Этот источник является встроенным по умолчанию источником для меток осей.
Если вы хотите установить одинаковые параметры интервала осей для нескольких осей,
Вы можете назначить один компонент TIntervalChartSource для Marks.Source каждой из этих осей.
Источник интервала даты и времени
editTDateTimeIntervalChartSource похож на TIntervalChartSource, но предоставляет метки в формате значения даты/времени. Этот источник автоматически выбирает подходящий календарный интервал (например, неделя или час) в зависимости от масштаба оси.
Обратите внимание, что значения X предоставленных элементов данных - это значения TDateTime и значения Label содержат отформатированные строки даты и времени. Если вы хотите использовать TDateTimeIntervalChartSource в качестве источника меток оси, вам, вероятно, следует установить свойства Marks.Format или Marks.Style, чтобы использовать предоставленные метки.
Если задано свойство DateTimeFormat, оно используется для форматирования всех меток.
Форматирование выполняется стандартной SysUtils.FormatDateTime.
Если DateTimeFormat пуст, формат выбирается автоматически в зависимости от масштаба.
TDateTimeIntervalChartSource определяется в модуле TAIntervalSources.
Примечания по оптимизации источников
editAPI первичного источника данных допускает произвольный доступ. Тем не менее, многие источники, в частности рандомные, из базы данных и вычисляемые, могут проявлять квадратичное или худшее поведение при случайном доступе. Сам TAChart заботится об использовании только последовательного доступа (хотя может потребоваться несколько проходов). Источники оптимизируют последовательный доступ с помощью внутреннего состояния. Код пользователя должен быть аккуратен, чтобы не сбросить это состояние во время рисования диаграммы из обработчиков событий или кода пользовательской серии.
Заметным исключением является списочный источник, который гарантированно обеспечивает быстрый произвольный доступ. Его можно использовать для кеширования медленных источников с помощью процедуры CopyFrom.
Также обратите внимание, что указатель, возвращаемый функцией GetItem, может указывать на внутренний буфер, который будет перезаписан следующим вызовом GetItem. Опять же, списочный источник не имеет этого ограничения.
Координаты и оси
edit- Координаты оси (известные в некоторых других приложениях как координаты объекта) — это «сырые» значения координат, полученные из данных. Как следует из названия, координаты оси интерпретируются в терминах конкретной оси — одно и то же значение координаты может иметь разное значение в зависимости от оси, к которой оно применяется.
- Координаты графика (также известные как мировые координаты) преобразуются из координат оси с использованием преобразования оси, например логарифмического масштаба. Координаты графика общие для всех объектов на графике.
- Координаты изображения (также известные как координаты экрана) преобразуются из координат графика на основе области просмотра диаграммы. Это преобразование всегда является линейным, и на него могут влиять такие инструменты диаграммы, как масштабирование и панорамирование.
- Координаты устройства обычно равны координатам экрана, но могут быть скорректированы в соответствии с бэкендом чертежа, чтобы приспособиться к различным физическим разрешениям (значениям DPI). См., например, отрисовщик принтера.
Вы можете добавить или удалить произвольное количество осей, отредактировав свойство AxisList. По умолчанию диаграмма имеет две оси: одну горизонтальную и одну вертикальную. Они доступны через свойства BottomAxis и LeftAxis. Обратите внимание, что эти свойства являются псевдонимами для кода AxisList[0] и AxisList[1], поэтому, если вы удалите эти оси по умолчанию, доступ к BottomAxis и LeftAxis вернет nil.
Визуально ось состоит из осевой линии (нарисованной AxisPen), линий сетки (нарисованной GridPen), делений, меток и стрелки.
Каждая ось рисуется внутри собственного прямоугольника, определяемого размером меток и делений. Назначив нескольким осям один и тот же положительный Group номер, вы можете сделать так, чтобы они разделяли одну и ту же прямоугольную область. Сгруппированные оси можно использовать для создания «панелей», когда несколько рядов рисуются на разных участках одного и того же графика.
Оси с одинаковым выравниванием, но разными группами, укладываются рядом друг с другом. Вы можете использовать свойство Margin для управления расстоянием между такими осями.
Преобразования осей
editПреобразования осей сгруппированы в компоненте TChartAxisTransformations. Он содержит список преобразований, которые применяются в указанном порядке. (Например, выполнение масштабирования до и после логарифмирования даст разные результаты).
Чтобы преобразования возымели эффект, следует:
- Убедиться, что свойство
Enabledимеет значение true для всех преобразований. - Назначить компонент преобразований свойству
Transformationsхотя бы одной оси. - Назначить свойства
AxisIndexXи/илиAxisIndexYряда соответствующему индексу оси.
Обратите внимание, что по умолчанию AxisIndexX иcode>AxisIndexY имеют специальное значение -1, что означает «игнорировать преобразования осей». Также обратите внимание, что если вы добавите или удалите оси, индексы могут измениться. Вы можете повернуть серию, назначив AxisIndexX вертикальной оси и AxisIndexY горизонтальной оси.
Линейное и логарифмическое преобразование
editЭто простые арифметические преобразования.
Трансформация с автоматическим масштабированием
editЧтобы отобразить несколько серий с независимым масштабированием, назначьте их двум или более осям и примените TAutoScaleAxisTransform к каждой оси. См. демку "axistransf", страница "Linear", флажок "Auto scale".
Используя свойства MinValue и MaxValue, вы можете управлять координатами на графике автоматически масштабируемого ряда. Например, задав одному преобразованию диапазон от 0 до 1, а другому — диапазон от 1 до 2, вы ограничите все ряды, использующие первое преобразование, верхней половиной диаграммы, а все ряды, использующие второе преобразование в нижнюю половину (при условии, что не осталось неназначенных рядов).
Совокупное преобразование нормального распределения
editИспользуйте TCumulNormDistrAxisTransform, чтобы установить кумулятивное нормальное распределение как преобразование оси. Это может быть полезно при составлении статистических графиков.
Обратите внимание, что результат этого преобразования находится в диапазоне от 0 до 1. Рекомендуется соответствующим образом ограничить диапазон осей.
См. пример на странице «Нормальное распределение» демки «axistransf».
Пользовательское преобразование
editВы можете создать свою собственную трансформацию либо путем наследования от TAxisTransform, или, если вы предпочитаете «визуальное» программирование, используйте TUserDefinedAxisTransform.
В любом случае есть два основных требования:
- функции
AxisToGraphиGraphToAxisдолжны быть определены везде в диапазоне данных и обратны друг другу (например, теперь избегайте только деления, а также умножения на ноль). - Функции должны быть монотонными.
Оси даты и времени
editИспользование значений даты/времени для меток оси является распространенным требованием. Правильный способ сделать это зависит от точного характера ваших данных даты/времени:
- Если данные являются актуальными значениями
TDateTime, используйте его как координату X в пунктах, назначьтеTDateTimeIntervalChartSourceMarks.Sourceсоответствующей оси, аMarks.Styleизмените наsmsLabel.TDateTimeIntervalChartSourceобеспечивает автоматическую маркировку в зависимости от масштаба в широком диапазоне -- от столетий до миллисекунд. - Если данные представлены в физических единицах, но вне диапазона значений
TDateTime, таких как астрономические или микроэлектронные тайминги, используйте их как обычную координату X с пользовательскимMarks.Format. - Если данные представлены в календарных единицах, таких как месяцы и годы, что характерно для финансовых данных, у вас есть несколько вариантов:
- Если единицы даты «равноудалены» при интерпретации как числа (например, простые числа года), назначьте один и тот же источник данных как для серий, так и для меток осей, а затем используйте пользовательский
Marks.Format, событиеAxis.OnMarkToTextили полеTextэлементов данных для форматирования дат в соответствии с вашими требованиями. - Если единицы даты не «равноудалены» (например, числа в формате ГГГГММ или даже строки-даты), вместо этого используйте суррогатную координату X (обычно просто точечный индекс) и отображайте даты, используя методы, описанные выше.
- Предварительно преобразуйте координаты в значения
TDateTime, затем используйтеTDateTimeIntervalChartSource, как описано выше.
- Если единицы даты «равноудалены» при интерпретации как числа (например, простые числа года), назначьте один и тот же источник данных как для серий, так и для меток осей, а затем используйте пользовательский
Диапазоны осей
editДиапазон оси измеряется в осевых единицах и определяет протяженность ряда, прикрепленного к этой оси.
Обычно диапазон осей равен объединению всех экстентов серии, но его можно переопределить с помощью свойства Range.
Метки осей отображаются внутри диапазона меток осей, который определяется как пересечение:
- Логический экстент (преобразованный в координаты оси)
- Суммарный экстент всех рядов данных этой оси, если
Marks.AtDataOnly = true - Свойство
Marks.Range.
Интервалы осей
editМетки осей располагаются вдоль оси через равные промежутки, выбранные графиком.
На выбор интервалов можно повлиять с помощью свойства Intervals. Это свойство имеет несколько подсвойств, которые применяются в следующем порядке:
- Свойство
Optionsсодержит набор флагов, управляющих использованием других параметров. Если флаг не установлен, соответствующий параметр игнорируется. NiceSteps— это строка, содержащая последовательность «множителей шага» — значений с плавающей запятой в диапазоне от 0 до 1, исключая 0. Если это свойство применяется, шаг оси будет равен степени десяти, умноженной на одно из предоставленных значений. Если можно использовать несколько множителей, будет выбран крайний левый. Множители разделяются вертикальной чертой (|).- Если
NiceStepsигнорируется или TAChart не может найти подходящий шаг, диапазон оси будет разделен на равные интервалы независимо от количества знаков после запятой в представлении значений меток. В этом случае рекомендуется уменьшить количество видимых цифр вMarks.Format. - свойства
MinLengthиMaxLengthустанавливают пределы длины интервала «в единицах изображения» (обычно в пикселях). - Свойство
Count— желаемое количество меток оси. Среди всех шагов оценки, прошедших предыдущие тесты, TChart выбирает тот, который дает количество оценок, ближайшее кCount. Если свойствоCountигнорируется или есть несколько шагов с одинаковым количеством меток, выбирается самый длинный шаг. - Свойство
Toleranceустанавливает максимальное расстояние «в единицах изображения», на которое может быть перемещена метка, чтобы уменьшить длину ее десятичного представления. Это помогает избежать большого количества бессмысленных цифр в заголовках меток, когда предыдущие шаги по какой-то причине не привели к созданию «хороших» меток. Обратите внимание, что на этом этапе игнорируются все предыдущие ограничения, поэтому большие значенияToleranceмогут привести к значительным искажениям. Часто бывает достаточно установкиTolerance = 1.
Обратите внимание, что если вы устанавливаете источник диаграммы вручную, свойство Intervals может применяться только частично или не применяться вовсе. Например, список источника не может гарантировать максимальную длину интервала, так как он имеет только конечное число точек. См. также интервальный источник диаграммы.
Положение оси
editПо умолчанию ось выравнивается по стороне диаграммы, соответствующей свойству Alignment.
Вы можете позиционировать ось по-разному, задав свойства Position и PositionUnits.
Допускаются следующие значения свойства PositionUnits:
cuPercent-- процент отсечения прямоугольника.cuGraph-- абсолютная позиция в координатах графика.cuPixels-- позиция в единицах экрана относительно координат по умолчанию.
Примечание 1: Если положение оси отличается от значения по умолчанию (Position = 0 и PositionUnits = cuPercent), он будет исключен из расчета полей, поэтому будет казаться, что он перекрывает серию.
Примечание 2: Alignment влияет не только на положение самой оси, но и на соответствующие метки. Таким образом, если две оси имеют Position = 50 и PositionUnits = cuPercent, но одна имеет Alignment = calLeft, а другая Alignment = calRight, они будут отображать общую линию оси с метками на разных стороны.
См. пример на странице "Position" демку "axis".
Названия осей
editЕсли свойство TextFormat переключено на tfHTML, то HTML-объекты и теги могут быть встроены для специального форматирования заголовков осей, таких как подстрочные/надстрочные индексы или греческие символы. Подробнее см. HTML.
Размер LabelSize
editНачиная с Lazarus v1.4 оси диаграммы имеют новое свойство LabelSize, которое, если оно отличается от 0, переопределяет автоматический расчет пространства, необходимого для меток осей. LabelSize приблизительно определяет пиксели между линией оси и заголовком оси, независимо от размера меток оси. Эту функцию можно использовать для выравнивания линий осей нескольких диаграмм, которые расположены друг над другом или рядом.
См. демку «axisalign» и графическое объяснение для примера.
Если (ненулевое) значение LabelSize слишком маленькое, метки осей могут доходить до заголовка оси или даже обрезаться на границе диаграммы.
Экстенты и поля
editЭкстенты
editЭкстент диаграммы представляет собой прямоугольник в координатах графа.
TChart определяет несколько экстентов:
- Full extent (полный) -- обычно определяется автоматически как область, охватывающая все данные из рядов и диапазонов осей. Возвращается функцией
GetFullExtent. - Fixed extent(фиксированный) -- определяется свойством
TChart.Extent. Может частично или полностью переопределить расчет полного экстента. LogicalExtent-- запрошенный пользователем экстент для отображения на изображении диаграммы. Запись в это свойство является официальным способом изменения экстента диаграммы с помощью внешнего кода. Например,LogicalExtent := GetFullExtent(почти) эквивалентен вызову процедурыZoomFull.CurrentExtent-- экстент, фактически отображаемый пользователю. Может отличаться отLogicalExtentиз-за необходимости резервирования места для ряда метки, внутренней диаграммы поля и т.д.
Значение минимального экстента не может быть больше значения максимального экстента. При попытке установить такие значения будет сгенерировано исключение. Для предотвращения исключений можно использовать процедуру .Extent.FixTo(aBounds: TDoubleRect) для установки логических экстентов. Значения в TDoubleRect упорядочены следующим образом: [xmin, ymin, xmax, ymax].
Чтобы инвертировать экстенты, свойство Inverted оси (левой, нижней и т.д.) должно быть установлено в True.
Важно: установка логических экстентов будет работать должным образом, только если для всех Margins диаграммы установлено значение 0 (значение по умолчанию — 4), а для параметра Series.Marks.AutoMargins для всех рядов диаграммы установлено значение False (по умолчанию — True). В противном случае запрошенный экстент будет увеличен, чтобы включить в него также Margins диаграммы и Marks серии.
Ограничения области отображения
editПо умолчанию TAChart допускает произвольные области отображения. Однако из соображений удобства и производительности может быть желательно
ограничить их размер. Например, установка нижней границы размера может запретить чрезмерное масштабирование,
а установка верхней границы может вынудить пользователя видеть лишь часть очень длинного ряда в каждый момент времени.
Область отображения можно ограничить с помощью свойства ExtentSizeLimit.
Вложенные свойства MinX, MinY, UseMinX и UseMinY управляют
нижними границами области, тогда как
вложенные свойства MaxX, MaxY, UseMaxX и UseMaxY управляют
верхними границами.
Ограничения области задаются в единицах графика.
Установка Proportional = true принудительно задаёт текущей области форму, соответствующую форме области построения.
Это может быть полезно для картографических или математических графиков, требующих одинакового масштаба по обеим осям.
Связанные области отображения
editКомпонент TChartExtentLink позволяет обеспечить постоянное совпадение логических областей отображения нескольких диаграмм,
перечисленных в свойстве LinkedCharts. В Laz 2.1+ компонент был расширен дополнительным свойством AlignSides, которое корректирует свойства LabelSize выровненных диаграмм таким образом, что соответствующие стороны областей построения также выравниваются.
Это удобно для имитации многопанельных макетов диаграмм. Пример см. в демонстрации «panes».
Поля
editMargin — это отступ, резервируемый по краям прямоугольной области. Поля измеряются в единицах изображения (обычно в пикселях). Сама диаграмма имеет два вида полей:
- Внутренние (свойство
Margins) — применяются после отрисовки осей. Также зависят от меток рядов и самих рядов. - Внешние (свойство
MarginsExternal) — применяются до отрисовки осей. Также зависят от меток осей и стрелок.
Другие элементы диаграммы, такие как легенда, заголовок, нижний колонтитул и подписи, также имеют поля.
Примечания по оптимизации
editВычисление CurrentExtent и фактических полей является нетривиальным итеративным процессом (подробности см. в коде TChart.PrepareAxis).
Хотя обычно это происходит быстро, в сложных случаях может потребоваться несколько проходов по источникам диаграммы.
Графическое объяснение
edit
Примеры
editЭтот пример кода создает массив TCharts с постоянной шириной графика.
uses
...
TAGraph, TAChartAxisUtils, math;
...
procedure TForm1.Button1Click(Sender:TObject);
const
aHeight = 200;
var
i, j: integer;
mycharts: array of TChart;
begin
SetLength(mycharts,8);
for i:= 0 to high(mycharts) do
begin
mycharts[i] := TChart.Create(self);
mycharts[i].Height := aHeight - 10;
mycharts[i].Top := aHeight* i;
mycharts[i].width := 600;
mycharts[i].AxisList.Add;
for j:= 0 to mycharts[i].AxisList.Count -1 do
begin
mycharts[i].AxisList[j].Title.Visible := True;
mycharts[i].AxisList[j].Title.Caption := 'Axis ' + IntToStr(i + 1) + ',' + IntToStr(j + 1) ;
if (mycharts[i].AxisList[j].Alignment = calLeft) or (mycharts[i].AxisList[j].Alignment = calRight) then
begin
mycharts[i].AxisList[j].Title.LabelFont.Orientation := 400 + trunc (Random(800));
mycharts[i].AxisList[j].Title.LabelFont.Size := 10 + trunc(Random(20));
mycharts[i].AxisList[j].Range.UseMax := True;
mycharts[i].AxisList[j].Range.Max := power(10,random(5));
mycharts[i].AxisList[j].Range.UseMin := True;
mycharts[i].AxisList[j].Range.Min := - power(10,random(5));;
mycharts[i].AxisList[j].Margin := 0;
mycharts[i].AxisList[j].Title.Margins.Top := 0;
mycharts[i].AxisList[j].Title.Distance := 20;
mycharts[i].AxisList[j].title.FixedSize := 40;
mycharts[i].AxisList[j].LabelSize := 50;
end;
end;
mycharts[i].parent := self;
end;
end;
Инструменты
editИнструменты диаграммы определяют, как диаграмма реагирует на различные действия пользователя, прежде всего на движения мыши и щелчки. Примеры использования инструментов можно увидеть в демонстрациях "tools" или "barseriestools".
Инструменты сгруппированы в компоненте TChartToolset, который должен быть назначен свойству Toolset диаграммы.
Один и тот же набор инструментов может использоваться в нескольких диаграммах.
Если Toolset не назначен, из соображений совместимости используется встроенный набор инструментов, состоящий из
инструмента масштабирования перетаскиванием и инструмента панорамирования перетаскиванием; эти встроенные инструменты можно отключить по отдельности, установив свойства диаграммы AllowZoom и/или AllowPanning в значение false (последнее доступно только начиная с Lazarus v2.2+).
При каждом действии пользователя инструменты из набора обрабатываются по порядку, и для каждого инструмента:
- Если
Enabled=false, инструмент игнорируется. - Если
Shiftне совпадает с текущим состоянием клавиш-модификаторов, инструмент игнорируется. - Инструменту передаётся запрос на обработку действия.
- Если инструмент сигнализирует, что действие обработано, обработка прекращается, иначе переходит к следующему инструменту. Таким образом, инструменты с одинаковым значением
Shiftмогут различаться по специальным условиям активации. Например, некоторые инструменты перетаскивания можно настроить так, чтобы они не активировались при простом щелчке, оставляя событие щелчка доступным для других действий. - Наконец, если подходящий инструмент не найден, вызывается обработчик событий диаграммы. Обратите внимание, что это означает: обработчики событий диаграммы работают только при отключённых инструментах. Как правило, для интерактивности рекомендуется использовать инструменты; обработчики событий диаграммы оставлены преимущественно для обеспечения совместимости.
В приложении можно, например, создать панель инструментов, в которой каждая кнопка включает соответствующий инструмент из набора и отключает все остальные.
Как вариант, назначив разные значения Shift, можно одновременно включить несколько инструментов.
Некоторые инструменты публикуют свойство EscapeCancels, которое при значении true отменяет операцию инструмента при нажатии клавиши ESC.
Обработка клавиатуры в инструментах
editПомимо событий мыши, некоторые инструменты могут реагировать на нажатия клавиш — например, инструмент перекрестия с Shift = [ssCtrl] будет отображать перекрестие при нажатой клавише CTRL без нажатия кнопок мыши.
К сожалению, для получения событий клавиатуры диаграмма должна находиться в фокусе.
Это означает, что после того как пользователь взаимодействовал с другими элементами управления на той же форме, диаграмма перестаёт реагировать на события только клавиатуры.
Чтобы предотвратить это, можно либо вызвать метод Chart.SetFocus, либо установить Chart.AutoFocus = true, что заставит диаграмму захватывать фокус при наведении на неё указателя мыши.
Режим рисования
editНекоторые инструменты, такие как масштабирование перетаскиванием или перекрестие, отображают перемещаемые фигуры поверх диаграммы при движении мыши.
Существует два способа отображения таких фигур: либо просто рисовать их поверх диаграммы, полностью перерисовывая диаграмму при каждом движении мыши, либо использовать режим пера pmXor для рисования и стирания фигуры непосредственно из обработчика события MouseMove.
Первый метод позволяет использовать произвольный цвет и стиль пера, но второй значительно эффективнее.
Кроме того, некоторые наборы виджетов игнорируют всё рисование вне события Paint; в таком случае второй метод вообще не будет работать.
Метод отображения управляется свойством DrawingMode со следующими значениями:
tdmXor-- использовать метод XOR;tdmNormal-- использовать полную перерисовку диаграммы;tdmDefault-- использовать метод XOR на наборах виджетов, где он гарантированно работает (Windows и Gtk), и полную перерисовку на остальных.
Инструменты области отображения
editИнструменты области отображения изменяют логическую область отображения диаграммы.
Инструменты масштабирования можно анимировать, установив AnimationSteps в значение больше 1 и задав соответствующий AnimationInterval в миллисекундах.
В инструментах масштабирования свойство LimitToExtent позволяет ограничить масштабирование полной областью диаграммы по всем или некоторым направлениям. Это же свойство доступно и в инструментах панорамирования для аналогичной цели при перемещении области просмотра.
Инструмент масштабирования перетаскиванием
editTZoomDragTool позволяет пользователю увеличивать масштаб, рисуя прямоугольник мышью.
Этот прямоугольник становится новой логической областью отображения.
Восстановление масштаба до полной области достигается несколькими действиями,
управляемыми свойством RestoreExtentOn:
zreDragTopLeft,zreDragTopRight,zreDragBottomLeft,zreDragBottomRight-- перетаскивание в указанном направлении,zreClick-- щелчок без перетаскивания,zreDifferentDrag-- перетаскивание в направлении, отличном от использованного при увеличении.
По умолчанию RestoreExtentOn = [zreClick, zreDragTopLeft, zreDragTopRight, zreDragBottomLeft], что означает:
полная область восстанавливается либо щелчком, либо рисованием прямоугольника в любом направлении, кроме направления сверху-слева вниз-направо.
Для получения поведения, совместимого с более ранними версиями TeeChart от Delphi, укажите RestoreExtentOn = [zreDragTopLeft, zreDragTopRight, zreDragBottomLeft].
Для получения поведения, совместимого с более новыми версиями TeeChart, укажите RestoreExtentOn = [zreDifferentDrag].
Перечисляемое свойство RatioLimit ((zrlNone, zrlProportional, zrlFixedX, zrlFixedY) позволяет ограничить масштабирование по одной из координат или сохранять исходные пропорции в процессе масштабирования.
Инструмент масштабирования щелчком
editTZoomClickTool позволяет пользователю увеличивать или уменьшать масштаб, щёлкая по диаграмме мышью.
ZoomFactor — это масштабный множитель, применяемый инструментом: значения меньше 1 соответствуют уменьшению масштаба, а больше 1 — увеличению.
ZoomRatio позволяет создать непропорциональный эффект масштабирования, задавая соотношение масштабов X и Y. Иными словами, коэффициент масштабирования по X задаётся свойством ZoomFactor, а коэффициент по Y равен произведению ZoomFactor*ZoomRatio.
- В частности, для масштабирования только по горизонтали коэффициент по Y должен равняться 1, то есть
ZoomFactor*ZoomRatio = 1илиZoomRatio = 1/ZoomFactor. Например, еслиZoomFactorдля оси X равен 1.1, тоZoomRatioдолжен быть равен 1/1.1 = 0.909. - Аналогично, для масштабирования только по вертикали коэффициент по X должен равняться 1, то есть
ZoomFactor = 1, а коэффициент по Y задаётся одним лишьZoomRatio. - Наконец, в обычном случае, когда масштабирование по X и Y должно быть одинаковым, оставьте
ZoomRatioравным 1 и управляйте общим коэффициентом масштабирования только черезZoomFactor.
Если FixedPoint равно true, в качестве неподвижной точки масштабирования используется место щелчка мышью, в противном случае используется центр изображения диаграммы.
Инструмент масштабирования колесом мыши
editTZoomMouseWheelTool позволяет пользователю изменять масштаб колесом мыши.
Его свойства идентичны свойствам инструмента масштабирования щелчком.
При прокрутке колеса мыши вверх диаграмма масштабируется с коэффициентом ZoomFactor,
а при прокрутке вниз — с коэффициентом 1/ZoomFactor.
Инструмент панорамирования перетаскиванием
editTPanDragTool позволяет пользователю перемещать логическую область отображения, перетаскивая мышь в направлениях,
указанных свойством Directions.
Используйте свойство MinDragRadius для различения перетаскивания от щелчка.
Инструмент панорамирования щелчком
editTPanClickTool позволяет пользователю перемещать логическую область отображения, щёлкая внутри диапазона Margins пикселей от соответствующего края изображения диаграммы.
Величина смещения при панорамировании определяется расстоянием от края диаграммы (чем ближе к краю, тем больше смещение).
Установка Interval в миллисекундах позволяет продолжать панорамирование с заданным интервалом до отпускания кнопки мыши.
Инструмент панорамирования колесом мыши
editTPanMouseWheelTool позволяет пользователю перемещать логическую область отображения прокруткой колеса мыши.
При прокрутке колеса вверх область смещается в направлении WheelUpDirection, а при прокрутке вниз — в противоположном направлении.
Скорость перемещения управляется свойством Step.
Инструменты данных
editИнструменты данных привязаны к конкретным рядам данных через свойство AffectedSeries, представляющее собой строку индексов рядов, разделённых запятыми.
Обратите внимание, что индексы могут измениться при добавлении или удалении рядов.
Пустое значение AffectedSeries означает, что инструменты работают со всеми рядами диаграммы.
При активации инструмента данных он определяет ближайшую точку затронутых рядов, находящуюся в пределах GrabRadius (в пикселях).
С помощью набора Targets: TNearestPointTargets можно контролировать, какая часть сложного ряда должна быть захвачена:
nptPoint: инструмент должен захватить точку данных в (x, y).nptXList: если источник ряда имеет несколько значений x, инструмент должен захватить любое из значений в XList.nptYList: если источник ряда имеет несколько значений y, инструмент должен захватить любое из значений в YList.nptCustom: предназначено для специальных эффектов, зависящих от ряда. Например, в случае столбчатого ряда функция GetNearestPoint переопределяется для принятия попаданий внутри столбцов ряда при установке этого параметра.
Все параметры включены по умолчанию.
Для более тонкого управления большинство рядов имеют такой же набор Targets, называемый ToolTargets. Параметр должен быть включён как в настройках инструмента, так и в настройках ряда. Таким образом, инструменты могут совместно использоваться рядами, по-разному реагирующими на каждый параметр. См. демонстрацию "barseriestools" в качестве примера.
Для больших рядов эффективность можно повысить, используя сортированный источник, небольшой GrabRadius и DistanceMode<>cdmOnlyY.
Инструмент перетаскивания точки данных
editTDataPointDragTool позволяет пользователю изменять значения данных, перетаскивая точку данных.
Требует, чтобы источником данных ряда был источник-список.
Для ограничения направления перетаскивания или области захвата можно использовать события OnDrag и OnDragStart.
Пример см. в демонстрации "dragdrop".
Инструмент щелчка по точке данных
editTDataPointClickTool позволяет назначить обработчик события OnPointClick, который будет вызываться при щелчке пользователя по точке данных.
Инструмент подсказки для точки данных
editTDataPointHintTool отображает подсказку при наведении указателя мыши на точку данных.
Подсказка либо совпадает с меткой точки (если UseDefaultHintText=true), либо определяется вызовом обработчика события OnHint.
По умолчанию этот инструмент отображает отдельное окно подсказки, независимое от подсказки приложения.
Для использования единого окна подсказки на всё приложение можно установить UseApplicationHint=true.
Обратите внимание, что подсказка на уровне приложения не работает совместно с клавишами-модификаторами
и кнопками мыши, поэтому подсказка отображается только при отсутствии нажатых кнопок (то есть свойство Shift должно быть пустым при UseApplicationHint=true).
Инструмент перекрестия для точки данных
editTDataPointCrosshairTool отображает перекрестие с центром в точке данных. Он заменяет «прицел», существовавший в старых версиях TAChart.
Инструмент измерения расстояния между точками данных
editTDataPointDistanceTool позволяет измерять и отображать расстояние между двумя точками на диаграмме.
Инструменты элементов диаграммы
editИнструмент щелчка по оси
editЭтот инструмент генерирует событие OnClick при щелчке пользователя по оси или её заголовку. Событие передаёт в качестве параметров нажатую ось и набор элементов TAxisHitTest:
ahtTitle: щелчок по заголовку осиahtLine: щелчок по линии оси (допустимый допуск определяется свойствомGrabRadiusинструмента или значениямиTickLengthиInnerTickLengthоси — берётся наибольшее из них).ahtLabels: щелчок в области меток оси. Не различается, по метке или по пустому пространству между метками был произведён щелчок.ahtAxisStart: щелчок по линии или области меток произошёл в первой четверти длины осиahtAxisCenter: щелчок по линии или области меток произошёл в центральной части (две четверти) длины осиahtAxisEnd: щелчок по линии или области меток произошёл в последней четверти длины оси.
Инструмент щелчка по заголовку/нижнему колонтитулу
editСобытие OnClick генерируется при щелчке пользователя по заголовку или нижнему колонтитулу диаграммы. Событие передаёт в качестве параметра нажатый заголовок/нижний колонтитул.
Инструмент щелчка по легенде
editГенерирует событие OnClick при щелчке по легенде диаграммы. Событие передаёт легенду в качестве параметра.
Пользовательский инструмент
editЧтобы добавить собственный инструмент, унаследуйтесь от TUserDefinedTool или используйте его напрямую,
назначив один или несколько обработчиков событий On{After,Before}{KeyDown,KeyUp,MouseDown,MouseMove,MouseUp,MouseWheelDown,MouseWheelUp}.
Вызовите метод Handled инструмента, чтобы указать, что дальнейшая обработка события не требуется.
Декоративные элементы
editЗаголовок и нижний колонтитул
editЗаголовок и нижний колонтитул диаграммы — это многострочные тексты, отображаемые соответственно выше и ниже диаграммы. Они поддерживают различные варианты поворота и выравнивания.
HTML
editЕсли версия Lazarus 1.8 или новее, в тексты заголовка и нижнего колонтитула можно встраивать HTML-сущности и некоторые HTML-теги для расширенных возможностей форматирования. Эта функция включается переключением свойства TextFormat в значение tfHTML. Помимо текстов заголовка и нижнего колонтитула, она доступна также для подписей осей, меток осей, меток рядов и текстов легенды/заголовков рядов.
- Нестандартные символы можно встраивать с помощью соответствующих HTML-сущностей, то есть в виде кодов, начинающихся с амперсанда (&), стандартизованного сокращения названия символа (или его шестнадцатеричного либо десятичного значения в Unicode) и заканчивающихся точкой с запятой (;). Список всех HTML-сущностей можно найти на http://unicode.e-workers.de/entities.php.
Пример: Текстsin 2α = 2 sin α cos αотображается как "sin 2α = 2 sin α cos α" <sub>...</sub>отображает заключённый текст как нижний индекс.
Пример:H<sub>2</sub>Oотображается на диаграмме как "H2O"<sup>...</sup>отображает заключённый текст как верхний индекс.
Пример:cm<sup>2</sup>отображается на диаграмме как "cm2"<b>...</b>отображает заключённый текст жирным шрифтом.
Аналогично теги <i>...</i>, <u>...</u>, <s>...;</s> используются для форматирования фрагментов текста как курсив, подчёркнутый изачёркнутый
Пример:Plot of <b>x</b> <i>vs.</i> <b>y</b>отображается на диаграмме как "Plot of x vs. y"- Теги
<font>...</font>используются для изменения шрифта заключённого текста:- Цвет текста: Встроенный код
This text is <font color="red">RED</font>отображает заключённый текст красным цветом, то есть как "This text is RED". Цвет задаётся наиболее распространёнными названиями цветов или шестнадцатеричными HTML-кодами цвета RGB в формате#rrggbbили#rgb, где r, g, b — шестнадцатеричные байты компонент красного, зелёного и синего цвета. Трёхзначные коды#rgbэквивалентны шестизначным кодам#rrggbb, в которых обе цифры одного компонента одинаковы. - Название шрифта задаётся атрибутом
name. - Размер шрифта управляется атрибутом
size. Он принимает значения "x-small", "small", "medium", "large", "x-large", "xx-large", соответствующие размерам шрифта 7, 10, 12, 14, 18, 24pt. Также можно напрямую задать размер в пунктах или пикселях, добавив суффикс "pt" или "px" соответственно. - Пример: Следующий код добавляет двустрочный нижний колонтитул, в котором вторая строка набрана синим, 8pt, подчёркнутым шрифтом Times New Roman:
- Цвет текста: Встроенный код
Chart.Foot.Text.Clear;
Chart.Foot.Text.Add('Reference:');
Chart.Font.Text.Add('<font name="Times New Roman" size="8pt" color="blue"><u>www.freepascal.org/</u></font>');
Не рекомендуется изменять название и размер шрифта в пределах одной строки, поскольку модули отрисовки TAChart не могут точно выровнять базовую линию символов разных шрифтов и размеров
Демонстрационное приложение в папке demo/html установки Lazarus активно использует встроенные HTML-коды.
Легенда
editЛегенда диаграммы — это таблица, в каждой строке которой содержится значок и текстовая строка.
Линии сетки управляются свойствами GridHorizontal и GridVertical.
Легенда поддерживает различные варианты выравнивания и может располагаться внутри диаграммы или
на боковой панели. Легенду можно отображать в двух и более столбцах,
задав свойство ColumnCount.
Установка ColumnCount в очень большое значение фактически создаёт «горизонтальную» легенду.
Элементы легенды генерируются на основе рядов диаграммы, у которых оба свойства
Active и ShowInLegend установлены в true.
В зависимости от Legend.Multiplicity ряд может порождать один
элемент или по одному элементу на каждую точку.
Элементы легенды можно группировать под подзаголовками.
Подзаголовки берутся из свойства GroupNames,
а каждый ряд может использовать свойство Legend.GroupIndex
для указания своей группы.
Элементы легенды сортируются следующим образом:
- По индексу группы; элементы без группы (
GroupIndex=-1) идут первыми, чтобы не было путаницы с последней группой. - По свойству
Order; элементы без явного порядка (Order=-1) идут последними. - По порядку создания рядов.
- Для нескольких элементов на ряд — по порядку генерации (для стандартных рядов это порядок точек).
Отсортированные элементы затем добавляются в таблицу легенды по строкам или по столбцам
в зависимости от свойства ItemFillOrder.
Текст элемента легенды
editТекст элемента легенды генерируется соответствующим рядом на основе свойства Legend.Format.
Это свойство используется в качестве первого аргумента функции
SysUtils.Format,
второй аргумент которой содержит следующие элементы данных:
- Для кратности по рядам:
- 0:
Titleряда - 1:
Indexряда
- 0:
- Для кратности по точкам:
- То же, что и метки ярлычков
Если свойство TextFormat переключено в tfHTML, для специального форматирования текстов легенды можно встраивать HTML-сущности и теги. Подробности см. в разделе HTML.
Пользовательские элементы легенды
editПроизвольные элементы легенды можно генерировать, переопределив события OnCreate и OnDraw свойства Legend ряда.
Обратите внимание, что количество пользовательских элементов управляется исключительно свойством UserItemsCount и не зависит от Multiplicity. Также учтите, что свойства GroupIndex и Order фактически задаются на каждый элемент, поэтому можно полностью переопределить всю легенду из одного (возможно, фиктивного) ряда.
Стрелки
editНаконечники стрелок можно рисовать на концах линий осей, линий констант, линий-связей меток и т.д.
Это управляется соответственно свойствами TChartAxis.Arrow, TConstantLine.Arrow, TChartMarks.Arrow.
Форма наконечника стрелки определяется свойствами Width, Length и BaseLength,
например:
- Тонкий клин:
BaseLength = 0 - Треугольник:
BaseLength = Length - Ромб:
BaseLength = 2 * Length - Перевёрнутый треугольник:
BaseLength > 0,Length = 0
На изображении показаны эти стрелки, созданные при Length=10 и Width=5.
Прозрачность
editСвойство Transparency ряда представляет уровень прозрачности от 0 (полностью непрозрачный) до 255 (полностью прозрачный — то есть невидимый).
Замечание о совместимости: Модули отрисовки FPVectorial и TFPCanvas в настоящее время не поддерживают прозрачность из-за ограничений используемых библиотек. Модули отрисовки Printer и WMF в принципе не могут поддерживать прозрачность.
Замечание об оптимизации: Поддержка прозрачности в LCL является рудиментарной, поэтому текущая реализация модуля отрисовки TCanvas может работать медленно при большом количестве прозрачных рядов и крупных диаграммах. Для повышения эффективности рекомендуется использовать как можно меньше различных уровней прозрачности и не перемежать ряды с разной прозрачностью. Как вариант, используйте BGRABitmap в качестве бэкенда, поскольку он имеет более быструю реализацию прозрачности.
ChartStyles
editTChartStyles можно использовать для управления внешним видом «слоёв» рядов областей, линий и столбцов с несколькими значениями y. Их также можно применять для раскраски областей между делениями осей в виде полос.
Метки
editМетки аннотируют определённые точки диаграммы. Эти точки могут быть заданы рядом или осью. Как правило, метка состоит из некоторого графического элемента (например, деления оси) и текстового ярлыка. Однако любой из этих элементов можно опустить.
Примеры можно увидеть в демонстрации "labels"(ярлычки).
Метки ярлычков
editТекст ярлыка может быть заключён в рамку, управляемую свойствами LabelBrush и Frame.
Сам текст формируется на основе элементов источника данных с помощью свойства Format.
Это свойство используется в качестве первого аргумента функции
SysUtils.Format,
второй аргумент которой содержит следующие элементы данных:
- 0: Y
- 1: Y как процент от суммы Y
- 2: Текст
- 3: Сумма Y
- 4: X
Где «сумма Y» — это сумма всех значений Y для данного источника. Обратите внимание, что не все источники предоставляют все перечисленные выше элементы.
Некоторые предопределённые форматы можно задать через свойство Style.
Если источник является многозначным, свойство YIndex определяет, какое значение Y используется.
Если YIndex = -1, для каждого значения Y отображается отдельная метка, что удобно для накопительных рядов.
Текст отрисовывается с использованием LabelFont. Обратите особое внимание на то, что TAChart поддерживает произвольную
Orientation шрифта.
Метки ярлычков обычно учитываются при вычислении полей, чтобы гарантировать, что все метки помещаются в области просмотра.
Это поведение можно отключить, установив свойство AutoMargins в значение false.
Многострочные метки
editЕсли текст метки содержит последовательность символов LineEnding, он разбивается на несколько строк.
Строки разной длины выравниваются в соответствии со свойством Alignment.
HTML-коды в метках
editЕсли свойство TextFormat переключено в tfHTML, для специального форматирования меток можно встраивать HTML-сущности и теги. Подробности см. в разделе HTML.
Позиции меток и точки привязки
editПоложение метки относительно аннотируемой точки определяется владельцем метки (рядом или осью).
Общие свойства меток включают Distance, задающее расстояние
от начальной точки до точки привязки в единицах изображения, и Attachment, управляющее
тем, считается ли точка привязки центром или краем рамки ярлыка.
Кроме того, базовые ряды диаграммы имеют свойство MarkPositions, задающее
направление смещения ярлыков относительно точек данных ряда следующим образом:
- lmpOutside -- в сторону от центра облака точек данных; для TBarSeries и TAreaSeries имеет особый смысл: в сторону от ZeroLevel, заданного для этого ряда.
- lmpPositive -- в положительном направлении оси Y ряда
- lmpNegative -- в отрицательном направлении оси Y ряда
- lmpInside -- в сторону центра облака точек данных; для TBarSeries и TAreaSeries: в сторону ZeroLevel
В Lazarus 2.0+ TBarSeries и TAreaSeries имеют дополнительное свойство MarkPositionCentered, позволяющее центрировать начала меток между точками данных и нулевым уровнем. Чтобы разместить метки точно по центру столбцов BarSeries или по центру линии спуска AreaSeries, необходимо дополнительно изменить следующие свойства: Marks.Distance = 0 и Marks.Attachment = maCenter.
Поворот меток
editМетки можно поворачивать на любой угол с точностью 1/10 градуса, изменяя Orientation их шрифта; значение задаётся в десятых долях градуса, то есть значение 450 соответствует углу 45°. 0° означает горизонтальную ориентацию, угол увеличивается против часовой стрелки.
Поворот обычно выполняется относительно центра ярлыка. Метки осей и рядов дополнительно имеют свойство RotationCenter для переноса центра вращения к краю текста:
- raCenter -- настройка по умолчанию, то есть вращение происходит вокруг центра текста
- raLeft -- центр вращения находится у левого края ярлыка.
- raRight -- центр вращения находится у правого края текста.
- raEdge -- игнорируется для меток рядов (заменяется на raLeft). Но для меток осей центр вращения автоматически смещается к началу или концу текста, чтобы исключить поворот ярлыка внутрь диаграммы.
Отрисовщики
editДля низкоуровневых процедур рисования TAChart использует специальный набор классов, реализующих интерфейс IChartDrawer.
Это обеспечивает такие возможности, как печать диаграмм и экспорт их в формат SVG.
Эти классы называются графическими бэкендами или сокращённо отрисовщиками.
Отрисовщик TCanvas
editTCanvasDrawer — это отрисовщик по умолчанию, используемый для отображения диаграммы в TCanvas. Это включает в себя экран и различные форматы растровых изображений. Изображение, созданное этим отрисовщиком, используется в качестве эталона при разработке и отладке других бэкендов.
Отрисовщик TFPCanvas
editTFPCanvasDrawer аналогичен отрисовщику TCanvas, но основан на TFPCanvas
(который является аналогом TCanvas, реализованным в FCL вместо LCL).
Пример см. в демонстрации "nogui".
Хотя TFPCanvas и, соответственно, TFPCanvasDrawer имеют ограниченную реализацию
некоторых возможностей TAChart, их важным преимуществом является возможность компиляции приложения с набором виджетов nogui.
Это особенно полезно для веб-приложений, которые могут генерировать растровые изображения диаграмм без каких-либо дополнительных графических зависимостей или необходимости установки X/Gtk/Qt на сервере.
Отрисовщик SVG
editTSVGDrawer создаёт текстовый поток с изображением диаграммы в формате SVG.
Аналогично отрисовщику TFPCanvas, он не зависит от LCL и может использоваться в веб-приложениях
для генерации векторных диаграмм с набором виджетов nogui.
Пример см. в демонстрации "save".
Для этого отрисовщика единицей изображения является единица холста SVG, а не пиксель.
Обратите внимание, что из-за природы SVG невозможно измерить размеры шрифта, поэтому они аппроксимируются грубо.
Это может приводить к таким проблемам, как выход текста ярлыка за пределы прямоугольника метки, особенно в браузерах
вроде Firefox, не поддерживающих атрибут textLength.
Отрисовщик OpenGL
editTOpenGLDrawer рисует диаграмму в текущем контексте OpenGL.
Он подходит для использования в играх и других приложениях, работающих исключительно на OpenGL.
Отрисовщик OpenGL предполагает наличие ортогональной проекции, но не устанавливает её самостоятельно. Пример см. в демонстрации "opengl".
Обратите внимание, что, как и в самом OpenGL, поддержка шрифтов в TOpenGLDrawer крайне ограничена.
Отрисовщик принтера
editTPrinterDrawer рисует диаграмму на холсте принтера. Он не очищает страницу.
Хотя холст принтера является потомком TCanvas, и поэтому печать может выполняться с использованием отрисовщика по умолчанию, TPrinterDrawer выполняет правильное масштабирование координат изображения в соответствии с DPI принтера и экрана.
Вы можете использовать этот отрисовщик для экспорта диаграммы в формат PDF с помощью одного из доступных продуктов для записи PDF.
Пример см. в демонстрации "print".
Обратите внимание, что этот отрисовщик находится в отдельном пакете TAChartPrint.
Отрисовщик AggPas
editTAggPasDrawer рисует диаграмму с использованием библиотеки AggPas.
AggPas обеспечивает высокоскоростное сглаженное рисование и включён в исходные тексты Lazarus. К сожалению, библиотека в настоящее время не поддерживается, и в поддержке TAChart имеются некоторые ограничения.
Обратите внимание, что этот отрисовщик находится в отдельном пакете TAChartAggPas.
Отрисовщик BGRABitmap
editTBGRADrawer рисует диаграмму с использованием библиотеки BGRABitmap.
BGRABitmap — недавно созданная и активно развиваемая графическая библиотека, предоставляющая, в частности, сглаживание и богатый выбор градиентов.
В настоящее время BGRABitmap поддерживает все возможности TAChart, но несколько медленнее других методов отрисовки.
Обратите внимание, что этот отрисовщик находится в отдельном пакете TAChartBGRA, который зависит от внешнего пакета bgrabitmappack.
Отрисовщик FPVectorial
editTFPVectorialDrawer рисует диаграмму с использованием библиотеки fpvectorial.
FPVectorial обеспечивает экспорт в различные векторные форматы,
включая SVG, PDF, CorelDraw и даже инструкции для станков лазерной резки металла.
В настоящее время он имеет некоторые ограничения в поддержке TAChart, но активно развивается.
Обратите внимание, что этот отрисовщик находится в отдельном пакете TAChartFPVectorial,
который зависит от пакета fpvectorialpkg.
Отрисовщик WMF
editTWindowsMetafileDrawer рисует диаграмму в файл Windows Metafile.
Он использует WinAPI напрямую и поэтому будет работать только в Windows. Поддержка WMF была добавлена в fpvectorial, который предоставляет кроссплатформенную альтернативу этому пакету.
Навигация
editНавигация по диаграмме состоит из двух частей: перемещение логической области отображения без изменения масштаба и визуализация положения и размера логической области относительно полной области отображения. Перемещение области (без её визуализации) возможно с помощью инструментов панорамирования. Примеры можно увидеть в демонстрации "navigation".
Полосы прокрутки
edit
TChartNavScrollBar — это потомок TCustomScrollBar с дополнительным свойством Chart, ссылающимся на диаграмму. TChartNavScrollBar синхронизирует своё положение с областью диаграммы в обоих направлениях. Если логическая область равна полной области или превышает её, навигационная полоса прокрутки не выполняет никаких действий.
Установка AutoPageSize = true позволяет TChartNavScrollBar выбирать размер страницы пропорционально логической области.
Обратите внимание, что свойства Min и Max не изменяются автоматически. Рекомендуется устанавливать Min = 0, а Max — в достаточно большое целое значение, чтобы избежать проблем с округлением. Также обратите внимание, что TChartNavScrollBar не выравнивается и не прикрепляется к диаграмме автоматически, поэтому он может быть произвольно расположен на форме.
Панель навигации
edit
Компонент TChartNavPanel отображает логическую и полную область отображения назначенной диаграммы в виде прямоугольников разного цвета, позволяя пользователю перетаскивать прямоугольник логической области при AllowDragNavigation = true.
Если MiniMap = true, панель дополнительно отображает ряды диаграммы.
TChartNavPanel может иметь произвольный размер, однако рекомендуется сохранять соотношение высоты к ширине таким же, как у назначенной диаграммы. Установка Proportional = true принудительно обеспечивает одинаковые пропорции даже при несоблюдении указанного условия, ценой некоторого неиспользуемого пространства на панели.
Живой просмотр
edit
Хотя TChartLiveView не является инструментом навигации напрямую, он тесно с ней связан. В случае длинного массива поступающих данных он предоставляет удобный способ отображать область просмотра только с самыми последними данными, пока более старые данные уходят влево за пределы области просмотра.
Область просмотра обновляется при каждом изменении полной области назначенной диаграммы. Однако при установке свойства Active в значение false область просмотра фиксируется — это настройка, позволяющая пользователю просматривать более старые данные или изменять область отображения, пока одновременно продолжают поступать новые данные.
Свойство ViewportSize задаёт ширину видимой области просмотра в единицах графика. Если установлено значение 0, вместо него используется ширина текущей LogicalExtent.
Перечисляемое свойство ExtentY = (lveAuto, lveFull, lveLogical) определяет высоту области просмотра:
lveAutoавтоматически подстраивает высоту под диапазон видимых данных. Это работает также в случае, когда диаграмма содержит несколько осей Y. Если для оси определён диапазонRange(то есть заданыaxis.Range.Min/axis.Range.UseMinи/илиaxis.Range.Max/axis.Range.UseMax), компонент сохраняет его до тех пор, пока значения рядов находятся в пределах этого диапазона.lveFullфиксирует высоту по полной области диаграммы.lveLogicalфиксирует высоту по логической области диаграммы.
Методы StoreAxisRange и RestoreAxisRange используются для внутренних целей, поскольку компонент может изменять параметры Range оси. Будьте осторожны при вызове этих методов, так как при неправильном использовании они могут нарушить работу живого просмотра.
Дополнительные компоненты
editПанель легенды
editTChartLegendPanel предоставляет легенду, которую можно разместить в любом месте формы. Легенда берётся из диаграммы, назначенной свойству Chart панели легенды. Собственную легенду диаграммы при этом следует отключить.
Список рядов диаграммы
editTChartListbox — это универсальная замена легенды, отображающая значок и заголовок каждого ряда диаграммы, привязанной к свойству Chart списка. Но в отличие от стандартной легенды, он также содержит флажки для каждого ряда. Снятие флажка скрывает соответствующий ряд, установка флажка отображает его снова. Список отслеживает изменения в привязанной диаграмме и обновляется автоматически.
Свойство CheckStyle позволяет переключить список с поведения в стиле флажков (cbsCheckbox, может быть отмечена произвольная комбинация рядов) на поведение в стиле переключателей (cbsRadioButton, может быть отмечен только один ряд). В зависимости от CheckStyle для каждого ряда отображается либо значок переключателя, либо значок флажка.
События генерируются при щелчке по флажку/переключателю или заголовку ряда (соответственно OnCheckboxClick или OnItemClick), а также при двойном щелчке по значку ряда (OnSeriesIconDblClick). Последнее событие предназначено для открытия диалога изменения цвета ряда, стиля указателя, заголовка ряда и т.д.
Элементы списка формируются иначе, чем для обычной легенды. В процессе заполнения игнорируется свойство ряда Legend.Visible, управляющее отображением ряда в легенде. Вместо него предусмотрено событие OnAddSeries, в котором параметр var с именем Skip следует установить в true, если ряд, переданный в качестве другого аргумента, должен быть исключён из списка. Каждый ряд представлен только одним элементом, то есть свойство Multiplicity ряда также игнорируется. Кроме того, группировка элементов не поддерживается.
Порядок элементов списка обычно определяется порядком рядов в легенде диаграммы и зависит от параметров Legend.Inverted диаграммы и Legend.Order рядов. Кроме того, элементы можно переставлять независимо от легенды, вызывая метод ExchangeSeries(AIndex1, AIndex2) с индексами списка в качестве параметров. Также имеется метод Sort для сортировки списка по заголовкам рядов (порядок сортировки можно инвертировать, установив необязательный параметр Descending или Chart.Legend.Inverted в значение true). Обратите внимание, что метод Sort работает только с рядами, имеющими значение Legend.Order по умолчанию (-1).
Список изображений диаграммы
editTChartImageList собирает значки, отображаемые для каждого ряда в легенде, и может использоваться для элементов управления, поддерживающих списки изображений, таких как деревья, списки или меню, для отображения значков каждого ряда. Значки извлекаются из диаграммы, назначенной свойству Chart компонента. Список изображений отслеживает изменения в диаграмме и автоматически обновляет свои изображения при любых изменениях ряда. Событие OnPopulate генерируется при перестройке списка изображений.
Обратите внимание, что такой список изображений является временным, то есть его изображения не сохраняются в файле lfm формы. Тем не менее во время выполнения он может использоваться как стандартный список изображений с другими изображениями. Просто добавьте эти изображения, не связанные с рядами, до назначения диаграммы списку изображений. Используйте свойство FirstSeriesIndex для получения индекса изображения первого ряда в списке. Как вариант, индекс изображения конкретного ряда можно найти с помощью функции ImageIndexOfSeries(series).
В Laz 2.1+ компонент TChartImageList можно использовать также во время проектирования. При этом сохраняются только те изображения, которые не привязаны к ряду.
Выпадающий список диаграммы
editTChartCombobox — это расширенный выпадающий список. В зависимости от свойства Mode (ccmPointerStyle, ccmPenStyle, ccmPenWidth, ccmBrushStyle) он заполняется названиями и соответствующими значками для выбора стиля указателя, стиля пера, ширины пера или стиля заливки. Поэтому он удобен для элементов интерфейса, с помощью которых пользователь может изменять внешний вид рядов и других объектов диаграммы.
Выпадающий список не привязан к конкретной диаграмме. Используйте событие OnChange для передачи изменённого свойства ряду.
Совместимость с TeeChart
editTeeChart — это стандартный набор компонентов для построения диаграмм, используемый в Delphi.
Хотя TAChart не ставит целью совместимость с TeeChart, базовый набор возможностей и названий очень похож, поэтому простые примеры могут одинаково работать в обеих библиотеках.
Более сложные возможности — в частности, многозначные ряды, источники рядов, множественные оси — реализованы иначе, чем в TeeChart. Это сделано намеренно и не изменится.
Более подробную информацию см. на странице сравнения.
Для помощи в переносе кода TeeChart на TAChart можно использовать модуль TAChartTeeChart. Он содержит вспомогательные классы, добавляющие
или эмулирующие некоторые специфичные для TeeChart свойства и методы.
Обратите внимание, что использование этого модуля для обычной разработки НЕ рекомендуется, поскольку эмуляция предназначена лишь для имитации подмножества возможностей, реализованных в TeeChart, и может работать ненадёжно при совместном использовании с полным набором возможностей TAChart.
Технические подробности
editПорядок отрисовки
editОтрисовка диаграммы состоит из трёх этапов:
- Подготовка: На этом этапе инициализируются различные внутренние структуры данных.
- Измерение: На этом этапе диаграмма вычисляет размеры всех элементов и оптимизирует их для наилучшего представления. Оптимизация может потребовать нескольких итераций, поэтому этап измерения зачастую является наиболее трудоёмким как по сложности реализации, так и по времени выполнения.
- Отрисовка: На этом этапе отображается фактическое изображение диаграммы.
Среди различных элементов диаграммы также существует определённый порядок:
- Фон (свойство
TChart.Color). - Задняя стенка (свойство
TChart.BackColor). - Ряды и оси в соответствии со свойством
ZPosition. Для каждого ряда и оси графические элементы отрисовываются до меток. Обратите внимание, что это защищает метки от перекрытия осью или рядом, которому они принадлежат, но не другими осями или рядами. - Легенда.
- Инструменты.
Обратите внимание, что ZPosition работает как для двумерных, так и для трёхмерных диаграмм, поэтому ряды и оси можно накладывать в произвольном порядке.
Стиль кода
editИсторически исходные тексты FPC, Lazarus и LCL содержат смесь стилей кодирования, при этом общее правило звучит как «придерживайтесь стиля окружающего кода».
Однако, поскольку у TAChart значительно меньше разработчиков, вполне реально принять и поддерживать единый стиль во всём коде TAChart. Если вы хотите внести вклад в TAChart, пожалуйста, форматируйте свой код соответствующим образом. Также помните, что любой стиль кодирования может быть нарушен в определённых ситуациях при наличии достаточно веской причины, однако в этом случае, пожалуйста, поясняйте её.
Пробелы
edit- Нигде не должно быть двойных пробелов.
- Пробелы после: операторов, запятой, точки с запятой, оператора присваивания, закрывающей скобки в выражениях (но не в вызовах функций).
- Пробелы перед: операторами, оператором присваивания, открывающей скобкой в выражениях (но не в вызовах функций).
Строки
edit- Нигде не должно быть двойных пустых строк.
- Пустые строки между процедурами, классами и секциями модуля. Редкие пустые строки внутри тел процедур для разделения логических блоков.
- Длина строки не более 80 символов, с редкими исключениями.
- Один оператор на строку, за исключением if ... then {exit|break|continue} и некоторых редких случаев массового присваивания.
- Если строка слишком длинная, переносы строк можно вставлять после следующих символов в порядке убывания приоритета: ключевые слова, открывающая круглая скобка, открывающая квадратная скобка, точка с запятой, запятая, оператор.
Отступы и блоки
edit- Всегда два пробела — как для блоков, так и для строк продолжения.
- begin на той же строке, что и управляющий оператор; end выровнен по управляющему оператору.
- end всегда на отдельной строке. В частности, end else begin пишется в две строки.
- Размещайте then или do на отдельной строке, чтобы отделить сложное условие от тела оператора:
while
long condition or
another long condition
do
loop body
- Используйте begin/end только при необходимости (то есть не для одиночных операторов).
Комментарии
edit- Помещайте заголовок лицензии в начало каждого файла.
- Однострочные комментарии везде, кроме заголовка лицензии и автоматически сгенерированных заголовков классов в разделе реализации.
- Используйте в комментариях только полные предложения, начинающиеся с заглавной буквы и заканчивающиеся точкой.
- Комментарии следует размещать перед комментируемым кодом, за исключением редких случаев, когда комментарий умещается в конце той же строки.
- Комментарии должны содержать только информацию, не очевидную из исходного кода. В частности, выбирайте содержательные имена процедур и аргументов вместо добавления комментариев, описывающих их использование.
Имена
edit- Константы используют ALL_CAPS_WITH_UNDERSCORE, всё остальное — CamelCase.
- Локальные переменные начинаются со строчной буквы, всё остальное — с заглавной, даже если библиотека FPC не согласна с этим (например, ``Math``, а не ``math``).
- Поля класса начинаются с 'F', аргументы — с 'A', типы — с 'T', модули TAChart — с 'TA'.
Объявления переменных
edit- Инициализируйте при возможности.
- Локальные переменные размещайте после вложенных процедур, если только они не используются этими процедурами.
- Группируйте переменные по типу.
Классы и методы
edit- Методы сгруппированы по классам; методы внутри класса отсортированы по алфавиту как в интерфейсной части, так и в разделе реализации. Количество предупреждений Code Observer о «Несортированных членах» должно быть равно нулю.
- Если необходимо сгруппировать методы по теме, используйте спецификаторы видимости в качестве разделителей тем. В частности, группируйте переопределённые методы отдельно от вновь введённых.
- По возможности используйте видимость strict private/strict protected.
Подсказки и предупреждения
edit- Код должен компилироваться без подсказок и предупреждений.
- Подавляйте предупреждения «неиспользуемый параметр» с помощью процедуры ``Unused`` из модуля TAChartUtils или директивы Lazarus IDE {%H-}.
Поток управления
edit- Используйте exit или raise для прерывания выполнения метода при нарушении предусловия.
- Используйте перечислители там, где это возможно.
- Используйте with осторожно и только там, где его применение существенно сокращает объём кода, в минимально возможном диапазоне.
- Ограничивайте длину всех процедур 50–60 строками и активно используйте вложенные процедуры.