Справочник MQL4 Основы языка Функции Функции обработки событий

Функции обработки событий

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

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

OnStart

Функция OnStart() является обработчиком события Start, которое автоматически генерируется только для запущенных на выполнение скриптов. Должна иметь тип void, параметров не имеет:

void OnStart();

Для функции OnStart() допустимо указывать тип возвращаемого значения int.

OnInit

Функция OnInit() является обработчиком события Init. Может иметь тип void или int, параметров не имеет:

void OnInit();

Событие Init генерируется сразу после загрузки эксперта или индикатора. Функция OnInit() используется для инициализации. Если OnInit() имеет возвращаемое значение типа int, то ненулевой код возврата означает неудачную инициализацию и генерирует событие Deinit с кодом причины деинициализации REASON_INITFAILED.

Результат выполнения функции OnInit() анализируется исполняющей подсистемой терминала только в том случае, если программа скомпилирована с использованием #property strict.

Для оптимизации входных параметров эксперта рекомендуется в качестве кода возврата использовать значения из перечисления ENUM_INIT_RETCODE. Эти значения предназначены для организации управления ходом оптимизации. Прямо при инициализации эксперта еще до запуска самого тестирования можно запросить информацию о конфигурации и ресурсах с помощью функции TerminalInfoInteger().

ENUM_INIT_RETCODE

Идентификатор	Описание
INIT_SUCCEEDED	Инициализация прошла успешно, тестирование эксперта можно продолжать. Этот код означает то же самое, что и нулевое значение – инициализация эксперта в тестере прошла успешно.
INIT_FAILED	Неудачная инициализация, тестирование нет смысла продолжать из-за неустранимых ошибок. Например, не удалось создать индикатор, необходимый для работы эксперта. Возврат этого значения означает то же самое, что и возврат значения, отличного от нуля – инициализация эксперта в тестере прошла неудачно.
INIT_PARAMETERS_INCORRECT	Предназначен для обозначения программистом некорректного набора входных параметров, в общей таблице оптимизации строка результата с таким кодом возврата будет подсвечена красным цветом. Тестирование для данного набора параметров эксперта не будет выполняться.

Функция OnInit() типа void всегда означает удачную инициализацию.

OnDeinit

Функция OnDeinit() вызывается при деинициализации и является обработчиком события Deinit. Должна быть объявлена с типом void и иметь один параметр типа const int , который содержит код причины деинициализации. Если объявлен иной тип, компилятор выдаст предупреждение, но функция вызываться не будет.

void OnDeinit(const int reason);

Событие Deinit генерируется для экспертов и индикаторов в следующих случаях:

перед переинициализацией в связи со сменой символа или периода графика, к которому прикреплена mql4-программа;
перед переинициализацией в связи со сменой входных параметров;
перед выгрузкой mql4-программы.

OnTick

Событие NewTick генерируется только для экспертов при поступлении нового тика по символу, к графику которого прикреплен эксперт. Функцию OnTick() бесполезно определять в пользовательском индикаторе или скрипте, поскольку событие NewTick для них не генерируется.

Событие Tick генерируется только для экспертов, но это не означает, что эксперты обязаны иметь функцию OnTick(), так как для экспертов генерируются не только события NewTick, но и события Timer, BookEvent и ChartEvent. Должна быть объявлена с типом void, параметров не имеет:

void OnTick();

OnTimer

Функция OnTimer() вызывается при наступлении события Timer, которое генерируется системным таймером только для экспертов и индикаторов – использовать ее в скриптах нельзя. Периодичность наступления этого события устанавливается при подписке на получение функцией EventSetTimer() уведомлений о событии Timer.

Отписывание от приема посылки событий таймера для конкретного эксперта производится функцией EventKillTimer(). Функция должна быть определена с типом void, параметров не имеет:

void OnTimer();

Рекомендуется вызывать функцию EventSetTimer() однократно в функции OnInit(), а функцию EventKillTimer() вызывать однократно в OnDeinit().

Каждый эксперт и каждый индикатор работает со своим таймером, и получает события только от него. При завершении работы mql4-программы таймер уничтожается принудительно, если он был создан, но не был отключен функцией EventKillTimer().

OnTester

