Fonctions de Gestion d'Evènement

Le langage MQL5 permet de gérer certains évènements prédéfinis. Les fonctions pour gérer ces évènements doivent être définies dans un programme MQL5 ; le nom de la fonction, le type de retour, la composition des paramètres (s'il y en a) et leurs types doivent correspondre exactement à la description de chaque fonction de gestion des évènements.

Le gestionnaire d'évènements du terminal client identifie les fonctions gérant tel ou tel évènement par le type de la valeur de retour et des paramètres. Si d'autres paramètres ne correspondant pas aux descriptions ci-dessous sont spécifiés pour une certaine fonction, ou qu'un autre type de retour est indiqué, cette fonction ne sera pas utilisée comme gestionnaire d'évènement.

OnStart #

La fonction OnStart() est le gestionnaire de l'évènement Start, qui n'est automatiquement généré que pour exécuter des scripts. Elle doit être de type void sans aucun paramètre :

Pour la fonction OnStart(), le type de retour int peut être spécifié.

OnInit #

La fonction OnInit() est le gestionnaire de l'évènement Init. Elle doit être de type void ou int, sans aucun paramètre :

L'évènement Init est généré immédiatement après qu'un Expert Advisor ou qu'un indicateur est chargé ; cet évènement n'est pas généré pour les scripts. La fonction OnInit() est utilisé pour l'initialisation. Si OnInit() a une valeur de retour de type int, un code de retour différent de zéro signifie un échec de l'initialisation et l'évènement Deinit est généré avec le code de la raison de la désinitialisation REASON_INITFAILED.

Lors du retour de INIT_FAILED, l'EA est supprimé de force du graphique.

Au retour de INIT_FAILED, l'indicateur n'est pas supprimé du graphique. L'indicateur restant sur le graphique n'est pas opérationnel – les gestionnaires d'événements ne sont pas appelés dans l'indicateur.

Pour optimiser les paramètres d'entrée d'un Expert Advisor, il est recommandé d'utiliser les valeurs de l'énumération ENUM_INIT_RETCODE comme code de retour. Ces valeurs sont utilisées pour gérer le déroulé de l'optimisation, incluant la sélection des agents de test les plus appropriés. Pendant l'initialisation d'un Expert Advisor avant le démarrage du test, vous pouvez demander des informations sur la configuration et les ressources d'un agent (le nombre de coeurs, la quantité de mémoire libre, etc.) avec la fonction TerminalInfoInteger(). Selon les informations reçues, vous pouvez soit décider d'utiliser cet agent de test, ou de le rejeter pendant l'optimisation de cet Expert Advisor.

ENUM_INIT_RETCODE

La fonction OnInit() du type void dénote toujours une initialisation réussie.

OnDeinit #

La fonction OnDeinit() est appelée pendant la désinitialisation et est le gestionnaire de l'évènement Deinit. Elle doit être déclarée comme retournant un type void et ne doit avoir qu'un seul paramètre de type const int, contenant le code de la raison de la désinitialisation. Si un type différent est déclaré, le compilateur génère un avertissement, mais la fonction ne peut pas être appelée. Pour les scripts, l'évènement Deinit n'est pas généré et la fonction OnDeinit() ne peut donc pas être utilisée dans les scripts.

L'évènement Deinit est généré pour les Expert Advisors et pour les indicateurs dans les cas suivants :

• avant une réinitialisation en raison du changement du symbole ou de la période du graphique auquel le programme mql5 est attaché ;

• avant une réinitialisation en raison du changement des paramètres d'entrée ;

• avant le déchargemnt du programme mql5.

OnTick #

L'évènement NewTick est généré pour les Expert Advisors uniquement lorsqu'un nouveau tick est reçu pour le symbole auquel l'Expert Advisor est attaché. Il est inutile de définir la fonction OnTick() dans un indicateur personnalisé ou dans un script car l'évenement NewTick n'est pas généré pour eux.

L'évènement Tick n'est généré que pour les Expert Advisors, mais cela ne signifie pas que les Expert Advisors ont besoin de la fonction OnTick(), puisque seuls les évènements NewTick sont générés pour les Expert Advisors, mais les évènements Timer, BookEvent et ChartEvent sont également générés. Elle doit être déclarée de type void, sans aucun paramètre :

OnTimer #

La fonction OnTimer() est appelée lorsque l'évènement Timer survient. Il n'est généré par la minuterie du système que pour les Expert Advisors et les indicateurs - il ne peut pas être utilisé dans les scripts. La fréquence de survenue de l'évènement est définie lors de l'abonnement aux notifications de cet évènement et devant être reçus par la fonction EventSetTimer().

Vous pouvez désenregistrer un certain Expert Advisor pour ne plus reçevoir les évènements de minuterie en utilisant la fonction EventKillTimer(). La fonction doit être déclarée retournant le type void, sans aucun paramètre :

Il est recommandé d'appeler la fonction EventSetTimer() dans la fonction OnInit(), et la fonction EventKillTimer() devrait être appelée dans OnDeinit().

Chaque Expert Advisor, de même que chaque indicateur, fonctionne avec sa propre minuterie et ne reçoit les évènements que de lui. Dès que le programme mql5 s'arrête, la minuterie est détruite en force, si elle a été créée mais n'a pas été désactivée par la fonction EventKillTimer().

OnTrade #

La fonction est appelée lorsque l'évènement Trade survient, qui apparaît lorsque vous changer la liste des ordres placés et des positions ouvertes, l'historique des ordres et l'historique des transactions. Lorsqu'une activité de trading est effectuée (ouverture d'un ordre en attente, ouverture/fermeture d'une position, mise en place d'un stop, déclenchemet d'un ordre en attente, etc.), l'historique des ordres et des transactions et/ou la liste des positions et des ordres en cours sont changés conforméménet.

Les utilisateurs doivent implémenter de façon indépendante dans le code la vérification de l'état du compte de trading lorsqu'un évènement est reçu (si cela est requis par les conditions de la stratégie de trading). Si l'appel à la fonction OrderSend() s'est terminé avec succès et a retourné true, cela signifie que le serveur de trading a placé l'ordre dans la queue pour être exécuté et lui a assigné un numéro de ticket. Dès que le serveur a traité cet ordre, l'évènement Trade est généré. Et si un utilisateur a toujours la valeur du ticket, il peut savoir ce qu'il s'est passé sur l'ordre avec cette valeur pendant la gestion de l'évènement OnTrade().

OnTradeTransaction #

Lorsque certaines actions sont effectuées sur un compte de trading, son état change. Ces actions correspondent à :

• L'envoi d'une demande de trade depuis une application MQL5 dans le terminal client en utilisant les fonctions OrderSend et OrderSendAsync et leurs exécutions ultérieures ;
• L'envoi d'une demande de trade via l'interface graphique du terminal et son exécution ultérieure ;

• L'action des ordres en attente et des ordres stop sur le serveur ;
• L'exécution d'opérations sur le serveur de trades.

Les transactions de trading suivantes sont effectuées comme étant le résultat de ces actions :

• gestion d'une demande de trade ;
• changement d'ordres d'ouverture ;
• changement de l'historiuque des ordres ;
• changement de l'historique des transactions ;
• changement des positions.

Par exemple, lors de l'envoi d'un ordre d'achat au marché, il est géré, un ordre buy correspondant est créé pour le compte, l'ordre est alors exécuté et supprimé de la liste des ordres ouvertes, il est ensuite ajouté à l'historique des ordres, une transaction correspondante est ajoutée à l'historique et une nouvelle position est créée. Toutes ces actions sont des transactions de trading. L'arrivée d'une telle transaction dans le terminal est un évènement TradeTransaction. Il appelle le gestionnaire OnTradeTransaction

Le gestionnaire contient trois paramètres :

• trans - ce paramètre prend la structure MqlTradeTransaction décrivant une transaction de trading appliquée à un compte de trading ;
• request - ce paramètre prend la structure MqlTradeRequest décrivant une demande de trade ;
• result - ce paramètre prend la structure MqlTradeResult décrivant le résultat de l'exécution de la demande de trade.

Les deux derniers paramètres request et result sont remplis par valeurs seulement pour les transactions de type TRADE_TRANSACTION_REQUEST, les données des transactions peuvent être récupérées dans le paramètrs type de la variable trans. Notez que dans ce cas, le champ request_id dans la variable result contient l'identifiant de la demande de trade request, après l'exécution de laquelle la transaction de trading décrite dans la variable trans a été effectuée. L'identifiant de la demande permet d'associer l'action effectuée (appel des fonctions OrderSend ou OrderSendAsync) avec le résultat de cette action envoyée à OnTradeTransaction().

Une demande de trade envoyée manuellement depuis le terminal ou via les fonctions OrderSend()/OrderSendAsync() peut générer plusieurs transactions consécutives sur le serveur de trades. La priorité de l'arrivée des ces transactions dans le terminal n'est pas garantie. Vous ne devez donc pas supposer qu'un groupe de transactions arrivera après un autre lors du développement de votre algorithme de trading.

Après avoir envoyé les transactions de trade pour un compte client, elles sont régulièrement placée dans la queue des transactions de trade du terminal, à partir de laquelle elles sont régulièrement envoyées vers le point d'entrée OnTradeTransaction dans l'ordre d'arrivée au terminal.

Lors du traitement des transactions de trade par un Expert Advisor avec la fonction OnTradeTransaction, le terminal continue de traiter les nouvelles transactions de trade qui continuent d'arriver. L'état d'un compte de trading peut donc changer pendant une opération OnTradeTransaction. Par exemple, alors qu'un programme MQL5 traite l'ajout d'un nouvel ordre, il peut être exécuté, supprimé de la liste des ordres ouverts et déplacé dans l'historique. Par la suite, l'application sera notifiée de ces évènements.

La longueur de la queue des transactions est de 1024 éléments. Si OnTradeTransaction traite une nouvelle transaction depuis trop longtemps, les anciennes transactions de la queue peuvent etre remplacées par les nouvelles.

OnTester #

La fonction OnTester() est le gestionnaire de l'évènement Tester qui est automatiquement généré après que le test d'un Expert Advisor sur l'historique et sur un intervalle choisi est terminé. La fonction doit retourner un type double, et ne pas avoir de paramètres :

La fonction est appelée juste avant l'appel à OnDeinit() et a le même type de valeur de retour - double. OnTester() ne peut être utilisée que lors du test d'Expert Advisors. Son intérêt principal est de calculer une certaine valeur qui est utilisée comme Critère max personnalisé dans l'optimisation génétique des paramètres d'entrée.

Dans l'optimisation génétique, le tri descendant est appliqué aux résultats en une seule génération. C'est à dire que du point de vue du critère d'optimisation, les meilleurs résultats sont ceux ayant les plus grandes valeurs (pour le Critère maximum d'optimisation, les valeurs retournées par la fonction OnTester sont prises en compte). Dans ce type de tri, les valeurs les moins bonnes sont positionnées à la fin et jetées ensuite et ne participet pas à la formation de la génération suivante.

