【MQL5】ObjectSetInteger関数について

ObjectSetInteger関数の働き・役割

ObjectSetInteger関数は、指定されたオブジェクトの整数プロパティを設定するための関数です。オブジェクトのプロパティを変更することで、チャート上のオブジェクトの表示や動作をカスタマイズすることができます。

ObjectSetInteger関数の引数について

ObjectSetInteger関数の引数構成は以下の通りです。この関数は複数の書式を持つオーバーロード関数です。

※オーバーロード関数についての詳細は↓の記事をご参照ください。

書式1

bool ObjectSetInteger(
  long chart_id,                     // チャート識別子
  string name,                       // オブジェクト名
  ENUM_OBJECT_PROPERTY_INTEGER prop_id, // プロパティ
  long prop_value                    // 値
);

chart_idはチャートの識別子で、0を指定すると現在のチャートを意味します。0以外の値としては、特定のチャートのIDを使用して他のチャートを指定することができます。

nameはオブジェクトの名前です。

prop_idはプロパティの識別子で、ENUM_OBJECT_PROPERTY_INTEGERの値の一つです。

ENUM_OBJECT_PROPERTY_INTEGERは、MQL5で使用されるオブジェクトの整数型プロパティを定義するenum列挙型です。これにより、チャート上のオブジェクトに関連する様々なプロパティを統一的に管理し、設定や取得を行うことができます。プロパティは色、スタイル、位置、サイズなど多岐にわたり、オブジェクトの表示方法や動作を詳細に制御するために使用されます。

※ENUM_OBJECT_PROPERTY_INTEGERの識別子についての詳細は↓の記事をご参照ください。

prop_valueは設定するプロパティの値です。

書式2

bool ObjectSetInteger(
  long chart_id,                     // チャート識別子
  string name,                       // オブジェクト名
  ENUM_OBJECT_PROPERTY_INTEGER prop_id, // プロパティ
  int prop_modifier,                 // 修飾子
  long prop_value                    // 値
);

chart_id、name、prop_idは書式1と同様です。

prop_modifierは指定されたプロパティの修飾子です。修飾子はフィボナッチツールのレベル数及びグラフィックオブジェクトのアンドリューズピッチフォークを示します。レベルの番号付けは0から始まります。

修飾子とは？

「修飾子」とは、プロパティの設定や取得をより具体的に制御するための追加情報を提供するものです。MQL5における修飾子は、FibonacciツールやAndrew’s Pitchforkなどの複雑なオブジェクトで特定のレベルやポイントを指定する際に使用されます。これにより、プロパティがオブジェクト全体に対してではなく、特定の部分に適用されるようになります。

prop_valueは設定するプロパティの値です。

ObjectSetInteger関数の戻り値について

書式1

ObjectSetInteger関数は、指定されたオブジェクトプロパティに整数型の値を設定し、成功した場合にはtrueを、失敗した場合にはfalseを返します。プロパティ値を直接設定するバリアントです。

書式2

ObjectSetInteger関数は、指定されたオブジェクトプロパティに整数型の値を設定し、成功した場合にはtrueを、失敗した場合にはfalseを返します。修飾子を使用してプロパティ値を設定するバリアントです。

ObjectSetInteger関数を使う際の注意点

ObjectSetInteger関数を使用する際には、いくつかの点に注意が必要です。まず、指定されたオブジェクトが存在しない場合や、無効なプロパティ識別子を指定した場合には、関数はfalseを返します。オブジェクトのプロパティを変更する際には、そのプロパティが有効であるかどうかを確認することが重要です。また、チャートの識別子として0を指定すると、現在のチャートが対象となります。

さらに、修飾子を使用する場合には、修飾子の値が正しい範囲内にあることを確認してください。特に、フィボナッチツールのレベルやグラフィックオブジェクトのアンドリューズピッチフォークなどで使用する場合、レベルの番号付けは0から始まります。間違った修飾子を使用すると、期待通りの動作をしない可能性があります。

エラーが発生した場合は、GetLastError関数を使用して詳細なエラー情報を取得し、問題を特定することができます。これにより、適切なデバッグと修正が可能となります。

※GetLastError関数についての詳細は↓の記事をご参照ください。

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

