Настройка графических построений: PlotIndexSetInteger

За настройки графических построений в MQL5 API отвечает группа функций: PlotIndexSetInteger, PlotIndexSetDouble, PlotIndexSetString. Целочисленные свойства можно также читать через PlotIndexGetInteger. Нас в первую очередь как раз интересуют целочисленные свойства.

Функция PlotIndexSetInteger имеет две формы. О том, чем они отличаются — чуть ниже.

bool PlotIndexSetInteger(int index, ENUM_PLOT_PROPERTY_INTEGER property, int value)

bool PlotIndexSetInteger(int index, ENUM_PLOT_PROPERTY_INTEGER property, int modifier,
int value)

Функция задает значение свойства графического построения под номером index. Значение index должно находиться в пределах от 0 до P - 1, где P — количество графических построений, заданное директивой #property indicator_plots. Само свойство идентифицируется параметром property: допустимые величины следует брать из перечисления ENUM_PLOT_PROPERTY_INTEGER (см. далее). Значение свойства передается в параметре value.

Вторая форма функции предназначена для свойств, которые распространяются на несколько компонентов (принадлежащих, тем не менее, одному свойству). В частности, для диаграмм некоторых типов может быть назначен не один цвет, а целая палитра: тогда параметр modifier позволяет изменить любой цвет в этом наборе.

В случае успешного выполнения функция возвращает true, в противном случае false.

В следующей таблице перечислены доступные свойства ENUM_PLOT_PROPERTY_INTEGER.

Идентификатор	Описание	Тип свойства
PLOT_ARROW	Код стрелки из шрифта Wingdings для диаграмм DRAW_ARROW	uchar
PLOT_ARROW_SHIFT	Смещение стрелок по вертикали для диаграмм DRAW_ARROW	int
PLOT_DRAW_BEGIN	Индекс первого бара (слева направо), с которого начинаются данные	int
PLOT_DRAW_TYPE	Тип графического построения (диаграммы)	ENUM_DRAW_TYPE
PLOT_SHOW_DATA	Признак отображения значений построения в Окне данных (true — видно, false — не видно)	bool
PLOT_SHIFT	Сдвиг графического построения индикатора по оси времени в барах (положительный — вправо, отрицательный — влево)	int
PLOT_LINE_STYLE	Стиль отрисовки линий	ENUM_LINE_STYLE
PLOT_LINE_WIDTH	Толщина линий в пикселях (1 - 5)	int
PLOT_COLOR_INDEXES	Количество цветов (1 - 64)	int
PLOT_LINE_COLOR	Цвет отрисовки	color (модификатор — номер цвета)

Постепенно мы изучим все свойства, но сейчас сконцентрируемся на трех основных: PLOT_DRAW_TYPE, PLOT_LINE_STYLE и PLOT_LINE_COLOR.

Индикаторы в MetaTrader 5 поддерживают несколько предопределенных типов диаграмм, называемых графическими построениями. Они определяют одновременно и способ визуального представления и требуемую структуру буферов с исходными данными для отображения.

Всего таких базовых построений 10, и на уровне MQL5 они описываются идентификаторами в перечислении ENUM_DRAW_TYPE. Именно свойству PLOT_DRAW_TYPE следует присвоить одно из значений ENUM_DRAW_TYPE.

Тип визуализации примеры	Описание	Количество буферов
DRAW_NONE IndDeltaVolume.mq5	на графике ничего не отображается, но значения соответствующего буфера доступны в Окне данных	1
DRAW_LINE IndLabelHighLowClose.mq5, IndWPR.mq5, IndUnityPercent.mq5	кривая линия по значениям буфера ("пустые" элементы образуют пропуск в линии)	1
DRAW_SECTION	прямые отрезки, образующие ломаную между "непустыми" элементами буфера (при отсутствии пропусков аналогично DRAW_LINE)	1
DRAW_ARROW IndReplica3.mq5, IndFractals.mq5	символы (метки)	1
DRAW_HISTOGRAM IndDeltaVolume.mq5	гистограмма от нулевой линии до значений буфера	1
DRAW_HISTOGRAM2 IndLabelHighLowClose.mq5	гистограмма между значениями парных элементов двух индикаторных буферов	2
DRAW_ZIGZAG IndFractalsZigZag.mq5	прямые отрезки, образующие ломаную между последовательно встречающимися "непустыми" элементами двух буферов (похож на DRAW_SECTION, но в отличие от него допускает вертикальные отрезки на одном баре)	2
DRAW_FILLING	цветная заливка канала между двумя линиями по парным значениям в двух буферах	2
DRAW_BARS IndSubChartSimple.mq5	отображение в виде баров: четыре цены на бар указываются в четверке смежных буферов, в порядке OHLC	4
DRAW_CANDLES IndSubChartSimple.mq5	отображение в виде японских свечей: четыре цены на бар указываются в четверке смежных буферов, в порядке OHLC	4