Функция OnTester() является обработчиком события Tester, которое автоматически генерируется по окончании исторического тестирования эксперта на заданном интервале дат. Функция должна быть определена с типом double, параметров не имеет:

double OnTester();

Функция вызывается непосредственно перед вызовом функции OnDeinit() и имеет тип возвращаемого значения double. Функция OnTester() может быть использована только в экспертах при тестировании и предназначена в первую очередь для расчета некоторого значения, используемого в качестве критерия Custom max при генетической оптимизации входных параметров.

При генетической оптимизации сортировка результатов в пределах одного поколения производится по убыванию. То есть, лучшими с точки зрения критерия оптимизации считаются результаты с наибольшим значением (для критерия оптимизации Custom max в расчет принимаются значения, возвращенные функцией OnTester). Худшие значения при такой сортировке помещаются в конец и впоследствии отбрасываются и не принимают участия в формировании следующего поколения.

OnChartEvent

OnChartEvent() является обработчиком группы событий ChartEvent:

CHARTEVENT_KEYDOWN — событие нажатия клавиатуры, когда окно графика находится в фокусе;
CHARTEVENT_MOUSE_MOVE — события перемещения мыши и нажатия кнопок мыши (если для графика установлено свойство CHART_EVENT_MOUSE_MOVE=true);
CHARTEVENT_OBJECT_CREATE — событие создания графического объекта (если для графика установлено свойство CHART_EVENT_OBJECT_CREATE=true);
CHARTEVENT_OBJECT_CHANGE — событие изменения свойств объекта через диалог свойств;
CHARTEVENT_OBJECT_DELETE — событие удаления графического объекта (если для графика установлено свойство CHART_EVENT_OBJECT_DELETE=true);
CHARTEVENT_CLICK — cобытие щелчка мыши на графике;
CHARTEVENT_OBJECT_CLICK — событие щелчка мыши на графическом объекте, принадлежащем графику;
CHARTEVENT_OBJECT_DRAG — событие перемещения графического объекта при помощи мыши;
CHARTEVENT_OBJECT_ENDEDIT — событие окончания редактирования текста в поле ввода графического объекта LabelEdit;
CHARTEVENT_CHART_CHANGE — событие изменения графика;
CHARTEVENT_CUSTOM+n — идентификатор пользовательского события, где n находится в диапазоне от 0 до 65535.
CHARTEVENT_CUSTOM_LAST — последний допустимый идентификатор пользовательского события (CHARTEVENT_CUSTOM+65535).

Функция может вызываться в экспертах и индикаторах, должна иметь тип void и 4 параметра:

void OnChartEvent(const int id,         // идентификатор события
                  const long& lparam,   // параметр события типа long
                  const double& dparam, // параметр события типа double
                  const string& sparam  // параметр события типа string
  );

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

Событие	Значение параметра id	Значение параметра lparam	Значение параметра dparam	Значение параметра sparam
Событие нажатия клавиатуры	CHARTEVENT_KEYDOWN	Код нажатой клавиши	Количество нажатий клавиши,сгенерированных за время её удержания в нажатом состоянии	Строковое значение битовой маски, описывающее статус кнопок клавиатуры
События мыши (если для графика установлено свойство CHART_EVENT_MOUSE_MOVE=true)	CHARTEVENT_MOUSE_MOVE	X координата	Y координата	Строковое значение битовой маски, описывающее статус кнопок мыши
Событие создания графического объекта (если для графика установлено свойство CHART_EVENT_OBJECT_CREATE=true)	CHARTEVENT_OBJECT_CREATE	—	—	Имя созданного графического объекта
Событие изменения свойств объекта через диалог свойств	CHARTEVENT_OBJECT_CHANGE	—	—	Имя измененного графического объекта
Событие удаления графического объекта (если для графика установлено свойство CHART_EVENT_OBJECT_DELETE=true)	CHARTEVENT_OBJECT_DELETE	—	—	Имя удаленного графического объекта
Событие щелчка мыши на графике	CHARTEVENT_CLICK	X координата	Y координата	—
Событие щелчка мыши на графическом объекте	CHARTEVENT_OBJECT_CLICK	X координата	Y координата	Имя графического объекта, на котором произошло событие
Событие перемещения графического объекта при помощи мыши	CHARTEVENT_OBJECT_DRAG	—	—	Имя перемещенного графического объекта
Событие окончания редактирования текста в поле ввода графического объекта "Поле ввода"	CHARTEVENT_OBJECT_ENDEDIT	—	—	Имя графического объекта "Поле ввода", в котором завершилось редактирование текста
Событие изменения графика	CHARTEVENT_CHART_CHANGE	—	—	—
Пользовательское событие с номером N	CHARTEVENT_CUSTOM+N	Значение, заданное функцией EventChartCustom()	Значение, заданное функцией EventChartCustom()	Значение, заданное функцией EventChartCustom()

