【MQL5】ChartApplyTemplate関数について

ChartApplyTemplateの働き・役割
ChartApplyTemplateの引数について
1. 第1引数
2. 第2引数
ChartApplyTemplateの戻り値について
ChartApplyTemplateを使う際の注意点
ChartApplyTemplateを使ったサンプルコード
サンプルコードに使われた関数や文法要素の簡単な解説
テンプレートファイルの検索ルール

ChartApplyTemplateの働き・役割

ChartApplyTemplate関数は、指定したテンプレートをチャートに適用するために使用されます。
テンプレートとは、チャートの設定や表示オブジェクトを保存したファイルであり、これを使用することで、異なるチャートに同じ設定を簡単に適用することができます。
ChartApplyTemplate関数は、チャートメッセージキュー（処理待ちの命令リスト）にコマンドを追加し、以前の全てのコマンドの処理後に実行されます。

ChartApplyTemplateの引数について

ChartApplyTemplate関数の引数構成は以下の通りです。

bool ChartApplyTemplate(
   long chart_id,     // チャートの識別子
   const string filename    // テンプレートファイルの名前
);

第1引数

chart_idはチャートの識別子を指定します。0を指定すると現在のアクティブなチャートを意味します。特定のチャートを指定する場合は、そのチャートのIDを使用します。

第2引数

filenameはテンプレートファイルの名前を指定します。このファイル名は、テンプレートが保存されている場所に存在する必要があります。拡張子「.tpl」を含めて指定します。

ファイル名だけでなく、ファイルパスを指定することも可能です。

※ファイルパスの指定についてはこの後詳しく解説します。

ChartApplyTemplateの戻り値について

ChartApplyTemplate関数は、テンプレートの適用が成功したかどうかを示すブール値を返します。具体的には、コマンドがチャートキュー（処理待ちの命令リスト）に追加された場合はtrueを、そうでない場合はfalseを返します。エラー情報を取得するには、GetLastError関数を使用します。

ChartApplyTemplateを使う際の注意点

ChartApplyTemplate関数を使用する際には以下の点に注意してください。

テンプレートファイルの存在確認: 指定したテンプレートファイルが存在することを確認してください。ファイル名のスペルミスやパスの間違いがないように注意しましょう。
チャートIDの確認: 正しいチャートIDを指定してください。間違ったIDを指定すると、意図しないチャートにテンプレートが適用される可能性があります。
エキスパートアドバイザーの動作: 新しいテンプレートの読み込みが成功した場合、エキスパートアドバイザー（EA）はアンロード（実行中のEAをメモリから取り除くこと）されます。つまり、EAがチャート上で動作し続けることはできなくなり、動作を停止します。テンプレートを適用することで、EAとそのテンプレートの設定を共存させることはできません。
取引権限の制限: セキュリティ上の理由で、テンプレートの適用によって取引権限が制限されることがあります。
例えば、ライブ取引許可はChartApplyTemplate関数を使用してテンプレートを適用することによって開始されたエキスパートアドバイザーには自動的には付与されません。

ChartApplyTemplateを使ったサンプルコード

以下に、ChartApplyTemplate関数を使用したサンプルコードを示します。このコードは、現在のアクティブなチャートに「ExampleTemplate.tpl」というテンプレートを適用するものです。

// OnStart関数はスクリプトの実行が開始されたときに自動的に呼び出されます
void OnStart()
{
    // テンプレートファイルのパスを指定します
    string templatePath = "\\Files\\ExampleTemplate.tpl";

    // テンプレートファイルが存在するか確認します
    if(FileIsExist(templatePath))
    {
        // テンプレートを適用する
        bool result = ChartApplyTemplate(0, templatePath);

        // テンプレートの適用結果をエキスパートログに出力する
        if(result)
        {
            Print("テンプレートの適用に成功しました。");
            // チャートを再描画
            ChartRedraw();
        }
        else
        {
            Print("テンプレートの適用に失敗しました。エラーコード: ", GetLastError());
        }
    }
    else
    {
        Print("テンプレートファイルが見つかりません: ", templatePath);
    }
}

サンプルコードに使われた関数や文法要素の簡単な解説

OnStart関数

OnStart関数は、スクリプトの実行が開始されたときに自動的に呼び出されます。MQL5でスクリプトを作成する際に基本的なエントリーポイントとなる関数です。

ChartApplyTemplate関数

ChartApplyTemplate関数は、指定したチャートにテンプレートを適用するために使用されます。引数としてチャートIDとテンプレートファイル名を受け取ります。

FileIsExist関数

FileIsExist関数は、指定したファイルが存在するかどうかを確認します。存在する場合はtrueを、存在しない場合はfalseを返します。

Print関数

Print関数は、指定したメッセージをエキスパートログに出力します。デバッグや情報の確認に使用される基本的な関数です。

ChartRedraw関数

ChartRedraw関数は、チャートを再描画します。テンプレート適用後にチャートの表示を更新するために使用されます。

このように、ChartApplyTemplate関数を使うことで、簡単にテンプレートをチャートに適用し、同じ設定を複数のチャートに反映させることができます。テンプレートを活用することで、トレードの効率を向上させることが可能です。

テンプレートファイルの検索ルール