В данной таблице приведены не все элементы ENUM_DRAW_TYPE. Существуют аналоги таких же построений с поддержкой расцвечивания отдельных элементов (баров). Мы представим их в отдельном разделе Поэлементное раскрашивание диаграмм. В документации по MQL5 приведены примеры для всех типов, а в рамках этой книги есть некоторые исключения: наличие демонстрационных индикаторов указано рядом с названиями типов.

Во всех случаях, включая DRAW_NONE, данные из буфера доступны в других программах через функцию CopyBuffer.

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

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

Идентификатор	Описание
STYLE_SOLID	сплошная линия
STYLE_DASH	прерывистая линия
STYLE_DOT	пунктирная линия
STYLE_DASHDOT	штрих-пунктирная линия
STYLE_DASHDOTDOT	штрих - две точки

Наконец, цвет линии задается свойством PLOT_LINE_COLOR. В простейшем случае данное свойство содержит один единственный цвет для всей диаграммы. Для некоторых типов диаграмм, в частности, DRAW_CANDLES, можно указать несколько цветов с помощью параметра-модификатора. Об этом мы поговорим позднее (см. пример IndSubChartSimple.mq5 в разделе Мультивалютные и мультитаймфреймовые индикаторы).

Вышеназванных трех свойств достаточно для демонстрации отображения индикатора IndReplica2.mq5. Добавим два входных параметра DrawType и LineStyle типов ENUM_DRAW_TYPE и ENUM_LINE_STYLE соответственно, а затем вызовем функцию PlotIndexSetInteger несколько раз в OnInit для установки свойств отрисовки индикатора.

#property indicator_chart_window
#property indicator_buffers 1
#property indicator_plots 1

input ENUM_DRAW_TYPE DrawType = DRAW_LINE;
input ENUM_LINE_STYLE LineStyle = STYLE_SOLID;

double buffer[];

int OnInit()
{
   // регистрируем массив в качестве индикаторного буфера
   SetIndexBuffer(0, buffer);

   // настраиваем свойства диаграммы под номером 0
   PlotIndexSetInteger(0, PLOT_DRAW_TYPE, DrawType);
   PlotIndexSetInteger(0, PLOT_LINE_STYLE, LineStyle);
   PlotIndexSetInteger(0, PLOT_LINE_COLOR, clrBlue);

   return INIT_SUCCEEDED;
}

Для свойства PLOT_LINE_COLOR мы не стали заводить входную переменную, поскольку это и некоторые другие свойства напрямую доступны из диалога свойств любого индикатора — на закладке Цвета. По умолчанию, то есть сразу после запуска индикатора цвет линии будет синим, но его, а также толщину линии и её стиль можно поменять в диалоге (на указанной закладке). Наш параметр LineStyle отчасти дублирует соответствующую ячейку Стиль в таблице Цвета, но и дает некоторое преимущество. Дело в том, что стандартные "контролы" диалога не позволяют выбрать стиль, когда ширина линии больше 1. А с помощью входной переменной LineStyle мы можем получить, например, штрих-пунктирную линию при заданной ширине 3 пикселя.

Заполнение буфера данными в OnCalculate остается без изменений по сравнению с IndReplica1.mq5.

Откомпилировав и набросив индикатор на график, получим ожидаемую картину: линия синего цвета по ценам закрытия на графике и соответствующие цены закрытия баров в Окне данных.

Меняя входной параметр DrawType, мы можем наблюдать, как меняется способ отображения данных из буфера. При этом следует выбирать только типы, для которых требуется единственный буфер. Любой другой тип графического построения (DRAW_HISTOGRAM2, DRAW_ZIGZAG, DRAW_FILLING, DRAW_BARS, DRAW_CANDLES) просто не сможет работать на одном буфере и ничего не покажет. Также не имеет смысла выбирать типы построений с цветным раскрашиванием (начинаются со слова "Color"), так как для них требуется дополнительный буфер с номерами цветов на каждом баре (как уже было сказано, мы познакомимся с этой возможностью в разделе Поэлементное раскрашивание диаграмм).

