Using Tools From an Advanced Custom Study


Introduction

This page documents programmatically adding Chart Drawings and interacting with user drawn Chart Drawings through the Advanced Custom Study Interface and Language. For information about Drawing Tools, refer to Chart Drawing Tools.

Using Tools with sc.UseTool()

Type: ACSIL Function

Declaration: int UseTool(s_UseTool& UseTool);

This page documents programmatically adding the same type of Chart Drawings to a chart from Advanced Custom Studies, that are normally drawn by a user using the Chart Drawing Tools. Therefore, Advanced Custom Studies can independently add the same types of Chart Drawings to a chart programmatically.

Refer to the Sierra Chart Advanced Custom Study Interface and Language (ACSIL) page for more information about the Advanced Custom Study Interface and Language.

To use the built-in Sierra Chart Drawing Tools from an Advanced Custom Study, you will use the sc.UseTool() function.

When calling this function, a Chart Drawing is added to an internal list in a chart. The sc.UseTool() function supports many different drawing types. This is a very powerful feature. You can place various types of Chart Drawing objects on a chart or place Text anywhere on a chart, and dynamically move those objects. You can control the foreground and background colors and font size of Text.

The sc.UseTool() function uses the s_UseTool structure to specify the various parameters for the tool. You need to define an instance of the s_UseTool structure in your function. sc.UseTool() takes a reference to the s_UseTool instance you defined in the study function.

Set the relevant members of the s_UseTool structure, call the sc.UseTool() function and pass an instance of s_UseTool to that function. The DrawingType member of the s_UseTool structure specifies which drawing tool to use.

Before setting the members of s_UseTool, always be sure to use the Clear() function of the s_UseTool structure to initialize the structure. This is especially important if you are using the same instance of the structure to multiple calls of sc.UseTool(). Refer to the code example below.

The s_UseTool Member Descriptions section documents the members of the s_UseTool structure for all of the imported drawing tools. For actual code examples, refer to the scsf_UseToolExample located in the /ACS_Source/studies.cpp file in the folder where Sierra Chart is installed to on your system.

For another example to place text on a chart, refer to the scsf_CountDownTimer in the /ACS_Source/studies2.cpp file.

This paragraph applies when s_UseTool::AddAsUserDrawnDrawing is not set which is almost always the case. Chart Drawings added with sc.UseTool(), are automatically deleted from the chart when the study is removed from the chart, or when the study is fully recalculated, unless you have set s_UseTool::AddAsUserDrawnDrawing to 1 (TRUE). In which case there is no need to delete chart drawings manually by using sc.DeleteACSChartDrawing().

Expressly deleting a chart drawing with sc.DeleteACSChartDrawing() is only needed for more specialized purposes.

On a recalculation of a study that has added non-user drawn Chart Drawings through ACSIL will have those Chart Drawings automatically deleted.

Chart drawings added by an ACSIL function are never saved to a Chartbook. They exist only in temporary memory.

Preventing More Than One Chart Drawing Per Chart Bar

When adding Chart Drawings with sc.UseTool() it is important not to add more than one Chart Drawing per chart bar unless that is the intention. During a full recalculation of the study, if one Chart Drawing is added per chart bar, there will not be a problem in this case.

However, during normal chart updating sc.Index is set to the index of the last bar in the chart from the prior chart update. Therefore, it is important not to add another Chart Drawing to the bar at that index if that is not the intention.

When updating the existing Chart Drawing at that index, set s_UseTool::AddMethod to UTAM_ADD_OR_ADJUST and specify the same s_UseTool::LineNumber previously used for that index. You may want to hold this LineNumber in a Persistent Variable.

Return Value

sc.UseTool() returns 1 on success, 0 on failure. If UTAM_ADD_OR_ADJUST is used for the AddMethod, and at least one drawing with the given LineNumber exists, then the return value will be the number of chart drawings that were adjusted.

Code Example

// Marker example
s_UseTool Tool;
int UniqueLineNumber = 74191;//any random number.

Tool.Clear(); // Reset tool structure.  Good practice but unnecessary in this case.
Tool.ChartNumber = sc.ChartNumber;

Tool.DrawingType = DRAWING_MARKER;
Tool.LineNumber =  UniqueLineNumber +1;

BarIndex = max(0, sc.ArraySize - 35);

Tool.BeginDateTime = sc.BaseDateTimeIn[BarIndex];
Tool.BeginValue = sc.High[BarIndex];

Tool.Color = RGB(0,200,200);
Tool.AddMethod = UTAM_ADD_OR_ADJUST;

Tool.MarkerType = MARKER_X;
Tool.MarkerSize = 8;

Tool.LineWidth = 5;

sc.UseTool(Tool);
        

Adjusting Existing Chart Drawings

When a Chart Drawing is added to the chart through the use of the sc.UseTool function, it can later be modified. The method by which a chart drawing can be modified is by calling the sc.UseTool with s_UseTool::AddMethod set to UTAM_ADD_OR_ADJUST, which is the default.

Set the same s_UseTool::LineNumber that was previously used when the Chart Drawing was originally added. If s_UseTool::LineNumber was not set when calling sc.UseTool, then you need to have remembered the LineNumber that was automatically set and returned.

If you plan to modify ACSIL added Chart Drawings, then when specifying the s_UseTool::LineNumber, then normally you should be using a unique LineNumber for each drawing. If s_UseTool::LineNumber is not set, a unique number will automatically be set.

Set the other members of the s_UseTool structure that you want to modify. The structure members that you do not want to change need to be left unset. For more information, refer to AddMethod.

It is possible to modify a Chart Drawing that was added as a user drawn drawing. A drawing is considered a user drawn drawing if it was added with sc.UseTool and the s_UseTool::AddAsUserDrawnDrawing variable is set to 1.

When modifying a user drawn drawing, it is necessary to set s_UseTool::AddAsUserDrawnDrawing to modify it.

Drawing Tools and s_UseTool Member Descriptions

DrawingType

Type: DrawingTypeEnum

