【MQL5】ObjectCreate関数について

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

ObjectCreate関数の働き・役割

ObjectCreate関数は、指定されたチャートにグラフィカルオブジェクトを作成するための関数です。この関数を使用することで、チャート上に線、矢印、テキストラベルなどの様々なオブジェクトを配置できます。

ObjectCreate関数の引数について

ObjectCreate関数の引数構成は以下の通りです。この関数は複数の引数を持ち、最大で30個のアンカーポイントを指定できます。

書式

bool ObjectCreate(
  long chart_id,                    // チャート識別子
  string name,                      // オブジェクト名
  ENUM_OBJECT type,                 // オブジェクトタイプ
  int sub_window,                   // サブウィンドウ番号
  datetime time1,                   // 最初のアンカーポイントの時間
  double price1,                    // 最初のアンカーポイントの価格
  ...                               // 最大30個のアンカーポイント
  datetime timeN=0,                 // N番目のアンカーポイントの時間
  double priceN=0                   // N番目のアンカーポイントの価格
);

各引数の説明

chart_id
チャートの識別子です。0を指定すると現在のチャートを意味します。

name
オブジェクトの名前です。この名前はチャート内で一意(他に同じものが存在しない）である必要があります。

type
オブジェクトのタイプを示します。ENUM_OBJECT列挙型の値のいずれかです。

sub_window
チャートのサブウィンドウの番号を指定します。0はメインチャートウィンドウを意味します。

time1
最初のアンカーポイントの時間を指定します。
※アンカーポイントとは、グラフィックオブジェクトの基準点となる位置のことです。この基準点を中心にして、オブジェクトの位置やサイズが決定されます。アンカーポイントを指定することで、オブジェクトの配置が正確に制御され、チャート上の表示が意図した通りになります。

price1
最初のアンカーポイントの価格を指定します。

timeN
N番目のアンカーポイントの時間を指定します（初期値は0）。

priceN
N番目のアンカーポイントの価格を指定します（初期値は0）。

オブジェクト作成時には、それぞれのオブジェクト特定の数のアンカーポイントのを指定する必要があります。

※各オブジェクトごとに必要なアンカーポイント数については↓の記事をご参照ください。

ObjectCreate関数の戻り値について

ObjectCreate関数は、指定されたチャートのキュー（処理待ちの命令リスト）にオブジェクト作成コマンドが正常に追加された場合にtrueを返し、失敗した場合にはfalseを返します。チャートのキューにコマンドが追加されると、そのコマンドは非同期的に処理されます。

※「非同期的に処理されると」は、コマンドが即座に実行されるのではなく、処理待ちリストに追加され、他の処理と並行して順次実行されることを意味します。これにより、プログラムの他の部分がブロックされることなく処理が進行します。

同じ名前のオブジェクトが既に存在する場合、新しいオブジェクトを作成するのではなく、既存のオブジェクトの位置を更新しようとすることを意味します。つまり、オブジェクトの名前が重複している場合には、既存のオブジェクトの座標が変更される可能性があります。これにより、同じ名前のオブジェクトが複数存在するのを防ぎます。

ObjectCreate関数を使う際の注意点

指定されたオブジェクト名がチャート内で一意であることを確認する必要があります。同じ名前のオブジェクトが既に存在する場合、新しいオブジェクトを作成するのではなく、既存のオブジェクトの位置が変更されます。

ObjectCreate関数は非同期的に処理されるため、コマンドが即座に実行されるわけではありません。これは、コマンドが処理待ちリスト（キュー）に追加され、他の処理と並行して順次実行されることを意味します。そのため、関数がtrueを返しても、オブジェクトが期待通りに表示されない場合があることに注意してください。

ObjectCreate関数では常に非同期呼び出しが使用されます。これが、この関数がチャートキューにコマンドを追加した結果だけを返す理由です。この場合、trueはコマンドが正常にエンキュー（キューに追加）されたことを意味しますが、その実行結果は不明です。

コマンドの実行結果を確認するにはObjectFind関数またはオブジェクトプロパティをリクエストするObjectGetXXX関数などを使用できます。ただし、それらの関数はそのチャートのキューの最後に追加され、（同期呼び出しのために）実行結果を待つため、時間がかかる可能性があります。チャート上で多数のオブジェクトを操作する場合は、この特徴を考慮する必要があります。

オブジェクト名は63文字を超えることはできません。

チャートに指標を含むサブウィンドウが存在する場合、チャートサブウィンドウの番号付けは1から始まります。チャートのメインウィンドウは常に0インデックスを持ちます。

多くのアンカーポイント（最大30）は、将来の使用のために実装されています。同時に、グラフィックオブジェクトのためのアンカーポイントの上限が30であるのは、関数を呼び出す際に使用できるパラメータ数の制限（64以下）によって決定されています。

オブジェクトの名称が変更された場合、「古い名称のオブジェクトの削除イベント」と「新しい名称のオブジェクトの作成イベント」という2つのイベントが同時に形成されます。これらのイベントはエキスパートアドバイザーまたは指標のOnChartEvent関数によって処理されます。

これらの注意点を踏まえ、ObjectCreate関数を使用する際には、正しいパラメータを設定し、オブジェクトの状態を確認するための追加のコードを考慮してください。

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

以下は、ObjectCreate関数を使用してチャート上に垂直線オブジェクトを作成し、そのプロパティを設定するサンプルコードです。

// スクリプトの開始関数
void OnStart() 
{
    // チャートIDとオブジェクト名を定義
    long chart_id = 0; // 現在のチャート
    string obj_name = "MyVerticalLine";

    // 垂直線オブジェクトを作成
    if(!ObjectCreate(chart_id, obj_name, OBJ_VLINE, 0, TimeCurrent(), 0))
    {
        Print("オブジェクトの作成に失敗しました");
        return;
    }

    // 垂直線の色を設定
    ObjectSetInteger(chart_id, obj_name, OBJPROP_COLOR, clrRed);
    
    // オブジェクトの色プロパティを取得する方法1（書式1）
    long color_value = ObjectGetInteger(chart_id, obj_name, OBJPROP_COLOR);
    // 結果をエキスパートログに出力
    PrintFormat("オブジェクト '%s' の色は %d です（書式1）", obj_name, color_value);
    
    // オブジェクトの色プロパティを取得する方法2（書式2）
    long color_value_ref;
    bool result = ObjectGetInteger(chart_id, obj_name, OBJPROP_COLOR, 0, color_value_ref);
    if(result)
    {
        // 成功した場合の処理
        PrintFormat("オブジェクト '%s' の色は %d です（書式2）", obj_name, color_value_ref);
    }
    else
    {
        // 失敗した場合の処理
        PrintFormat("オブジェクト '%s' の色の取得に失敗しました（書式2）", obj_name);
    }
}

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

OnStart関数

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

ObjectCreate関数

ObjectCreate関数は、指定されたチャートにグラフィカルオブジェクトを作成するための関数です。chart_idでチャートの識別子を、nameでオブジェクトの名前を、typeでオブジェクトの種類を指定します。sub_windowでサブウィンドウの番号、time1とprice1で最初のアンカーポイントの時間と価格を指定します。この例では、垂直線オブジェクト（OBJ_VLINE）を現在のチャートに作成しています。