【MQL5】TranslateKey関数について

スポンサーリンク

TranslateKey関数の働き・役割

TranslateKey関数は、指定された仮想キーコード（特定のキーを示すコード）をUnicode文字に変換するために使用されます。この関数は、現在の入力言語とコントロールキー（ShiftやCtrlなど）の状態を考慮して、キー入力が発生した際にそのキーが表すUnicode文字を取得します。主にキー入力イベントの処理で、ユーザーが押したキーを文字として取得したい場合に活用されます。

TranslateKey関数は、内部的にToUnicodeEx API（Windowsの機能呼び出し用インターフェース）を利用して、仮想キーコードからUnicode文字への変換を行います。ToUnicodeExは、CおよびC++で利用されるWindows API（アプリケーション・プログラミング・インターフェース）で、Windows OSのユーザーインターフェースライブラリ（User32.dll）に含まれており、仮想キーコードをUnicode文字に変換する役割を持っています。このため、多言語対応のシステムでも入力文字を適切に取得することが可能です。

TranslateKey関数の引数について

short  TranslateKey(
  int  key_code      // Unicode文字を受け取るキーコ—ド
  );

TranslateKey関数には、以下の引数が含まれています。

key_code

key_codeは整数型の引数で、Unicode文字に変換するための仮想キーコード（特定のキーを示すコード）を指定します。この仮想キーコードは、一般的にキーボードの特定のキーに割り当てられており、TranslateKey関数はこのコードを基にUnicode文字を取得します。

TranslateKey関数の戻り値について

TranslateKey関数は、指定された仮想キーコードがUnicode文字に変換できる場合、そのUnicode文字を戻り値として返します。戻り値がUnicode文字である場合、変換が正常に行われたことを示します。一方、変換が失敗した場合には、-1が返されます。この失敗は、変換対象のキーコードが有効でない場合や、Shiftキーなど特定の修飾キーが押されていてToUnicodeEx APIで処理できないケースに発生します。

TranslateKey関数を使ったサンプルコード

void OnChartEvent(const int id, const long& lparam, const double& dparam, const string& sparam)
{
    // idがCHARTEVENT_KEYDOWN（キーダウンイベント）であるかを確認
    // CHARTEVENT_KEYDOWNはキーが押された際に発生するイベントIDです
    if (id == CHARTEVENT_KEYDOWN)
    {
        // TranslateKey関数を使用して、押されたキーコードをUnicode文字に変換
        // lparamには押されたキーの仮想キーコード（特定のキーを示すコード）が格納されています
        short sym = TranslateKey((int)lparam);

        //--- 変換されたUnicode文字が有効な文字（0より大きい値）かを判定
        // symが0より大きい場合、変換に成功し有効なUnicode文字が取得できています
        if (sym > 0)
            // Print関数を使用して、取得したUnicode文字をエキスパートログに出力
            // symは数値としてのUnicode値、ShortToString(sym)は文字としてのUnicodeを表します
            Print(sym, "'", ShortToString(sym), "'");
        else
            // 変換に失敗した場合、エラーメッセージをエキスパートログに出力
            // 変換に失敗した理由として、修飾キーや無効なキーコードが含まれている可能性があります
            Print("Error in TranslateKey for key=", lparam);
    }
}

サンプルコード解説

このサンプルコードでは、OnChartEvent関数を使用して、チャート上でのイベントを監視し、キー入力イベントに応じてUnicode文字に変換する処理を行っています。各ステップについて詳しく説明します。

OnChartEvent関数について

OnChartEvent関数は、MQL5の特定のイベントが発生したときに自動的に呼び出される関数で、ここではキー入力イベントを処理しています。以下の4つの引数を取ります。

1. id: 発生したイベントの種類を表すIDで、CHARTEVENT_KEYDOWNなどが含まれます。
2. lparam: イベントの追加情報で、キー入力の場合には押されたキーの仮想キーコード（特定のキーを示すコード）を含みます。
3. dparam: イベントに関連する価格やボリューム情報を保持する変数ですが、ここでは使用しません。
4. sparam: 追加の文字列情報を保持しますが、キー入力イベントでは通常使用しません。

キー入力の確認とTranslateKey関数の利用

まず、idがCHARTEVENT_KEYDOWNであるかを確認し、この条件を満たす場合のみ、キー入力のイベントとして処理を行います。

次に、TranslateKey関数を使用して、lparamに格納されているキーコードを基にUnicode文字に変換します。この変換には、仮想キーコードとキーボードの現在の状態が考慮され、必要に応じて対応する文字がUnicode形式で取得されます。

変換の成功と失敗の判定

変換の結果が0より大きい場合、symには変換に成功したUnicode文字の値が格納されています。ここで、Print関数を使ってエキスパートログに変換結果を出力します。この出力には、数値としてのUnicode値（sym）とその文字形式（ShortToString(sym)）が含まれます。

一方、変換が失敗した場合（戻り値が0以下の場合）には、Print関数を使ってエキスパートログにエラーメッセージを出力します。この場合、TranslateKey関数が期待通りにキーコードを文字に変換できなかったことを示しています。

TranslateKey関数を使ってEAを作る際のアイディア

TranslateKey関数を利用することで、ユーザーのキー入力に応じて動作を変化させるEA（エキスパートアドバイザー）を作成することが可能です。以下にいくつかのアイディアを紹介します。

アイディア1: キー入力による売買指示

TranslateKey関数を活用して、ユーザーが特定のキーを押すことで即座に売買指示を出せるEAを作成できます。例えば、「B」キーを押すと買いポジションを、「S」キーを押すと売りポジションを作成するような仕組みを作り、チャートを見ながら迅速に注文を実行するサポートが可能です。

アイディア2: 注文管理やポジションクローズ

キー入力を使って注文やポジションを管理するEAも考えられます。たとえば、「C」キーで全ポジションをクローズする、「P」キーで一部のポジションをクローズする、などの機能を実装し、チャート上での操作を効率化します。このようなEAは、急激な相場変動時に迅速に対応する助けとなります。

アイディア3: チャート設定やインジケータのカスタマイズ

TranslateKey関数を用いて、キー入力に応じてチャートの表示内容やインジケータのパラメータを変更するEAを作成することも可能です。例えば、「U」キーで移動平均線の期間を長くし、「D」キーで短くするなど、簡単なキー操作でチャートを見やすくカスタマイズする機能を追加できます。

アイディア4: メッセージ入力での記録機能

TranslateKey関数を利用して、ユーザーが入力したテキストをログに記録する機能も考えられます。例えば、ユーザーがトレードに関するメモを残したい場合に、キー入力を通じてメッセージを記録するEAを作成することで、後から振り返る際に役立つデータとして活用できます。

TranslateKey関数を使うことで、EAはキー入力に応じた柔軟な操作が可能となり、売買指示や注文管理、インジケータの調整など多様な機能を実装できるため、ユーザーの利便性を向上させるツールとして活用できます。