ChartIQ SDK Documentation

new Chart()

Defines an object used for rendering a chart and is automatically created by the CIQ.ChartEngine. Chart objects contain the data and config for each chart but they don't actually exist on the screen until a panel is attached. A chart object is attached to both the main chart panel and any related study panels so they can share the same chart data.

Example: stxx.panels['chart'].chart

Example: stxx.chart (convenience shortcut for accessing the main chart object - same as above)

Example stxx.panels['Aroon (14)'].chart

Members

allowScrollFuture :boolean

If set to false, during zooming and panning operations the chart will be anchored on right side preventing white space to be created beyond the newest tick. If both CIQ.ChartEngine.Chart#allowScrollPast and CIQ.ChartEngine.Chart#allowScrollFuture are set to false, allowScrollFuture will take precedence if the candle is manually set to create space (CIQ.ChartEngine#setCandleWidth), but automated zoom operations (CIQ.ChartEngine#zoomOut) will maintain both scroll restrictions. When viewing a specified date range on the chart, if this flag is set to false, any portion of the range beyond the last quote will not be displayed.

Type:

boolean

Since:

6.1.0 Also respects studies that render into the future, such as the Ichimoku cloud.

Default Value:

true

Example

stxx.chart.allowScrollFuture=false;

allowScrollPast :boolean

