MQL5 · Bases du langage
Les fonctions événementielles MQL5 : OnInit, OnTick, OnTimer, OnDeinit
Comprendre quand le terminal appelle OnInit, OnDeinit, OnTick, OnTimer, OnTradeTransaction ou OnChartEvent : signatures exactes, codes de retour, motifs de désinitialisation et file des événements.
Un programme MQL5 ne s’exécute pas de haut en bas comme un script classique : il réagit à des événements que le terminal lui transmet en appelant des fonctions au nom réservé. OnInit() est appelée au chargement, OnDeinit() au déchargement, OnTick() à chaque nouveau tick du symbole du graphique (Expert Advisors uniquement), OnTimer() à intervalle régulier après EventSetTimer(), OnTradeTransaction() à chaque transaction de trading, OnChartEvent() lors des actions sur le graphique, et OnCalculate() dans les indicateurs. Les scripts n’ont qu’un point d’entrée, OnStart(). Le nom, le type de retour et les paramètres de chaque gestionnaire doivent correspondre exactement à la documentation, sinon le terminal ne l’appelle pas.
Cette page fait partie de la rubrique Les bases du langage MQL5. La manière d’organiser ces fonctions dans un robot complet est présentée dans Structure d’un Expert Advisor.
Les gestionnaires et leurs signatures
| Gestionnaire | Signature | Programmes concernés |
|---|---|---|
| OnStart | void OnStart() | Scripts |
| OnInit | int OnInit() ou void OnInit() | EA, indicateurs |
| OnDeinit | void OnDeinit(const int reason) | EA, indicateurs |
| OnTick | void OnTick() | EA |
| OnTimer | void OnTimer() | EA, indicateurs |
| OnTrade | void OnTrade() | EA |
| OnTradeTransaction | void OnTradeTransaction(const MqlTradeTransaction& trans, const MqlTradeRequest& request, const MqlTradeResult& result) | EA |
| OnChartEvent | void OnChartEvent(const int id, const long& lparam, const double& dparam, const string& sparam) | EA, indicateurs |
| OnBookEvent | void OnBookEvent(const string& symbol) | EA, indicateurs |
| OnCalculate | deux formes, voir la rubrique indicateurs | Indicateurs |
| OnTester | double OnTester() | EA, en test |
Les gestionnaires OnTesterInit(), OnTesterPass() et OnTesterDeinit() complètent la liste pour les optimisations ; ils sont traités dans la rubrique consacrée au Strategy Tester.
OnInit : préparer le programme
L’événement Init est généré après le chargement du programme, mais aussi après un changement de symbole ou de timeframe, une recompilation, une modification des paramètres ou, pour un EA, un changement de compte. C’est le lieu des préparations : création des handles d’indicateurs, vérification des paramètres, lancement du timer, reconstruction d’un état à partir de l’historique.
La forme int OnInit() permet de signaler l’issue de l’initialisation avec une valeur de l’énumération ENUM_INIT_RETCODE :
INIT_SUCCEEDED(0) : initialisation réussie ;INIT_FAILED: échec fatal ; un EA est retiré du graphique, un indicateur reste affiché mais inactif ;INIT_PARAMETERS_INCORRECT: jeu de paramètres invalide, utile en optimisation pour rejeter une combinaison ;INIT_AGENT_NOT_SUITABLE: l’agent de test ne convient pas (mémoire insuffisante, par exemple).
Une valeur non nulle déclenche ensuite OnDeinit() avec le motif REASON_INITFAILED. La forme void OnInit() équivaut toujours à un succès.
OnDeinit : nettoyer avant l’arrêt
OnDeinit(const int reason) est appelée avant le déchargement. Le paramètre reason indique la cause, parmi les constantes documentées : REASON_PROGRAM (0, l’EA s’est arrêté lui-même avec ExpertRemove()), REASON_REMOVE (1, retiré du graphique), REASON_RECOMPILE (2), REASON_CHARTCHANGE (3, symbole ou période changés), REASON_CHARTCLOSE (4), REASON_PARAMETERS (5), REASON_ACCOUNT (6), REASON_TEMPLATE (7), REASON_INITFAILED (8) et REASON_CLOSE (9, fermeture du terminal).
La documentation précise que l’exécution d’OnDeinit() est limitée à 2,5 secondes, au-delà desquelles elle est interrompue. On y libère les handles avec IndicatorRelease(), on arrête le timer avec EventKillTimer(), on supprime les objets graphiques créés par le programme. On n’y lance pas d’opérations longues.
Distinguer les motifs est utile : un changement de timeframe (REASON_CHARTCHANGE) n’est pas une raison de supprimer un panneau d’information qui sera recréé une seconde plus tard, alors qu’un retrait du graphique (REASON_REMOVE) l’est.
OnTick : réagir aux prix
L’événement NewTick n’est généré que pour les Expert Advisors, à la réception d’un tick du symbole du graphique sur lequel l’EA est attaché. Les ticks des autres symboles ne déclenchent pas OnTick() ; un EA multi-symboles doit donc s’appuyer sur un timer ou interroger les autres symboles à chaque tick du symbole principal.
Point essentiel documenté : si un événement NewTick est déjà dans la file ou en cours de traitement, le nouveau n’est pas ajouté. Autrement dit, les ticks qui arrivent pendant que OnTick() s’exécute sont ignorés par l’EA. Un OnTick() lent ne rattrape jamais son retard : il saute des cotations. D’où l’importance de limiter les calculs, par exemple en ne travaillant qu’à l’ouverture d’une nouvelle bougie.
La documentation note aussi que OnTick() continue d’être appelée lorsque le bouton de trading automatique est désactivé : seules les requêtes de trading sont bloquées.
OnTimer : agir à intervalle régulier
EventSetTimer(secondes) ou EventSetMillisecondTimer(millisecondes), appelées en général dans OnInit(), déclenchent périodiquement OnTimer(). Chaque programme ne dispose que d’un timer. Comme pour les ticks, un événement Timer n’est pas ajouté à la file s’il y en a déjà un en attente ou en cours de traitement. La documentation de EventSetMillisecondTimer() précise qu’en temps réel, la résolution est limitée à environ 10 à 16 millisecondes. Le timer est détruit à l’arrêt du programme, mais il est propre de l’arrêter explicitement avec EventKillTimer() dans OnDeinit(). Ses usages sont détaillés dans Utiliser OnTimer.
OnTrade et OnTradeTransaction
OnTrade() est appelée lorsqu’une opération de trading s’achève sur le serveur : placement, modification ou suppression d’un ordre, ouverture ou fermeture de position, modification des stops. OnTradeTransaction() va plus loin et reçoit le détail de chaque transaction, avec la requête et le résultat associés. La documentation indique que la file des transactions contient 1024 éléments et que les plus anciens peuvent être perdus si le traitement est trop lent. Le sujet est développé dans OnTradeTransaction : réagir aux événements de trading.
OnChartEvent : interactions avec le graphique
Le terminal génère des événements graphiques lors d’une frappe au clavier sur le graphique actif, de la création, du clic, du déplacement ou de la suppression d’un objet graphique, ou de la fin d’une saisie dans un champ de texte. Un programme peut aussi envoyer ses propres événements avec EventChartCustom(). C’est la base des panneaux et boutons.
Exemple complet : un EA qui journalise son cycle de vie
//+------------------------------------------------------------------+
//| EA : cycle de vie et principaux gestionnaires d'evenements |
//+------------------------------------------------------------------+
input int InpPeriodeMA = 50; // Periode de la moyenne mobile
int g_handleMA = INVALID_HANDLE;
int g_ticks = 0;
int OnInit()
{
if(InpPeriodeMA <= 1)
return(INIT_PARAMETERS_INCORRECT); // combinaison rejetee
g_handleMA = iMA(_Symbol, _Period, InpPeriodeMA, 0, MODE_EMA, PRICE_CLOSE);
if(g_handleMA == INVALID_HANDLE)
{
Print("Creation du handle impossible, erreur ", GetLastError());
return(INIT_FAILED); // l'EA sera retire du graphique
}
if(!EventSetTimer(60)) // OnTimer toutes les 60 secondes
Print("Timer non cree, erreur ", GetLastError());
Print("OnInit : pret");
return(INIT_SUCCEEDED);
}
void OnDeinit(const int reason)
{
EventKillTimer();
if(g_handleMA != INVALID_HANDLE)
IndicatorRelease(g_handleMA);
switch(reason)
{
case REASON_CHARTCHANGE: Print("OnDeinit : changement de symbole ou de periode"); break;
case REASON_PARAMETERS: Print("OnDeinit : parametres modifies"); break;
case REASON_REMOVE: Print("OnDeinit : EA retire du graphique"); break;
default: PrintFormat("OnDeinit : motif %d", reason); break;
}
}
void OnTick()
{
g_ticks++; // compte les ticks traites
}
void OnTimer()
{
PrintFormat("OnTimer : %d ticks traites depuis la derniere minute", g_ticks);
g_ticks = 0;
}
void OnTradeTransaction(const MqlTradeTransaction& trans,
const MqlTradeRequest& request,
const MqlTradeResult& result)
{
if(trans.type == TRADE_TRANSACTION_DEAL_ADD) // une transaction (deal) a ete ajoutee
PrintFormat("Nouveau deal #%I64u sur %s", trans.deal, trans.symbol);
}
void OnChartEvent(const int id, const long& lparam, const double& dparam, const string& sparam)
{
if(id == CHARTEVENT_KEYDOWN)
PrintFormat("Touche pressee, code %I64d", lparam);
}
Attachez cet EA à un graphique, changez de timeframe, modifiez un paramètre puis retirez-le : le journal montre l’enchaînement exact des appels et les motifs de désinitialisation.
Pièges fréquents
- Signature incorrecte :
void OnDeinit()sans paramètre, ouint OnTick(), ne sont pas reconnus comme gestionnaires. - Travail lourd dans OnInit : l’historique d’un symbole peut ne pas être encore disponible au chargement. Préférez vérifier les données au premier tick utile.
- OnTick trop long : les ticks reçus pendant son exécution sont perdus pour l’EA.
- État perdu à la réinitialisation : un changement de période déclenche Deinit puis Init ; les variables globales repartent de leur valeur initiale.
- OnDeinit qui dépasse 2,5 secondes : il est interrompu. Pas d’attente ni de boucle longue à cet endroit.
- Timer non arrêté : sans conséquence à l’arrêt, mais source de confusion si l’on recrée un timer avec une autre période sans arrêter le précédent.
FAQ
Que se passe-t-il si un tick arrive pendant OnTick ?
Selon la documentation, un nouvel événement NewTick n’est pas mis en file si un autre est déjà en attente ou en cours de traitement. L’EA ignore donc les ticks reçus pendant l’exécution de OnTick.
OnTick est-elle appelée pour les autres symboles ?
Non. NewTick n’est généré que pour le symbole du graphique sur lequel l’EA est attaché. Pour suivre d’autres symboles, utilisez un timer ou interrogez leurs prix depuis OnTick.
Quelle valeur renvoyer dans OnInit en cas d’erreur ?
INIT_FAILED pour une erreur fatale (handle impossible à créer, symbole indisponible) et INIT_PARAMETERS_INCORRECT pour des paramètres incohérents. INIT_SUCCEEDED signale le succès.
Combien de temps OnDeinit peut-elle durer ?
La documentation fixe une limite de 2,5 secondes, au-delà de laquelle l’exécution est interrompue. Limitez-vous à la libération des ressources et à quelques messages.
- Types de données en MQL5
- Variables, constantes et portée
- Paramètres input et sinput
- Opérateurs et expressions
- Conditions if, else et switch
- Boucles for, while et do while
- Écrire ses propres fonctions
- Tableaux statiques et dynamiques
- ArraySetAsSeries et indexation des séries
- Manipuler les chaînes de caractères
- Dates, heures et fuseaux
- Structures (struct) et MqlRates, MqlTick
- Énumérations (enum) personnalisées
- #include, #define et #property
- Print, Comment, Alert : déboguer avec le journal
- NormalizeDouble et précision des prix
- SymbolInfoDouble, SymbolInfoInteger
- AccountInfoDouble : lire les informations du compte
- Bien utiliser MetaEditor
