ObjectSetString関数の働き・役割
ObjectSetString関数は、指定されたグラフィカルオブジェクトの文字列型プロパティの値を設定するための関数です。
ObjectSetString関数を使用して、オブジェクトに関連するテキストや名前などを変更できます。
ObjectSetString関数の引数について
ObjectSetString関数の引数構成は以下の通りです。この関数は複数の書式を持つオーバーロード関数です。
※オーバーロード関数についての詳細は↓の記事をご参照ください。
書式1
bool ObjectSetString(
long chart_id, // チャート識別子
string name, // オブジェクト名
ENUM_OBJECT_PROPERTY_STRING prop_id, // プロパティ識別子
string prop_value // プロパティ値
);
chart_idはチャートの識別子で、0を指定すると現在のチャートを意味します。
nameはオブジェクトの名前です。
prop_idはプロパティの識別子で、ENUM_OBJECT_PROPERTY_STRINGの値の一つです。
※ENUM_OBJECT_PROPERTY_STRINGは、グラフィカルオブジェクトの文字列型プロパティを指定するための列挙型です。この列挙型を使用することで、オブジェクトに関連する名前やテキスト、ツールヒントなどの文字列データを取得または設定できます。
ENUM_OBJECT_PROPERTY_STRINGについての詳細は↓の記事をご参照ください。
prop_valueは設定する文字列のプロパティ値です。
書式2
bool ObjectSetString(
long chart_id, // チャート識別子
string name, // オブジェクト名
ENUM_OBJECT_PROPERTY_STRING prop_id, // プロパティ識別子
int prop_modifier, // プロパティ修飾子
string prop_value // プロパティ値
);chart_id、name、prop_id、prop_valueは書式1と同様です。
prop_modifierは指定されたプロパティの修飾子です。修飾子はフィボナッチツールのレベル数及びグラフィックオブジェクトのアンドリューズピッチフォークを示します。レベルの番号付けは0から始まります。
※「修飾子」とは、プロパティの設定や取得をより具体的に制御するための追加情報を提供するものです。MQL5における修飾子は、FibonacciツールやAndrew’s Pitchforkなどの複雑なオブジェクトで特定のレベルやポイントを指定する際に使用されます。これにより、プロパティがオブジェクト全体に対してではなく、特定の部分に適用されるようになります
ObjectSetString関数の戻り値について
ObjectSetString関数は、グラフィカルオブジェクトのプロパティ変更コマンドが正常にチャートに送信された場合にのみtrueを返し、その他の場合はfalseを返します。エラーの詳細を知るには、GetLastError関数を呼び出します。
この関数は非同期呼び出しを使用します。
非同期呼び出しとは、関数がコマンドをチャートのキューに追加した後、すぐに制御を返すことを意味します。コマンドの実行結果を確認するには、指定されたオブジェクトプロパティをリクエストする関数を使用できますが、そのような関数はキューの最後に追加されるため、時間がかかる可能性があります。
オブジェクトの名前が変更された場合、「古い名称のオブジェクトの削除イベント」と「新しい名称のオブジェクトの作成イベント」という2つのイベントが同時に発生します。これらのイベントはエキスパートアドバイザーまたはインジケータのOnChartEvent関数で処理されます。
ObjectSetString関数を使う際の注意点
オブジェクト名はチャート内で一意（他には存在しない状態）でなければなりません。既存の名前を持つオブジェクトのプロパティを変更しようとすると、そのオブジェクトのプロパティが上書きされます。
ObjectSetString関数を使ったサンプルコード
以下は、ObjectSetString関数を使用して、チャート上にある垂直線オブジェクトのテキストプロパティを設定するサンプルコードです。
// スクリプトの開始関数
void OnStart()
{
long chart_id = 0; // 現在のチャート
string obj_name = "MyVerticalLine";
datetime current_time = TimeCurrent(); // 現在時刻の取得
// 垂直線オブジェクトを作成
if(ObjectCreate(chart_id, obj_name, OBJ_VLINE, 0, current_time, 0))
{
PrintFormat("オブジェクト '%s' が作成されました", obj_name);
}
else
{
PrintFormat("オブジェクト '%s' の作成に失敗しました", obj_name);
return;
}
// オブジェクトのテキストプロパティを設定
if(ObjectSetString(chart_id, obj_name, OBJPROP_TEXT, "現在時刻"))
{
PrintFormat("オブジェクト '%s' にテキストが設定されました", obj_name);
}
else
{
PrintFormat("オブジェクト '%s' のテキスト設定に失敗しました", obj_name);
}
}
サンプルコードに使われた関数や文法要素の簡単な解説
OnStart関数
OnStart関数はスクリプトの実行が開始されたときに自動的に呼び出されます。この関数内に実行したい処理を記述します。
ObjectCreate関数
ObjectCreate関数は、指定されたチャート上にオブジェクトを作成するための関数です。このサンプルコードでは、垂直線（OBJ_VLINE）を現在のチャートに作成します。current_timeは現在時刻を示し、垂直線の時間座標として使用されます。
ObjectSetString関数
ObjectSetString関数は、指定されたオブジェクトの文字列型プロパティを設定するための関数です。このサンプルコードでは、垂直線オブジェクトのテキストプロパティに「現在時刻」という文字列を設定しています。
OBJPROP_TEXT識別子
OBJPROP_TEXTは、オブジェクトのテキストプロパティを示す識別子です。
このプロパティを設定することで、オブジェクトに表示されるテキストを指定できます。
このサンプルコードでは、垂直線オブジェクトに「現在時刻」というテキストが設定されます。
設定されたテキストは、オブジェクトを選択したときに表示されるツールチップや、特定のプロパティダイアログで確認することができます。
PrintFormat関数
PrintFormat関数は、指定されたフォーマットに従って文字列を作成し、エキスパートログに出力する関数です。引数としてフォーマット文字列と、それに続く可変数の引数を指定します
TimeCurrent関数
TimeCurrent関数は、現在のサーバー時間を取得するための関数です。返される値はdateTime型です。これを使用して、垂直線を現在時刻に描画します。
このサンプルコードでは、チャート上に現在時刻に垂直線オブジェクトを作成し、そのテキストプロパティを設定します。設定が成功した場合、その旨をエキスパートログに出力します。
コメント