OnCalculate

Функция OnCalculate() вызывается только в пользовательских индикаторах при необходимости произвести расчет значений индикатора по событию Calculate. Обычно это происходит при поступлении нового тика по символу, для которого рассчитывается индикатор. При этом индикатор не обязательно должен быть прикреплен к какому-нибудь ценовому графику данного символа.

Функция OnCalculate() должна иметь тип возвращаемого значения int.

int OnCalculate (const int rates_total,      // размер входных таймсерий
                 const int prev_calculated,  // обработано баров на предыдущем вызове
                 const datetime &time[],     // Time
                 const double &open[],       // Open
                 const double &high[],       // High
                 const double &low[],        // Low
                 const double &close[],      // Close
                 const long &tick_volume[],  // Tick Volume
                 const long &volume[],       // Real Volume
                 const int &spread[]         // Spread
   );

Параметры open[], high[], low[] и close[] содержит массивы с ценами открытия, максимальной, минимальной ценами и ценами закрытия текущего таймфрейма. Параметр time[] содержит массив со значениями времени открытия, параметр spread[] – массив, содержащий историю спредов (если спред предусмотрен для данного торгового инструмента). Параметры volume[] и tick_volume[] содержат соответственно историю торгового и тикового объема.

Чтобы определить направление индексации в массивах time[], open[], high[], low[], close[], tick_volume[], volume[] и spread[], необходимо вызывать функцию ArrayGetAsSeries(). Чтобы не зависеть от умолчаний, необходимо безусловно вызывать функцию ArraySetAsSeries() для тех массивов, с которыми предполагается работать.

Первый параметр rates_total содержит количество баров, доступных индикатору для расчета, и соответствует количеству баров, доступных на графике.

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

Для этого обычно достаточно вернуть значение параметра rates_total, которое содержит количество баров при текущем вызове функции. Если с момента последнего вызова функции OnCalculate() ценовые данные были изменены (подкачана более глубокая история или были заполнены пропуски истории), то значение входного параметра prev_calculated будет установлено в нулевое значение самим терминалом.

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

Пример индикатора:

#property indicator_chart_window
#property indicator_buffers 1
//---- plot Line
#property indicator_label1  "Line"
#property indicator_type1   DRAW_LINE
#property indicator_color1  clrDarkBlue
#property indicator_style1  STYLE_SOLID
#property indicator_width1  1
//--- indicator buffers
double         LineBuffer[];
//+------------------------------------------------------------------+
//| Custom indicator initialization function                         |
//+------------------------------------------------------------------+
int OnInit()
  {
//--- indicator buffers mapping
   SetIndexBuffer(0,LineBuffer,INDICATOR_DATA);
//---
   return(INIT_SUCCEEDED);
  }
//+------------------------------------------------------------------+
//| Custom indicator iteration function                              |
//+------------------------------------------------------------------+
int OnCalculate(const int rates_total,
                const int prev_calculated,
                const datetime& time[],
                const double& open[],
                const double& high[],
                const double& low[],
                const double& close[],
                const long& tick_volume[],
                const long& volume[],
                const int& spread[])
  {
//--- получим количество доступных баров для текущих символа и периода на графике
   int bars=Bars(Symbol(),0);
   Print("Bars = ",bars,", rates_total = ",rates_total,", prev_calculated = ",prev_calculated);
   Print("time[0] = ",time[0]," time[rates_total-1] = ",time[rates_total-1]);
//--- return value of prev_calculated for next call
   return(rates_total);
  }
//+------------------------------------------------------------------+

Смотри также

Выполнение программ, События клиентского терминала, Работа с событиями

Экспортирование функцийПеременные