This member needs to be set to one of the following drawing types, unless you are adjusting an existing drawing:

  • DRAWING_LINE: Draws a Line on the chart.
  • DRAWING_RAY: Draws a Ray on the chart.
  • DRAWING_EXTENDED_LINE: Draws an Extended Line (extends in both directions) on the chart.
  • DRAWING_RECTANGLEHIGHLIGHT: Draws a rectangle highlight drawing.
  • DRAWING_RECTANGLE_EXT_HIGHLIGHT: Draws a rectangle highlight drawing that extends either right or left.
  • DRAWING_ELLIPSEHIGHLIGHT: Draws an ellipse highlight drawing.
  • DRAWING_TRIANGLE: Draws a triangle drawing.
  • DRAWING_TEXT: This tool draws text anywhere on the chart and in any chart region. You can use both absolute and relative positioning. You can specify various font properties. A very good example of how to use this tool and what you can do can be found in the scsf_WoodiesPanel function in the /ACS_Source/studies7.cpp file. This is in the folder where Sierra Chart is installed to on your computer.
  • DRAWING_STATIONARY_TEXT: This tool draws text on the chart using realtive positions.
  • DRAWING_RETRACEMENT : This tool draws a 2-point Retracement drawing on the chart.
  • DRAWING_EXPANSION : This tool draws a 2-point Expansion drawing on the chart.
  • DRAWING_PROJECTION : This tool draws a 3-point Projection drawing on the chart.
  • DRAWING_CALCULATOR: This tool draws a Chart Calculator line on the chart.
  • DRAWING_HORIZONTALLINE: This tool draws a Horizontal Line drawing on the chart. This horizontal line extends from the left side of the chart window to the right side of the chart window.
  • DRAWING_HORIZONTAL_RAY: Draws a Horizontal Ray on the chart. This horizontal line extends from s_UseTool::BeginDateTime to the right side of the chart window.
  • DRAWING_HORIZONTAL_LINE_NON_EXTENDED: This tool draws a Horizontal Line on the chart which does not extend. It begins at s_UseTool::BeginDateTime and ends at s_UseTool::EndDateTime.
  • DRAWING_VERTICALLINE: This tool draws a Vertical line drawing on the chart.
  • DRAWING_ARROW: This tool draws an Arrow drawing on the chart.
  • DRAWING_PITCHFORK: This tool draws a Pitchfork drawing on the chart.
  • DRAWING_PITCHFORK_SCHIFF: This tool draws a Schiff Pitchfork drawing on the chart.
  • DRAWING_PITCHFORK_MODIFIED_SCHIFF: This tool draws a Modified Schiff Pitchfork drawing on the chart.
  • DRAWING_TIME_EXPANSION: This tool draws a 2-point Time Expansion drawing on the chart.
  • DRAWING_TIME_PROJECTION: This tool draws a 3-point Time Projection drawing on the chart.
  • DRAWING_PARALLEL_LINES: This tool draws a Parallel Lines drawing on the chart.
  • DRAWING_PARALLEL_RAYS: This tool draws a Parallel Rays drawing on the chart.
  • DRAWING_LINEAR_REGRESSION: This tool draws a Linear Regression drawing on the chart.
  • DRAWING_RAFF_REGRESSION_CHANNEL: This tool draws a Raff Regression Channel drawing on the chart.
  • DRAWING_MARKER: This tool draws a Marker drawing on the chart. For a Marker drawing, it is necessary to set the s_UseTool::MarkerType to specify the actual type of marker.
  • DRAWING_FAN_FIBONACCI: This tool draws a Fibonacci Fan drawing on the chart.
  • DRAWING_REWARD_RISK: This tool draws a Reward Risk drawing on the chart.
  • DRAWING_SWING_MARKER: This tool draws a Swing Marker drawing on the chart.
  • DRAWING_DATE_MARKER: This tool draws a Date Marker drawing on the chart.
  • DRAWING_REWARD_RISK : This tool draws a Reward Risk drawing on the chart. For an example function which demonstrates its use, refer to the scsf_UseToolExampleRewardRisk() function in the /ACS_Source/Studies.cpp file. The Reward/Risk drawing is a rather complex drawing to add due to the number of options. The example lays out all of the options and documents what they do. The example should be used to understand how to add a DRAWING_REWARD_RISK drawing.

AddMethod

Type: Integer

Possible values:

  • UTAM_ADD_ALWAYS: The drawing will be added to the chart even if another Chart Drawing with the same LineNumber already exists. However, it is not possible to add more than one user drawn (s_UseTool::AddAsUserDrawnDrawing = 1) drawing with the same LineNumber.
  • UTAM_ADD_ONLY_IF_NEW: The Chart Drawing will only be added if no other Chart Drawing already on the chart has the same LineNumber if LineNumber is nonzero.
  • UTAM_ADD_OR_ADJUST: If the Chart Drawing already exists on the chart as identified by the LineNumber member, then that existing Chart Drawing will be adjusted. Otherwise, a new Chart Drawing will be added.

    If LineNumber is not set, then a new Chart Drawing will be added. Upon return from the sc.UseTool function, LineNumber will be set to the automatically assigned number.

    If the drawing is adjusted, then only the s_UseTool structure members specified will be updated, the others will be left as is.

    If the DrawingType member is a different type than specified previously for the same LineNumber, then the chart drawing type will change to the new specified DrawingType.
  • AddMethod by default is set to UTAM_ADD_OR_ADJUST.

ChartNumber

Type: Integer

This member is ignored if s_UseTool::AddAsUserDrawnDrawing is 0, which is the default.

When s_UseTool::AddAsUserDrawnDrawing is set to 1 or a nonzero value, then ChartNumber specifies the chart number that the drawing will be drawn on. Use 0 to put the drawing on the same chart that the study is applied to.

There are special considerations when setting s_UseTool::AddAsUserDrawnDrawing to 1. Be sure to read the documentation for s_UseTool::AddAsUserDrawnDrawing.

The ChartNumber of a chart is the number of the chart and this is displayed after the "#" sign on the top line of the chart. Each chart has a unique number identifying itself within its Chartbook.

LineNumber

Type: Integer

The LineNumber is a unique integer identifier used to identify the Chart Drawing added with the sc.UseTool function. This LineNumber is used to later identify the drawing.

This LineNumber is needed when performing modifications to the Chart Drawing and deleting the Chart Drawing.

Setting the LineNumber is optional and not recommended unless there is a special reason.

If a LineNumber is not specified, it will be automatically assigned as a positive number by ACSIL after calling the sc.UseTool function. You will be able to get the value after calling the sc.UseTool function.

A negative number is assigned in the case of when s_UseTool::AddAsUserDrawnDrawing is set to a nonzero number.

Do not use a negative LineNumber when s_UseTool::AddAsUserDrawnDrawing is set to a nonzero number because a negative number may conflict with other user drawn Chart Drawings added by ACSIL and also through the Sierra Chart user interface. However, using a -1 is a flag to the sc.UseTool function to automatically assign the LineNumber. So a -1 is acceptable.

The LineNumber for ACSIL added drawings will not conflict with user drawn chart drawings when s_UseTool::AddAsUserDrawnDrawing is set to 0.

If you are assigning a LineNumber in your own code, it is recommended to use at least six digits to ensure uniqueness among other Chart Drawings on the chart added by ACSIL. Therefore, it is recommended to let Sierra Chart assign the LineNumber unless you need to have control over it for some reason.

After calling the sc.UseTool function, the LineNumber if it was not set, will be set. You can then check what the LineNumber is and set it into a Persistent Variable if needed.

Multiple nonuser drawn Chart Drawings can be set to the same LineNumber for special purposes, like being able to adjust them all at once. If you are using the same LineNumber for multiple Chart Drawings, then the s_UseTool::AddMethod member will need to be set to UTAM_ADD_ALWAYS.

It is not possible to add more than one user drawn (s_UseTool::AddAsUserDrawnDrawing = 1) drawing with the same LineNumber.

When adding multiple Chart Drawings with the same LineNumber, be certain that you only add the Chart Drawing once at each bar index where you want it. Do not add it on every call to your study function if you only want one instance of the Chart Drawing at a particular bar index.

When calling the sc.UseTool function and the AddMethod is set to UTAM_ADD_OR_ADJUST, the Chart Drawing with the specified LineNumber will be adjusted.

BeginDateTime

Type: SCDateTime

The Date and Time at which the chart drawing begins.

This is not used with the Horizontal line tool.

To use a value relative to the left side of the chart for BeginDateTime rather than an absolute Date Time value, specify an integer value from 1 to 150. Where 1 represents the left side of the chart window and where 150 represents the right side of the chart window, not including the Values Scale on the right side of the chart.

