Обзор функций для работы с полным набором свойств графиков

Свойства графиков доступны для чтения и изменения через группы ChartSet- и ChartGet-функций, в каждой из которых собраны свойства определенного типа: вещественные числа (double), целые числа (long, int, datetime, color, bool, перечисления) и строки.

Все функции принимают первым параметром идентификатор графика. Значение 0 означает текущий график, то есть эквивалентно передаче результата вызова ChartID(). Вместе с тем, это не означает, что идентификатор текущего графика равен 0.

Константы, описывающие все свойства, формируют три перечисления ENUM_CHART_PROPERTY_INTEGER, ENUM_CHART_PROPERTY_DOUBLE, ENUM_CHART_PROPERTY_STRING, которые используются в качестве параметров функций для соответствующего типа. Сводную таблицу всех свойств можно найти в документации MQL5, на странице о свойствах графиков. В следующих разделах этой главы мы постепенно рассмотрим практически все свойства, группируя их по назначению. Исключение составят лишь свойства управления событиями на графике — их мы опишем в соответствующем разделе главы про события.

Элементам всех трех перечислений назначены такие значения, что они составляют единый перечень без пересечений (повторений). Это позволяет по конкретному значению определить тип перечисления. Например, имея константу, мы можем последовательно пытаться преобразовать её в строку с названием одного из перечислений, пока не достигнем успеха.

int value = ...;

ResetLastError(); // очищаем код ошибки, если она была ранее
EnumToString((ENUM_CHART_PROPERTY_INTEGER)value); // результирующая строка не важна
if(_LastError == 0) // анализируем, есть ли новая ошибка
{
   // успех - это элемент ENUM_CHART_PROPERTY_INTEGER
   return ChartGetInteger(0, (ENUM_CHART_PROPERTY_INTEGER)value);
}

ResetLastError();
EnumToString((ENUM_CHART_PROPERTY_DOUBLE)value);
if(_LastError == 0)
{
   // успех - это элемент ENUM_CHART_PROPERTY_DOUBLE
   return ChartGetDouble(0, (ENUM_CHART_PROPERTY_DOUBLE)value);
}

... // продолжаем аналогичную проверку для ENUM_CHART_PROPERTY_STRING

Позже мы воспользуемся этим подходом в тестовых скриптах.

Некоторые свойства (например, количество видимых баров) доступны только на чтение и не могут быть изменены. Они будут далее помечаться "r/o" (read-only).

Функции чтения свойств имеют краткую и полную форму: краткая — непосредственно возвращает затребованное значение, а полная — логический признак успеха (true) или ошибки (false), а само значение помещается в последний параметр, передаваемый по ссылке. При использовании краткой формы особенно важно проверять код ошибки в переменной _LastError, потому что значение 0 (NULL), возвращаемое в случае проблем, может являться в общем случае корректным.

При обращении к некоторым свойствам необходимо указывать дополнительный параметр (window), который служит для указания номера окна/подокна графика. 0 означает основное окно. Подокна нумеруются, начиная с 1. Некоторые свойства применяются к графику целиком — для них предусмотрены варианты функций без параметра window.

Ниже приведены прототипы функций для чтения и записи целочисленных свойств. Обратите внимание, что тип значений в них — это long.

bool ChartSetInteger(long chartId, ENUM_CHART_PROPERTY_INTEGER property, long value)

bool ChartSetInteger(long chartId, ENUM_CHART_PROPERTY_INTEGER property, int window, long value)

long ChartGetInteger(long chartId, ENUM_CHART_PROPERTY_INTEGER property, int window = 0)

bool ChartGetInteger(long chartId, ENUM_CHART_PROPERTY_INTEGER property, int window, long &value)

Аналогично описаны функции для вещественных свойств. Доступных для записи вещественных свойств у подокон не существует, поэтому форма ChartSetDouble только одна — без параметра window.

bool ChartSetDouble(long chartId, ENUM_CHART_PROPERTY_DOUBLE property, double value)

double ChartGetDouble(long chartId, ENUM_CHART_PROPERTY_DOUBLE property, int window = 0)

bool ChartGetDouble(long chartId, ENUM_CHART_PROPERTY_DOUBLE property, int window, double &value)

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

bool ChartSetString(long chartId, ENUM_CHART_PROPERTY_STRING property, string value)

string ChartGetString(long chartId, ENUM_CHART_PROPERTY_STRING property)

bool ChartGetString(long chartId, ENUM_CHART_PROPERTY_STRING property, string &value)

При чтении свойств с помощью краткой формы ChartGetInteger/ChartGetDouble параметр window является необязательным и по умолчанию подразумевает основное окно (window = 0).

Функции для установки свойств графика (ChartSetInteger, ChartSetDouble, ChartSetString) являются асинхронными и служат для отправки графику команд на изменение. При успешном выполнении этих функций команда попадает в общую очередь событий графика, и возвращается результат true. При возникновении ошибки функции вернут false, а код ошибки необходимо проверять в переменной _LastError.

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

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

Функции получения свойств графика (ChartGetInteger, ChartGetDouble, ChartGetString) являются синхронными, то есть вызывающий код дожидается результата их выполнения.

Получение символа и таймфрейма произвольного графика

Описательные свойства графика