OnTesterInit #

La fonction OnTesterInit() est le gestionnaire de l'évènement TesterInit, qui est automatiquement généré avant le lancement de l'optimisation de l'Expert Advisor dans le strategy tester. La fonction doit être définie avec le type de retour void. Elle n'a pas de paramètres :

Avec le lancement de l'optimisation, un Expert Advisor ayant les fonctions OnTesterDeinit() ou OnTesterPass() est automatiquement chargé dans un graphique séparé du terminal avec le symbole et la période spécifiés dans le tester, et reçoit l'évènement TesterInit. La fonction est utilisée pour l'initialisation des Expert Advisor avant le lancement de l'optimisation pour pouvoir ensuite traiter les résultat de l'optimisation.

OnTesterPass #

La fonction OnTesterPass() est le gestionnaire de l'évènement TesterPass, qui est automatiquement généré lorsqu'un nouveau cadre est reçu pendant une optimisation d'un Expert Advisor dans le strategy tester. La fonction doit être définie avec le type de retour void. Elle n'a pas de paramètres :

Un Expert Advisor ayant la fonction OnTesterPass() est automatiquement chargé dans un graphique séparé du terminal avec le symbole et la période spécifiés pour le test, et reçoit les évènement TesterPass lorsqu'un nouveau cadre est reçu pendant l'optimisation. La fonction est utilisée pour la gestion dynamique des résultats d'optimisation "sur le vif" sans attendre la fin de l'optimisation. Les cadres sont ajoutés avec la fonction FrameAdd(), qui peut être appelée après la fin d'une passe dans la fonction OnTester().

