ACSIL Interface Members - sc.Subgraph Array
On This Page
- sc.Subgraph.Data / sc.Subgraph
Type: Array of study Subgraph structures.
sc.Subgraph is an array of the subgraphs available to the study. There is currently a maximum of SC_SUBGRAPHS_AVAILABLE (60) subgraphs available for your study to use.
Subgraphs have two purposes. The first is to display data which is part of the study onto the chart. The individual drawings in a study graph are considered subgraphs. The second purpose is to hold data for background calculations or to hold data that needs to be maintained between function calls. If you are using the sc.Subgraph.Data member array of a subgraph for the second purpose, then do not name a subgraph unless you want the data to appear on the chart. By default, subgraphs do not have names unless you set them. If you do want to make the background data visible for debugging purposes, then a subgraph can have a name. However in this case, set its draw style to DRAWSTYLE_IGNORE. This is very useful for debugging. The data can be viewed in the Window >> Chart Values Window.
There are also the Extra Arrays to hold data for background calculations and hold data that needs to be maintained between function calls. Refer to the Extra Arrays member of this Subgraph structure.
A useful method to make it easier to work with a sc.Subgraph and the sc.Subgraph.Data array is to use a C++ reference. A reference is defined with SCSubgraphRef. SCSubgraphRef is a reference to the sc.Subgraph type. Below is an example of defining and using a reference.
// Make a reference to the second subgraph and call it PlotB SCSubgraphRef PlotB = sc.Subgraph; // Now the PlotB reference can be used in place of sc.Subgraph // Set the value of the element in the Subgraph Data array the // current index to 10. // This is the same as sc.Subgraph[sc.Index] = 10.0f; PlotB[sc.Index] = 10.0f; // Calculate the simple moving average and store the result in // the Data array of PlotB (sc.Subgraph). sc.SimpleMovAvg(sc.BaseDataIn[SC_LAST], PlotB, 20);
sc.Subgraph Structure Members
sc.Subgraph.Data / sc.Subgraph
Read/Write. Array of float variables (SCFloatArray).
sc.Subgraph.Data is the array of values for the subgraph. This is where you will store the results of your calculations, and this is the data that will be graphed on the chart if the sc.Subgraph has the Name member set and has a visible DrawStyle. The size of this array is equal to sc.ArraySize. If you have set sc.IsCustomChart, the size of this array is equal to sc.OutArraySize.
If you are familiar with the Sierra Chart Spreadsheet Studies, it may help to think of this array as a column of data in a Spreadsheet (formula columns K through Z). The Spreadsheet Studies uses these same Subgraph Data arrays to hold the results from the formula columns.
A shorthand method to access a Subgraph Data array element exists. Example: sc.Subgraph[i] is equivalent to sc.Subgraph.Data[i]. When passing a Subgraph Data array to an array based study function such as sc.Highest(), you do not need to use the second set of brackets. For example, use sc.Subgraph.
For more information about the Subgraph structure and the purpose of Subgraphs, see sc.Subgraph.
For information about indexing and array sizes see Array Indexing and Sizes.
// Set the value of the element at the current index in the third subgraph to 12.5 sc.Subgraph[sc.Index] = 12.5f;
// Calculate the exponential moving average with a Length of 20 on the closing // prices from the chart and store the result in the second subgraph (sc.Subgraph). sc.ExponentialMovAvg(sc.BaseDataIn[SC_LAST], sc.Subgraph, 20); // Calculate the simple moving average with a Length of 20 on the exponential // moving average that was calculated above. To do this, use the second // subgraph (sc.Subgraph) as the input for the simple moving average. // Store the result in the first subgraph (sc.Subgraph). sc.SimpleMovAvg(sc.Subgraph, sc.Subgraph, 20);
The sc.Subgraph.GetArraySize() function gets the number of sc.Subgraph.Data arrays within the sc.Subgraph. Normally, this will return the maximum number of Subgraphs. As of 2013-8 this is 60.
Type: Read/Write array of float arrays (SCFloatArray).
Arrays[Index1][Index2]: This member is an array of arrays to be used for storing background or intermediate calculations and to store data that needs to be held between function calls.
As of 2016-02 there are 12 extra arrays for each sc.Subgraph.
The arrays referred to by sc.Subgraph.Arrays are of type SCFloatArray. The reference type to them is SCFloatArrayRef.
These extra array elements can be accessed by using sc.Subgraph.Arrays[Index1][Index2]. Where Index1 can be from 0 to (12 - 1) and represent these internal Subgraph arrays. Where Index2 is the same index value as used with the sc.Subgraph.Data arrays (This accesses the primary graphable Data array for the Subgraph).
Each of the sc.Subgraph.Arrays arrays has the same size as sc.Subgraph.Data. A working example can be found in the scsf_ExtraArraysExample function in the /ACS_Source/studies.cpp file.
As with all arrays used in ACSIL, these are safe and using an index which is out of bounds does not cause any harm. It is simply adjusted to be within the bounds. For example, if Index2 is -1, it will be adjusted to 0.
Note: Some study functions that take arrays for input and output require a reference to a sc.Subgraph and not a reference to a SCFloatArray contained within a sc.Subgraph. An example is sc.MACD().
These functions will use the extra arrays contained within the passed sc.Subgraph (sc.Subgraph.Arrays). Usually they will use 2 or 3 extra arrays, but it could be up to 6 to 8 extra arrays. After passing a Subgraph to one of these functions, you do not want to use one of these extra arrays in the sc.Subgraph for another purpose by writing to it.
To do a reference to an Extra Array to make accessing it easier, define a reference like this:
SCFloatArrayRef myArray = sc.Subgraph.Arrays; // Set the array element at the current index to 10. This is just an example. myArray[sc.Index] = 10;
Passing Extra Arrays to Functions
To pass an Extra Array to a function you simply define the parameter type as SCFloatArrayRef. Refer to the scsf_PassingExtraArray function in the /ACS_Source/studies.cpp file in the folder Sierra Chart is installed to.
Read/Write string variable.
Initial value: "" (empty string)
sc.Subgraph.Name is the name of the Subgraph. If there is no name, the Subgraph will not be drawn, and it will not be displayed on the list of Subgraphs in the Subgraphs tab on the Study Settings window. It is useful to use a sc.Subgraph to store some background or intermediate calculation that should not be displayed. This is a good example of when you would want to leave the Name blank, so that it will not be graphed on the chart.
// Set the name of the first subgraph sc.Subgraph.Name = "First Subgraph";
Read/Write color variable.
sc.Subgraph.PrimaryColor is the primary color for the subgraph. This is the only color for the subgraph if the secondary color is not used. For more information on colors, see the RGB Color Values note.
// Set the primary color for the first subgraph to red sc.Subgraph.PrimaryColor = RGB(255,0,0);
Read/Write color variable.
sc.Subgraph.SecondaryColor is the secondary color of the subgraph. For more information on colors, see the RGB Color Values note.
// Set the secondary color for the first subgraph to yellow sc.Subgraph.SecondaryColor = RGB(255,255,0);
Initial value: 0 (FALSE)
sc.Subgraph.SecondaryColorUsed can be a TRUE (1) or FALSE (0) value indicating that the secondary color of the subgraph is used. When this is set to 1 (TRUE) the secondary color is made available for the subgraph in the Subgraphs tab on the Technical Study Settings window. Setting this does not automatically color your subgraph based on it's slope, however if the Auto-Coloring option is on for the subgraph, then this secondary color is used.
// Enable the secondary color for the first subgraph sc.Subgraph.SecondaryColorUsed = 1;
Read/Write array of Integer color values.
sc.Subgraph.DataColor is an array of RGB (unsigned Integer) color values associated with each element of a sc.Subgraph.Data array.
If you use this array, the sc.Subgraph.Data elements will be drawn using the colors in this array rather than the primary color of the sc.Subgraph.
The DataColor array has the same number of elements as the sc.Subgraph.Data array. The color in each element of this array will line up directly with the value in each element of the sc.Subgraph.Data array.
The colors in this array are unset unless you set them. For more information on colors, refer to RGB Color Values.
For information about indexing and array sizes, refer to Array Indexing and Sizes.
For a code example, refer to scsf_SimpMovAvgColored in studies.cpp inside the ACS_Source folder inside of the Sierra Chart installation folder.
Colors for Price Bar Graph Draw Types
In the case where you are using a sc.GraphDrawType other than GDT_CUSTOM, then the following details how the sc.Subgraph.DataColor arrays affect the elements of each price bar Graph Draw Type.
- CandleUpOutlineColor = sc.Subgraph[SC_OPEN].DataColor
- CandleUpFillColor = sc.Subgraph[SC_HIGH].DataColor
- CandleDownOutlineColor = sc.Subgraph[SC_LOW].DataColor
- CandleDownFillColor = sc.Subgraph[SC_LAST].DataColor
Using sc.Subgraph.DataColor Array for GDT_NUMERIC_INFORMATION sc.GraphDrawType
The sc.Subgraph.DataColor array can be used to set the foreground and background colors of each element of a Subgraph displayed in a GDT_NUMERIC_INFORMATION table. GDT_NUMERIC_INFORMATION is set through sc.GraphDrawType.
To be able to set the foreground and background color requires that these colors be combined into a single 4 byte color value by using the sc.CombinedForegroundBackgroundColorRef function.
// Set the color of the Data element at the current Index (sc.Index) // for the third Subgraph (Subgraph) to Blue. sc.Subgraph.DataColor[sc.Index] = RGB(0,0,255); // Set the color of the Data element at the current Index (sc.Index) // for the third Subgraph (Subgraph) to the Primary Color. sc.Subgraph.DataColor[sc.Index] = sc.Subgraph.PrimaryColor; // Set the color of the Data element at the current Index (sc.Index) // for the third Subgraph (Subgraph) to the Secondary Color. sc.Subgraph.DataColor[sc.Index] = sc.Subgraph.SecondaryColor;
Read/Write Integer variable.
Initial value: DRAWSTYLE_LINE or DRAWSTYLE_IGNORE
sc.Subgraph.DrawStyle is the Draw Style that is used to draw the Subgraph. These are relevant when sc.GraphDrawType is set to GDT_CUSTOM. This is the default setting. The Draw Styles you can use are as follows:
- DRAWSTYLE_CUSTOM_TEXT (This is for internal Sierra Chart use only. It is not an actual visible Draw Style. It is used only to set the Color and Font height for text drawn on the chart.)
- DRAWSTYLE_BACKGROUND (example function: scsf_BackgroundDrawStyleExample in studies8.cpp)
For descriptions and more information about each of the above Draw Styles, refer to Draw Style on the Chart Studies documentation page.
When using the Color Bar type of styles (DRAWSTYLE_COLORBAR, DRAWSTYLE_COLORBARHOLLOW, DRAWSTYLE_COLORBAR_CANDLEFILL), these will color the existing chart bars. Typically you will set the sc.GraphRegion to 0 when using these draw styles. To color a particular bar in the chart, you will set a sc.Subgraph array element to any nonzero value to color the corresponding chart bar. The color that will be used will be the sc.Subgraph .PrimaryColor unless you are using the sc.Subgraph .DataColor array. For more information, see the Color Bar style. For an example, see the scsf_ColorBarOpenClose in the studies.cpp file inside the /ACS_Source folder inside of the Sierra Chart installation folder.
When you use a sc.GraphDrawType setting value other than GDT_CUSTOM, then the sc.Subgraph.DrawStyle variable is automatically set for each of the relevant sc.Subgraphs needed by the sc.GraphDrawType. You cannot change them. Additionally, it is not possible when you are drawing a price bar type of graph (GraphDrawType not equal to GDT_CUSTOM), to also use standard study lines or other Draw Styles using the other available sc.Subgraphs which are not used by the sc.GraphDrawType. In this case you will need to use a separate study for those.
When you use DRAWSTYLE_TEXT this means the specified text is drawn at each bar/column in the chart at the value specified in the corresponding Subgraph Data element. The actual text is specifed with sc.Subgraph.TextDrawStyleText. The font height is specified through sc.Subgraph.LineWidth. If sc.Subgraph.DrawZeros is 0, and the sc.Subgraph Data element for a bar/column in the chart is set to zero, no text will be drawn.
// Set the draw style of the first subgraph to the stair-step style sc.Subgraph.DrawStyle = DRAWSTYLE_STAIR;
Initial value: LINESTYLE_SOLID
sc.Subgraph.LineStyle is the style with which lines are drawn. This only applies to subgraphs where sc.Subgraph.DrawStyle is DRAWSTYLE_LINE, DRAWSTYLE_BAR, DRAWSTYLE_DASH, or DRAWSTYLE_STAIR. The line styles you can use are as follows:
Line styles only work when sc.Subgraph.LineWidth is set to 0 or 1. If the line width is greater than 1, the line will appear solid.
// Set the line style of the first subgraph to the "dot" style sc.Subgraph.LineStyle = LINESTYLE_DOT;
Initial value: 1
sc.Subgraph.LineWidth is the width in pixels for the Subgraph Draw Style. Not all the available Draw Styles will support a Line Width. When the Draw Style is set to DRAWSTYLE_TEXT, this controls the font height. In this case, setting this to 10 will mean a 10 point height.
// Set the line width of the second subgraph to 2 pixels sc.Subgraph.LineWidth = 2;
Initial value: 0
sc.Subgraph.LineLabel can be set to a set of flags to enable displaying and positioning of the Name and/or Value of the subgraph. You can set this to a combination of the following flags:
// Set the second subgraph to display it's name on the far right side of the chart and center it vertically. sc.Subgraph.LineLabel = LL_DISPLAY_NAME | LL_NAME_ALIGN_CENTER | LL_NAME_ALIGN_FAR_RIGHT;
Read/Write Integer variable.
Initial value: SNV_DISPLAY_IN_WINDOWS | SNV_DISPLAY_IN_DATA_LINE
sc.Subgraph.DisplayNameValueInWindowsFlags can be set to a set of flags to enable displaying of the subgraph's Name and Value on the Region Data Line on the chart window and/or in the Chart Values Windows.
sc.Subgraph.DisplayNameValueInWindowsFlags = SNV_DISPLAY_IN_WINDOWS | SNV_DISPLAY_IN_DATA_LINE;
Initial value: 0
AutoColors a subgraph. Can be one of the following constants:
sc.Subgraph.AutoColoring = AUTOCOLOR_SLOPE;
Type : Read/Write variable.
Initial value: 0 (disabled)
sc.Subgraph.DrawZeros can be a TRUE (1) or FALSE (0) value to enable or disable the drawing of Subgraph Data array elements that have a value of zero. Set this value to 1 to enable the drawing of zero values. Set this value to 0 to disable the drawing of zero values. When this is disabled, the Subgraph Draw Style of DRAWSTYLE_LINE will draw a continuous line between the chart columns that have non-zero values.
sc.Subgraph.DrawZeros = 1;
Type : Read/Write Integer variable.
Initial value: 0
This is either the positive or negative displacement, in chart columns, to shift the sc.Subgraph  forward or backward by. A positive number will shift the subgraph forward and a negative number will shift the subgraph backward. For more information, refer to Displacement in the Chart Studies documentation.
sc.Subgraph.GraphicalDisplacement = 1;
Type : Read/Write variable.
Initial value: 0
ExtendedArrayElementsToGraph is the number of sc.Subgraph.Data array elements after sc.ArraySize that will be graphed into the extended area on the chart. The extended area on the chart are the columns after the very last bar in the chart. You can see this area by scrolling past the right edge of the chart. This is also known as the Right Side Fill Space/Forward Projection area.
For a code example, refer to the scsf_ExtendedArrayExample function in the /ACS_Source/Studies6.cpp file in the Sierra Chart installation folder.
sc.Subgraph.ExtendedArrayElementsToGraph = 10;
Type : Read/Write SCString variable.
TextDrawStyleText is used to specify the actual text to use with the DRAWSTYLE_TEXT text draw style.
sc.Subgraph.DrawStyle =DRAWSTYLE_TEXT; sc.Subgraph.TextDrawStyleText = "Buy"; sc.Subgraph.LineWidth = 10;// Use a font height of 10.
Type : Read/Write SCString variable.
ShortName is used to specify the subgraph Short Name.
// Set the short name of the first subgraph sc.Subgraph.ShortName = "FSG";
*Last modified Tuesday, 27th September, 2016.