MQL4 Reference Object Functions ObjectCreate

ObjectCreate

The function creates an object with the specified name, type, and the initial coordinates in the specified chart subwindow of the specified chart. There are two variants of the function:

bool  ObjectCreate(
   long          chart_id,      // chart ID
   string        object_name,   // object name
   ENUM_OBJECT   object_type,   // object type
   int           sub_window,    // window index
   datetime      time1,         // time of the first anchor point
   double        price1,        // price of the first anchor point
   ...
   datetime      timeN=0,       // time of the N-th anchor point
   double        priceN=0       // price of the N-th anchor point
   );

The function creates an object with the specified name, type, and the initial coordinates in the specified chart subwindow:

bool  ObjectCreate(
   string        object_name,   // object name
   ENUM_OBJECT   object_type,   // object type
   int           sub_window,    // window index
   datetime      time1,         // time of the first anchor point
   double        price1,        // price of the first anchor point
   datetime      time2=0,       // time of the second anchor point
   double        price2=0,      // price of the second anchor point
   datetime      time3=0,       // time of the third anchor point
   double        price3=0       // price of the third anchor point
   );

Parameters

chart_id

[in] Chart identifier.

object_name

[in] Name of the object. The name must be unique within a chart, including its subwindows.

object_type

[in] Object type. The value can be one of the values of the ENUM_OBJECT enumeration.

sub_window

[in] Number of the chart subwindow. 0 means the main chart window. The specified subwindow must exist (window index must be greater or equal to 0 and less than WindowsTotal()), otherwise the function returns false.

time1

[in] The time coordinate of the first anchor point.

price1

[in] The price coordinate of the first anchor point.

time2=0

[in] The time coordinate of the second anchor point.

price2=0

[in] The price coordinate of the second anchor point.

time3=0

[in] The time coordinate of the third anchor point.

price3=0

[in] The price coordinate of the third anchor point.

timeN=0

[in] The time coordinate of the N-th anchor point.

priceN=0

[in] The price coordinate of the N-th anchor point.

Return Value

When the function is used on the current chart, the chart is accessed directly (a usual behavior in MQL4), and the return of true means a successful creation of an object; otherwise false is returned. In this case, you should call GetLastError() for further information about the error.

To create objects on a different size, an asynchronous function call is used, and ObjectCreate() only returns the result of command adding to the chart queue. In this case true means that the object creation command has been successfully enqueued, while the command execution result is unknown. To check the command execution result, you can use the ObjectFind function or any other function that request object properties, such as ObjectGetXXX. However, you should keep in mind that such functions are added to the end of the queue of that chart, and they wait for the execution result (due to the synchronous call), and can therefore be time consuming.

Note

An object name should not exceed 63 characters. Characters not belonging to the current code page are not allowed (characters that cannot be converted from Unicode to ANSI are replaced with '?'). If programs are to be distributed among users with different code pages, we strongly recommend using Latin characters in object names.

Objects of the OBJ_LABEL type ignore the coordinates. Use the ObjectSet() function to set up the OBJPROP_XDISTANCE and OBJPROP_YDISTANCE properties. The chart sub-windows (if there are sub-windows with indicators in the chart) are numbered starting from 1. The chart main window always exists and has the 0 index. Coordinates must be passed in pairs: time and price. For example, the OBJ_VLINE object needs only time, but price (any value) must be passed, as well.

Example:

//+------------------------------------------------------------------+
//| Script program start function                                    |
//+------------------------------------------------------------------+
int start()
  {
   int i;
   string obj_name="label_object";
   long current_chart_id=ChartID();
//--- creating label object (it does not have time/price coordinates)
   if(!ObjectCreate(current_chart_id,obj_name,OBJ_LABEL,0,0,0))
     {
      Print("Error: can't create label! code #",GetLastError());
      return(0);
     }
//--- set color to Red
   ObjectSetInteger(current_chart_id,obj_name,OBJPROP_COLOR,clrRed);
//--- move object down and change its text
   for(i=0; i<200; i++)
     {
      //--- set text property
      ObjectSetString(current_chart_id,obj_name,OBJPROP_TEXT,StringFormat("Simple Label at y= %d",i));
      //--- set distance property
      ObjectSet(obj_name,OBJPROP_YDISTANCE,i);
      //--- forced chart redraw
      ChartRedraw(current_chart_id);
      Sleep(10);
     }
//--- set color to Blue
   ObjectSetInteger(current_chart_id,obj_name,OBJPROP_COLOR,clrBlue);
//--- move object up and change its text
   for(i=200; i>0; i--)
     {
      //--- set text property
      ObjectSetString(current_chart_id,obj_name,OBJPROP_TEXT,StringFormat("Simple Label at y= %d",i));
      //--- set distance property
      ObjectSet(obj_name,OBJPROP_YDISTANCE,i);
      //--- forced chart redraw
      ChartRedraw(current_chart_id);
      Sleep(10);
     }
//--- delete object
   ObjectDelete(obj_name);
   return(0);
  }