Drawing Text After the End of the Chart Bars: It is possible to draw text after the end of the chart bars. This only applies in the case of when the Tool member of s_UseTool is DRAWING_TEXT. To do this use an integer value of -1, -2, -3 or lower. A value of -1 will display the text in the fill space after the very last bar in the chart, and a value of -2 or lower will display the text in the fill space even when the chart is scrolled back towards the left. When drawing text in the fill space on the right side of the chart, by default the text is one bar spacing beyond the last bar. To increase the spacing use a value less than -2 such as -3. -3 will draw the text in the fill space and it will be offset from the last bar by 2 bar spacings.

Drawing Chart Drawings In The Fill Space (Forward Projection Area): If you want the beginning point of your chart drawing to be in the fill space or forward projection area on the right side of the chart after the last loaded bar in the chart, then use code similar to the example below. This only applies to non-text drawings. This does not work with Text drawings.

s_UseTool UseTool;

UseTool.Clear();

// BeginDateTime is at the second column in the forward projection area

UseTool.BeginDateTime = sc.BaseDateTimeIn[sc.ArraySize + 1];
            

EndDateTime

Type: SCDateTime

The Date and Time at which the chart drawing ends. In the case of an extending chart drawing, this is the date and time which the drawing extends from.

This is not used with the Horizontal Line, Vertical Line, or Text tools.

To use a value relative to the left side of the chart for EndDateTime rather than an absolute Date Time value, specify an integer value from 1 to 150. Where 1 represents the left side of the chart window and where 150 represents the right side of the chart window, not including the Values Scale on the right side of the chart.

Drawing Chart Drawings In The Fill Space (Forward Projection Area): If you want the ending point of your chart drawing to be in the fill space or forward projection area on the right side of the chart after the last loaded bar in the chart, then use code similar to the example below. This only applies to non-text drawings. This does not work with Text drawings.

s_UseTool UseTool;

UseTool.Clear();

UseTool.EndDateTime = sc.BaseDateTimeIn[sc.ArraySize + 4];
            

ThirdDateTime

Type: SCDateTime

For drawings with three points, ThirdDateTime specifies the Date and Time of the third point. Valid for DRAWING_PROJECTION, DRAWING_PITCHFORK, DRAWING_PITCHFORK_SCHIFF, DRAWING_PITCHFORK_MODIFIED_SCHIFF, DRAWING_TRIANGLE, DRAWING_TIME_PROJECTION, DRAWING_PARALLEL_LINES, and DRAWING_PARALLEL_RAYS. Specified in same manner as EndDateTime.

BeginIndex

Type: Integer

Drawings may be specified with a bar Index instead of a Date-Time to specify the horizontal position. Using this member instead of BeginDateTime will be dramatically more efficent, and allows for bars with the same timestamp to be distinguished. BeginIndex is used to specify the first point of a drawing.

s_UseTool Tool;
Tool.BeginIndex = sc.Index;
            

EndIndex

Type: Integer

Drawings may be specified with a bar Index instead of a Date-Time to specify the horizontal position. Using this member instead of EndDateTime will be dramatically more efficent, and allows for bars with the same timestamp to be distinguished. EndIndex is used to specify the second point of a drawing.

ThirdIndex

Type: Integer

When using bar indexes to define drawing points, ThirdIndex specifies the bar index of the third point for drawings that used three points. Valid for DRAWING_PROJECTION, DRAWING_PITCHFORK, DRAWING_PITCHFORK_SCHIFF, DRAWING_PITCHFORK_MODIFIED_SCHIFF, DRAWING_TRIANGLE, DRAWING_TIME_PROJECTION, DRAWING_PARALLEL_LINES, and DRAWING_PARALLEL_RAYS.

UseRelativeVerticalValues / UseRelativeValue

Type: Integer

Set UseRelativeVerticalValues to 1 or any nonzero value, to use BeginValue and EndValue as relative vertical scale values to the Chart Region instead of as absolute scale values. Refer to the BeginValue and EndValue documentation.

It is supported to use BeginValue and EndValue as relative vertical scale values to the Chart Region by setting UseRelativeVerticalValues to 1 and still use BeginDateTime and EndDateTime as absolute references to specific Date-Times.

UseRelativeVerticalValues does not apply to any of the *DateTime or *Index members.

BeginValue

Type: Float

The vertical axis chart value for the beginning point of the Chart Drawing. This value needs to be based on the values of the main price graph or the first study graph in the Chart Region (specified with the Region member) where the Chart Drawing will be located.

This is not used with the Vertical line tool.

If UseRelativeVerticalValues is set to 1 or a nonzero value, then BeginValue is a value relative to the Chart Region itself completely independent of the scale used for the graphs in the Chart Region. It is a percentage. Where 1 = 1%. The entire height of the Chart Region is 100%. 0 = The bottom of the Chart Region. 100 = The top of the Chart Region. These values apply to the Chart Region and not the entire height of the chart window unless there is only a single Chart Region displayed.

The horizontal axis equivalent to UseRelativeVerticalValues is by setting the BeginDateTime member to a integer value between 1 to 150.

EndValue

Type: Float

The vertical axis chart value for the ending point of the Chart Drawing. This is not needed for the Text tool. This value needs to be based on the values of the main price graph or the first study graph in the Chart Region (specified with the Region member) where the Chart Drawing will be located.

This is not used with the Horizontal or Vertical line tools.

If UseRelativeVerticalValues is set to 1 or a nonzero value, then EndValue is a value relative to the Chart Region itself completely independent of the scale used for the graphs in the Chart Region. It is a percentage. Where 1 = 1%. The entire height of the Chart Region is 100%. 0 = The bottom of the Chart Region. 100 = The top of the Chart Region. These values apply to the Chart Region and not the entire height of the chart window unless there is only a single Chart Region displayed.

The horizontal axis equivalent to UseRelativeVerticalValues is by setting the EndDateTime member to a integer value between 1 to 150.

ThirdValue

Type: Float

For drawings with three points, the ThirdValue member specifies the vertical scale value of the third point.

Valid for DRAWING_PROJECTION, DRAWING_PITCHFORK, DRAWING_PITCHFORK_SCHIFF, DRAWING_PITCHFORK_MODIFIED_SCHIFF, DRAWING_TIME_PROJECTION, DRAWING_PARALLEL_LINES, and DRAWING_PARALLEL_RAYS.

Specified in same manner as EndValue.

Region

Type: integer

This is the region on the chart where the Chart Drawing appears. This number is 0 based and must be 0 to 12.

Region 0 represents Chart Region 1. This is where the Main Price Graph is located. Regions 1 to 11 correspond to chart regions 2 to 12. This is where the study graphs below the Main Price Graph are located.

Color

Type: unsigned integer (COLORREF)

The Chart Drawing color in RGB format. The default value of this is RGB(0, 0, 0) which is equal to black. This variable must be set, otherwise you will not see the Chart Drawing on a black background.

For the Rectangle, Ellipse, and Triangle Chart Drawings ( DRAWING_RECTANGLEHIGHLIGHT, DRAWING_RECTANGLE_EXT_HIGHLIGHT, DRAWING_ELLIPSEHIGHLIGHT, DRAWING_TRIANGLE), this member specifies the outline color of the Chart Drawing. In order to see the outline, it is necessary to set the LineWidth to 1 or greater. Otherwise, the outline will not be visible.