Ниже показаны варианты отображения DRAW_LINE, DRAW_SECTION, DRAW_HISTOGRAM, DRAW_ARROW.

Типы диаграмм на одном буфере

Если бы не выбранные специально разные стили — STYLE_SOLID для DRAW_LINE и STYLE_DOT для DRAW_SECTION, эти типы отрисовки нельзя было бы отличить, потому что в нашем буфере все элементы имеют "непустые" значения. Напомним, что по умолчанию под "пустым" значением подразумевается специальная константа EMPTY_VALUE, которую мы не использовали. Секции (отрезки) в DRAW_SECTION проводятся, минуя "пустые" элементы, и это становится заметно только при наличии таковых. Про установку "пустых" элементов мы поговорим в разделе Визуализация пропусков данных.

Гистограмма от нулевой линии DRAW_HISTOGRAM обычно применяется в индикаторах с собственным окном, здесь же она приведена для демонстрации. Мы создадим индикатор в подокне с данным типом отрисовки в разделе Ожидание данных и управление видимостью (см. пример IndDeltaVolume.mq5).

Для типа DRAW_ARROW система по умолчанию использует символ заполненного кружка (код 159), однако его можно заменить на другой с помощью вызова PlotIndexSetInteger(индекс, PLOT_ARROW, код).

Коды и внешний вид символов шрифта Wingdings можно посмотреть в справке по MQL5.

В еще одной модификации индикатора IndReplica3.mq5 добавим входные параметры для выбора символа "стрелки" (ArrowCode), а также для сдвига этих меток на графике по вертикали (ArrowPadding) и горизонтали (TimeShift).

input uchar ArrowCode = 159;
input int ArrowPadding = 0;
input int TimeShift = 0;

Вертикальный сдвиг по шкале цен задается в пикселях (положительные значения означают сдвиг вниз, отрицательные — вверх). Горизонтальный по шкале времени — задается в барах (положительные значения — это сдвиг вправо, в будущее, а отрицательные — влево, в прошлое). Новые входные переменные передаются в вызовы PlotIndexSetInteger в OnInit.

int OnInit()
{
   ...
   PlotIndexSetInteger(0, PLOT_DRAW_TYPE, DRAW_ARROW);
   PlotIndexSetInteger(0, PLOT_ARROW, ArrowCode);
   PlotIndexSetInteger(0, PLOT_ARROW_SHIFT, ArrowPadding);
   PlotIndexSetInteger(0, PLOT_SHIFT, TimeShift);
   ...
}

На следующем скриншоте показан пример выполнения IndReplica3.mq5 на графике с настройками 117 (ромб), -50 (50 точек вверх), 3 (3 бара вправо/вперед).

Точечная диаграмма со сдвигами меток по вертикали и горизонтали

Наш индикатор по умолчанию строится по типу цены Close (хотя пользователь и может поменять это в диалоге свойств, в выпадающем списке Применить к). При необходимости можно назначить другую начальную настройку с помощью директивы:

#property indicator_applied_price PRICE_TYPE

Здесь вместо PRICE_TYPE следует указать любую константу из перечисления ENUM_APPLIED_PRICE. В него же входит и PRICE_CLOSE, соответствующая умолчанию. Например, следующая директива, добавленная в исходный код приведет к тому, что индикатор будет по умолчанию строиться на "типичной" цене.

#property indicator_applied_price PRICE_TYPICAL

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

Чтобы узнать в исходном коде текущее состояние свойств из перечисления ENUM_PLOT_PROPERTY_INTEGER используйте функцию PlotIndexGetInteger.

int PlotIndexGetInteger(int index, ENUM_PLOT_PROPERTY_INTEGER property)

int PlotIndexGetInteger(int index, ENUM_PLOT_PROPERTY_INTEGER property, int modifier)

Функция обычно применяется в паре с функцией PlotIndexSetInteger для копирования свойств рисования из одной линии в другую или для чтения свойств из кодов универсальных mqh-файлов, включаемых в исходный код различных индикаторов.

К сожалению, аналогичных функций PlotIndexGetDouble и PlotIndexGetString не предусмотрено.

Назначение массива в качестве буфера: SetIndexBuffer

Правила сопоставления буферов и диаграмм