OnTesterDeinit #

OnTesterDeinit() est le gestionnaire de l'évènement TesterDeinit, qui est automatiquement généré après la fin de l'optimisation d'un Expert Advisor dans le strategy tester. La fonction doit être définie avec le type de retour void. Elle n'a pas de paramètres :

Un Expert Advisor ayant la fonction TesterDeinit() est automatiquement chargé sur un graphique au lancement de l'optimisation, et reçoit TesterDeinit après sa fin. La fonction est utilisée pour le traitement final de tous les résultats d'optimisation.

OnBookEvent #

La fonction OnBookEvent() est le gestionnaire de BookEvent. BookEvent est généré pour les Expert Advisors et les indicateurs lorsque le Depth of Market change. Elle doit être de type void et avoir un paramètre de type string :

Pour recevoir les évènements BookEvent pour n'importe quel symbole, nous n'avez qu'à vous inscrire pour recevoir les évènements pour ce symbole en utilisant la fonction MarketBookAdd(). Pour se désabonner des évènements BookEvent pour un symbole donnée, appelez MarketBookRelease().

Contrairement aux autres évènements, l'évènement BookEvent est diffusé. Cela signifie que si un Expert Advisor s'abonne pour recevoir les évènements BookEvent en utilisant MarketBookAdd, tous les autres Experts Advisors qui ont une fonction OnBookEvent() recevront également cet évènement. Il est donc nécessaire d'analyser le nom du symbole qui est passé à la fonction dans le paramètre const string& symbol.