SecondaryColor

Type: unsigned integer (COLORREF)

The fill color in RGB format. This applies to the following Chart Drawing types: DRAWING_RECTANGLEHIGHLIGHT, DRAWING_RECTANGLE_EXT_HIGHLIGHT, DRAWING_ELLIPSEHIGHLIGHT, DRAWING_TRIANGLE.

TransparencyLevel

Type: Integer

TransparencyLevel sets the amount of transparency for the interior fill area for the following Chart Drawing types: DRAWING_RECTANGLEHIGHLIGHT, DRAWING_RECTANGLE_EXT_HIGHLIGHT, DRAWING_ELLIPSEHIGHLIGHT, DRAWING_TRIANGLE.

0 means that the interior fill is completely solid and has no transparency. 100 means that the interior fill is completely transparent and not even visible.

SquareEdge

Type: Integer

Set this to 1 to use square edges for the ends of a Line or Ray.

LineWidth

Type: Integer

The line width of the Chart Drawing in pixels. The default is 1. However, you should always set this value so the code is clear.

For the Rectangle, Triangle, and Ellipse Chart Drawing types (DRAWING_RECTANGLEHIGHLIGHT, DRAWING_RECTANGLE_EXT_HIGHLIGHT, DRAWING_ELLIPSEHIGHLIGHT, DRAWING_TRIANGLE), in order to see the outline it is necessary to set the LineWidth to 1 or greater. Otherwise, the outline will not be visible.

LineStyle

Type: Integer

The line style for the chart drawing. Available line styles are: LINESTYLE_SOLID, LINESTYLE_DASH, LINESTYLE_DOT, LINESTYLE_DASHDOT, and LINESTYLE_DASHDOTDOT.

Text

Type: SCString

The text to draw onto the chart. This applies to the DRAWING_TEXT tool. This member can also be used with the DRAWING_HORIZONTALLINE tool. In this case, this is the text that displays below the horizontal line.

For multiline text, each line needs to be terminated with a "\n" character.

If the Text member contains "\n" characters for multiline text, you also need to set MultiLineLabel = 1 .

DisplayHorizontalLineValue

Type: Integer

This member only applies to the DRAWING_HORIZONTALLINE tool. Set this to 1 to display the value of the horizontal line underneath the horizontal line. Set this to 0 to not display the value of the horizontal line. If this is set to any other value (default), then visibility of the horizontal line's value is determined using the setting under Global Settings >> Tool Settings >> Horizontal/Vertical .

FontSize

Type: Integer

The Font Size of the text. This applies to the DRAWING_TEXT tool.

FontBackColor

Type: unsigned integer (COLORREF)

The color for the text background in RGB format. This applies to the DRAWING_TEXT tool.

FontFace

Type: SCString

The Font Face name. Such as Arial. This can be left unset to use the Font Face specified in Global Settings >> Tool Settings >> Text. This applies to the DRAWING_TEXT tool.

FontBold

Type: Integer

Set this to 1 to make the font Bold. Set it to 0, to not. The default is 0. This applies to the DRAWING_TEXT tool.

FontItalic

Type: Integer

Set this to 1 to make the font Italic. Set it to 0, to not. The default is 0. This applies to the DRAWING_TEXT tool.

TextAlignment

Type: Integer

This member can be optionally set to one or more of the following flags separated by the C++ OR (|) operator: DT_TOP, DT_VCENTER, DT_BOTTOM, DT_CENTER, DT_LEFT, DT_RIGHT. The default is DT_TOP and DT_LEFT. These alignment flags apply to the DRAWING_TEXT tool only and not any other tools.

This member can also be set to apply text alignment to the Text drawn on a DRAWING_HORIZONTALLINE drawing. In this case this can be set to DT_LEFT or DT_RIGHT. By default text is aligned to the left.

This member can also be a set to apply the text alignment to the Text drawn on a DRAWING_RECTANGLEHIGHLIGHT or DRAWING_RECTANGLE_EXT_HIGHLIGHT drawing. In this case, this can be set to DT_LEFT or DT_RIGHT. By default the text is aligned to the left.

ReverseTextColor

Type: Integer

Set this to 1, to reverse the color of the text when using the DRAWING_TEXT drawing type. The text will be drawn with the chart background color and the area around the text will be drawn with the specified color (Color member).

The default value is 0, meaning a reversed color is not used.

This applies to the DRAWING_TEXT drawing type.

MarkerType

Type: Integer

When using DRAWING_MARKER, this member is used to set the marker type to be drawn. The following constant values can be used:

  • MARKER_POINT: Draws a point.
  • MARKER_DASH: Draws a dash.
  • MARKER_SQUARE: Draws a square.
  • MARKER_STAR: Draws a star.
  • MARKER_PLUS: Draws a "+".
  • MARKER_X: Draws an "X".
  • MARKER_ARROWUP: Draws an up arrow.
  • MARKER_ARROWDOWN: Draws a down arrow.
  • MARKER_ARROWRIGHT: Draws a right arrow.
  • MARKER_ARROWLEFT: Draws a left arrow.
  • MARKER_TRIANGLEUP: Draws a up triangle.
  • MARKER_TRIANGLEDOWN: Draws a down triangle.
  • MARKER_TRIANGLERIGHT: Draws a right triangle.
  • MARKER_TRIANGLELEFT: Draws a left triangle.
  • MARKER_DIAMOND: Draws a diamond.

MarkerSize

Type: Integer

When using DRAWING_MARKER, this member is used to set the size of the marker be drawn, and should be greater than zero. This value is ignored if UseBarSpacingForMarkerSize is set.

UseBarSpacingForMarkerSize

Type: Integer

When using DRAWING_MARKER, this member can be set to 1 to specify that the size of the marker drawn is set based on the bar spacing. When set, the marker size will scale with the bar spacing as it is changed.

ShowVolume

Type: Integer

When using DRAWING_CALCULATOR, this member can be set to 1 to specify that the total volume between the start and end points is displayed in the drawing result text.

ShowAskBidDiffVolume

Type: Integer

When using DRAWING_CALCULATOR, this member can be set to 1 to specify that the total Ask Volume minus the total Bid Volume between the start and end points is displayed in the drawing result text.

ShowPriceDifference

Type: Integer

When using DRAWING_CALCULATOR, this member can be set to 1 to specify that the price difference of the start and end points is displayed in the drawing result text.

ShowTickDifference

Type: Integer

When using DRAWING_CALCULATOR, this member can be set to 1 to specify that the price difference of the Begin and End points, measured in ticks, is displayed in the drawing result text. The Tick Size must be properly set for the chart.

ShowCurrencyValue

Type: Integer

When using DRAWING_CALCULATOR, this member can be set to 1 to specify that the price difference of the Begin and End points, measured in currency value, is displayed in the drawing result text. The Tick Size and Currency Value per Tick must be properly set for the chart.

ShowPercentChange

Type: Integer

When using DRAWING_CALCULATOR, this member can be set to 1 to specify that the price difference of the start and end points, measured as a percentage change, is displayed in the drawing result text.

ShowTimeDifference

Type: Integer

When using DRAWING_CALCULATOR, this member can be set to 1 to specify that the time difference of the start and end points is displayed in the drawing result text.

ShowNumberOfBars

Type: Integer

