【MQL5】ChartSetString関数について

ChartSetString関数の働き・役割
ChartSetString関数の引数について
1. ENUM_CHART_PROPERTY_STRINGについて
  1. CHART_COMMENT
  2. CHART_EXPERT_NAME
2. CHART_SCRIPT_NAME
ChartSetString関数の戻り値について
ChartSetString関数を使ったサンプルコード
サンプルコードに使われた関数や文法要素の簡単な解説

ChartSetString関数の働き・役割

ChartSetString関数は、指定されたチャートのプロパティに文字列型の値を設定するために使用されます。
この関数は、指定されたプロパティに新しい値を設定し、チャート上の表示や情報を変更するために活用されます。
プロパティの設定はチャートのメッセージキューに追加され、他のすべてのコマンドが処理された後に実行されます。これにより、コメントやその他の文字列情報をチャートに表示することが可能となります。

ChartSetString関数の引数について

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

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

chart_idは、対象となるチャートの識別子を指定します。0を指定すると現在のチャートが対象となります。

prop_idは、設定するチャートプロパティの識別子を指定します。この識別子はENUM_CHART_PROPERTY_STRING型の値で、チャートのコメントやチャートのサブウィンドウ名などのプロパティが含まれます。

str_valueは、設定するプロパティの値として使用される文字列です。文字列の長さは最大で2045文字に制限されており、これを超える部分は切り捨てられます。

例：

bool result = ChartSetString(0, CHART_COMMENT, "新しいコメント");

この例では、現在のチャートのコメントプロパティに「新しいコメント」という文字列を設定しています。

ENUM_CHART_PROPERTY_STRINGについて

ChartSetString関数で使用されるENUM_CHART_PROPERTY_STRINGの識別子について説明します。これらの識別子は、チャートの特定のプロパティを指し示し、対応する値を設定するために使用されます。

CHART_COMMENT

プロパティ型：string

説明：チャート内に表示されるコメントテキストを設定します。チャート上に自由にコメントを追加でき、情報の表示やメモの記入に使用されます。

CHART_EXPERT_NAME

プロパティ型：string(読み込み専用)

説明：指定されたchart_idを持つチャート上で起動されたエキスパートアドバイザー（EA）の名前を示します。このプロパティは読み込み専用であり、設定することはできません。

CHART_SCRIPT_NAME

プロパティ型：string(読み込み専用)

説明：指定されたchart_idを持つチャート上で起動されたスクリプトの名前を示します。このプロパティも読み込み専用であり、設定することはできません。

ChartSetString関数の戻り値について

ChartSetString関数は、指定されたプロパティに文字列値を設定する際の成功または失敗を示すブール値を返します。

関数が正常に実行され、指定されたチャートのプロパティにコマンドが追加された場合、戻り値はtrueです。これにより、プロパティの変更が正常にキューに追加されたことを確認できます。

一方、何らかの理由でコマンドがキューに追加されなかった場合、戻り値はfalseです。この場合、GetLastError関数を使用してエラーの詳細情報を取得できます。

以下に、戻り値の使用例を示します。

bool result = ChartSetString(0, CHART_COMMENT, "新しいコメント");
if (result) {
    Print("コメントが正常に設定されました。");
} else {
    Print("コメントの設定に失敗しました。エラーコード: ", GetLastError());
}

この例では、ChartSetString関数の戻り値をチェックし、成功した場合には「コメントが正常に設定されました」と表示し、失敗した場合にはエラーコードを表示します。

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

以下に、ChartSetString関数を使用してチャートにコメントを設定するサンプルコードを示します。

// OnTick関数は新しいティックデータが到着するたびに呼び出されます
void OnTick()
{
    // シンボルの現在のAsk価格とBid価格、そしてスプレッドを取得します
    double Ask = SymbolInfoDouble(Symbol(), SYMBOL_ASK);
    double Bid = SymbolInfoDouble(Symbol(), SYMBOL_BID);
    int Spread = SymbolInfoInteger(Symbol(), SYMBOL_SPREAD);

    // StringFormat関数を使って、取得した価格情報をフォーマットした文字列を作成します
    string comment = StringFormat("価格情報:\nAsk = %G\nBid = %G\nSpread = %d", Ask, Bid, Spread);

    // ChartSetString関数を使用して、チャートにコメントを設定します
    bool result = ChartSetString(0, CHART_COMMENT, comment);

    // 結果を確認し、成功した場合と失敗した場合のメッセージをエキスパートログに出力します
    if (result) {
        Print("コメントが正常に設定されました。");
    } else {
        Print("コメントの設定に失敗しました。エラーコード: ", GetLastError());
    }
}

このコードでは、OnTick関数内でシンボルの価格情報を取得し、それをフォーマットしてチャートのコメントとして設定しています。設定の成功または失敗に応じて、適切なメッセージがエキスパートログに出力されます。

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

OnTick関数

OnTick関数は、新しいティックデータ（価格情報）が到着するたびに自動的に呼び出されます。この関数内で価格情報の更新や取引ロジックの実行を行います。

SymbolInfoDouble関数

SymbolInfoDouble関数は、指定されたシンボルのダブル型プロパティの値を取得します。この例では、現在のAsk価格とBid価格を取得するために使用されています。

第1引数（symbol）：シンボル（通貨ペアや銘柄など）の名前を指定します。
第2引数（prop_id）：取得するプロパティの識別子を指定します。SYMBOL_ASKは現在のAsk価格、SYMBOL_BIDは現在のBid価格を意味します。

SymbolInfoInteger関数

SymbolInfoInteger関数は、指定されたシンボルの整数型プロパティの値を取得します。この例では、現在のスプレッドを取得するために使用されています。

第1引数（symbol）：シンボルの名前を指定します。
第2引数（prop_id）：取得するプロパティの識別子を指定します。SYMBOL_SPREADは現在のスプレッドを意味します。

StringFormat関数

StringFormat関数は、指定された書式に従って文字列を作成します。この例では、取得した価格情報をフォーマットして、表示用の文字列を作成しています。

フォーマット指定子の仕組み

フォーマット指定子は、出力形式を指定するための記号です。StringFormat関数では、フォーマット指定子を使って値を文字列として整形します。指定子は百分率（%）記号の後に続く文字で表されます。

%G：浮動小数点数を効率的な形式で出力します。
%d：整数値を10進数で出力します。

このサンプルコードでは、Ask価格とBid価格に対して%Gを使用し、スプレッドに対して%dを使用しています。

ChartSetString関数

ChartSetString関数は、指定されたチャートのプロパティに文字列型の値を設定します。この例では、チャートにコメントを設定するために使用されています。

第1引数（chart_id）：チャートの識別子を指定します。0を指定すると現在のチャートが対象となります。
第2引数（prop_id）：設定するプロパティの識別子を指定します。CHART_COMMENTはチャートのコメントプロパティを意味します。
第3引数（str_value）：設定するプロパティの値として使用される文字列を指定します。

Print関数

Print関数は、指定されたメッセージをエキスパートログに出力します。この例では、コメントの設定が成功したかどうかを確認するためのメッセージを出力しています。

GetLastError関数

GetLastError関数は、直近に発生したエラーコードを取得します。ChartSetString関数の実行が失敗した場合に、その理由を特定するために使用されます。

以上の各要素を組み合わせることで、シンボルの価格情報を取得し、それをチャートのコメントとして設定する処理を実現しています。