OnChartEvent #

OnChartEvent() est le gestionnaire d'un groupe d'évènements ChartEvent events:

• CHARTEVENT_KEYDOWN – évènement d'appui sur une touche lorsque la fenêtre du graphique reçoit le focus ;

• CHARTEVENT_MOUSE_MOVE – évènements de déplacement et de clics de souris (si CHART_EVENT_MOUSE_MOVE=true est défini pour le graphique) ;

• CHARTEVENT_OBJECT_CREATE – évènement de création d'un objet graphique (si CHART_EVENT_OBJECT_CREATE=true est défini pour le graphique) ;

• CHARTEVENT_OBJECT_CHANGE – évènement de changement de la propriété d'un objet via la boîte de dialogue des propriétés ;

• CHARTEVENT_OBJECT_DELETE – évènement de suppression d'un objet graphique (si CHART_EVENT_OBJECT_DELETE=true est défini pour le graphique) ;

• CHARTEVENT_CLICK – évènement de clic de souris sur le graphique ;

• CHARTEVENT_OBJECT_CLICK – évènement de clic de souris dans un objet graphique appartenant au graphique ;

• CHARTEVENT_OBJECT_DRAG – évènement de déplacement d'un objet graphique avec la souris ;
• CHARTEVENT_OBJECT_ENDEDIT – évènement de fin de l'édition du texte dans la zone de saisie d'un objet graphique LabelEdit ;

• CHARTEVENT_CHART_CHANGE  – évènement de changement du graphique ;

• CHARTEVENT_CUSTOM+n – identifiant de l'évènement utilisateur, où n est dans l'intervalle de 0 à 65535.
• CHARTEVENT_CUSTOM_LAST – le dernier identifiant possible pour un évènement personnalisé (CHARTEVENT_CUSTOM +65535).

La fonction ne peut être appelée que dans les Expert Advisors et les indicateurs. La fonction doit être de type void avec 4 paramètres :

Pour chaque type d'évènement, les paramètres d'entrée de la fonction OnChartEvent() ont des valeurs définies requises pour le traitement de cet évènement. Les évènements et les valeurs passés via ces paramètres sont listés dans le tableau ci-dessous.

OnCalculate #

La fonction OnCalculate() n'est appelée que pour les indicateurs personnalisés lorsqu'il est nécessaire de calculer les valeurs de l'indicateur pour l'évènement Calculate. Ceci arrive habituellement lorsqu'un nouveau tick est reçu pour le symbole pour lequel l'indicateur est calculé. Cette indicateur n'a pas besoin d'être attaché à un graphique des prix de ce symbole.