When using DRAWING_CALCULATOR, this member can be set to 1 to specify that the time duration of the start and end points, measured in number of bars, is displayed in the drawing result text.

ShowAngle

Type: Integer

When using DRAWING_CALCULATOR, this member can be set to 1 to specify that the angle of the calculator line is displayed in the drawing result text.

ShowEndPointPrice

Type: Integer

When using DRAWING_CALCULATOR, this member can be set to 1 to specify that the price value of the drawing endpoint is displayed in the drawing result text.

ShowEndPointDateTime

Type: Integer

When using DRAWING_CALCULATOR, this member can be set to 1 to specify that the date and time of the drawing endpoint is displayed in the drawing result text.

ShowEndPointDate

Type: Integer

When using DRAWING_CALCULATOR, this member can be set to 1 to specify that the date of the drawing endpoint is displayed in the drawing result text.

ShowEndPointTime

Type: Integer

When using DRAWING_CALCULATOR, this member can be set to 1 to specify that the time of the drawing endpoint is displayed in the drawing result text.

MultiLineLabel

Type: Integer

When using DRAWING_CALCULATOR, this member can be set to 1 to specify that result text should be split into multiple lines, one line for each result type. When not set, the result text is all contained on a singe line.

When using DRAWING_TEXT and the s_UseTool::Text member contains new line characters ("\n"), then MultiLineLabel needs to be set to 1 to cause the text to be displayed on multiple lines.

ShowPercent

Type: Integer

When using DRAWING_RETRACEMENT, DRAWING_EXPANSION, or DRAWING_PROJECTION, this member can be set to 1 to specify that the level percentage be displayed in the drawing level text label.

ShowPrice

Type: Integer

When using DRAWING_RETRACEMENT, DRAWING_EXPANSION, or DRAWING_PROJECTION this member can be set to 1 to specify that the level price value be displayed on the drawing as a text label.

When using DRAWING_RECTANGLEHIGHLIGHT or DRAWING_RECTANGLE_EXT_HIGHLIGHT this member can be set to 1 to specify that the price values be displayed as text labels on the rectangle drawings. In this case the alignment is controlled with TextAlignment.

RoundToTickSize

Type: Integer

When using DRAWING_RETRACEMENT, DRAWING_EXPANSION, or DRAWING_PROJECTION, this member can be set to 1 to specify that the level price values should be rounded to the nearest TickSize.

ExtendLeft

Type: Integer

When using DRAWING_RETRACEMENT, DRAWING_EXPANSION, or DRAWING_PROJECTION, this member can be set to 1 to specify that the level lines will extend to the left.

ExtendRight

Type: Integer

When using DRAWING_RETRACEMENT, DRAWING_EXPANSION, or DRAWING_PROJECTION, this member can be set to 1 to specify that the level lines will extend to the right.

TimeExpVerticals

Type: Integer

When using DRAWING_TIME_EXPANSION or DRAWING_TIME_PROJECTION, this member can be set to specify the type of vertical time lines to draw. The possible constant values are:

  • TIME_EXP_EXTENDED: The vertical time lines extend from the top to bottom of the chart region.
  • TIME_EXP_STANDARD: For DRAWING_TIME_EXPANSION, the vertical time lines extend from the drawing begining price value to the drawing ending price value. For DRAWING_TIME_PROJECTION, the begin and end are drawing points 2 & 3.
  • TIME_EXP_COMPRESSED: The vertical time lines are compressed around the horizontal time line.

TimeExpTopLabel1

Type: Integer

When using DRAWING_TIME_EXPANSION or DRAWING_TIME_PROJECTION, this member can be set to specify the contents of the first top text label, which is placed above the corresponding vertical time line. The possible constant values are:

  • TIME_EXP_LABEL_NONE: No value specified.
  • TIME_EXP_LABEL_PERCENT: Time specified as percentage.
  • TIME_EXP_LABEL_BARS: Time specified in number of bars.
  • TIME_EXP_LABEL_PERCENTBARS: Percentage (Number of Bars).
  • TIME_EXP_LABEL_BARSPERCENT: Number of Bars (Percentage).
  • TIME_EXP_LABEL_DATE: Date for vertical.
  • TIME_EXP_LABEL_TIME: Time for vertical.
  • TIME_EXP_LABEL_DATETIME: Date-Time for Vertical

TimeExpTopLabel2

Type: Integer

When using DRAWING_TIME_EXPANSION or DRAWING_TIME_PROJECTION, this member can be set to specify the contents of the second top text label, which is placed above the corresponding vertical time line. The possible values are specified above.

TimeExpBottomLabel1

Type: Integer

When using DRAWING_TIME_EXPANSION or DRAWING_TIME_PROJECTION, this member can be set to specify the contents of the first bottom text label, which is placed below the corresponding vertical time line. The possible values are specified above.

TimeExpBottomLabel2

Type: Integer

When using DRAWING_TIME_EXPANSION or DRAWING_TIME_PROJECTION, this member can be set to specify the contents of the second bottom text label, which is placed below the corresponding vertical time line. The possible values are specified above.

TimeExpBasedOnTime

Type: Integer

When using DRAWING_TIME_EXPANSION or DRAWING_TIME_PROJECTION, this member can be set to 1 to specify that the tool should use DateTimes instead of bar counts to calculate the time spans. This setting is really only relevant if the tool is being applied to a non-time based chart.

TransparentLabelBackground

Type: Integer

For tools that use text labels, this member can be set to 1 to specify that the labels should use a transparent background for the labels. Otherwise an opaque background is used.

FixedSizeArrowHead

Type: Integer

When using DRAWING_ARROW, setting this member to 1 specifies that the ArrowHeadSize member specifies a fixed size. Otherwise, the ArrowHeadSize member specifies an arrowhead/body ratio.

RetracementLevels[]

Type: float[32]

This array of float values specifies the levels for the drawing tools that require levels. These include DRAWING_RETRACEMENT, DRAWING_EXPANSION, DRAWING_PROJECTION, DRAWING_TIME_EXPANSION, DRAWING_TIME_PROJECTION, DRAWING_PITCHFORK, DRAWING_PITCHFORK_SCHIFF, DRAWING_PITCHFORK_MODIFIED_SCHIFF, DRAWING_PARALLEL_LINES, DRAWING_PARALLEL_RAYS, DRAWING_LINEAR_REGRESSION, and DRAWING_RAFF_REGRESSION_CHANNEL.

Each tool has built in levels that define the basic tool. For example, DRAWING_RETRACEMENT has the initial angled line, and DRAWING_PARALLEL_LINES has the two base lines. The color, width, and style of the base tool are Controlled with Color, LineWidth, and LineStyle. The level color, width, and style are Controlled with LevelColor, LevelWidth, and LevelStyle. All levels are specified as a floating point percentage (Example: 0.618) except for DRAWING_LINEAR_REGRESSION, which specifies number of standard deviations (Example: 2.0).

LevelColor[]

Type: COLORREF[32]

This array specifies the colors for the corresponding tool levels set with RetracementLevels[].

LevelWidth[]

Type: int[32]

This array specifies the line widths for the corresponding tool levels set with RetracementLevels[]. The width needs to be greater than or equal to 1.

LevelStyle[]

Type: int[32]