/** If set to false, during zooming and panning operations the chart will be anchored on left side preventing white space to be created past the oldest tick. If both CIQ.ChartEngine.Chart#allowScrollPast and CIQ.ChartEngine.Chart#allowScrollFuture are set to false, allowScrollFuture will take precedence if the candle is manually set to create space (CIQ.ChartEngine#setCandleWidth), but automated zoom operations (CIQ.ChartEngine#zoomOut) will maintain both scroll restrictions.

The amount of white space allowed on the right will be limited by CIQ.ChartEngine#minimumLeftBars

Type:

boolean

Default Value:

true

Example

stxx.chart.allowScrollPast=false;

barsHaveWidth :boolean

Whether chart's main renderer's bars have width, as opposed to a line-type chart whose "bars" are just a point on the chart. This is useful when the engine adjusts the chart for smooth scrolling and homing.

Type:

boolean

Since:

5.1.0

baseline :object

Parameters used to control the baseline in baseline_delta charts

Type:

object

baseline[`actualLevel`] :number

actualLevel - This is computed automatically. Do not set.

Type:

number

baseline[`defaultLevel`] :number

defaultLevel - If set to a value, overrides the default behavior of baseline chart which is to set baseline to leftmost point visible on the chart.

Type:

number

baseline[`includeInDataSegment`] :boolean

includeInDataSegment - If set to true, forces a line chart (usually a baseline chart) to begin inside the chart, whereas normally the first point in a line chart is off the left edge of the screen.

Note: Only applies when set by the chart, will not work if set by a renderer.

Type:

boolean

baseline[`userLevel`] :boolean|number

userLevel - Value of the user-set baseline level. To prevent user from adjusting the baseline, set this property to false.

Type:

boolean | number

bottom :number

Type:

number

breakpoint :string

Used to determine chart display characteristics that are dependent on chart size, such as the width and font of the y-axis.

Meant to be used in tandem with CSS responsive design breakpoints. Do not set directly; instead use CIQ.ChartEngine#notifyBreakpoint, which ensures that the relevant styles (which have already been calculated) are updated based on the new breakpoint.

Type:

string

Since:

8.2.0

Default Value:

null

calculateTradingDecimalPlaces :function

Called to determine the number of decimal places in which a security trades.

The function this is called in CIQ.ChartEngine#setMasterData. The result is assigned to CIQ.ChartEngine.Chart#decimalPlaces, which is used for the heads-up display and for the current price pointer label.

Format:

stxx.chart.calculateTradingDecimalPlaces(
    {
         stx: CIQ.ChartEngine,
         chart: CIQ.ChartEngine.Chart,
         symbol: string,
         symbolObject: object
    }
)

Type:

function

Since:

8.0.0 Replaces CIQ.ChartEngine.callbacks[`calculateTradingDecimalPlaces`].

Default Value:

CIQ.calculateTradingDecimalPlaces

context :CanvasRenderingContext2D

Type:

CanvasRenderingContext2D

currentMarketData :object

READ ONLY. A "snapshot" of the market for the active instrument. This data is ephemeral in nature and not used to produce a time series chart. But rather used on our peripheral plugins that require more details on the current market, such as TFC and Active Trader. This data is programmatically collated from the incoming data and is updated with the most recent information so it should not be altered manually.

The currentMarketData object contains the following information:

Last Bid
Last Ask
Last Price
Last Size
Lastest Level 2 information

For more details see CIQ.ChartEngine#updateCurrentMarketData

Type:

object

Since:

6.1.0

customChart :object

This object is used to temporarily override the coloring logic used on some default chart types, or to completely override the layout.chartType allowing you to then define a totally custom rendering.

The colorFunction is only available on the following chart types:

Colored Line
Colored Bar
Colored Mountain
Colored Step
Candle
Hollow Candle
Volume Candle

Expected format :

chartEngine.chart.customChart={colorFunction: myColorFunction}

chartEngine.chart.customChart={chartType:myChartType}

chartEngine.chart.customChart={colorFunction: myColorFunction, chartType:myChartType}

Where:

myColorFunction is the function that contains the logic for overriding default color logic for a default chart. Please contact us for more guidance on how to create your own chart types.
This function must support the following parameters:
- stx - A chart object
- quote - A properly formatted OHLC object.
- mode - A string applicable on 'candle', 'hollow_candle' and 'volume_candle' charts only. Allowed values:
- shadow- indicates the function is asking for the candle wick color
- outline indicates the function is asking for the candle border color
- solid indicates the function is asking for the candle fill color(Inside of candle. Not applicable on 'hollow_candle' or 'volume_candle')
Example: myColorFunction(stx,quote,mode);
This function must return a string|object representing the color to use for the bar, candle or line segment component.
Return null to skip the current datapoint and draw nothing in its place.
For colored line charts a color/pattern combination can be returned in an object of the following format: {pattern:[3,3],color:"red"}
myChartType is the name of your custom chart. Setting this value will force "displayChart" to execute your exact code for rendering a chart. You will need to add your rendering code inside a "displayChart" API injection ( must be an append to be executed after the default functionality.).

You may set to null any of the parameters to default to existing settings.

If you are simply setting the customChart object in-line, rather than using it as part of an AP injection into the animation loop, it may be necessary to call setMainSeriesRenderer to immediately display results.

To restore the original chart settings, set this object to null (and call setMainSeriesRenderer() if necessary).

See Chart Styles and Types for more details.

Type:

object

Examples

Using the customChart object in-line on your code:

//you may want to add a menu selection to activate a special candle chart by executing this code in response to the menu selection:
stxx.chart.customChart={colorFunction: function(stx, quote, mode){
		if(mode=="shadow" || mode=="outline") return "black";  //draw black wicks and borders
		else{
			if(quote.Close>100) return "green";
			else if(quote.DT.getHours()<12) return "yellow";
			else return "orange";
		}
		return null;
	  }
	};
stxx.setMainSeriesRenderer();

// to deactivate, you can execute this code:
stxx.chart.customChart={colorFunction: null};
stxx.setMainSeriesRenderer();

Using the customChart object inside an API injection:

CIQ.ChartEngine.prototype.prepend("displayChart", function(chart){
    if ( this.layout.chartType =="candle")
        this.chart.customChart={
            colorFunction:function(stx, quote, mode){
                if(quote.Close>quote.iqPrevClose) return "blue";
                else if(quote.Close<quote.iqPrevClose) return "yellow";
                else return "gray";
            }
       }
   else
       this.chart.customChart = null;
});

dataSegment :array

READ ONLY. Contains the portion of the CIQ.ChartEngine.Chart#dataSet that is currently displayed on the screen (view-window). It includes both full and partial bars, and may even include a bar whose visible portion is entirely off the screen. As the chart is panned or zoomed, the dataSegment is updated to reflect the new position in the chart.

To properly access the portion of the dataSegment representing bars that are at least 50% showing on the screen, use CIQ.ChartEngine#getDataSegment.

See the Data Integration tutorial for details.

Type:

array

dataSet :array

Contains the current complete data set created from CIQ.ChartEngine.Chart#masterData by CIQ.ChartEngine#createDataSet; adjusted for periodicity and with calculated studies.

See the Data Integration and Studies tutorials for more details.

Type:

array

decimalPlaces :number

READ ONLY. Maximum number of decimal places in data set.

This can be changed by setting CIQ.ChartEngine.Chart#calculateTradingDecimalPlaces to a different function. See CIQ.calculateTradingDecimalPlaces for more details.

Type:

number

defaultChartStyleConfig :object

For chart types which have configuration settings (such as the aggregate charts renko, kagi, etc) contains those default settings. This object holds the settings for the current chart type only.

Type:

object

Since:

3.0.0

Default Value:

{}

defaultPlotField :string

For line and mountain type charts set this to a value other than "Close" to have those chart types plot a different field.

Type:

string

Since:

3.0.0

Default Value:

dynamicYAxis :boolean

If true, the y-axis width is based on the width of the displayed instrument prices.

To prevent constant resizing of the y-axis, the dynamic width setting starts at the initial axis width (CIQ.ChartEngine.YAxis#width) and increases to ensure all digits are in view as the user zooms and pans the chart. The dynamic width setting returns to the initial width only when key events happen, such as removing a study or series or changing the instrument.

Applies to all y-axes attached to a chart.

Type:

boolean

Since:

5.1.1

Default Value:

true

See:

CIQ.ChartEngine.AdvancedInjectable#resetDynamicYAxis.

endPoints :object

Type:

object

forcePercentComparison :boolean

If true, comparisons force a 'percent' chart scale every time a new series is added, and once the last comparison series is removed, the chart will be forced to 'linear' scale. In between adding series, the scale can be changed at any time by programmatically calling calling CIQ.ChartEngine#setChartScale

If false, the chart will not change scale when a comparison series is added or removed and CIQ.ChartEngine#setChartScale must be explicitly called to set the desired scale. This allows for more flexibility in case 'linear' and 'percent' are not the preferred default scales, or the UI is requires to manage the scale separately.

Note this will only take effect on the main chart panel's main axis.

Type:

boolean

Since:

6.2.0

Default Value:

true

gaplines :object

READ ONLY. Gap filling style for the chart (line/mountain chart types only). By default gaps on lines and mountain charts will not be connected. Modify by using CIQ.ChartEngine#setGapLines.

Type:

object

Since:

4.0.0

height :number

Type:

number

hideDrawings :boolean

Set to true to temporarily hide drawings

Type:

boolean

highLowBars :boolean

Whether chart's main renderer's bars plot more than one data field (OHLC charts). When this is true, will disable the use of CIQ.ChartEngine.Chart#defaultPlotField.

Type:

boolean

Since:

5.1.0

includeOverlaysInMinMax :boolean

Set this to true to include the chart overlay/study values in the calculation to determine the high and low values for the chart. This may cause the chart to shrink vertically to ensure all study/overlay data is in view. Setting it to false, will maintain the current candle's height, but some of the study/overlay data may be out of the display range.

This will affect studies such as 'Pivot Points' where all the pivot lines will be visible by “squeezing the y-axis”.

Type:

boolean

Since:

2016-12-01.4.13
3.0.10 Switched default to true.

Default Value:

true

left :number

Type:

number

legendRenderer :function

Function used to render the Legend when multiple series are being displayed on the main chart panel. Update your prototype or a specific chart instance, if you want to use a different rendering method for legend.

To activate the legend, you must first define the location in stx.chart.legend. This is done by providing the x and y coordinates for the first element in the legend as follows:

stxx.chart.legend={
		x: yourXlocation,
		y: yourYlocation
};

Once set, a legend item for each series you add will be added as defined by this function.

Defaults to CIQ.drawLegend, which uses CIQ.drawLegendItem

Type:

function

Since:

07/01/2015

Examples

// define your legend renderer
stxx.chart.legendRenderer = yourFunction; // must follow the function signature of CIQ.drawLegend;
// actiate the legend
stxx.chart.legend={
		x: 50,
		y: 50
};

// sample series legend function
		 	stxx.chart.legendRenderer = function(stx, params){
				var coordinates=params.coordinates;
				var context=stx.chart.context;
				context.textBaseline="top";
				var rememberFont=context.font;
				stx.canvasFont("stx-legend",context);

				var chart=params.chart;
				if(!coordinates) coordinates=chart.legend;
				var xy=[coordinates.x, coordinates.y];
				var lineColor=stx.defaultColor;

				for(var i=0;i<2;i++){ // loop twice, first for the base then again for the series
					for(var field in params.legendColorMap){
						var legendItem=params.legendColorMap[field];
						if(legendItem.isBase && (i || params.noBase)) continue;
						if(!legendItem.isBase && !i) continue;
						var c;
						if(legendItem.color instanceof Array){
							var colors=legendItem.color;
							for(c=colors.length-1;c>=0;c--){
								if(CIQ.isTransparent(colors[c])) colors.splice(c,1);
							}
							if(colors.length>1){
								var grd=context.createLinearGradient(xy[0],xy[1],xy[0]+10,xy[1]);
								for(c=0;c<colors.length;c++){
									grd.addColorStop(c/(colors.length-1),colors[c]);
								}
								lineColor=grd;
							}else if(colors.length>0){
								lineColor=colors[0];
							}else{
								lineColor=stx.getCanvasColor("stx_line_chart");
							}
						}else{
							lineColor=null;
						}
						if(lineColor) {
							var display = field;
							if (legendItem.display){
								display = legendItem.display;
							}
							if(!display){
								if(chart.symbolDisplay){
									display=chart.symbolDisplay;
								}else{
									display=chart.symbol;
								}
							}
							if(xy[0]+context.measureText(display).width>chart.panel.right){
								xy=[coordinates.x, coordinates.y+context.measureText("M").width+6];  // M is squarish, with width roughly equaling height: https://stackoverflow.com/questions/1134586/how-can-you-find-the-height-of-text-on-an-html-canvas
							}
							xy=CIQ.drawLegendItem(stx, xy, display, lineColor, legendItem.opacity);
						}
					}
				}
				context.font=rememberFont;
			};

lineApproximation :boolean

When candleWidth<1, setting to true will create approximation of a line chart to improve rendering performance.

Must allow for smaller candle sizes by lowering CIQ.ChartEngine#minimumCandleWidth and allow for larger dataset by increasing CIQ.ChartEngine#maxDataSetSize or setting it to 0.

Type:

boolean

Since:

4.1.0

Default Value:

true

lineStyle :object

READ ONLY. Style for the main series renderer. Set by using CIQ.ChartEngine#setLineStyle.

Type:

object

Since:

4.0.0

lockScroll :boolean

Set this to true to turn off auto-scrolling when fresh data comes in. By default, the chart will scroll backward whenever a new bar comes in, so as to maintain the chart's forward position on the screen. If lockScroll is true then fresh bars with advance the chart forward (and eventually off the right edge of the screen)

Note that setSpan({base:"today"}) will set an internal variable that accomplishes the same thing. This is a unique case.

Type:

boolean

Since:

05-2016-10

masterData :array

READ ONLY. The master data for this chart. This data is never modified by the chart engine itself and should not be altered directly.

Use CIQ.ChartEngine#loadChart , CIQ.ChartEngine#updateChartData to load/update this object.

See the Data Integration tutorial for details.

Type:

array

maxTicks :number

Will contain the maximum number of bars that can be displayed on the chart. This number is auto-computed by the ChartEngine when the user zooms or the size of the chart changes. Since charts can pan slightly off the edge of the screen, this number is width/candleWidth + 2 in order allow partial candles to be displayed on both edges.

Type:

number

right :number

Type:

number

scroll :number

Current number of ticks scrolled in from the end of the chart. Setting to zero would theoretically cause the chart to be scrolled completely to the left showing an empty canvas. Setting to 10 would display the last 10 candles on the chart. Setting to maxTicks would display a full screen on the chart (assuming enough data is available).

To immediately activate, call draw()

Type:

number

Examples

Scroll to the most current (beginning) position in the chart.

stxx.chart.scroll=0;

Scroll to the end of the chart.

stxx.chart.scroll=stxx.chart.dataSet.length;

scrubbed :array

Contains a copy of the CIQ.ChartEngine.Chart#dataSet, scrubbed for null entries (gap dates). This is used by studies to avoid gaps being interpreted as "zero" values and throwing off calculations.

See the Studies tutorial for more details.

Type:

array

segmentImage :array

READ ONLY. Contains data pertaining to variable width candles, such as volume candles, used to determine location of bars on the screen.

Type:

array

series :object

Contains information about the series that are associated with the chart. Series are additional data sets, such as used for comparison charts. Note that a series may have a different y-axis calculation than the price chart. See the "parameters" section of CIQ.ChartEngine#addSeries for details

Type:

object

seriesRenderers :object

Contains "renderers" that are used to create the visualizations for series.

Renderers will be drawn in their object order, which can be altered if needed to force certain renderings to be drawn before or after others. See example.

Type:

object

Example

This sample code shows how to move up one place a renderer called "comparison D"

var rendererName = "comparison D";
var newRenderers = {};
var pos = 0;
var r;

for (r in stxx.chart.seriesRenderers) {
    if (r == rendererName) break;
    pos++;
}

if (pos) { // Not already at top.
    var i = 0;
    for (r in stxx.chart.seriesRenderers) {
        if (i == pos - 1) newRenderers[rendererName] = stxx.chart.seriesRenderers[rendererName];
        if (r == rendererName) continue;
        newRenderers[r] = stxx.chart.seriesRenderers[r];
        i++;
    }
    stxx.chart.seriesRenderers = newRenderers;
}

standaloneBars :boolean

Whether chart's main renderer's bars represent a stand-alone entity as opposed to a vertex in a line-type chart. This is important when the engine tries to render the data points right off the chart; in a stand-alone bar, the points right off the chart need not be considered.

Type:

boolean

Since:

5.1.0

symbol :string

The current symbol for the chart

Type:

string

symbolDisplay :string

Set this to preset an alternate name for the symbol on the chart label and comparison legend. You can set stxx.chart.symbolDisplay='yourName'; right before calling loadChart(). Alternatively, a good place to set it is in your fetch function, if using quotefeed. See example.

Type:

string

Example

// on your initial data fetch call add the following
params.stx.chart.symbolDisplay='yourName for '+params.symbol;

symbolObject :object

The current symbolObject for the chart. Generally this is simply {symbol: symbol}. This is initialized by CIQ.ChartEngine#loadChart.

Type:

object

tension :number

Set to a value between 0 and 1 to soften the curves on a line or mountain chart for the primary series.

This only affects the primary chart series. For setting tension on additional series see CIQ.ChartEngine#addSeries

Splining is a mathematical process that rounds the connectors between segments. This results in a very pleasing, smooth look. Please note that technical analysts generally do not like splined charts because they obscure the actual closing prices of securities. Splining should be used only when the use case doesn't require exact values.

Type:

number

top :number

Type:

number

width :number

Type:

number

xAxis :CIQ.ChartEngine.XAxis

Contains the {@CIQ.ChartEngine.XAxis} object for the chart.

Type:

CIQ.ChartEngine.XAxis

xaxis :array

Contains data entries for the full x-axis, including entries for "future" bars that are displayed on the chart. floatDate and headsUp use these values for display to the user. It is a superset of dataSegment.

Type:

array

xaxisFactor :number

Determines at which zoom level interior axis points are displayed. Value in pixels.

Type:

number

Default Value:

yaxisMarginMultiplier :number

How much to multiply the yAxis.initialMarginTop and yAxis.initialMarginBottom for the main chart. Set to 1 to keep the initial values.

Type:

number

Since:

8.6.0

Default Value:

yaxisPaddingLeft :number

How much padding to leave for the left y-axis. Default is enough for the axis. Set to zero to overlap y-axis onto chart.

Type:

number

Since:

07/01/2015

Example

stxx.chart.yaxisPaddingLeft=0;
stxx.chart.yAxis.displayBorder=false; // hide the vertical axis line.
//must call the following 2 lines to activate if the axis is already drawn.
stxx.calculateYAxisPositions();
stxx.draw();

yaxisPaddingRight :number

How much padding to leave for the right y-axis. Default is enough for the axis. Set to zero to overlap y-axis onto chart.

Type:

number

Since:

07/01/2015

Example

stxx.chart.yaxisPaddingRight=0;
stxx.chart.yAxis.displayBorder=false; // hide the vertical axis line.
//must call the following 2 lines to activate if the axis is already drawn.
stxx.calculateYAxisPositions();
stxx.draw();

Class: Chart

new Chart()

Members

allowScrollFuture :boolean

Type:

Example

allowScrollPast :boolean

Type:

Example

barsHaveWidth :boolean

Type:

baseline :object

Type:

baseline[`actualLevel`] :number

Type:

baseline[`defaultLevel`] :number

Type:

baseline[`includeInDataSegment`] :boolean

Type:

baseline[`userLevel`] :boolean|number

Type:

bottom :number

Type:

breakpoint :string

Type:

calculateTradingDecimalPlaces :function

Type:

context :CanvasRenderingContext2D

Type:

currentMarketData :object

Type:

customChart :object

Type:

Examples

dataSegment :array

Type:

dataSet :array

Type:

decimalPlaces :number

Type:

defaultChartStyleConfig :object

Type:

defaultPlotField :string

Type:

dynamicYAxis :boolean

Type:

endPoints :object

Type:

forcePercentComparison :boolean

Type:

gaplines :object

Type:

height :number

Type:

hideDrawings :boolean

Type:

highLowBars :boolean

Type:

includeOverlaysInMinMax :boolean

Type:

left :number

Type:

legendRenderer :function

Type:

Examples

lineApproximation :boolean

Type:

lineStyle :object

Type:

lockScroll :boolean

Type:

masterData :array

Type:

maxTicks :number

Type:

right :number

Type:

scroll :number

Type:

Examples