// スクリプトの開始関数
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関数は、指定されたチャート上にオブジェクトを作成するための関数です。引数としてチャートID、オブジェクト名、オブジェクトタイプ、サブウィンドウ番号、時間、価格を指定します。成功した場合はtrue、失敗した場合はfalseを返します。

ObjectSetInteger関数

ObjectSetInteger関数は、指定されたオブジェクトの整数プロパティを設定するための関数です。書式1では、チャートID、オブジェクト名、プロパティID、プロパティ値を指定します。書式2では、プロパティIDに加えて修飾子を指定します。成功した場合はtrue、失敗した場合はfalseを返します。

ObjectGetInteger関数

ObjectGetInteger関数は、指定されたオブジェクトの整数プロパティを取得するための関数です。書式1では、チャートID、オブジェクト名、プロパティIDを指定し、プロパティ値を直接返します。書式2では、チャートID、オブジェクト名、プロパティID、修飾子を指定し、プロパティ値を参照で受け取ります。成功した場合はtrue、失敗した場合はfalseを返します。

Print関数

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

PrintFormat関数

PrintFormat関数は、指定されたフォーマットに従って文字列を作成し、エキスパートログに出力する関数です。引数としてフォーマット文字列と、それに続く可変数の引数を指定します。

TimeCurrent関数

TimeCurrent関数は、現在のサーバー時間を取得するための関数です。返される値はdateTime型です。これをオブジェクト作成時のタイムスタンプとして使用します。

このサンプルコードでは、”EURUSD”のチャート上に垂直線オブジェクトを作成し、その色プロパティを設定します。その後、設定された色プロパティを取得し、結果をエキスパートログに出力します。書式1と書式2の両方の方法を使用してプロパティを取得しています。

公式リファレンスのサンプルコードについて

公式リファレンスのObjectSetInteger関数を使ったサンプルコードはMetaTrader5のチャート上にカラーボックスを作成するものです。カラーボックスはウェブカラーを使用しており、各色を示すための編集オブジェクトとして配置されます。全体のコード記述は以下の通りです。

//+------------------------------------------------------------------+
//|                                               Table of Web Colors|
//|                         Copyright 2011, MetaQuotes Software Corp |
//|                                       https://www.metaquotes.net |
//+------------------------------------------------------------------+
#define X_SIZE 140     // 編集オブジェクトの幅
#define Y_SIZE 33      // 編集オブジェクトの高さ
//+------------------------------------------------------------------+
//| ウェブカラーの配列                                               |
//+------------------------------------------------------------------+
color ExtClr[140]=
 {
  clrAliceBlue,clrAntiqueWhite,clrAqua,clrAquamarine,clrAzure,clrBeige,clrBisque,clrBlack,clrBlanchedAlmond,
  clrBlue,clrBlueViolet,clrBrown,clrBurlyWood,clrCadetBlue,clrChartreuse,clrChocolate,clrCoral,clrCornflowerBlue,
  clrCornsilk,clrCrimson,clrCyan,clrDarkBlue,clrDarkCyan,clrDarkGoldenrod,clrDarkGray,clrDarkGreen,clrDarkKhaki,
  clrDarkMagenta,clrDarkOliveGreen,clrDarkOrange,clrDarkOrchid,clrDarkRed,clrDarkSalmon,clrDarkSeaGreen,
  clrDarkSlateBlue,clrDarkSlateGray,clrDarkTurquoise,clrDarkViolet,clrDeepPink,clrDeepSkyBlue,clrDimGray,
  clrDodgerBlue,clrFireBrick,clrFloralWhite,clrForestGreen,clrFuchsia,clrGainsboro,clrGhostWhite,clrGold,
  clrGoldenrod,clrGray,clrGreen,clrGreenYellow,clrHoneydew,clrHotPink,clrIndianRed,clrIndigo,clrIvory,clrKhaki,
  clrLavender,clrLavenderBlush,clrLawnGreen,clrLemonChiffon,clrLightBlue,clrLightCoral,clrLightCyan,
  clrLightGoldenrod,clrLightGreen,clrLightGray,clrLightPink,clrLightSalmon,clrLightSeaGreen,clrLightSkyBlue,
  clrLightSlateGray,clrLightSteelBlue,clrLightYellow,clrLime,clrLimeGreen,clrLinen,clrMagenta,clrMaroon,
  clrMediumAquamarine,clrMediumBlue,clrMediumOrchid,clrMediumPurple,clrMediumSeaGreen,clrMediumSlateBlue,
  clrMediumSpringGreen,clrMediumTurquoise,clrMediumVioletRed,clrMidnightBlue,clrMintCream,clrMistyRose,clrMoccasin,
  clrNavajoWhite,clrNavy,clrOldLace,clrOlive,clrOliveDrab,clrOrange,clrOrangeRed,clrOrchid,clrPaleGoldenrod,
  clrPaleGreen,clrPaleTurquoise,clrPaleVioletRed,clrPapayaWhip,clrPeachPuff,clrPeru,clrPink,clrPlum,clrPowderBlue,
  clrPurple,clrRed,clrRosyBrown,clrRoyalBlue,clrSaddleBrown,clrSalmon,clrSandyBrown,clrSeaGreen,clrSeashell,
  clrSienna,clrSilver,clrSkyBlue,clrSlateBlue,clrSlateGray,clrSnow,clrSpringGreen,clrSteelBlue,clrTan,clrTeal,
  clrThistle,clrTomato,clrTurquoise,clrViolet,clrWheat,clrWhite,clrWhiteSmoke,clrYellow,clrYellowGreen
 };