This array specifies the line styles for the corresponding tool levels set with RetracementLevels[]. Available line styles are: LINESTYLE_SOLID, LINESTYLE_DASH, LINESTYLE_DOT, LINESTYLE_DASHDOT, and LINESTYLE_DASHDOTDOT.

AddAsUserDrawnDrawing

Type: Integer

This member specifies that a drawing is to be added as a user drawn drawing, which allows the user to interact with the ASCIL added drawing on the chart as if it had been added by the user with one of the drawing tools on the Tools menu.

Set this to 1 (TRUE) to make the drawing a user drawn drawing type. When a drawing is added with the AddAsUserDrawnDrawing member set to 1, this member must always be set to 1 when the drawing is updated/modified .

When working with ASCIL user drawn drawings, the sc.UserDrawnChartDrawingExists() and sc.GetUserDrawingByLineNumber() functions can be used to find and retrieve the drawing.

When you have added a chart drawing by setting AddAsUserDrawnDrawing to 1, then you must expressly delete the drawing by calling sc.DeleteUserDrawnACSDrawing().

A chart drawing added with AddAsUserDrawnDrawing set to 1 is not saved to a Chartbook like an actual user drawn drawing would be.

DrawUnderneathMainGraph

Type: Integer

When DrawUnderneathMainGraph is set to 1 (TRUE), then the Chart Drawing will be drawn underneath the main price graph and studies, independent of how the Chart >> Chart Settings >> Advanced Settings >> Draw Non-Highlight Chart Drawings Underneath Main Graph and Studies or Chart >> Chart Settings >> Advanced Settings >> Draw Highlight Drawings Underneath Main Graph and Studies options are set.

When DrawUnderneathMainGraph is set to 0 (FALSE), then the chart drawing will be drawn above the main price graph and studies, independent of how the Chart >> Chart Settings >> Advanced Settings >> Draw Non-Highlight Chart Drawings Underneath Main Graph and Studies or Chart >> Chart Settings >> Advanced Settings >> Draw Highlight Drawings Underneath Main Graph and Studies options are set.

When DrawUnderneathMainGraph is not set, then the chart drawing will be drawn based on the values of Chart >> Chart Settings >> Advanced Settings >> Draw Non-Highlight Chart Drawings Underneath Main Graph and Studies and Chart >> Chart Settings >> Advanced Settings >> Draw Highlight Drawings Underneath Main Graph and Studies options are set.

The default for DrawUnderneathMainGraph is not set.

UseToolConfigNum

Type: Integer

This can be set to 1 through 8. This specifies the particular tool configuration defined for the chart drawing tool specified, to automatically be applied to the chart drawing being added. for additional information, refer to .

FlatEdge

Type: Integer

Set this to 1 to use flat edges for the ends of a Line or Ray. This flag is mutually exclusive with the SquareEdge option.

DrawWithinRegion

Type: Integer

Set this to 1 for Vertical Line drawings to cause them to be drawn with the specified Chart Region only instead of across all Chart Regions.

CenterPriceLabels

Type: Integer

Set this to 1 for rectangle highlights to cause the price labels to be centered on the top/bottom price levels.

NoVerticalOutline

Type: Integer

Set this to 1 for rectangle highlight drawings to cause the vertical outline to not be drawn. The result is a rectangle highlight with only top and bottom outline lines similar to a double extending rectangle highlight drawing.

AllowSaveToChartbook

Type: Integer

Set this to 1 to allow a drawing added as a User Drawn Drawing to be saved to the Chartbook which contains the chart which contains the custom study which added the Chart Drawing, when the Chartbook is saved.

ShowBeginMark

Type: Integer

Set this to 1 to show a square mark at the beginning of a Line or other types of Chart Drawings which support marks at the anchor points. This is equivalent to the Options >> Mark setting in the Drawing Tool Configuration/Properties window.

ShowEndMark

Type: Integer

Set this to 1 to show a square mark at the ending of a Line or other types of Chart Drawings which support marks at the anchor points. This is equivalent to the Options >> Mark setting in the Drawing Tool Configuration/Properties window.


sc.ChartDrawingExists()

ACSIL Function

Declaration: int ChartDrawingExists(int ChartNumber, int LineNumber);

sc.ChartDrawingExists() is used to determine if a Chart Drawing with the specified LineNumber exists within the specified chart (ChartNumber).

This function ignores user drawn Chart Drawings, only Chart Drawings added by ACSIL.

This function returns the number of matching drawings found. See the scsf_UseToolExample() function in the /ACS_Source/studies.cpp file for example code on how to work with this function.

if (sc.ChartDrawingExists(sc.ChartNumber, 5))
{
    // A line with a LineNumber of 5 exists on the same chart that this study is on
}
        

sc.UserDrawnChartDrawingExists()

ACSIL Function

Declaration: int UserDrawnChartDrawingExists(int ChartNumber, int LineNumber);

sc.UserDrawnChartDrawingExists() function is used to determine if a user drawn Chart Drawing with the specified LineNumber exists within the specified chart (ChartNumber).

An ASCIL Chart Drawing is considered user drawn if it was added with the s_UseTool::AddAsUserDrawnDrawing member set to 1.

Non-user drawn ASCIL Chart Drawings are not searched with this function.

It returns the number of matching drawings found.

Refer to the scsf_UseToolExample() function in the /ACS_Source/studies.cpp file for example code on how to work with this function.

if (sc.UserDrawnChartDrawingExists(sc.ChartNumber, 5))
{
    // An ASCIL added user drawing with a LineNumber of 5 exists on the same chart that this study is on
}
        

sc.GetUserDrawnChartDrawing()

ACSIL Function

int GetUserDrawnChartDrawing(int ChartNumber, DrawingTypeEnum DrawingType, s_UseTool& ChartDrawing, int DrawingIndex);

sc.GetUserDrawnChartDrawing() is used to get a Chart Drawing drawn by a drawing Tool on the specified chart.

Only user drawn drawings can be retrieved, not Chart Drawings added by an ACSIL study, unless the Chart Drawing was specified as being s_UseTool::AddAsUserDrawnDrawing when adding it with sc.UseTool().

This function returns 1 on success, and 0 on error. A error includes an invalid drawing type specified or a drawing not found on the chart.

Refer to the scsf_GetChartDrawingExample function in the /ACS_Source/studies.cpp file for example code on how to work with this function.

Parameters

ChartNumber

This number corresponds to the number after the number "#" sign on the top line of the chart. Using a zero (0) will specify the chart the ACSIL study is applied to.

DrawingType