La fonction OnCalculate() doit retourner un type int. Il existe deux définitions possibles. Vous ne pouvez pas utiliser les deux versions de la fonction dans un même indicateur.

La première forme est prévue pour les indicateurs qui peuvent être calculés sur un seul buffer de données. Un exemple d'indicateur de ce type est le Custom Moving Average.

²As the price[] array, one of timeseries or a calculated buffer of some indicator can be passed. Pour déterminer la direction de l'indexation du tableau price[], appelez ArrayGetAsSeries(). Afin de ne pas dépendre des valeurs par défaut, vous devez appeler la fonction ArraySetAsSeries() pour ces tableaux de façon inconditionnelle.

Les séries de temps nécessaires ou un indicateur devant être utilisé comme le tableau price[] peuvent être sélectionnés par l'utilisateur dans l'onglet "Paramètres" lors du lancement de l'indicateur. Pour cela, vous devez sélectionner l'entrée nécessaire dans la liste déroulante du champ "Appliquer à".

Pour recevoir les valeurs d'un indicateur dans d'autres programmes mql5, la fonction iCustom() est utilisée, et retourne le handle de l'indicateur pour les opérations à suivre. Vous pouvez également spécifier le tableau price[] approprié ou le handle d'un autre indicateur. Ce paramètre doit être le dernier dans la liste des variables d'entrée de l'indicateur.
Exemple :

Dans cet exemple, le dernier paramètre passé esst la valeur PRICE_TYPICAL (de l'énumération ENUM_APPLIED_PRICE), qui indique que l'indicateur sera construit sur les prix typiques obtenus comme (High+Low+Close)/3. Si ce paramètre n'est pas spécifié, l'indicateur est construit sur les valeurs PRICE_CLOSE, c'est à dire les prix de clôture de chaque barre.

Un autre exemple montrant le passage du handle de l'indicateur comme le dernier paramètre pour spécifier le tableau price[], est donné dans la description de la fonction iCustom().
 

La seconde forme est prévue pour tous les autres indicateurs dans lesquels plus d'une séries de données est utilisée pour les calculs.

Les paramètres de open[], high[], low[] et close[] contiennent les tableaux des prix open, high, low et close de la période courante. Le paramètre time[] contient in tableau avec les valeurs des heures open, le paramètre spread[] est un tableau contenant l'historique des spreads (si un if spread est fourni pour l'instrument tradé). Les paramètres volume[] et tick_volume[] contiennent l'historique des volumes de trade et de tick respectivement.

Pour déterminer la direction d'indexation de time[], open[], high[], low[], close[], tick_volume[], volume[] et spread[], appelez ArrayGetAsSeries(). Afin de ne pas dépendre des valeurs par défaut, vous devez appeler la fonction ArraySetAsSeries() pour ces tableaux de façon inconditionnelle.

Le premier paramètre rates_total contient le nombre de barres disponibles pour le calcul de l'indicateur et correspond au nombre de barres disponibles dans le graphique.

Nous devons noter la connexion entre la valeur de retour de OnCalculate() et le deuxième paramètre d'entrée prev_calculated. Pendant l'appel de la fonction, le paramètre prev_calculated contient la valeur retournée par OnCalculate() pendant l'appel précédent. Ceci permet d'avoir des algorithmes plus économiques pour le calcul de l'indicateur afin d'éviter les calculs répétés pour les barres qui n'ont pas changé depuis la dernière exécution de cette fonction.

Pour cela, il est habituellement suffisant de retourner la valeur du paramètre rates_total, qui contient le nombre de barre dans l'appel actuel de la fonction. Si depuis le dernier appel à OnCalculate() les prix ont changé (un historique plus profond téléchargé ou les manques dans l'historique sont remplis)), la valeur du paramètre d'entrée prev_calculated sera mis à zéro par le terminal.

Note : si OnCalculate retourne zéro, alors les valeurs de l'indicateur ne sont pas affichées dans la fenêtre des Données dans le terminal client.

Pour mieux le comprendre, il est utile de démarrer l'indicateur dont le code est ci-dessous.

Example d'Indicateur :

Voir aussi

Exécuter des Programmes, Evènements du Terminal Client, Travailler avec des Evènements