テンプレートファイルは次のルールに従って検索されます：

//--- terminal_data_directory\MQL5\ でテンプレートを探す
ChartApplyTemplate(0,"\\first_template.tpl");
//--- directory_of_EX5_file\ に続いて terminal_data_directory\Profiles\Templates\でテンプレートを探す
ChartApplyTemplate(0,"second_template.tpl");
//--- directory_of_EX5_file\My_templates\ に続いて terminal_directory\Profiles\Templates\My_templates\ でテンプレートを探す
ChartApplyTemplate(0,"My_templates\\third_template.tpl");

a. バックスラッシュ”\”がパスの先頭にある場合

テンプレートは_terminal_data_directory\ MQL5フォルダとの相対パス（基準となるフォルダからのパス）で検索されます。バックスラッシュ””はディレクトリの区切りを表し、パスの先頭にある場合、そのパスはMQL5ディレクトリからの相対パス（基準となるフォルダからのパス）として解釈されます。

//--- terminal_data_directory\MQL5\ でテンプレートを探す
ChartApplyTemplate(0,"\\first_template.tpl");

この場合、テンプレートは_terminal_data_directory\MQL5\first_template.tplを基準に検索されます。バックスラッシュがパスの先頭にあるため、_terminal_data_directory\MQL5フォルダから相対的に検索します。

※。バックスラッシュが2つある部分は、プログラム内でバックスラッシュを認識させるための記法です。通常、バックスラッシュはエスケープシーケンスの一部として使用され、特定の文字（例えば、”\n”は改行、”\t”はタブ）を表します。バックスラッシュ自体を文字列内で表現するためには、2つのバックスラッシュ（”\”）を使用します。

相対パスの記述方式と見方

相対パスは、現在の作業ディレクトリ（フォルダ）を基準にしてファイルやフォルダを指定する方法です。これに対して、絶対パスはファイルシステムのルートから完全なパスを指定します。

相対パス: 基準フォルダからの経路を示す。例: “Templates\my_template.tpl”
絶対パス: ルートからの完全な経路を示す。例: “C:\Program Files\MetaTrader5\MQL5\Templates\my_template.tpl”

相対パスの利点は、プログラムが異なる環境で実行されても柔軟にファイルを参照できることです。バックスラッシュが先頭にある場合は、特定の基準フォルダからの相対パスとして解釈されます。

b. バックスラッシュがない場合

テンプレートは、ChartApplyTemplate関数を呼び出した実行可能なEX5ファイルの位置からの相対パスで検索されます。この場合、指定されたテンプレートファイルのパスは、現在の実行ファイルの場所を基準にして解釈されます。

//--- directory_of_EX5_file\ に続いて terminal_data_directory\Profiles\Templates\でテンプレートを探す
ChartApplyTemplate(0,"second_template.tpl");

この場合、テンプレートはChartApplyTemplate関数を呼び出した実行可能なEX5ファイルの位置から相対的に検索されます。最初にその位置を基準に検索し、見つからない場合はterminal_data_directory\Profiles\Templates\フォルダで検索されます。

c. 上記の2つで見つからない場合

テンプレートは terminal_directory\Profiles\Templates\ フォルダで検索されます。ここで、terminal_directoryはMetaTrader5クライアント端末が実行されているフォルダを指します。

//--- directory_of_EX5_file\My_templates\ に続いて terminal_directory\Profiles\Templates\My_templates\ でテンプレートを探す
ChartApplyTemplate(0,"My_templates\\third_template.tpl");

フォルダの場所について

terminal_directory: MetaTrader5が実行されているフォルダ。
terminal_data_directory: 編集可能なファイルが保存されているフォルダ。これは通常、オペレーティングシステム、ユーザー名、セキュリティ設定によって異なる場所にあります。

これらのフォルダの場所は、TerminalInfoString関数を使用して取得することができます。

void OnStart()
{
   // terminal_directoryを取得
// MetaTrader 5クライアント端末が実行されているフォルダのパスを取得します
string terminal_path = TerminalInfoString(TERMINAL_PATH);
Print("Terminal directory:", terminal_path);

// terminal_data_directoryを取得
// 編集可能なファイルが保存されているフォルダのパスを取得します
string terminal_data_path = TerminalInfoString(TERMINAL_DATA_PATH);
Print("Terminal data directory:", terminal_data_path);
}

このサンプルコードは、MetaTrader5クライアント端末が実行されているフォルダ（terminal_directory）と、編集可能なファイルが保存されているフォルダ（terminal_data_directory）のパスを取得し、それぞれのパスをエキスパートログに出力しています。
TERMINAL_PATHは、TerminalInfoString関数で使用される定数で、ENUM_TERMINAL_INFO_STRING列挙子に属しています。

TERMINAL_DATA_PATHは、編集可能なファイルが保存されているフォルダのパスを示します。このフォルダには、ユーザーの設定ファイル、データファイル、およびスクリプトやテンプレートなどが保存されており、通常はオペレーティングシステムやセキュリティ設定によって異なる場所にあります。TERMINAL_DATA_PATHも、TerminalInfoString関数で使用される定数で、ENUM_TERMINAL_INFO_STRING列挙子に属しています。