The chart drawing type that you want to get. This parameter can be any of the following:

  • DRAWING_LINE
  • DRAWING_RAY
  • DRAWING_HORIZONTALLINE
  • DRAWING_VERTICALLINE
  • DRAWING_ARROW
  • DRAWING_TEXT
  • DRAWING_CALCULATOR
  • DRAWING_RETRACEMENT
  • DRAWING_PROJECTION
  • DRAWING_RECTANGLEHIGHLIGHT
  • DRAWING_ELLIPSEHIGHLIGHT
  • DRAWING_TRIANGLE
  • DRAWING_FAN_GANN
  • DRAWING_PITCHFORK
  • DRAWING_CYCLE
  • DRAWING_TIME_EXPANSION
  • DRAWING_GANNGRID
  • DRAWING_ENTRYEXIT_CONNECTLINE
  • DRAWING_RECTANGLE_EXT_HIGHLIGHT
  • DRAWING_FAN_FIBONACCI
  • DRAWING_PARALLEL_LINES
  • DRAWING_PARALLEL_RAYS
  • DRAWING_LINEAR_REGRESSION
  • DRAWING_RAFF_REGRESSION_CHANNEL
  • DRAWING_EXTENDED_LINE
  • DRAWING_PITCHFORK_SCHIFF
  • DRAWING_PITCHFORK_MODIFIED_SCHIFF
  • DRAWING_EXPANSION
  • DRAWING_VOLUME_PROFILE
  • DRAWING_STATIONARY_TEXT
  • DRAWING_TIME_PROJECTION
  • DRAWING_MARKER
  • DRAWING_HORIZONTAL_RAY
  • DRAWING_HORIZONTAL_LINE_NON_EXTENDED
  • DRAWING_UNKNOWN. Use this constant to get any type of drawing. When the function returns and DrawingType was set to DRAWING_UNKNOWN, the ChartDrawing::DrawingType parameter member will indicate the type of drawing that has been found.

ChartDrawing

A reference to a s_UseTool structure. This is where the Chart Drawing information will be copied to. For the descriptions of the s_UseTool structure, refer to Drawing Tools and s_UseTool Member Descriptions.

User drawn Chart Drawings have a negative LineNumber. This is how you can distinguish Chart Drawings drawn by a user and also drawings flagged as user drawn which were added by the ACSIL.

DrawingIndex

An index to specify which instance of the matching chart drawing you want. This is a 0-based index in the order that chart drawings were added to the chart. For example, if DrawingIndex is 0, the function will return the first instance that matches the drawing type. If DrawingIndex is 1, the function will return the second instance that matches the drawing type.

Also you can give a negative index to specify drawings from the last drawing that was added to the chart. For example, if DrawingIndex is -1, the function will return the last drawing matching the drawing type that was added to the chart.

This index only counts the drawings on the chart that match the given DrawingType. For example, if DrawingType is DRAWING_RAY and DrawingIndex is 1, then the function will return the second Ray on the chart. If DrawingType is DRAWING_TEXT and DrawingIndex is 1, then the function will return the second text chart drawing on the chart. If DrawingType is DRAWING_TEXT and DrawingIndex is -1, then the function will return the last text chart drawing on the chart. If DrawingType is DRAWING_UNKNOWN, then the index counts all drawings on the chart.

Example:

// Gets the last drawn text on the chart and adds a message to the Sierra Chart message log, if the text exists.
s_UseTool ChartDrawing;
if (sc.GetUserDrawnChartDrawing(0, DRAWING_TEXT, &ChartDrawing, -1))
{
    sc.AddMessageToLog("Text was added on current chart!", 0);
    sc.AddMessageToLog(ChartDrawing.Text, 1);
}
            

sc.GetUserDrawingByLineNumber()

ACSIL Function

int GetUserDrawingByLineNumber(int ChartNumber, int LineNumber, s_UseTool& ChartDrawing, DrawingTypeEnum DrawingType, int DrawingIndex);

The sc.GetUserDrawingByLineNumber() function is used to get a user drawn Chart Drawing on the chart. This also includes Chart Drawings added by ACSIL which are flagged as user drawn when setting s_UseTool::AddAsUserDrawnDrawing = 1 when the drawing is added.

This function cannot get Chart Drawings which are added by ACSIL when s_UseTool::AddAsUserDrawnDrawing = 0.

This function returns 1 on success, and 0 on failure. A failure includes an invalid DrawingType specified or a Chart Drawing not found on the chart.

Refer to the scsf_GetChartDrawingExample function in the /ACS_Source/studies.cpp file for example code on how to work with this function.

When a user drawn Chart Drawing is being moved or adjusted by the user, the sc.GetUserDrawingByLineNumber() call will fail to find the Chart Drawing even though sc.UserDrawnChartDrawingExists() indicates that it exists. Therefore, a study should always use sc.UserDrawnChartDrawingExists() to detect if the user drawn Chart Drawing exists, and then use sc.GetUserDrawingByLineNumber() to get the Chart Drawing, and understand that a failure means that the Chart Drawing is being modified.

When a Chart Drawing you are getting is not visible in the current view of the chart, then s_UseTool::BeginIndex, s_UseTool::EndIndex, s_UseTool::ThirdIndex will all equal -1.

Parameters

ChartNumber

This number corresponds to the number after the number "#" sign on the top line of the chart. Using a zero (0) will specify the chart the custom study is applied to.

LineNumber

This number corresponds to the s_UseTool::LineNumber of the ASCIL added drawing.

This can be set to 0 in which case the search is not dependent on LineNumber and instead depends upon the other function parameters.

When LineNumber is set to a nonzero value, only Chart Drawings that match this are considered when searching.

The same LineNumber can be associated with multiple Chart Drawings, in which case the DrawingIndex can be used to further distiguish which drawing to retrieve.

ChartDrawing

A reference to a s_UseTool structure. This is where the Chart Drawing information will be copied to. For the descriptions of the s_UseTool structure, refer to Drawing Tools and s_UseTool Member Descriptions. Note that when chart drawings are returned through this function, the DrawingType member is set to indicate the type of drawing retrieved.

DrawingType

The chart drawing type that you want to get. This parameter can be any of the following:

  • DRAWING_LINE
  • DRAWING_RAY
  • DRAWING_HORIZONTALLINE
  • DRAWING_VERTICALLINE
  • DRAWING_ARROW
  • DRAWING_TEXT
  • DRAWING_CALCULATOR
  • DRAWING_RETRACEMENT
  • DRAWING_PROJECTION
  • DRAWING_RECTANGLEHIGHLIGHT
  • DRAWING_ELLIPSEHIGHLIGHT
  • DRAWING_TRIANGLE
  • DRAWING_FAN_GANN
  • DRAWING_PITCHFORK
  • DRAWING_CYCLE
  • DRAWING_TIME_EXPANSION
  • DRAWING_GANNGRID
  • DRAWING_ENTRYEXIT_CONNECTLINE
  • DRAWING_RECTANGLE_EXT_HIGHLIGHT
  • DRAWING_FAN_FIBONACCI
  • DRAWING_PARALLEL_LINES
  • DRAWING_PARALLEL_RAYS
  • DRAWING_LINEAR_REGRESSION
  • DRAWING_RAFF_REGRESSION_CHANNEL
  • DRAWING_EXTENDED_LINE
  • DRAWING_PITCHFORK_SCHIFF
  • DRAWING_PITCHFORK_MODIFIED_SCHIFF
  • DRAWING_EXPANSION
  • DRAWING_VOLUME_PROFILE
  • DRAWING_STATIONARY_TEXT
  • DRAWING_TIME_PROJECTION
  • DRAWING_MARKER
  • DRAWING_HORIZONTAL_RAY
  • DRAWING_HORIZONTAL_LINE_NON_EXTENDED
  • DRAWING_REWARD_RISK
  • DRAWING_SWING_MARKER
  • DRAWING_DATE_MARKER
  • DRAWING_OHLC_RAY
  • DRAWING_UNKNOWN. Use this constant to get any type of drawing. When the function returns and DrawingType was set to DRAWING_UNKNOWN, the ChartDrawing::DrawingType parameter member will indicate the type of drawing that has been found.

DrawingIndex

