Object functions
Hi folks,
You use objects (Line studies, shapes, arrows and texts) as a visual aid to facilitate the analysis of chart.
Drawing objects in MetaTrader manually is an easy task, you just have to choose the object you want to draw from the Insert menu or from the Line Studies toolbar (Figures 1 and 2).
Then you can modify/delete the created object by selecting the object on the chart and right click it then choose the operation you want from the context menu (Figure 3).
Figure 1 - Insert menu
Figure 2 - Line studies toolbar
Figure 3 - Objects context menu
Today we are going to know how to programicaly work with objects in MQL4. We are going to study the Object functions which enable us to handle everything you can manually do with the objects and the things you can't do manually.
For example if you have hundred of objects on the chart and you want to delete them, it's a hard task to do it manually but in MQL4 it's a very easy task (as you'll see later)
Let's see the Object functions:
ObjectCreate:
Syntax:
| bool ObjectCreate(string name, int type, int window, datetime time1, double price1, datetime time2=0, double price2=0, datetime time3=0, double price3=0) |
Description:
The ObjectCreate function creates a new object with the specified name and type, in the specified window and coordinates. The function returns true if the object successfully created otherwise it returns false. To know the exact error use GetLastError() function.
Object name:
The name of the object is the name you see in the Objects list window (Figure 4) and this name works as a handle for the object which you can use later to work with this object (For example to delete it or move it) so it must be unique.
Figure 4 - Objects list window
Windows:
You can draw the object on the chart main window (The main window which show the price date) or on any of the chart sub-windows , you use the index of the window with the ObjectCreate function and you have to remember that:
1- The index of the chart main window is 0.
2- The chart sub-windows indexes start from 1 up to the number of the windows minus 1.
3- To get the number of window use the function WindowsTotal( ).
4- To find the index of a specific window by its indicator name use the function WindowFind( string name).
5- The index of the window must be less than the total of windows (retuned by WindowsTotal( ) function).
Coordinates:
You can use up to 3 coordinates for the object drawing depending on the type of the object, for example the Vertical line object uses only 1 coordinate, the Trend line object uses 2 coordinates and the Channel object use 3 coordinates.
The X (vertical) coordinate of the object is the time on the chart and the Y (horizontal) coordinate of the object is the price on the chart (Figure 5).
The first coordinate pairs (X and Y) are required parameters even if an object like the OBJ_LABEL will ignore them, while the second and third coordinates pairs are optional and you have to use them only with the object which use 2 or 3 coordinates.
Figure 5 - Coordinates
Parameters:
string name:
The string name of the object which you will use it later as a reference of object.
int type:
The type of the object you want to draw, you pass to the ObjectCreate function the integer representation of the object or the constant name of this integer, this is the table of the object integers representation and their constant names:
Constant Value Description
| OBJ_VLINE | 0 | Vertical line. Uses time part of first coordinate. |
| OBJ_HLINE | 1 | Horizontal line. Uses price part of first coordinate. |
| OBJ_TREND | 2 | Trend line. Uses 2 coordinates. |
| OBJ_TRENDBYANGLE | 3 | Trend by angle. Uses 1 coordinate. To set angle of line use ObjectSet() function. |
| OBJ_REGRESSION | 4 | Regression. Uses time parts of first two coordinates. |
| OBJ_CHANNEL | 5 | Channel. Uses 3 coordinates. |
| OBJ_STDDEVCHANNEL | 6 | Standard deviation channel. Uses time parts of first two coordinates. |
| OBJ_GANNLINE | 7 | Gann line. Uses 2 coordinate, but price part of second coordinate ignored. |
| OBJ_GANNFAN | 8 | Gann fan. Uses 2 coordinate, but price part of second coordinate ignored. |
| OBJ_GANNGRID | 9 | Gann grid. Uses 2 coordinate, but price part of second coordinate ignored. |
| OBJ_FIBO | 10 | Fibonacci retracement. Uses 2 coordinates. |
| OBJ_FIBOTIMES | 11 | Fibonacci time zones. Uses 2 coordinates. |
| OBJ_FIBOFAN | 12 | Fibonacci fan. Uses 2 coordinates. |
| OBJ_FIBOARC | 13 | Fibonacci arcs. Uses 2 coordinates. |
| OBJ_EXPANSION | 14 | Fibonacci expansions. Uses 3 coordinates. |
| OBJ_FIBOCHANNEL | 15 | Fibonacci channel. Uses 3 coordinates. |
| OBJ_RECTANGLE | 16 | Rectangle. Uses 2 coordinates. |
| OBJ_TRIANGLE | 17 | Triangle. Uses 3 coordinates. |
| OBJ_ELLIPSE | 18 | Ellipse. Uses 2 coordinates. |
| OBJ_PITCHFORK | 19 | Andrews pitchfork. Uses 3 coordinates. |
| OBJ_CYCLES | 20 | Cycles. Uses 2 coordinates. |
| OBJ_TEXT | 21 | Text. Uses 1 coordinate. |
| OBJ_ARROW | 22 | Arrows. Uses 1 coordinate. |
| OBJ_LABEL | 23 | Text label. Uses 1 coordinate in pixels. |
int window:
The index of the window you want to draw the object on, the chart main window has the index 0 and the sub chart starts from 1 to the total of the window - 1.
datetime time1:
The first vertical coordinate of the object. This parameter is required and you can set it to 0 if the object will not use the vertical coordinate.
This parameter is a datetime type (because the vertical coordinate of the chart is the time coordinate).
double price1:
The first horizontal coordinate of the object. This parameter is required and you can set it to 0 if the object will not use the horizontal coordinate.
This parameter is a double type (because the horizontal coordinate of the chart is the price coordinate).
You have to note which currency pair you are going to draw on its chart because the prices ranges differs from currency to currency.
datetime time2:
The second vertical coordinate of the object. It's an optional parameter which you can use it if your object uses 2 coordinates.
double price2:
The second horizontal coordinate of the object. It's an optional parameter which you can use it if your object uses 2 coordinates.
datetime time3:
The third vertical coordinate of the object. It's an optional parameter which you can use it if your object uses 3 coordinates.
double price3:
The third horizontal coordinate of the object. It's an optional parameter which you can use it if your object uses 3 coordinates.
Example:
| // new text object |
ObjectDelete:
Syntax:
| bool ObjectDelete(string name) |
Description:
The ObjectDelete function deletes the object by its name (you have to provide the exact name of the object). If the object successfully deleted the function will return true, otherwise it will return false. Use GetLastError() function to get more details about the error.
Parameters:
string name:
The string name of the object you want to delete.
Example:
| ObjectDelete("text_object"); |
ObjectDescription:
Syntax:
| string ObjectDescription(string name) |
Description:
The ObjectDescription function returns the description of the object (Figure 6).
For the objects OBJ_TEXT and OBJ_LABEL which has no description the returned value is the text drawn by these objects (Figure 7).
Figure 6- Object description
Figure 7
Parameters:
string name:
The string name of the object you want to get its description.
Example:
| Print(ObjectDescription("Text 44465")); |
ObjectFind:
Syntax:
| int ObjectFind(string name) |
Description:
The ObjectFind function searches all the drawn objects for the specified object name and returns the index of the window that host the object if found and returns -1 if the object not found. The chart main window is 0 index and the first chart sub-window is 1 then 2 etc.
Parameters:
string name:
The string name of the object you want to search for.
Example:
| if(ObjectFind("line_object2")!=win_idx) return(0); |
ObjectGet:
Syntax:
| double ObjectGet(string name, int index) |
Description:
The ObjectGet function returns the value of the specified object property of the given index.
For example to get the first vertical (time) of the object use ObjectGet(object_name, 0).
Parameters:
string name:
The string name of the object you want to get one of its proporties.
int index:
The property index which can be one of these values:
Constant Value Type Description
| OBJPROP_TIME1 | 0 | datetime | Datetime value to set/get first coordinate time part. |
| OBJPROP_PRICE1 | 1 | double | Double value to set/get first coordinate price part. |
| OBJPROP_TIME2 | 2 | datetime | Datetime value to set/get second coordinate time part. |
| OBJPROP_PRICE2 | 3 | double | Double value to set/get second coordinate price part. |
| OBJPROP_TIME3 | 4 | datetime | Datetime value to set/get third coordinate time part. |
| OBJPROP_PRICE3 | 5 | double | Double value to set/get third coordinate price part. |
| OBJPROP_COLOR | 6 | color | Color value to set/get object color. |
| OBJPROP_STYLE | 7 | int | Value is one of STYLE_SOLID, STYLE_DASH, STYLE_DOT, STYLE_DASHDOT, STYLE_DASHDOTDOT constants to set/get object line style. |
| OBJPROP_WIDTH | 8 | int | Integer value to set/get object line width. Can be from 1 to 5. |
| OBJPROP_BACK | 9 | bool | Boolean value to set/get background drawing flag for object. |
| OBJPROP_RAY | 10 | bool | Boolean value to set/get ray flag of object. |
| OBJPROP_ELLIPSE | 11 | bool | Boolean value to set/get ellipse flag for fibo arcs. |
| OBJPROP_SCALE | 12 | double | Double value to set/get scale object property. |
| OBJPROP_ANGLE | 13 | double | Double value to set/get angle object property in degrees. |
| OBJPROP_ARROWCODE | 14 | int | Integer value or arrow enumeration to set/get arrow code object property. |
| OBJPROP_TIMEFRAMES | 15 | int | Value can be one or combination (bitwise addition) of object visibility constants to set/get timeframe object property. |
| OBJPROP_DEVIATION | 16 | double | Double value to set/get deviation property for Standard deviation objects. |
| OBJPROP_FONTSIZE | 100 | int | Integer value to set/get font size for text objects. |
| OBJPROP_CORNER | 101 | int | Integer value to set/get anchor corner property for label objects. Must be from 0-3. |
| OBJPROP_XDISTANCE | 102 | int | Integer value to set/get anchor X distance object property in pixels. |
| OBJPROP_YDISTANCE | 103 | int | Integer value is to set/get anchor Y distance object property in pixels. |
| OBJPROP_FIBOLEVELS | 200 | int | Integer value to set/get Fibonacci object level count. Can be from 0 to 32. |
| OBJPROP_LEVELCOLOR | 201 | color | Color value to set/get object level line color. |
| OBJPROP_LEVELSTYLE | 202 | int | Value is one of STYLE_SOLID, STYLE_DASH, STYLE_DOT, STYLE_DASHDOT, STYLE_DASHDOTDOT constants to set/get object level line style. |
| OBJPROP_LEVELWIDTH | 203 | int | Integer value to set/get object level line width. Can be from 1 to 5. |
| OBJPROP_FIRSTLEVEL+n | 210+n | int | Fibonacci object level index, where n is level index to set/get. Can be from 0 to 31. |
Example:
| color oldColor=ObjectGet("hline12", OBJPROP_COLOR); |
ObjectGetFiboDescription:
Syntax:
| string ObjectGetFiboDescription(string name, int index) |
Description:
The ObjectGetFiboDescription function returns the description of the given Fibonacci object level.
For example in Figure 8 the description of the second line from bottom (its index is 0) is "23.6".
The index of Fibonacci object levels start from bottom upward and you can use up to 32 levels.
Figure 8
Parameters:
string name:
The string name of the Fibonacci object you want to get its level description.
int index:
The index of the level (line) you want to get its level description.
Example:
| Print(ObjectGetFiboDescription("Fibo 2638", 1)); |
ObjectGetShiftByValue:
Syntax:
| int ObjectGetShiftByValue(string name, double value) |
Description:
The ObjectGetShiftByValue function returns the index of the bar (shifted from the current - 0 upward) for the given price of the given object. This price is calculated with the first and second coordinates of the object (using liner equation).
Foe example in figure 9 the bar index for the price 1.2156 of the Trendline object is the bar 11.
Figure 9
Parameters:
string name:
The string name of the object you want to get the bar index for one of its prices (values)
double value:
The price value of the object.
Example:
| Print(ObjectGetShiftByValue("Trendline 5879", 1.2156)); |
In the next lesson we are going to continue with the remaining Object Function and we are going to make a simple MQL program to apply what we learnt about the objects programming.
Hope you find the lesson helpful one and hope to see your comments!
Coders Guru!