【MQL5】ChartGetString関数について

ChartGetString関数の働き・役割
ChartGetString関数の引数について
1. 書式1
2. 書式2
ChartGetString関数の戻り値について
1. 書式1
2. 書式2
ChartGetString関数を使う際の注意点
1. 同期型関数
2. 非同期型関数
ChartGetString関数を使ったサンプルコード
サンプルコードに使われた関数や文法要素の簡単な解説

ChartGetString関数の働き・役割

ChartGetString関数は、指定されたチャートのプロパティの値を文字列として取得するために使用されます。プロパティは、ENUM_CHART_PROPERTY_STRING列挙型で定義された特定のプロパティを指定します。例えば、チャートに設定されたコメントを取得する際に利用されます。

ChartGetString関数の引数について

ChartGetString関数は2つの異なる形式で呼び出すことができます。それぞれの引数について説明します。

書式1

string ChartGetString(
  long chart_id,                  // チャート識別子
  ENUM_CHART_PROPERTY_STRING prop_id // プロパティ識別子
);

chart_id: チャートの識別子を指定します。0を指定すると現在のチャートを意味します。
prop_id: 取得するチャートプロパティの識別子です。これはENUM_CHART_PROPERTY_STRING型で定義されている必要があります。

※下記参照渡しの記事も参考にしてください。

書式2

bool ChartGetString(
  long chart_id,                  // チャート識別子
  ENUM_CHART_PROPERTY_STRING prop_id, // プロパティ識別子
  string& string_var              // プロパティのターゲット変数
);

chart_id: 書式1と同様に、チャートの識別子を指定します。
prop_id: 書式1と同様に、取得するチャートプロパティの識別子です。
string_var: 取得したプロパティの値を格納するための変数です。

ChartGetString関数の戻り値について

書式1

ChartGetString関数は、指定されたプロパティの値を文字列として直接返します。

書式2

ChartGetString関数は、関数の成功に応じてtrueまたはfalseを返します。成功した場合、プロパティの値は参照によって渡されたstring_varに格納されます。エラーが発生した場合はfalseを返し、詳細なエラー情報はGetLastError関数を使用して取得できます。

ChartGetString関数を使う際の注意点

ChartGetString関数は、チャートにプロットされたコメントを取得するために使用されます。ChartGetString関数やComment関数と併用されることが一般的です。また、ChartGetString関数は同期型であり、呼び出し前にチャートキューに追加されたすべてのコマンドの実行を待機します。そのため、パフォーマンスに影響を与える可能性があることを考慮する必要があります。

同期型関数

同期型関数が呼び出されると、その関数の処理がすべて完了するまで、後続の命令や関数処理は実行されずに待機します。
その為、同期型関数は順番に処理が行われるため確実に結果を取得できますが、場合によっては処理に時間がかかる可能性もあります。

非同期型関数

非同期型関数が呼び出されると、その関数が処理をしている間にも、後続の命令や関数が実行されます。つまり、非同期型関数は他の処理を待たせず、同時に進行することができます。
よって、非同期型関数は複数の処理を同時に進行できるため効率的に処理を行うことができる一方で、複数のタスクが同時に動くため、エラー処理や予期しない動作対策に注意を払う必要があります。

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

// OnStart関数はスクリプトの実行が開始されたときに自動的に呼び出されます
void OnStart()
{
  // ChartSetString関数を使用してチャートにコメントを設定します
  ChartSetString(0, CHART_COMMENT, "テストコメント。\n第二行。\n第三行！");

  // ChartRedraw関数を呼び出してチャートを再描画します
  ChartRedraw();

  // 1秒間の遅延を入れます
  Sleep(1000);

  // ChartGetString関数を使用してチャートのコメントを取得します
  string comment;
  if (ChartGetString(0, CHART_COMMENT, comment))
  {
    // 取得したコメントをエキスパートログに出力します
    Print(comment);
  }
  else
  {
    // コメントの取得に失敗した場合のエラーメッセージを出力します
    Print("コメントの取得に失敗しました。エラーコード: ", GetLastError());
  }
}

このサンプルコードでは、まずChartSetString関数を使ってチャートにコメントを設定します。次に、ChartRedraw関数でチャートを再描画し、1秒間の遅延を挟んでから、ChartGetString関数を使って設定したコメントを取得しています。取得に成功した場合はそのコメントをエキスパートログに出力し、失敗した場合はエラーメッセージを出力します。

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

OnStart関数は、スクリプトの実行が開始されると自動的に呼び出される関数です。この関数内にスクリプトのメイン処理を記述します。

ChartSetString関数は、チャートに文字列を設定する関数です。第1引数に0を指定すると現在のチャートを意味します。第2引数にはCHART_COMMENTを指定して、チャートに設定するコメントのプロパティ識別子を示します。第3引数は設定する文字列であり、”テストコメント。\n第二行。\n第三行！”という文字列を渡しています。なお、\nは改行文字を表し、文字列内で行を分けることができます。

ChartRedraw関数は、チャートを再描画する関数です。設定したコメントをすぐに反映させるために使用します。

Sleep関数は、指定したミリ秒だけスクリプトの実行を一時停止する関数です。ここでは1秒（1000ミリ秒）間の遅延を挟んでいます。

stringは、文字列型の変数を宣言するためのキーワードです。ここではチャートのコメントを格納するためのローカル変数として、commentという名前の変数を宣言しています。

ChartGetString関数は、チャートのコメントを取得する関数です。第1引数に0を指定すると現在のチャートを意味します。第2引数にはCHART_COMMENTを指定して、取得するプロパティの識別子を示します。第3引数のcommentは取得したコメントを格納するための変数です。この関数は取得に成功するとtrueを返し、失敗するとfalseを返します。