//+------------------------------------------------------------------+
//| 編集オブジェクトを作成と初期化                                   |
//+------------------------------------------------------------------+
void CreateColorBox(int x, int y, color c)
 {
  // 新しい編集オブジェクトの名前を作成
  string name="ColorBox_"+(string)x+"_"+(string)y;

  // 新しい編集オブジェクトを作成
  if(!ObjectCreate(0, name, OBJ_EDIT, 0, 0, 0))
  {
    Print("Cannot create: '", name, "'");
    return;
  }

  // 座標、幅及び高さを設定する
  ObjectSetInteger(0, name, OBJPROP_XDISTANCE, x * X_SIZE);
  ObjectSetInteger(0, name, OBJPROP_YDISTANCE, y * Y_SIZE);
  ObjectSetInteger(0, name, OBJPROP_XSIZE, X_SIZE);
  ObjectSetInteger(0, name, OBJPROP_YSIZE, Y_SIZE);

  // テキストの色を設定する（背景色が黒の場合は白、その他の場合は黒）
  if(clrBlack == c) 
    ObjectSetInteger(0, name, OBJPROP_COLOR, clrWhite);
  else
    ObjectSetInteger(0, name, OBJPROP_COLOR, clrBlack);

  // 背景色を設定する
  ObjectSetInteger(0, name, OBJPROP_BGCOLOR, c);

  // テキストを設定する
  ObjectSetString(0, name, OBJPROP_TEXT, (string)c);
 }
//+------------------------------------------------------------------+
//| スクリプトプログラムを開始する関数                              |
//+------------------------------------------------------------------+
void OnStart()
 {
  // 色のついた編集オブジェクトの 7x20 の表を作る
  for(uint i = 0; i < 140; i++)
    CreateColorBox(i % 7, i / 7, ExtClr[i]);
 }

詳細な解説

定数定義

#define X_SIZE 140     // 編集オブジェクトの幅
#define Y_SIZE 33      // 編集オブジェクトの高さ

X_SIZEとY_SIZEは、カラーボックスの幅と高さを定義する定数です。

カラー配列

color ExtClr[140]= { ... };

ExtClr配列には、140種類のウェブカラーが格納されています。

CreateColorBox関数

ここではオリジナルの関数を定義しています。この関数は、指定された座標にカラーボックスを作成し、そのプロパティを設定します。

引数

int x: 水平方向の位置。
int y: 垂直方向の位置。
color c: カラーボックスの背景色。

処理内容

オブジェクトの名前を作成

string name = "ColorBox_" + (string)x + "_" + (string)y;

カラーボックスの名前を作成します。

オブジェクトの作成

if(!ObjectCreate(0, name, OBJ_EDIT, 0, 0, 0))
{
    Print("Cannot create: '", name, "'");
    return;
}

ObjectCreate関数を使用して新しい編集オブジェクトを作成します。
引数は、チャートID、オブジェクト名、オブジェクトタイプ（編集オブジェクト）を指定し、次にサブウィンドウ番号、時間、価格を0で指定します。
サブウィンドウ番号はオブジェクトを配置するウィンドウの番号、時間はオブジェクトのタイムスタンプ、価格は価格レベルを示します。失敗した場合はエラーメッセージを表示します。

