Event Handling

The MQL5 language provides handling of certain predefined events. The functions for handling these events should be defined in an MQL5 program: function name, return type, a set of parameters (if any) and their types should strictly correspond to the description of an event handling function.

The client terminal event handler uses the return and parameter types to identify functions processing an event. If a certain function has some parameters or a return type not corresponding to the descriptions below, such a function cannot be used for handling an event.

Function

Description

OnStart

The function is called when the Start event occurs to perform actions set in the script

OnInit

The function is called in indicators and EAs when the Init event occurs to initialize a launched MQL5 program

OnDeinit

The function is called in indicators and EAs when the Deinit event occurs to de-initialize a launched MQL5 program

OnTick

The function is called in EAs when the NewTick event occurs to handle a new quote

OnCalculate

The function is called in indicators when the Calculate event occurs to handle price data changes

OnTimer

The function is called in indicators and EAs during the Timer periodic event generated by the terminal at fixed time intervals

OnTrade

The function is called in EAs during the Trade event generated at the end of a trading operation on a trade server

OnTradeTransaction

The function is called in EAs when the TradeTransaction event occurs to process a trade request execution results

OnBookEvent

The function is called in EAs when the BookEvent event occurs to process changes in the market depth

OnChartEvent

The function is called in indicators and EAs when the ChartEvent event occurs to process chart changes made by a user or an MQL5 program

OnTester

The function is called in EAs when the Tester event occurs to perform necessary actions after testing an EA on history data

OnTesterInit

The function is called in EAs when the TesterInit event occurs to perform necessary actions before optimization in the strategy tester

OnTesterDeinit

The function is called in EAs when the TesterDeinit event occurs after EA optimization in the strategy tester

OnTesterPass

The function is called in EAs when the TesterPass even occurs to handle an arrival of a new data frame during EA optimization in the strategy tester

The client terminal sends incoming events to corresponding open charts. Also, events may be generated by charts (chart events) or mql5 programs (custom events). Generating graphical object creation/deletion events can be enabled/disabled by setting the CHART_EVENT_OBJECT_CREATE and CHART_EVENT_OBJECT_DELETE chart properties. Each mql5 application and chart have their own queue of events where all newly arrived events are placed.

A program gets events only from the chart it is running on. All events are handled one after another in the order of their receipt. If the queue already contains the NewTick event or this event is in the processing stage, then the new NewTick event is not added to mql5 application queue. Similarly, if the ChartEvent is already in an mql5 program queue or such an event is being handled, then a new event of this type is not placed into a queue. Timer event handling is processed in the same way – if the Timer event is already in the queue or is being handled, no new timer event is set into a queue.

Event queues have a limited but sufficient size, so the queue overflow is unlikely for a correctly developed program. When the queue overflows, new events are discarded without being set into a queue.

It is strongly recommended not to use infinite loops to handle events. Possible exceptions are scripts handling a single Start event.

Libraries do not handle any events.