An index to specify which instance of the matching Chart Drawing you want. This is a 0-based index in the order that Chart Drawings were added to the chart. For example, if DrawingIndex is 0, the function will return the first instance that matches the drawing type. If DrawingIndex is 1, the function will return the second instance that matches the drawing type.

Also a negative index can be used to specify Chart Drawings from the last drawing that was added to the chart. For example, if DrawingIndex is -1, the function will return the last Chart Drawing matching the drawing type that was added to the chart.

This index only counts the Chart Drawings on the chart that match the given DrawingType. For example, if DrawingType is DRAWING_RAY and DrawingIndex is 1, then the function will return the second Ray on the chart. If DrawingType is DRAWING_TEXT and DrawingIndex is 1, then the function will return the second Text drawing on the chart. If DrawingType is DRAWING_TEXT and DrawingIndex is -1, then the function will return the last Text drawing on the chart. If DrawingType is DRAWING_UNKNOWN, then DrawingIndex considers all Chart Drawings on the chart.

sc.DeleteACSChartDrawing()

ACSIL Function

Declaration: int DeleteACSChartDrawing(int ChartNumber, int Tool, int LineNumber);

The sc.DeleteACSChartDrawing() function deletes Chart Drawings that have been added by ACSIL studies using the sc.UseTool() function.

This function cannot be used to delete user drawn Chart Drawings. User drawn Chart Drawings are manually drawn by a user or ACSIL added Chart Drawings that have the s_UseTool::AddAsUserDrawnDrawing = 1 flag set. For deleting user drawn drawings, use sc.DeleteUserDrawnACSDrawing().

When a study is removed from the chart, or when it is fully recalculated, and it has Chart Drawings added with sc.UseTool(), these Chart Drawings are automatically deleted from the chart. Therefore, there is no need to use sc.DeleteACSChartDrawing().

This function should only be used for more specialized purposes like when you need to delete a Chart Drawing for some other reason.

For an example which uses this function, refer to the scsf_DeleteACSChartDrawingExample function in the /ACS_Source/studies.cpp file in the Sierra Chart installation folder.

ChartNumber

Type: Integer

The chart that contains the drawing. The default value is 0, which means the chart the ACSIL study is applied to. This number corresponds to the number after the number "#" sign on the top line of the chart.

Tool

Type: Integer

The Tool parameter can be TOOL_DELETE_ALL or TOOL_DELETE_CHARTDRAWING.

If Tool is set to TOOL_DELETE_ALL, then all non user drawn Chart Drawings on the specified ChartNumber will be deleted. The LineNumber parameter in this case is ignored and should be 0.

If Tool is set to TOOL_DELETE_CHARTDRAWING, then all non user drawn Chart Drawings with the specified LineNumber will be deleted from the chart specified by the ChartNumber parameter.

LineNumber

Type: Integer

The LineNumber of the Chart Drawings to delete. The LineNumber is the same LineNumber that was specified when adding the Chart Drawing with sc.UseTool(). In the case where LineNumber was not set when calling sc.UseTool(), then it will be automatically set. In this case remember it into a persistent integer and then it can be specified in this function call.

This parameter only applies to TOOL_DELETE_CHARTDRAWING.

Multiple Chart Drawings can be deleted if they use the same LineNumber. All chart drawings with the same LineNumber will be deleted from the chart.

Return Value

For TOOL_DELETE_ALL, 1 on success, 0 on failure.

For TOOL_DELETE_CHARTDRAWING, the number of chart drawings deleted.

sc.DeleteUserDrawnACSDrawing()

ACSIL Function

Declaration: int DeleteUserDrawnACSDrawing(int ChartNumber, int LineNumber);

The sc.DeleteUserDrawnACSDrawing() function deletes Chart Drawings that have been added by ACSIL studies using sc.UseTool() and have specified s_UseTool::AddAsUserDrawnDrawing = 1.

Chart Drawings manually drawn by a user can also be deleted with this function if the LineNumber for the drawing is known. This can be determined with the sc.GetUserDrawnChartDrawing() function.

When Chart Drawings have been added using sc.UseTool() and have specified s_UseTool::AddAsUserDrawnDrawing = 1, it is necessary to remove these drawings with sc.DeleteUserDrawnACSDrawing() in the study function when sc.LastCallToFunction is TRUE. Otherwise, they will remain on the chart.

ChartNumber

Type: Integer

The number of the chart that contains the Chart Drawing. The default value is 0, this means the chart the ACSIL study is applied to. This number corresponds to the number after the number "#" sign on the top line of the chart.

LineNumber

Type: Integer

The LineNumber of the Chart Drawing to delete.

Multiple chart drawings can be deleted. All chart drawings with the same LineNumber will be deleted from the chart.

The LineNumber is the same LineNumber that you specified when adding the chart drawing with sc.UseTool(), or was automatically set and remembered.

This can also be a LineNumber from an actual user drawn Chart Drawing retrieved with the sc.() function.

Return Value

The number of user drawn Chart Drawings deleted.

RGB Color Values

Colors are stored as 32-bit unsigned integer values. It is easiest to use the RGB function. It takes red, green, and blue integer values as parameters, and returns a color value. For more information, you may want to refer to the RGB color model Wikipedia article.

Here are some color examples:

  • Red: RGB(255,0,0)
  • Green: RGB(0,255,0)
  • Blue: RGB(0,0,255)
  • Magenta: RGB(255,0,255)
  • White: RGB(255,255,255)
  • Black: RGB(0,0,0)
  • Dark Blue: RGB(0,0,127)
  • Orange: RGB(255,127,0)
sc.Subgraph[0].PrimaryColor = RGB(255, 0, 0); // Set the primary color for the first subgraph to red
s_UseTool Tool;
Tool.Color = RGB(0, 0, 255); // Set Tool color to Blue
    

Drawing Chart Drawings On Top of or Underneath Main Graph and Studies

The Chart Drawings added by the sc.UseTool function can be set to be displayed on top of or underneath the Main Price Graph and Studies in the chart. This can be done by using the DrawUnderneathMainGraph member of the s_UseTool structure.

Also, there are 2 settings for this as well in Chart >> Chart Settings >> Advanced Settings.

They are Draw Non-Highlight Chart Drawings Under Main Graph and Studies and Draw Highlight Drawings Under Main Graph and Studies.

Adding Chart Drawings to Other Charts from an ACSIL Study Function

It is supported when using the sc.UseTool() function, to add Chart Drawings to a chart other than the chart the study function making the function call is applied to.

This can be done by setting the s_UseTool::ChartNumber member to the chart number that you want to add a drawing to.

It is also necessary to set s_UseTool::AddAsUserDrawnDrawing to 1.

Drawing Lines With a Specific Angle Using ACSIL

This section explains how to use ACSIL to draw lines at a specific angle. For introductory information about using drawing tools from ACSIL, refer to the Introduction section on this page.

The s_UseTool structure supports specifying the beginning and ending anchor points of the line using these members:

You need to make sure the combination of these values results in a line with a specific angle that you require. For example a 45 degree line will have a slope of 1. This means one unit of price over one unit of time. One unit of time is always one bar in the chart. The Drawing a Line with a Specific Angle or Slope section has complete information on this subject.

To have a better idea of all of this, it is recommended to manually draw Lines at 45 degrees to get an idea of what values to use.


*Last modified Thursday, 01st December, 2016.