オブジェクトのプロパティ設定

ObjectSetInteger(0, name, OBJPROP_XDISTANCE, x * X_SIZE);
ObjectSetInteger(0, name, OBJPROP_YDISTANCE, y * Y_SIZE);
ObjectSetInteger(0, name, OBJPROP_XSIZE, X_SIZE);
ObjectSetInteger(0, name, OBJPROP_YSIZE, Y_SIZE);

オブジェクトの位置（X軸、Y軸の距離）とサイズ（幅、高さ）を設定します。

x * X_SIZEやy * Y_SIZEは、各カラーボックスの位置を決定するために使用されます。xとyはそれぞれ水平および垂直の位置を示し、X_SIZEとY_SIZEは各ボックスの幅と高さを示します。これにより、各ボックスが適切な位置に配置されます。

第3引数に指定されている各識別子は、それぞれ以下の役割を持ちます。

OBJPROP_XDISTANCEはX軸の距離、OBJPROP_YDISTANCEはY軸の距離、冒頭で定義した定数でOBJPROP_XSIZEはオブジェクトの幅、OBJPROP_YSIZEはオブジェクトの高さを設定します。

x * X_SIZEやy * Y_SIZEを計算することで、各カラーボックスの正確な位置を計算します。
例えば、xが0の場合、カラーボックスは最左端に配置されますが、xが1の場合、カラーボックスは右にX_SIZE分だけ移動します。同様に、yが1の場合、カラーボックスは下にY_SIZE分だけ移動します。このようにして、各ボックスが均等に並びます。

テキストの色を設定

if(clrBlack == c) 
    ObjectSetInteger(0, name, OBJPROP_COLOR, clrWhite);
else
    ObjectSetInteger(0, name, OBJPROP_COLOR, clrBlack);

変数cはカラーボックスの背景色を示します。
この記述は、背景色が黒（clrBlack）の場合にテキスト色を白（clrWhite）に設定し、それ以外の場合にはテキスト色を黒（clrBlack）に設定します。こうすることで、テキストが背景色と十分なコントラストを持ち、視認性が確保されます。例えば、背景色が黒でテキスト色も黒だと文字が見えなくなるため、背景色が黒の場合はテキスト色を白に設定しています。

背景色とテキストの設定

ObjectSetInteger(0, name, OBJPROP_BGCOLOR, c);
ObjectSetString(0, name, OBJPROP_TEXT, (string)c);

背景色とテキストの設定を行います。

識別子「OBJPROP_BGCOLOR」はオブジェクトの背景色を設定するために使用されます。ここでは、変数c（カラーボックスの背景色）を指定しています。

ObjectSetString関数は、オブジェクトの文字列プロパティを設定するための関数です。ここでは、識別子「OBJPROP_TEXT」を使用して、オブジェクトに表示されるテキストを設定しています。

(string)cの記述は、変数cの値（色）を文字列に変換するためのタイプキャストです。このタイプキャストにより、色の値を文字列として表示させることができます。

※タイプキャストについての詳細は↓の記事をご参照ください。

OnStart関数

スクリプトの実行が開始されると、自動的に呼び出される関数です。この関数では、カラーボックスを7列×20行の表形式で配置します。

ループ処理

for(uint i = 0; i < 140; i++)
{
    CreateColorBox(i % 7, i / 7, ExtClr[i]);
}

このループは、140個のカラーボックスを作成するために使用されます。

CreateColorBox関数の第1引数と第2引数に使用されているi % 7とi / 7は、それぞれ水平方向と垂直方向の位置を決定するための計算です。

i % 7は剰余（余り）を計算する演算子です。例えば、iが0から6までの範囲では、剰余は0から6の値になります。これは、水平方向に0から6までの位置にカラーボックスを配置するために使用されます。
i / 7は商（整数の割り算の結果）を計算する演算子です。iが7になると、商は1になり、次の行に移動します。これにより、7列ごとに新しい行にカラーボックスを配置することができます。

例えば、iが8の場合、i % 7は1、i / 7は1になります。これは、2行目の2列目にカラーボックスを配置することを意味します。このようにして、カラーボックスを7列×20行に配置することができます。

実行結果は以下のようになります↓