API Reference
Namespaces
Classes
Events
Global
Externals

Namespace: CIQ

CIQ

Base namespace for CIQ library

Previously STX

Classes

Account
Animation
CSVReader
ChartEngine
ContinuousZoom
CrossSection
DataLoader
Drawing
EaseMachine
ExtendedHours
FullScreen
InactivityTimer
Marker
Market
MarketDepth
NameValueStore
Outliers
PlotComplementer
Plotter
RangeSlider
Renderer
ScriptIQ
Share
Shortcuts
SignalIQ
TCAnalystViews
TCTechnicalInsights
TFC
TableView
ThemeHelper
TimeSpanEventPanel
Tooltip
VisualEarnings
Visualization

Namespaces

Comparison
I18N
MobileBridge
PinnedMarker
QuoteFeed
RequestLimiter
SVGChart
Scripting
Studies
Studies
UI

Members


ipad :boolean

READ ONLY. Will be 'true' if the chart is running on an iPad

Type:
  • boolean

iphone :boolean

READ ONLY. Will be 'true' if the chart is running on an iPhone

Type:
  • boolean

isAndroid :boolean

READ ONLY. Will be 'true' if the chart is running on an Android OS device

Type:
  • boolean

isEdge :boolean

READ ONLY. Will be 'true' if the chart is running on a Edge Legacy browser

Type:
  • boolean

isFF :boolean

READ ONLY. Will be 'true' if the chart is running on a Firefox browser

Type:
  • boolean

isIE :boolean

READ ONLY. Will be 'true' if the chart is running on a IE browser

Type:
  • boolean

isIOS10 :boolean

READ ONLY. Will be 'true' if the chart is running on an iOS 10 device

Type:
  • boolean

isIOS7 :boolean

READ ONLY. Will be 'true' if the chart is running on an iOS 7 device

Type:
  • boolean

isIOS7or8 :boolean

READ ONLY. Will be 'true' if the chart is running on an IOS7, IOS8, IOS9 or IOS10 device

Type:
  • boolean

isIOS8 :boolean

READ ONLY. Will be 'true' if the chart is running on an iOS 8 device

Type:
  • boolean

isIOS9 :boolean

READ ONLY. Will be 'true' if the chart is running on an iOS 9 device

Type:
  • boolean

isMobile :boolean

READ ONLY. Will be 'true' if the chart is running on a mobile device ( CIQ.isAndroid, CIQ.ipad, or CIQ.iphone )

Type:
  • boolean

isSafari :boolean

READ ONLY. Will be 'true' if the chart is running on a Safari browser

Type:
  • boolean
Since:
  • 7.4.0


isSurface :boolean

READ ONLY. Will be 'true' if the chart is running on a MS Surface like device

Type:
  • boolean

isSurfaceApp :boolean

READ ONLY. Will be 'true' if the chart is running from a MS Surface application

Type:
  • boolean

isWebComponentsSupported :boolean

READ ONLY. Will be 'true' if the chart supports web components

Type:
  • boolean
Since:
  • 6.1.0


is_chrome :boolean

READ ONLY. Will be 'true' if the chart is running on a Chrome browser

Type:
  • boolean

localStorage :Object.<string, function()>

Some browsers don't support localStorage, worse won't let you polyfill (JDK7 webview). The CIQ.localStorage object allows us to add a polyfill.

Type:
  • Object.<string, function()>

noKeyboard :boolean

READ ONLY. Will be 'true' if the chart is running from a device with no Keyboard ( CIQ.isMobile or CIQ.isSurfaceApp )

Type:
  • boolean

privateBrowsingAlert :boolean

Set once after user is alerted that private browsing is enabled

Type:
  • boolean

resizeDetectInterval :number

Set to a positive number to use an interval to check for resizes instead of a ResizeObserver. The number chosen will be used as the number of milliseconds between checks.

Set to 0 to disable adding resize listeners.

Note: If an interval is passed to CIQ.resizeObserver, that value will be used instead. See CIQ.resizeObserver for more details.

Type:
  • number
Since:
  • 8.6.0


timeZoneMap :object

This object contains a reduced list of the timezones needed for the sample UI.

To see the current list and format, open your browser console and type CIQ.timeZoneMap.

There are more timezones loaded in the chart by default from /examples/markets/timezones.js. You can get a full list by running timezoneJS.timezone.getAllZones(); from your browser console. (timezoneJS can be made available by importing it from standard.js and assigning it to the global window object.)

Feel free to add other timezones and rules to this map if you want them to be available to users. Our complete list can be downloaded from here. This file is large, so add timezones with discretion.

Although we do update this file periodically, it may not be available immediately after every timezone change. If you require immediate updates, you should subscribe to a notification system that alerts you of these changes, then adjust the file as needed. IANA is a good source.

The following code snippet demonstrates how to add timezones and rules to this object. (You can add synonyms this way as well). To save space, you may want to cherry pick the zones that you will need and then add them in your initialization code.

	var myAdditionalZones = {
	 "zones" : {
	  "America/Toronto": [
	   [ 300, "Canada", "E%sT", null ]
	  ],
	  "Europe/Kiev": "Europe/Kyiv"  // maps left zone to right zone
	 },
	 "rules" : {
	  "Canada" : [
	   [ 2007, "max", "-", "Mar", "Sun>=8", [ 2, 0, 0, null ], 60, "D" ],
	   [ 2007, "max", "-", "Nov", "Sun>=1", [ 2, 0, 0, null ], 0, "S" ] ]
	 }
	}

// to add all timezones "zones" and "rules", you can simply load the entire timeZoneDataObject.txt file.
	if(timezoneJS) timezoneJS.timezone.loadZoneDataFromObject(myAdditionalZones);

Lastly, if you want users to be able to select the new timezones from the menus, be sure to also add their titles to the CIQ.timeZoneMap object to keep the list and the settings in sync:

CIQ.timeZoneMap["(UTC-05:00) Toronto"]="America/Toronto";

See CIQ.ChartEngine#setTimeZone for further instructions on how to set the different timezones on the chart.

Type:
  • object

touchDevice :boolean

READ ONLY. Will be 'true' if the chart is running on a touch capable device

Type:
  • boolean

wheelEvent

READ ONLY. String of appropriate wheel event based on browser features.

Methods


AnalystViews(stx, token, partner)

Controller class to assist in the creation and processing of Trading Central™ API requests.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart instance to modify

token string

Trading Central API token

partner number

Trading Central API partner number


TechnicalInsights(stx, auth, lang)

Controller class to assist in the creation and processing of TechnicalInsights API requests.

Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart instance to modify

auth string

A valid TechnicalInsights authentication token

lang string

Language identifier, eg "en". Must match an option in lexicon.json


activateImports(imports)

Activates an import. Should be called to activate an import for use by the API. If an import is not activated, its code is inaccessible and may be tree shaken by bundlers. Keeps track of which imports have been activated already so no import gets added more than once.

Each feature, component, or add-on is considered an import. For example, studies, drawings, and CIQ.RangeSlider are imports.

See the webpack examples (webpack.config.js and webpack.config.minimal.js in the root folder of the library) for detailed examples of how to import.

Note: DefinePlugin needs to be included in the webpack.config.js file in order to achieve tree shaking. Otherwise, all imports are automatically activated without the need for the developer to explicitly call this function.

Parameters:
Name Type Argument Description
imports object <repeatable>

A list of imports to add to the namespace.

Since:
  • 8.0.0


addInternalStylesheet(content, path [, doc])

Adds style content to a document if it has not been added already.

Parameters:
Name Type Argument Description
content string

Style content.

path string

Unique identifier, which prevents duplicate style inclusions.

doc Document <optional>

document to attach stylesheet to.

Since:
  • 8.0.0
  • 8.5.0 Added the doc parameter.

addMemberToMasterdata(params)

Convenience function to iterate through the charts masterData and add a data member. Used to load initial data for additional series and study symbols and should normally not be called directly. Unless used inside a study initialize function; use CIQ.ChartEngine#addSeries or CIQ.ChartEngine#updateChartData instead. Can be used with any array of data objects which contains at least the 'DT' (date in JavaScript format) and 'Close' ( close/last price ) elements of an OHLC object.

Parameters:
Name Type Description
params object

Parameters object

Properties
Name Type Argument Default Description
stx CIQ.ChartEngine <optional>

A chart object

data array <optional>

The data to add (which should align or closely align with the chart data by date)

fields array <optional>

The fields from the incoming data objects to extract and add as the new members in each masterData object. One new member will be added per field using the exact same name as in the incoming data. Example: (for each field name in the array) masterData[mIterator][fieldN]=data[dIterator][fieldN]. Takes precedence over createObject, label and fieldForLabel parameters. Use fields=["*"] to copy all fields in the data object.

label string <optional>

The name of the new member to add into each masterData object. Example: masterData[mIterator][label]=data[dIterator]["Close"]. Required unless "fields" is specified.

createObject string <optional>

If truthy, then each complete incoming data object will be assigned to the new label member in each masterData object. If set to "aggregate", will consolidate the OHLV data with the new data. The data object is expected to be a properly formatted OHLC record, or at least contain a 'Close' price, otherwise this parameter will not be honored. Example: masterData[mIterator][label]=data[dIterator]. This behavior is mutually exclusive with fields.
If the data object contains a 'Value' field, this parameter will not be honored and instead the 'Value' field will be used as follows: masterData[mIterator][label] = data[dIterator]["Value"];

fieldForLabel string <optional>
"Close"

If set, this will be the field from each incoming data object that will be copied into the new label member in each masterData object. If not set, "Close" or "Value" is used, whichever exists; and if neither exists, it will attempt to copy over a field matching the label name. Example: masterData[mIterator][label]=data[dIterator][fieldForLabel]. This behavior is mutually exclusive with fields and createObject.

fillGaps boolean <optional>

If true, then gaps in data will be filled by carrying forward the value of from the previous bar.

noCleanupDates boolean <optional>

If true then dates have been cleaned up already by calling CIQ.ChartEngine#doCleanupDates, so do not do so in here.

chart CIQ.ChartEngine.Chart <optional>

The chart to update

Since:
  • 04-2015
  • 15-07-01 Added fieldForLabel argument.
  • 3.0.0 All data sent in will be forced into the chart. Dates are no longer required to be exact matches (minutes, hours, seconds, milliseconds) in order to show up in comparisons.
  • 4.0.0 Arguments are now parameterized. Backward compatibility with old signature.
  • 4.0.0 Added ability to specify copying of all fields by setting params.fields=["*"].
  • 5.2.0 Enhanced parameter createObject to take a string.
  • 5.2.0 Added parameter noCleanupDates.
Example
//data element format if neither fields, fieldForLabel or createObject are used
{DT:epoch,Date:strDate,Value:value}
{DT:epoch,Date:strDate,Close:value }
//data element format if fields is used
{DT:epoch,Date:strDate,Field1:value,Field2:value,Field3:value,Field4:value}
//data element format if createObject is used
{DT:epoch,Date:strDate,AnyOtherData:otherData,MoreData:otherData,...}

addResizeListener(element, callback)

Deprecated since 7.4.0. Use CIQ.UI.addResizeListener instead.

Attaches a callback to listen for resize events on the DOM.

Designed to be used as a helper method for the included WebComponents. A full tutorial on how to work with and customize the Web Components can be found here: Web Component Interface.

Parameters:
Name Type Description
element node

The node to which the listener is attached.

callback function

The listener function to attach to the DOM element.

Deprecated:

addTranslatableAriaLabel(element, stx, original [, language])

Adds translatable aria-label attribute. If there is no translationCallback, the node will not be translatable.

Parameters:
Name Type Argument Description
element HTMLElement

The element to convert

stx CIQ.ChartEngine

The chart object

original string

The untranslated text

language string <optional>

Language. Defaults to CIQ.I18N.language.

Since:
  • 9.1.0


alert(text)

Creates a user-friendly alert.

The charting engine uses this function instead of window.alert() for warning and error messages. If the window object does not exist, the message is output to the console log.

Override this function to create a custom alert.

Parameters:
Name Type Description
text string

The message to be displayed.

Since:
  • 8.0.0 Output the message to the console log if the window object does not exist.

Example
// Override with a friendlier alert mechanism!
CIQ.alert=function(text){
	doSomethingElse(text);
}

appendClassName(node, className)

Appends a class name to a node if the node doesn't already have that class. Used to control dynamic behavior via CSS.

Parameters:
Name Type Description
node object

The DOM element to which the class is added.

className string

Name of the class to add to the DOM element.

Deprecated:
Example
// Apply an "active" css look to an object.
CIQ.appendClassName(myNode, "active");

biSquareMult(a, b)

Convenience function to calculate a**b where a and b are BigInts

Parameters:
Name Type Description
a BigInt

The base

b BigInt

The exponent

Since:
  • 9.0.0

Returns:

BigInt(a ** b)

Type
BigInt

blur( [node])

Reliable, cross-device blur method

Parameters:
Name Type Argument Description
node HTMLElement <optional>

The element to blur. If not supplied then document.activeElement will be blurred


borderPatternToArray( [width] [, pattern])

Convert a pattern type to an array useful for setting the context.setLineDash

Parameters:
Name Type Argument Default Description
width number <optional>
1

A valid lineWidth from 1

pattern string <optional>
solid

A valid pattern (solid, dotted, dashed)

Since:
  • 4.0.0

Returns:

The array representing pixels of draw/skip etc. Use it as argument to context.setLineDash()

Type
array

boxIntersects(bx1, by1, bx2, by2, x0, y0, x1, y1, vtype)

Determines whether a line intersects a box. This is used within the charting engine to determine whether the cursor has intersected a drawing. Note this function is meant to receive bx1, by1, bx2, by2, x0, y0, x1 and y1 as pixel values and not as ticks/axis values.

Parameters:
Name Type Description
bx1 number
by1 number
bx2 number
by2 number
x0 number
y0 number
x1 number
y1 number
vtype string

Either "segment", "ray" or "line". Anything else will default to segment.

Since:
  • 4.0.0 Added isLog parameter.
  • 6.0.0 Removed isLog parameter.
Returns:

Returns true if the line intersects the box

Type
boolean

calculateHeikinAshi(stx, newData, computed)

Calculates Heikin-Ashi values. Takes some unaggregated data and returns aggregated data.

This method is used inside CIQ.ChartEngine#createDataSet to determine the data aggregation logic and should not be called directly. Use CIQ.ChartEngine#setAggregationType instead.

See the Chart types tutorial for details on how to override aggregation type defaults.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

newData array

The data to aggregate. Normally the dataSet.

computed array

Cumulative computed records from last pass through this function. Used to increase performance by reusing pre-calculated bars and only calculate missing new bars.

Version:
  • ChartIQ Advanced Package
Since:
  • 04-2015-15
  • 3.0.0 Added computed parameter.
Returns:

The aggregated data

Type
array

calculateKagi(stx, newData, reversal, computed)

Calculates Kagi chart values. Takes some unaggregated data and returns aggregated data.

This method is used inside CIQ.ChartEngine#createDataSet to determine the data aggregation logic and should not be called directly. Use CIQ.ChartEngine#setAggregationType instead.

Kagi uses Close method only, not High/Low or ATR

See the Chart types tutorial for details on how to override aggregation type defaults.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

newData array

The data to aggregate. Normally the dataSet.

reversal number

The reversal percentage for the Kagi lines. This is typically user configurable. Default is 4% for daily, .4% for intraday.

computed array

Cumulative computed records from last pass through this function. Used to increase performance by reusing pre-calculated bars and only calculate missing new bars.

Version:
  • ChartIQ Advanced Package
Since:
  • 04-2015-15
  • 3.0.0 Added computed parameter.
Returns:

The aggregated data

Type
array

calculateLineBreak(stx, newData, pricelines, computed)

Calculates Line Break chart values. Takes some unaggregated data and returns aggregated data.

This method is used inside CIQ.ChartEngine#createDataSet to determine the data aggregation logic and should not be called directly. Use CIQ.ChartEngine#setAggregationType instead.

See the Chart types tutorial for details on how to override aggregation type defaults.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

newData array

The data to aggregate. Normally the dataSet.

pricelines number

The number of lines to use for the line break count. This is typically user configurable. Default is 3.

computed array

Cumulative computed records from last pass through this function. Used to increase performance by reusing pre-calculated bars and only calculate missing new bars.

Version:
  • ChartIQ Advanced Package
Since:
  • 04-2015-15
  • 3.0.0 Added computed parameter.
Returns:

The aggregated data

Type
array

calculatePointFigure(stx, newData, pandf, computed)

Calculates Point and Figure (P&F) chart values. Takes some unaggregated data and returns aggregated data.

This method is used inside CIQ.ChartEngine#createDataSet to determine the data aggregation logic and should not be called directly. Use CIQ.ChartEngine#setAggregationType instead.

See the Chart types tutorial for details on how to override aggregation type defaults.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

newData array

The data to aggregate. Normally the dataSet.

pandf object

The parameters for point and figure.

Properties
Name Type Argument Description
box number <optional>

The box size. Default is automatically determined based on the price.

reversal number <optional>

The reversal amount, in boxes. Default is 3.

computed array

Cumulative computed records from last pass through this function. Used to increase performance by reusing pre-calculated bars and only calculate missing new bars.

Version:
  • ChartIQ Advanced Package
Since:
  • 04-2015-15
  • 3.0.0 Added computed parameter.
Returns:

The aggregated data

Type
array

calculateRangeBars(stx, newData, range, computed)

Calculates range bars. Takes some unaggregated data and returns aggregated data.

This method is used inside CIQ.ChartEngine#createDataSet to determine the data aggregation logic and should not be called directly. Use CIQ.ChartEngine#setAggregationType instead.

See the Chart types tutorial for details on how to override aggregation type defaults.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

newData array

The data to aggregate. Normally the dataSet.

range number

The price range for the range bars. This is typically user configurable. Defaults to a range size so that about 300 bars worth of time are displayed, about a year for a daily chart, and about 5 hours on a minute chart.

computed array

Cumulative computed records from last pass through this function. Used to increase performance by reusing pre-calculated bars and only calculate missing new bars.

Version:
  • ChartIQ Advanced Package
Since:
  • 3.0.0 Added computed parameter.

Returns:

The aggregated data

Type
array

calculateTradingDecimalPlaces(params)

Determines how many decimal places the security trades.

This is the default calculateTradingDecimalPlaces function. It is used by CIQ.ChartEngine#setMasterData to round off the prices to an appropriate number of decimal places. The function is assigned to CIQ.ChartEngine.Chart#calculateTradingDecimalPlaces}, but you may set to your own logic instead.

The default algorithm is to check the most recent 50 quotes and find the maximum number of decimal places that the stock has traded. This will work for most securities but if your market data feed has rounding errors or bad data then you may want to supplement this algorithm that checks the maximum value by security type.

It defaults to a minimum of 2 decimals.

Parameters:
Name Type Description
params object

Parameters

Properties
Name Type Description
stx CIQ.ChartEngine

The chart object

chart CIQ.ChartEngine.Chart

The chart in question

symbol string

The symbol string

symbolObject object

The symbol object. If you create charts with just stock symbol then symbolObject.symbol will contain that symbol

Returns:

The number of decimal places

Type
number
Examples
//set your own logic for calculating decimal places.
var stxx=new CIQ.ChartEngine({container:document.querySelector(".chartContainer"), preferences:{labels:false, currentPriceLine:true, whitespace:0}});
stxx.chart.calculateTradingDecimalPlaces=yourCustomFunction;
// default code
CIQ.calculateTradingDecimalPlaces=function(params){
	var chart=params.chart;
	var decimalPlaces=2;
	var quotesToCheck = 50; // Check up to 50 recent quotes
	var masterData=chart.masterData;
	if(masterData && masterData.length > quotesToCheck){
		// exclude the current quote by setting i=2 in case animation is enabled. Animation uses very large decimals to allow for smooth movements.
		for(var i=2;i<quotesToCheck;i++){
			var position=masterData.length-i;
			if(position<0) break;
			var quotes=masterData[position];
			if(quotes.Close && typeof quotes.Close == 'number'){
				var cs=quotes.Close.toString();
				var point=cs.indexOf('.');
				if(point!=-1){
					var dp = cs.length-point-1;
					if(dp>decimalPlaces){
						decimalPlaces=dp;
					}
				}
			}
		}
	}
	var maxDecimalPlaces=chart.yAxis.maxDecimalPlaces;
	if(decimalPlaces>maxDecimalPlaces && maxDecimalPlaces!==null) decimalPlaces=maxDecimalPlaces;
	return decimalPlaces;
};

capitalize(string)

Capitalizes the first letter of a string.

Parameters:
Name Type Description
string string

String to be capitalized.

Since:
  • 7.4.0 Replaces String.prototype.capitalize.

Returns:

Capitalized version of the string.

Type
string

chooseForegroundColor(backgroundColor)

Chooses either a white or black foreground color depending on the "lightness" of the background color. Note that this simply checks if the value is above the hue which works well but not ideally for red colors which the human eye interprets differently. More complex algorithms are available, but chartists rarely use red as a background color.

Parameters:
Name Type Description
backgroundColor string

The background color (CSS format)

Returns:

Either #000000 (black) or #FFFFFF (white) depending on which will look best on the given background color

Type
string

cleanPeriodicity(period [, interval], timeUnit)

Convenience function to convert API periodicity parameters to internal periodicity format.

Parameters:
Name Type Argument Description
period string

The period value as required by CIQ.ChartEngine#setPeriodicity

interval string <optional>

The interval value as required by CIQ.ChartEngine#setPeriodicity

timeUnit string

The timeUnit value as required by CIQ.ChartEngine#setPeriodicity

Since:
  • 5.1.1

Returns:

object containing internally compliant periodicity, interval, and timeUnit

Type
object

clearCanvas(canvas [, stx])

Animation Loop

Clears the canvas. Uses the fastest known method except on the legacy Android browser which had many problems!

Parameters:
Name Type Argument Description
canvas object

A valid HTML canvas object

stx object <optional>

A chart object, only necessary for old Android browsers on problematic devices


clearNode(node)

Deprecated since 8.1.0. Use node.innerHTML="" instead.

Removes all DOM elements from within a given node. This is extremely useful when dynamically generating content.

Parameters:
Name Type Description
node HTMLElement

The node from which all DOM elements are removed.

Since:
  • 8.1.0 Deprecated.

Deprecated:
  • Use node.innerHTML="".


clearSafeClickTouches(div)

Clears all safeClickTouch events from a DOM element.

Parameters:
Name Type Description
div object

The DOM element to clear events


climbUpDomTree(el [, selector], bustShadowRoots)

Gets all parent elements, including the starting element itself, in order of distance from the starting element, nearest parent first.

Use instead of jQuery parents().

Parameters:
Name Type Argument Description
el Element

The starting element from which parent elements are obtained.

selector string <optional>

A CSS selector used to select the parent elements included in the ancestor list. If no selector is provided, all parent elements are included.

bustShadowRoots boolean

Set to true to penetrate shadow root boundaries.

Since:
  • 8.1.0
  • 8.8.0 Adds bustShadowRoots parameter.
Returns:

Ancestry of elements filtered by selector from the starting element up to and including the element.

Type
array

clone(from [, to] [, withoutPrototypeProperties])

Clones an object. This function creates a deep (recursive) clone of an object. The object can be a primitive or an object or an array. Note that cloning objects that reference DOM nodes can result in stack overflows. Use with caution.

Parameters:
Name Type Argument Description
from object

The source object

to object <optional>

Optional existing object of same type. Can improve performance when objects are reusable.

withoutPrototypeProperties boolean <optional>

If true do not copy prototype properties.

Since:
  • 9.2.0 added withoutPrototypeProperties parameter

Returns:

A deep clone of the "from" object

Type
object

colorToHex( [color])

Converts an RGB or RGBA color or CSS color keyword to a six-digit hexadecimal color number.

Parameters:
Name Type Argument Default Description
color string <optional>
#000000

The RGB or RGBA color or CSS color keyword.

Since:
  • 4.0.0 Converts three-digit hexadecimal color numbers (#FFC) to six-digit numbers (#FFFFCC).

Returns:

A six-digit hexadecimal color number. If the color parameter is not provided or has the value "transparent", "#000000" is returned.

Type
string
Example
console.log(CIQ.colorToHex("rgb(255, 255, 0)")); // #ffff00
console.log(CIQ.colorToHex("rgba(255, 255, 0, 0.3)")); // #ffff00
console.log(CIQ.colorToHex("#ff0")); // #ffff00
console.log(CIQ.colorToHex("yellow")); // #ffff00

colorsEqual(color1, color2)

Checks if two colors are the same. Will compare alpha channel is provided as well.

Parameters:
Name Type Description
color1 string

First color, in RGB, RGBA, CSS, hex, or literal format

color2 string

Second color, in RGB, RGBA, CSS, hex, or literal format

Since:
  • 4.0.0

Returns:

true if equivalent

Type
boolean
Example
var isSame=CIQ.colorsEqual("rgba(255,255,255,0.3)", "#FFFFFF");
		returns false
var isSame=CIQ.colorsEqual("rgba(255,255,255,1)", "#FFFFFF");
		returns true

commas(val)

Returns a string representation of a number with commas in thousands, millions or billions places. Note that this function does not handle values with more than 3 decimal places!!!

Parameters:
Name Type Description
val number

The value

Returns:

The result with commas

Type
string
Example
// Returns 1,000,000
CIQ.commas(1000000);

computeEquationChart(equation, map)

Computes an equation that may contain symbols and simple arithmetic operators. Parentheses can be used to separate portions of the equation. PEMDAS priority is observed. Symbols can be optionally contained within brackets. Valid examples: 3IBM, 4+(IBM2), (IBM-GM)/2 If the equation cannot be resolved an exception is thrown.

Parameters:
Name Type Description
equation string

The equation to compute.

map object

A map of symbols to data

Version:
  • ChartIQ Advanced Package
Returns:

A consolidated array of equation results

Type
array

condenseInt(txt)

Condenses a number into abbreviated form by adding "k","m","b" or "t". This method is used in the y-axis for example with volume studies. Rounds off decimal values to 4 places before condensing.

Parameters:
Name Type Description
txt number

A numerical value

Since:
  • 9.2.0 Rounds off decimal values to 2 or 4 places before condensing.

Returns:

Condensed version of the number if over 999, otherwise returns txt untouched

Type
string
Examples
// This will return 12.0m
CIQ.condenseInt(12000000);
// This will return 2.9876
CIQ.condenseInt(2.987654321);
// This will return 892.98
CIQ.condenseInt(892.987654321);
// This will return 1.23k
CIQ.condenseInt(1230.98765);

convertBoxToPixels(stx, panelName, box [, yAxis])

Converts a box represented by two corner coordinates [tick0,value0] and [tick1,value1] into pixel coordinates.

Parameters:
Name Type Argument Description
stx CIQ.ChartEngine

The chartEngine

panelName string

Panel on which the coordinates reside

box object

Box to convert

Properties
Name Type Argument Description
x0 number <optional>
y0 number <optional>
x1 number <optional>
y1 number <optional>
yAxis CIQ.ChartEngine.YAxis <optional>
Since:
  • 6.0.0
  • 8.4.0 Added yAxis parameter.
Returns:

A converted box

Type
object

convertClickToTouchEnd(id)

Converts an onClick event to an ontouchend event. If the device is known to be a touch device then this can be used to change onclick events that are set as attributes (in HTML). ontouchend events are more responsive than onclick events and can improve the user experience. When coding for cross-device implementations it is recommended to use CIQ.safeClickTouch programmatically rather than using hardcoded attributes

Parameters:
Name Type Description
id string

The id of a node containing an onClick attribute

Since:
  • 6.0.0 Deprecated

Deprecated:
  • Yes

convertCurrencyCode(code)

Converts a currency code from ISO to char

Parameters:
Name Type Description
code string

The string to convert (e.g., USD)

Returns:

The converted string, (e.g., $)

Type
string

convertFutureMonth(x)

Converts a future month to the month index or vice versa. Month indexes begin with 1 for January.

Parameters:
Name Type Description
x string

The value to convert. If numeric, converted to future month letter. If alphabetical, converted to month index.

Returns:

The converted value.

Type
string

convertTimeZone(dt, originalTimeZone, targetTimeZone)

Converts a Date object from one time zone to another using the timezoneJS.Date library

Parameters:
Name Type Description
dt date

Original JavaScript Date object, from the original time zone

originalTimeZone string

The original time zone

targetTimeZone string

The target time zone

Returns:

The date in the target timezone. This is a timezoneJS.Date which behaves the same as a native Date.

Type
date

convertToLocalTime(dt, originalTimeZone)

This method converts a time from another timezone to local time on the browser

Parameters:
Name Type Description
dt date

The original time

originalTimeZone string

A valid timezone

Returns:

The date converted to local time

Type
date

convertToNativeColor(color)

Converts a color to the internal format used by the browser. This allows interchange of hex, RGB, and RGBA colors.

Parameters:
Name Type Description
color string | Array.<string>

A CSS color or array of colors.

Since:
  • 8.8.0 Allow use of array as parameter and return value.

Returns:

The native formatted color or array of colors.

Type
string | Array.<string>

countDecimals(n)

Convenience function to count number of decimal places in a number

Parameters:
Name Type Description
n number

The number to check

Since:
  • 6.1.0
  • 6.2.0 Now handles scientific notation.
Returns:

Number of decimal places

Type
number

cqrender(node)

Copies the virtual DOM of an element to the actual DOM.

Note: Use CIQ.cqvirtual to first create a virtual DOM.

Parameters:
Name Type Description
node HTMLElement

The node for which the actual DOM is updated with the virtual DOM.

Since:
  • 8.1.0

Returns:

The actual DOM of the node.

Type
object

cqvirtual(node)

Creates a virtual DOM for an element.

A virtual DOM is faster and more efficient than the actual DOM for manipulation of an element's children.

Note: Use CIQ.cqrender to render the virtual DOM on the real DOM.

Parameters:
Name Type Description
node HTMLElement

The node for which the virtual DOM is created.

Since:
  • 8.1.0

Returns:

The virtual DOM of node.

Type
object

createLabel(params)

Adds text on the canvas for the floating label over the y-axis.

Uses native canvas functions to add the text. You can override this function if you wish to customize how the text on the floating y-axis labels are displayed. See example.

Parameters:
Name Type Description
params object
Properties
Name Type Description
ctx object

A valid HTML Canvas Context

x number

Left position of drawing on canvas

txt number

Text for the label

y number

Y position of drawing on canvas

margin object

Margin around the text

Properties
Name Type Description
left object

Left margin of text

top object

Top margin of text

backgroundColor number

Background color of the shape drawn under the text, if any. This is used to find the text color if there is no color specified

color number

Text color

Since:
  • 3.0.0

Example
// customized version which adds a dash before the label text
CIQ.createLabel=function(params){
    // set the vertical alignment of the text
    params.ctx.textBaseline="middle";
    // set the color for the text and background color behind the text
    params.ctx.fillStyle=params.color?params.color:CIQ.chooseForegroundColor(params.backgroundColor);
    if(	params.ctx.fillStyle === params.backgroundColor){
        // Best effort to pick a foreground color that isn't the same as the background!
        if(params.backgroundColor.toUpperCase()=="#FFFFFF")
            params.ctx.fillStyle="#000000";
        else
            params.ctx.fillStyle="#FFFFFF";
    }
    //add the text to the canvas.
    // see we are adding a dash ('- ') before the text
    params.ctx.fillText('- '+params.txt, params.x + params.margin.left, params.y + params.margin.top);
    // set the horizontal alignment of the text
    params.ctx.textAlign="left";
};

createObjectChainNames(field, properties)

Create arrow notation strings (field-->property) of a given field and an array of properties Used to create a set of object properties in string format for later use by CIQ.existsInObjectChain Its main use is to pass field names into CIQ.ChartEngine#determineMinMax.

Parameters:
Name Type Description
field string

Base object.

properties array

Array of strings representing properties

Since:
  • 5.1.0

Returns:

Array of object properties expressed in arrow notation (field-->property)

Type
array
Example
var fields=CIQ.createObjectChainNames("ABC.D",["High","Low"]);
fields===["ABC.D-->High","ABC.D-->Low"]

dataBindSafeAssignment(target, source)

This method changes the target object's contents to match the contents of the source object. This is functionally equivalent to target=source except that it preserves the existence of the target object. This is vitally important if there are data bindings to the target object otherwise those data bindings would remain attached to a phantom object! The logic here is orchestrated so that you will receive update, add and delete notifications for each field that changes.

Parameters:
Name Type Description
target object

The target object

source object

The source object

Since:
  • 2015-11-1


dateToStr(dt, str)

Formats a date according to an input string; for example, "YYYY:MM:dd hh:mm".

All matching tokens in the input string are replaced by their corresponding date or time value. Supported tokens and their values are as follows:

  • YYYY = full year
  • MM = month
  • dd = day
  • HH = hours (24-hour format)
  • hh = hours (12-hour format)
  • mm = minutes
  • ss = seconds
  • SSS = milliseconds

Values are formatted with leading zeroes as necessary.

Note: This function is less performant than the special-purpose format functions defined in this namespace, such as CIQ.mmddyyyy and CIQ.yyyymmdd, and should be used accordingly.

Parameters:
Name Type Description
dt Date

The date to format.

str string

The format for the date.

Since:
  • 8.1.0

Returns:

The formatted date string.

Type
string

deleteRHS(map, object)

Deletes the map entries for which the right-hand side is the object in question.

Parameters:
Name Type Description
map object

JavaScript map object

object object

The actual object to be deleted from the map

Returns:

Returns true if any object actually deleted

Type
boolean

deriveFromObjectChain(base, extension)

Given a dot notation string, we want to navigate to the location in a base object, creating the path along the way

Parameters:
Name Type Description
base object

Base object.

extension string

String in dot notation

Since:
  • 2015-11-1

Returns:

A tuple containing obj and member

Type
object
Example
var tuple=CIQ.deriveFromObjectChain(stx.layout, "pandf.box");
tuple.obj===stx.layout.pandf
tuble.member==="box"
tuple.obj[tuple.member]=3;  // stx.layout.pandf.box=3

derivedFrom(child, parent)

Replacement for isPrototypeOf and instanceof so that both types of inheritance can be checked

Parameters:
Name Type Description
child object

The object instance to check

parent object

Prototype

Since:
  • 07/01/2015

Returns:

True if the object is derived from the parent

Type
boolean

displayableDate(stx, chart, dt [, includeIntraYear])

Creates a displayable date string according to the current chart settings and periodicity.

Formats the date using one of the following formatters or default format (in order of preference):

  1. Chart x-axis formatter
  2. Chart engine internationalizer
  3. Default format
    a. Daily — mm/dd/yyyy
    b. Intraday — mm/dd hh:mm[:ss[:ms]]

This method is used in CIQ.ChartEngine.AdvancedInjectable#headsUpHR to format the date label that floats over the x-axis. Overwrite this method as needed to achieve the desired date format.

Parameters:
Name Type Argument Description
stx CIQ.ChartEngine

The charting object.

chart CIQ.ChartEngine.Chart

The chart to which the date applies.

dt Date

The date to format.

includeIntraYear boolean <optional>

If true, include the year in the intraday dates.

Since:
  • 4.0.0
  • 8.2.0 Added the includeIntraYear parameter.
Returns:

The formatted date.

Type
string

drawLegend(stx, params)

Default function to draw a legend for the series that are displayed on the chart.

See CIQ.ChartEngine.Chart#legendRenderer for activation and customization details.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object to draw

params object

parameters for drawing the legend

Properties
Name Type Argument Description
chart CIQ.ChartEngine.Chart <optional>

The chart object

legendColorMap object <optional>

A map of series names to colors and display symbols ( example IBM:{color:'red', display:'Int B M'} )

coordinates object <optional>

Coordinates upon which to draw the items, in pixels relative to top left of panel ( example {x:50, y:0} ). If null, uses chart.legend

noBase boolean <optional>

Set to true to not draw the base (the chart symbol's color) in the legend


drawLegendItem(stx, xy, label, color [, opacity] [, borderColor])

Draws an item in the legend and returns the position for the next item

Parameters:
Name Type Argument Description
stx CIQ.ChartEngine

The chart object

xy array

An X,Y tuple (from chart.legend)

label string

The text to print in the item

color string

The color for the background of the item

opacity number <optional>

The color for the background of the item

borderColor string <optional>

The color for the border of the item

Since:
  • 9.1.0 Added borderColor parameter.

Returns:

A tuple containing the X,Y position for the next the item

Type
array

efficientDOMUpdate(obj, member, value)

Sets a property or style of a DOM element only if the property or style does not already have the provided value.

This is more efficient than needlessly updating the DOM.

Parameters:
Name Type Description
obj object

The DOM element or an object in the element to update.

member string

The DOM element's property or style to update.

value string

The value to set.

Since:
  • 4.0.0
  • 8.1.0 Added return value.
Returns:

true if the value of member was changed.

Type
boolean
Examples

Set the HTML content of a DOM element.

CIQ.efficientDOMUpdate(node, "innerHTML", htmlString);

Set a style property of a DOM element.

CIQ.efficientDOMUpdate(controls.floatDate.style, "width", "auto");

elementDimensions(element [, flags])

Measures an element's styled width and height. Assumes all style units are in pixels (px), not percentages or "auto".

Use the flags parameter to specify whether padding, border, and margin should be included in the measurement.

Parameters:
Name Type Argument Description
element HTMLElement

The element to measure.

flags object <optional>

Measurement parameters.

Properties
Name Type Argument Description
padding boolean <optional>

Include padding in the measurement.

border boolean <optional>

Include border in the measurement.

margin boolean <optional>

Include margin in the measurement.

Since:
  • 8.1.0

Returns:

Width and height as properties of the returned object.

Type
object

ensureDefaults(target, defaults)

Accepts a default parameters object and sets the field values for the target only if they are missing. Note that a value of null will not be overridden. Only undefined (missing) values will be overridden.

Parameters:
Name Type Description
target object

The object needing potential default values

defaults object

Default values

Since:
  • 3.0.0

Returns:

Returns the modified target object

Type
object
Example
var target={"color":"red"};
var defaults={"color":"blue", "shape":"triangle"};
CIQ.ensureDefaults(target, defaults);
>> target==={"color":"red", "shape":"triangle"};

equals(a, b [, exclude])

Returns true if the objects are an exact match

Parameters:
Name Type Argument Description
a object

First object

b object

Second object

exclude object <optional>

Exclude these fields

Returns:

True if they are an exact match

Type
boolean

existsInObjectChain(base, extension)

Given an arrow notation string (a-->b-->c), we want to navigate to the location in a base object, to see if it exists

Parameters:
Name Type Description
base object

Base object.

extension string

String in arrow notation

Since:
  • 5.1.0

Returns:

A tuple containing obj and member; a null will be returned if path does not exist

Type
object
Example
var tuple=CIQ.existsInObjectChain(stx.dataSegment[0], "ABC.D-->High");
tuple.obj===stx.dataSegment[0]["ABC.D"]
tuple.member==="High"
tuple.obj[tuple.member]=28.7;  // stx.dataSegment[0]["ABC.D"].High=28.7

extend(target, source [, shallow])

Extends an object, similar to jquery.extend() with a deep copy

Only does a recursive deep copy if the source is plain object.

Parameters:
Name Type Argument Description
target object

Target object

source object

Original object

shallow boolean <optional>

If true then extend will not recurse through objects

Since:
  • 5.1.0 Undefined properties do not copy to target object.
  • 5.2.0 Target of a deep copy may now be a class instance.
Returns:

Target object after extension

Type
object

fetchEquationChart(params, cb)

Extracts symbols from an equation and fetches the quotes for them.

Parameters:
Name Type Description
params object

Parameters used for the fetch

cb function

Callback function once all quotes are fetched

Version:
  • ChartIQ Advanced Package

fillArea(stx, points, params)

Fills an area on the chart, usually created by a study.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

points array

The set of points, this is an array of chart coordinates in array form e.g. [[x1,y1],[x2,y2]]. The points should be arranged to form a loop; the loop need not be closed.

params object

parameters

Properties
Name Type Argument Description
color string | object <optional>

color, canvas gradient object or canvas pattern object to fill the area

opacity number <optional>

opacity of fill, 0 to 1. Defaults to 0.1

tension number <optional>

Tension for splining.

panelName string <optional>

Name of panel to draw on. If omitted or invalid, area may fill over top or bottom of plot area

yAxis CIQ.ChartEngine.YAxis <optional>

The y-axis for the area (will use default axis if not specified)

Since:
  • 01-2015-20 Added params.panelName.
  • 4.0.0 Combined arguments into params. Added tension.
  • 5.2.0 Added params.yAxis.

fillIntersecting(stx, panelName, parameters)

Fills an area on the chart delimited by intersecting bands.

Bands can be anchored by different y-axis as determined by the parameters.topAxis and parameters.bottomAxis parameters.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

panelName string

The name of the panel

parameters object

The configuration parameters

Properties
Name Type Argument Description
topBand string

The name of the quote field to use as the top band

bottomBand string

The name of the quote field to use as the bottom band

topSubBand string <optional>

Name of the field within the top band to use, for example when plotting a series

bottomSubBand string <optional>

Name of the field within the bottom band to use, for example when plotting a series

topColor string

The color of the top band, used to fill in a cloud whose top edge is the topBand

bottomColor string

The color the bottom band, used to fill in a cloud whose top edge is the bottomBand

tension number <optional>

Tension for splining.

topAxis CIQ.ChartEngine.YAxis

The y-axis for the top band (will use default axis if not specified)

bottomAxis CIQ.ChartEngine.YAxis

The y-axis for the bottom band (will use default axis if not specified)

skipTransform boolean

If true then any transformations (such as comparison charting) will not be applied

opacity number

The color opacity/transparency as a decimal number (1= full opacity / no transparency). Default is 0.3.

Since:
  • 4.0.0 Changed sd argument to panelName argument. Added parameters.topColor, parameters.bottomColor, parameters.opacity and parameters.skipTransform. Removed parameters.fillFuture.
  • 4.1.2 Removed quotes argument; function always uses chart.dataSegment.
Example
var parameters={
    topBand: "Leading Span A " + sd.name,
    bottomBand: "Leading Span B " + sd.name,
    topColor: "green",
    bottomColor: "red"
};
CIQ.fillIntersecting(stx, sd.panel, parameters)

fillTransparentCanvas(context, color, width, height)

Sets the transparent parts of the canvas to the specified background color. Used to ensure a background when turning charts into images because normally the background is the background of the DIV container and not the canvas itself.

Parameters:
Name Type Description
context object

An HTML canvas context

color string

The color to set the background. Any valid HTML canvas color.

width number

Width to apply color (Could be less than size of canvas)

height number

Height to apply color (Could be less than size of canvas if applying branding for instance)


findClosestParent(el, selector)

Deprecated since 8.1.0. Use Element.parentElement.prototype.closest() instead.

Convenience function for selecting a DOM element's closest parent element matching a selector.

Use instead of jQuery.closest().

Parameters:
Name Type Description
el HTMLElement

The DOM element for which the parent element is obtained.

selector string

A CSS selector used to select the parent element.

Since:
  • 7.3.0
  • 8.1.0 Deprecated.
Deprecated:
  • Use Element.parentElement.prototype.closest().

Returns:

The parent element of el matching selector, or null if no match is found.

Type
HTMLElement

findNodesByText(startNode, text)

Find all nodes that match the given text. This is a recursive function so be careful not to start too high in the DOM tree.

Parameters:
Name Type Description
startNode object

A valid DOM element from which to start looking

text string

The text to search for

Returns:

An array of nodes that match the text

Type
array

first(o)

Convenience function returns the first property in an object. Note that while this works in all known browsers the EMCA spec does not guarantee that the order of members in an object remain static. This method should therefore be avoided. When ordering is important use an Array!

Parameters:
Name Type Description
o object

A JavaScript object

Returns:

The first element in the object or null if it is empty

Type
object

fixPrice(price)

Given a numeric price that may be a float with rounding errors, this will trim off the trailing zeroes

Parameters:
Name Type Description
price number

The price

Returns:

The price trimmed of trailing zeroes

Type
number

fixScreen()

Fixes screen scroll. This can occur when the keyboard opens on an iPad or iPhone.


focus(node, useTimeout)

Microsoft surface bug requires a timeout in order for the cursor to show up in a focused text box. iPad also, sometimes, when embedded in an iframe, so set useTimeout if in an iframe!

Parameters:
Name Type Description
node object

A DOM element to focus

useTimeout number

Whether to apply a timeout or not. If number > 0, then the number of milliseconds.


formatEquation(equation)

Extracts symbols from an equation. An equation can consist of symbols and the following operators: +-/*%() PEMDAS order is followed. Additionally, symbols can be enclosed in brackets [] to treat them as literal non-parseables.

Parameters:
Name Type Description
equation string

The equation to parse (e.g., IBM+GE)

Version:
  • ChartIQ Advanced Package
Returns:

Parsed equation, {equation: [formatted equation], symbols: [array of symbols found in the equation]}

Type
object

friendlyDate(dt)

Converts a date into yyyy/mm/dd hh:mm format

Parameters:
Name Type Description
dt date

A JavaScript Date object

Returns:

Date in yyyy/mm/dd hh:mm format

Type
string

fromET(est)

Converts a JavaScript date from Eastern Time Zone to the browser's local time zone. Daylight Savings Time is hard coded. @see CIQ.getETDateTime

Parameters:
Name Type Description
est date

JavaScript Date object representing a date/time in eastern time zone

Returns:

JavaScript Date object converted to browser's local time zone

Type
date

get(path [, defaultValue])

Curried CIQ.getFromNS expecting the namespace to be CIQ.

Parameters:
Name Type Argument Description
path string

String in dot notation representing extension of the CIQ namespace to a desired property, method, or array.

defaultValue * <optional>

The value returned if the requested expression does not exist. If the requested expression is a function, set defaultValue to a function (usually function(){}) that can be run with any required arguments. If the requested expression is an array, set defaultValue to a default array, usually [].

Since:
  • 8.0.0

Returns:

The expression sought by combining the CIQ namespace and the path. If the expression does not exist, returns defaultValue (if provided), otherwise returns undefined.

Type
*
Example
// Accesses CIQ.Studies.studyLibrary.rsi if safe to do so (if exists).
CIQ.get("Studies.studyLibrary.rsi");
// Returns null if CIQ.Studies.studyLibrary.rsi does not exist.
CIQ.get("Studies.studyLibrary.rsi", null);

getActiveElement( [root])

Gets the active element, even within a shadow DOM.

Parameters:
Name Type Argument Default Description
root HTMLElement <optional>
document

Root element

Since:
  • 8.8.0

Returns:

The active element

Type
HTMLElement

getAjaxServer(url)

Returns an instance of XMLHttpRequest.

Parameters:
Name Type Description
url string

The URL to which the request is sent (not used).

Deprecated:
  • As of 8.0.0. Use new XMLHttpRequest().

Returns:

An XMLHttpRequest instance.

Type
object

getBackgroundColor(el)

Gets the background color of an element by traversing up the parent stack. This function will pierce shadow roots when traversing.

Parameters:
Name Type Description
el HTMLElement

The element to examine

Returns:

The background color

Type
string

getETDateTime()

Gets the current time in Eastern Time Zone. This can be used as a convenience for determining open and closing times of US markets.

Returns:

JavaScript Date representing the time in Eastern Time Zone

Type
date

getEventDOM( [e])

Gets the source element for a DOM event.

Parameters:
Name Type Argument Description
e object <optional>

The DOM event, if available from the browser. If an event is not provided, the window event is used.

Deprecated:
Returns:

The DOM node that registered the event.

Type
object

getFn(path [, defaultValue])

Curried CIQ.getFromNS expecting the namespace to be CIQ and a function to be returned.

Parameters:
Name Type Argument Description
path string

String in dot notation representing extension of the CIQ namespace to the desired function.

defaultValue * <optional>

The value returned if the requested function does not exist.

Since:
  • 8.0.0

Returns:

The function sought by combining the CIQ namespace and the path. If the function does not exist, returns function(){return defaultValue;}.

Type
function
Example
// Returns the function if safe to do so (if exists).
// Assigns "error" to the result if CIQ.Studies.removeStudy does not exist.
getFn("Studies.removeStudy", "error");

getFnFromNS(obj, path [, defaultValue])

Curried CIQ.getFromNS expecting a function to be returned if obj + path is not found.

Parameters:
Name Type Argument Description
obj object

Namespace to access.

path string

String in dot notation representing extension of the namespace to the desired function.

defaultValue * <optional>

The value returned if the requested function does not exist.

Since:
  • 8.0.0

Returns:

The function sought by combining the namespace and path. If the function does not exist, returns function(){return defaultValue;}.

Type
function
Example
// Invokes Math.Matrix.ScalarOperations.dotProduct with arguments (mA, mB) if safe to do so (if exists).
// Assigns NaN to the result if Math.Matrix.ScalarOperations.dotProduct does not exist.
let result=getFnFromNS(Math, "Matrix.ScalarOperations.dotProduct", NaN)(mA, mB);

getFromNS(namespace, path [, defaultValue])

Accesses a property, method, or array in a namespace.

Approximates optional chaining, checking whether the object at the end of namespace + path exists before returning it.

Parameters:
Name Type Argument Description
namespace object

Namespace to access.

path string

String in dot notation representing extension of the namespace to a desired property, method, or array.

defaultValue * <optional>

The value returned if the requested expression does not exist. If the requested expression is a function, set defaultValue to a function (usually function(){}) that can be run with any required arguments. If the requested expression is an array, set defaultValue to a default array, usually [].

Since:
  • 8.0.0

Returns:

The expression sought by combining the namespace and path. If the expression does not exist, returns defaultValue (if provided), otherwise returns undefined.

Type
*
Examples
// Accesses CIQ.Studies.studyLibrary.rsi if safe to do so (if exists).
CIQ.getFromNS(CIQ.Studies, "studyLibrary.rsi");
// or
CIQ.getFromNS(CIQ, "Studies.studyLibrary.rsi");
// Accesses Math.Matrix.ScalarOperations.dotProduct(mA, mB) if safe to do so (if exists).
// Returns 12 if Math.Matrix.ScalarOperations.dotProduct does not exist.
CIQ.getFromNS(Math, "Matrix.ScalarOperations.dotProduct", (a,b)=>a*b)(3, 4);

getHostName(url)

Returns the host portion of a URL.

Parameters:
Name Type Description
url string

The URL, such as document.location.href

Returns:

The host portion, including port, if the URL is a valid URI

Type
string

getLines(ctx, phrase, l)

Turns a portion of raw text into multi-line text that fits in a given width. This is used for autoformatting of annotations

Parameters:
Name Type Description
ctx object

A valid HTML Canvas Context

phrase string

The text

l number

The width in pixels to fit the text within on the canvas

Returns:

An array of individual lines that should fit within the specified width

Type
array

getMaxRenkoBarsPerRecord( [symbol])

Gets the maximum number of Renko bars that can be created per quote when using automatic brick size selection.

This method is used to adjust auto Renko brick size if the default algorithm set it too low, resulting in too many bars.

Override this function to adjust the return value based on the expected data set per symbol, thereby avoiding very long processing time due to small brick size selection.

Parameters:
Name Type Argument Description
symbol string | object <optional>

Chart symbol for which to return the maximum number of Renko bars per quote. If not provided, a default maximum value is returned.

Since:
  • 8.3.0

Returns:

The maximum number of Renko bars per quote.

Type
number

getObjectChainRoot(chain)

Return root of arrow notation string (field-->property)

Parameters:
Name Type Description
chain string

Arrow notation string.

Since:
  • 8.4.0

Returns:

Base object in string

Type
string
Example
var root=CIQ.getObjectChainRoot("ABC.D-->Low");
root==="ABC.D"

getYearDay( [dt])

Gets the day of the year

Parameters:
Name Type Argument Description
dt date <optional>

optional The date to check. If omitted, will use the current date.

Returns:

Day of year

Type
number

guaranteedSize(element)

Returns a guaranteed width and height. For instance, cq-context or any other wrapping tag can have a width of zero; if so, we need to go up the ancestry tree parent by parent until a parent element provides an actual width and height.

Parameters:
Name Type Description
element Element

The starting element for which the width and height are obtained.

Since:
  • 8.1.0

Returns:

Width and height of element as properties of the returned object.

Type
object

hasClassName(node, className)

Determines whether a class name is currently assigned to a DOM element.

Parameters:
Name Type Description
node object

The DOM node checked for the presence of the class name.

className string

The class name for which to check.

Deprecated:
Returns:

True, if the class name is currently assigned to the DOM element; otherwise, false.

Type
boolean

hexToRgba(color [, opacity])

Converts six-digit hexadecimal color numbers and RGB and RGBA color values to RGBA color values.

Parameters:
Name Type Argument Default Description
color string

A six-digit hexadecimal color number or RGB or RGBA color value; for example, "#FF00FF", "#ff00ff", "rgb(255,0,255)", or "rgba(255,0,255,0.5)".

If the argument is an RGB or RGBA color, the RGB color values remain the same, but the opacity is set to opacity. If the opacity parameter is not provided, an RGB color is given the default opacity; an RGBA color is returned unchanged. See examples below.

Note: Three-digit hexadecimal color numbers and CSS color keywords are not accepted.

opacity number <optional>
1

The alpha value of the color. Values must be greater than or equal to 0. Values greater than 1 are divided by 100.

Returns:

An RGBA color value.

Type
string
Example
console.log(CIQ.hexToRgba("#FF00FF")); // rgba(255,0,255,1)
console.log(CIQ.hexToRgba("#FF00FF", 0.75)); // rgba(255,0,255,0.75)
console.log(CIQ.hexToRgba("#FF00FF", 2)); // rgba(255,0,255,0.02)
console.log(CIQ.hexToRgba("rgb(255,0,255)")); // rgba(255,0,255,1)
console.log(CIQ.hexToRgba("rgb(255,0,255)", 0.75)); // rgba(255,0,255,0.75)
console.log(CIQ.hexToRgba("rgba(255,0,255,0.5)", 0.75)); // rgba(255,0,255,0.75)
console.log(CIQ.hexToRgba("rgba(255,0,255,0.5)")); // rgba(255,0,255,0.5)
console.log(CIQ.hexToRgba("#F0F")); // CIQ.hexToRgba: invalid hex : F0F
console.log(CIQ.hexToRgba("fuchsia")); // CIQ.hexToRgba: invalid hex : fuchsia

hhmm(dt)

Converts a JavaScript Date object to hh:mm format.

Parameters:
Name Type Description
dt date

Date object to be converted.

Since:
  • 8.0.0

Returns:

Time of the converted Date object in hh:mm format.

Type
string

hhmmss(dt)

Converts a JavaScript Date to hh:mm:ss format

Parameters:
Name Type Description
dt date

JavaScript Date object

Since:
  • 6.3.0

Returns:

Time in hh:mm:ss format

Type
string

hideByText(startNode, text)

Hide nodes that match a certain text string.

Parameters:
Name Type Description
startNode object

A valid DOM element from which to start looking

text string

The text to match against CIQ.findNodesByText


hideKeyboard( [newFocus])

Closes the keyboard on a touch device by blurring any active input elements.

Parameters:
Name Type Argument Description
newFocus HTMLElement <optional>

Element to change focus to


hslToRgb(h, s, l)

Converts an HSL color value to RGB. The conversion formula is adapted from http://en.wikipedia.org/wiki/HSL_color_space.

Assumes the values for h, s, and l are contained in the set [0, 1] and the returned RGB values are in the set [0, 255].

Parameters:
Name Type Description
h number

Hue

s number

Saturation

l number

Lightness

Since:
  • 7.5.0

Returns:

The RGB representation of the color.

Type
array

hsv(color)

Converts a color from hex or rgb format to Hue, Saturation, Value.

Parameters:
Name Type Description
color string

The color (from CSS)

Returns:

[Hue, Saturation, Value], or null if invalid color.

Type
array

inheritsFrom(me, ctor [, autosuper])

Creates a template for JavaScript inheritance.

By default the constructor (ctor) is called with no arguments.

Parameters:
Name Type Argument Default Description
me object

The object to receive the inheritance.

ctor object

The parent class or object.

autosuper boolean <optional>
true

Set to false to prevent the base class constructor from being called automatically.

Since:
  • 7.4.0 Replaces Function#ciqInheritsFrom.


innerHTML(node, html)

Microsoft RT disallows innerHTML that contains DOM elements. Use this method to override when necessary.

Parameters:
Name Type Description
node object

A valid DOM element to change innerHTML

html string

The html text to change

Example
CIQ.innerHTML(node, "My innerHTML contains <span>a span</span> and MS RT doesn't like that");

inputKeyEvents(node, cb)

Captures enter key events. Also clears the input box on escape key.

Parameters:
Name Type Description
node object

The DOM element to attach the event to. Should be a text input box.

cb function

Callback function when enter key is pressed.


installTapEvent(div [, params])

Converts an object to emit "stxtap" events. This uses CIQ.safeClickTouch. You should use addEventListener("tap") to receive the events.

Parameters:
Name Type Argument Description
div HTMLElement

The element to convert

params object <optional>

Parameters to pass to CIQ.safeClickTouch

Properties
Name Type Argument Default Description
stopPropagation boolean <optional>
false

If set to true then propagation will be stopped

Since:
  • 04-2015


intersectLineLineX(ax1, ax2, ay1, ay2, bx1, bx2, by1, by2)

Get the X intersection point between two lines

Parameters:
Name Type Description
ax1 number

Initial x coordinate start point of the first box.

ax2 number

Final x coordinate end point of the first box.

ay1 number

Initial y coordinate start point of the first box.

ay2 number

Final y coordinate end point of the fist box.

bx1 number

Initial x coordinate start point of the second box.

bx2 number

Final x coordinate end point of the second box.

by1 number

Initial y coordinate start point of the second box.

by2 number

Final y coordinate end point of the second box.


intersectLineLineY(ax1, ax2, ay1, ay2, bx1, bx2, by1, by2)

Get the Y intersection point between two lines

Parameters:
Name Type Description
ax1 number

Initial x coordinate start point of the first box.

ax2 number

Final x coordinate end point of the first box.

ay1 number

Initial y coordinate start point of the first box.

ay2 number

Final y coordinate end point of the fist box.

bx1 number

Initial x coordinate start point of the second box.

bx2 number

Final x coordinate end point of the second box.

by1 number

Initial y coordinate start point of the second box.

by2 number

Final y coordinate end point of the second box.


isDST( [dt])

Determines whether the input date is during daylight saving time (DST).

Parameters:
Name Type Argument Description
dt date <optional>

The date to check. If the parameter is omitted, the current date is used.

Deprecated:
  • As of 8.0.0. This function may return inaccurate results for some countries.

Returns:

True for DST, otherwise false.

Type
boolean

isEmpty(o)

Returns true if an object has no members

Parameters:
Name Type Description
o object

A JavaScript object

Returns:

True if there are no members in the object

Type
boolean

isSubsetOf(a, b)

Returns true if whatever is in object b is also in object a.

Parameters:
Name Type Description
a object

First object

b object

Second object

Since:
  • 9.1.0

Returns:

True if object a contains object b

Type
boolean

isTransparent(color)

Returns true if the color is transparent. In particular, it checks RGBA status. Note that the charting engine often interprets transparent colors to mean that a color should be automatically determined based on the brightness of the background.

Parameters:
Name Type Description
color string

The color (from CSS)

Returns:

True if transparent

Type
boolean

isValidNumber(n)

Convenience function to determine if a value is a valid number.

Parameters:
Name Type Description
n number

The number to check

Since:
  • 5.2.2

Returns:

True if n is a real finite number. NaN, Infinity, null, undefined, etc are not considered to be a valid number.

Type
boolean

last(o)

Convenience function for returning the last property in an object. Note that while this works in all known browsers the EMCA spec does not guarantee that the order of members in an object remain static. This method should therefore be avoiding. When ordering is important use an Array!

Parameters:
Name Type Description
o object

A JavaScript object

Returns:

The final member of the object or null if the object is empty

Type
object

linesIntersect(x1, x2, y1, y2, x3, x4, y3, y4, type)

Determines whether two lines intersect

Parameters:
Name Type Description
x1 number
x2 number
y1 number
y2 number
x3 number
x4 number
y3 number
y4 number
type string

Either "segment", "ray" or "line"

Returns:

Returns true if the two lines intersect

Type
boolean

loadScript(scriptName [, cb] [, isModule] [, doc])

Loads JavaScript dynamically. Keeps a static memory of scripts that have been loaded to prevent them from being loaded twice. The callback function however is always called, even if the script has already been loaded.

Parameters:
Name Type Argument Description
scriptName string

The URL of the script to load.

cb function <optional>

Callback function to call when the script is loaded.

isModule boolean <optional>

If true, the script loads a module.

doc Document <optional>

document to attach script to.

Since:
  • 8.0.0 Added the isModule parameter.
  • 8.5.0 Added the doc parameter.

loadStylesheet(stylesheet, cb [, doc])

Loads a stylesheet.

Parameters:
Name Type Argument Description
stylesheet string

Name of stylesheet file.

cb function

Function to call when the stylesheet is fully loaded

doc Document <optional>

document to attach stylesheet to.

Since:
  • 2016-03-11
  • 8.5.0 Added the doc parameter.

loadUI(url, el, cb)

Dynamically load UI elements from an external HTML file. This is accomplished by rendering raw HTML in an iframe and then cloning all of the newly created DOM elements into our main document. Repeated requests for the same resource load data from the existing iframe.

The title of the iframe is checked. External content should not have a title. By convention, 404 and 500 errors have a title. And so, we can determine whether the iframe contains valid content.

Parameters:
Name Type Description
url string

The external URL from which new UI content is fetched.

el HTMLElement

Element to which the UI content is appended. The default is document.body.

cb function

A callback function to call when the new UI is available.

Since:
  • 6.1.0 Added the el parameter.
  • 7.2.0 Added caching per application instance by reusing the iframe contents.

loadWidget(widget, el, cb, isModule)

Loads a feature function widget. Feature function widgets consist of a CSS file, a JavaScript file, and an HTML file.

Use this function to dynamically load content and functionality.

Parameters:
Name Type Description
widget string

Name of the widget to load. The widget's JavaScript, CSS, and HTML files should have this name.

el HTMLElement

Element to which to append the UI content. The default is document.body.

cb function

Function to call when the widget is fully loaded.

isModule boolean

When true, the script loads a module.

Since:
  • 6.1.0 Added the el parameter.
  • 8.0.0 Added the isModule parameter.

localStorageSetItem(name, value)

Convenience function for storing a name/value pair in local storage. Detects whether private browsing is enabled since local storage is inoperable under private browsing.

Parameters:
Name Type Description
name string

The name for the stored item.

value string

The value for the stored item.


log10(y)

Returns the log base 10 of a value

Parameters:
Name Type Description
y number

The value

Returns:

log10 value

Type
number

logPackageInfo()

Output complete chart library package information stored in CIQ.packageInfo to the browser console.

This function is called from the cq-lookup UI component when the value "ciqinfo" is entered.

Since:
  • 8.6.0


logVersion()

Output the chart library version to the browser console. This is called automatically when loadChart is called. In a multi-chart environment, it will only display for the first chart.

Since:
  • 8.6.0


makeCamelCase(name)

Converts from hyphenated to camel case. Used primarily for converting css style names (which are hyphenated) to property values (which are camel case)

Parameters:
Name Type Description
name string

Hyphenated style name

Returns:

Camel case style name

Type
string

makeTranslatableElement(element, stx, original [, language])

Converts a node to one which will translate its inner text when another language is chosen. If there is no translationCallback, the node will not be translatable.

Parameters:
Name Type Argument Description
element HTMLElement

The element to convert

stx CIQ.ChartEngine

The chart object

original string

The untranslated text

language string <optional>

Language. Defaults to CIQ.I18N.language.

Since:
  • 8.8.0


metricsClient(enable)

Enables or disables the usage metrics client. Sets CIQ.logMetrics.

Parameters:
Name Type Description
enable boolean

A boolean that sets the current state of the metrics server client

Since:
  • 8.8.0

Returns:
  • config The metrics client config object

    Type
    object
  • config.clientId The client's uuid

    Type
    string
  • config.url The URL of the server to which all logging requests are sent

    Type
    string

minMax(series, field, subField, highLow)

This method will return a tuple [min,max] that contains the minimum and maximum values in the series where values are series[field].

Parameters:
Name Type Description
series array

The series

field string

The name of the series to look at

subField string

The name of the field within the series to look at

highLow boolean

True when comparing max High/min Low vs a specific field

Since:
  • 5.1.0 Added subField, highLow arguments

Returns:

Tuple containing min and max values in the series

Type
array

mmddhhmm(strdt)

Converts a string form date into mm-dd hh:mm format

Parameters:
Name Type Description
strdt string

Date in string format (such as yyyymmddhhmm, yyyy-mm-dd hh:mm, etc)

Since:
  • 5.0.0 will output seconds and millis if present

Returns:

Date in mm-dd hh:mm format

Type
string

mmddyyyy(dt)

Converts a JavaScript Date or string form date to mm/dd/yyyy format

Parameters:
Name Type Description
dt string

Date in JavaScript Date or string format such as YYYY-MM-DD

Since:
  • 2016-07-16

Returns:

Date in mm/dd/yyyy format

Type
string

money(val [, decimals] [, currency])

Prints out a number in US Dollar monetary representation

Parameters:
Name Type Argument Default Description
val number

The amount

decimals number <optional>
2

Number of decimal places.

currency string <optional>

Currency designation. If omitted, will use $.

Returns:

US Dollar monetary representation // Returns $100.00 CIQ.money(100, 2);

Type
string

monthAsDisplay(i, displayLetters [, stx])

Convenience function for creating a displayable month name using CIQ.monthLetters and CIQ.monthAbv. Please note that those arrays may not be utilized if the library is used in conjunction with Internationalization. This method is used primarily to create the x-axis of a chart

Parameters:
Name Type Argument Description
i number

The numerical month (0-11)

displayLetters boolean

True if just the first letter should be displayed (such as a tight display)

stx object <optional>

The chart object, only necessary if Internationalization is in use

Returns:

String representation of the month

Type
string

newChild(div, tagName [, className] [, txt])

Convenience function for dynamically creating a new node and appending it into the DOM.

Parameters:
Name Type Argument Description
div object

The targeted parent node

tagName string

The type of node to be created

className string <optional>

Optional class name to set the new node

txt string <optional>

Optional text to insert

Returns:

The new node

Type
object

noop(params)

Displays floating text label, without any background shapes, over the y-axis.

Calls CIQ.createLabel; which can be customized to control the text format for these labels. Will draw text in the color normally used for the background shape. For example, 'green' text for the up tick and 'red' text for a down tick.

Visual Reference:
noop

Parameters:
Name Type Description
params object
Properties
Name Type Description
ctx object

A valid HTML Canvas Context.

x number

Left position of drawing on canvas.

txt number

Text for the label.

y number

Vertical position of drawing on canvas.

margin object

Margin around the text.

Properties
Name Type Description
left object

Left margin of text.

top object

Top margin of text.

backgroundColor number

Text color; since there is no background shape.

Since:
  • 3.0.0 Function signature changed. This function now takes a params object instead of eight different parameters.
  • 5.2.1 Will now draw text in the color normally used for the background shape. For example, 'green' text for the up tick and 'red' text for a down tick.

objLength(o)

Returns the number of members in an object

Parameters:
Name Type Description
o object

A valid JavaScript object

Returns:

The number of members in the object

Type
number

outerWidth(node)

Deprecated since 8.1.0. Use CIQ.elementDimensions instead.

Measures the width of a DOM element, including left and right margins.

Parameters:
Name Type Description
node HTMLElement

The DOM element for which the width is measured.

Since:
  • 8.1.0 Deprecated.

Deprecated:
  • Use CIQ.elementDimensions; for example, CIQ.elementDimensions(node, {margin:1, padding:1, border:1}).width.

Returns:

The width of the DOM element, including margins.

Type
number

pageHeight( [win])

Returns the height of the page. It is aware of iframes and so will never return a value that is greater than the value of the parent

Parameters:
Name Type Argument Description
win Window <optional>

Optional top level window, if not the main window where library is loaded

Since:
  • 8.5.0 Added win parameter.

Returns:

Height of page in pixels

Type
number

pageWidth( [win])

Returns the width of the page. It is aware of iframes and so will never return a value that is greater than the value of the parent

Parameters:
Name Type Argument Description
win Window <optional>

Optional top level window, if not the main window where library is loaded

Since:
  • 8.5.0 Added win parameter.

Returns:

Width of page in pixels

Type
number

postAjax(params, arg1, arg2, arg3, arg4)

Convenience function for making an ajax post. If payload is non-null then the method will be set to POST, otherwise GET.

Parameters:
Name Type Description
params object

Parameters for the post

Properties
Name Type Argument Description
url string <optional>

The url to send the ajax query to

payload string <optional>

An optional payload to send

cb CIQ.postAjax~requestCallback <optional>

Callback function when complete

contentType string <optional>

Optionally override the content type

noEpoch boolean <optional>

By default, the epoch is appended as a query string to bust caching. Set this to false to not append the epoch.

method string <optional>

Optionally override the HTTP method

headers object <optional>

Optional additional HTTP headers to send. Example: {"x-custom-header-1":"abc","x-custom-header-2":"123"}

responseHeaders boolean <optional>

Optional Set to true to have callback passed the response headers from the server

timeout number <optional>

Optional Request timeout in msec. If omitted, timeout is default (no timeout)

ungovernable boolean <optional>

Optional If true, request not subject to rate limiting

arg1 string

Payload

arg2 function

Callback

arg3 string

Ajax content type

arg4 boolean

Set to true for no epoch

Since:
  • 3.0.0 Added timeout and ungovernable parameters.

Returns:

True if there were no errors fetching data.

Type
boolean

prepareChannelFill(stx, parameters)

Fills an area on the chart delimited by non-intersecting top and bottom bands (channel), usually created by a study.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

parameters object

The configuration parameters

Properties
Name Type Description
panelName string

The name of the panel

noSlopes boolean

If set, then the chart will fill rectangles with no transition lines between levels

topBand string

The name of the quote field to use as the top band

bottomBand string

The name of the quote field to use as the bottom band

opacity number

The color opacity/transparency as a decimal number (1= full opacity / no transparency)

color string

The fill color

Since:
  • 4.1.2 Removed quotes argument; function always uses chart.dataSegment.

Example
CIQ.prepareChannelFill(stx,{"color":dngradient,"opacity":1,"panelName":sd.name,"topBand":"Zero "+sd.name,"bottomBand":"Under "+sd.name});

preparePeakValleyFill(stx, parameters)

Fills an area on the chart delimited by a series line closed off by a horizontal threshold line, usually created by a study.

Visual Reference:
Elder Force Shading

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object

parameters object

The configuration parameters

Properties
Name Type Argument Description
panelName string <optional>

The name of the panel

band string <optional>

The name of the quote field to use as the series line

threshold number <optional>

The price where the horizontal line hits yaxis/series to enclose the fill area. If not set will look to parameters.reverse to determine if threshold is the lowest or highest value of the plot.

reverse boolean <optional>

Valid only if parameters.threshold is not set. If this parameter is set to true, threshold will be highest value of plot. Otherwise, threshold will be lowest value of plot.

direction number <optional>

1 to fill from the threshold upwards or -1 to fill from the threshold downwards

edgeHighlight object <optional>

Set to either a color or a Styles object as returned from CIQ.ChartEngine#canvasStyle to draw the threshold line.

edgeParameters object <optional>

The parameters to draw the threshold line as required by CIQ.ChartEngine#plotLine

gapDisplayStyle object | boolean | string <optional>

Gap object as set by See CIQ.ChartEngine#setGapLines.

opacity number <optional>

The color opacity/transparency as a decimal number (1= full opacity / no transparency). Default is 0.3.

step boolean <optional>

True for a step chart

tension number <optional>

Tension for splining.

color string <optional>

The fill color

roundOffEdges boolean <optional>

Round the first and last point's X value to the previous and next integer, respectively.

yAxis CIQ.ChartEngine.YAxis <optional>

The y-axis for the band (will use default axis if not specified)

Since:
  • 4.0.0 Added parameters.reverse, made parameters.threshold optional in case filling to top or bottom of panel.
  • 4.1.2 Removed quotes argument; function always uses chart.dataSegment.
  • 5.2.0 Added params.yAxis.
  • 5.2.0 Deprecated parameters.gaps and replaced with parameters.gapDisplayStyle.
Examples
if(sd.outputs.Gain) CIQ.preparePeakValleyFill(stx,{panelName:sd.panel, band:"Result " + sd.name, threshold:sd.study.centerline, direction:1, color:sd.outputs.Gain});
if(sd.outputs.Loss) CIQ.preparePeakValleyFill(stx,{panelName:sd.panel, band:"Result " + sd.name, threshold:sd.study.centerline, direction:-1, color:sd.outputs.Loss});
// see visual reference for rendering image
	CIQ.Studies.displayElderForce=function(stx, sd, quotes){
		CIQ.Studies.displaySeriesAsLine(stx, sd, quotes);
		var color=CIQ.Studies.determineColor(sd.outputs.Result);
		var panel=stx.panels[sd.panel];
		var yAxis=sd.getYAxis(stx);
		var params={skipTransform:panel.name!=sd.chart.name, panelName:sd.panel, band:"Result " + sd.name, threshold:0, color:color, yAxis:yAxis};
		params.direction=1;
		CIQ.preparePeakValleyFill(stx,params);
		params.direction=-1;
		CIQ.preparePeakValleyFill(stx,params);
	};

qs( [query])

A parsed query string object Does not support using multi-value keys (i.e. "a=1&a=2")

Parameters:
Name Type Argument Description
query string <optional>

Query string. If not provided, then the browser location's query string will be used

Returns:

An object containing the parsed values of the query string

Type
object

random()

Cryptographically safe replacement for Math.random Will fallback to Math.random in any enviroment that does not support crypto.getRandomValues

Since:
  • 8.7.0

Returns:

number Random number

Type
number

readablePeriodicity(stx)

Creates a string with a periodicity that is easy to read given a chart

Parameters:
Name Type Description
stx CIQ.ChartEngine

A chart object

Returns:

A periodicity value that can be displayed to an end user

Type
string

rect(params)

Displays a floating label over the y-axis.

Draws a rectangle on the canvas using CIQ.roundRect with a radius of 0 It then calls CIQ.createLabel to print the text over this background shape; which can be customized to control the text format for these labels.

Visual Reference:
rect

Parameters:
Name Type Description
params object
Properties
Name Type Argument Description
ctx object

A valid HTML Canvas Context

x number

Left position of drawing on canvas

top number

Top position of drawing on canvas

width number

Width of rectangle

height number

Height of rectangle

fill boolean <optional>

Whether to fill the background, or just draw the rectangle border.

txt number <optional>

Text for the label

y number <optional>

Y position of drawing on canvas

margin object <optional>

Margin around the text

Properties
Name Type Argument Description
left object <optional>

Left margin of text

top object <optional>

Top margin of text

backgroundColor number <optional>

Background color. This is the background color of the rectangle.

color number <optional>

Text color

Since:
  • 3.0.0 Function signature changed. This function now takes a params object instead of eight different parameters.


removeChildIfNot(node [, selector])

Removes from node all children that do not match selector. Removes all children if no selector is provided.

Parameters:
Name Type Argument Description
node HTMLElement

Parent node from which child nodes are removed.

selector string <optional>

CSS selector used to select child nodes that are not removed from node.

Since:
  • 8.1.0

Returns:

node, containing only those children selected by selector; all other children removed.

Type
HTMLElement

removeNullValues(obj)

Returns an object copy with any null values removed

Parameters:
Name Type Description
obj object

Object to remove nulls

Returns:

Object with nulls removed

Type
object

removeResizeListener(element, callback)

Removes an attached resize event listener from a DOM element.

Designed to be used as a helper method for the included WebComponents. A full tutorial on how to work with and customize the Web Components can be found here: Web Component Interface.

Parameters:
Name Type Description
element node

The node from which the listener is removed.

callback function

The listener function to be removed.

Deprecated:

replaceFields(obj, mapping)

This method will iterate through the object and replace all of the fields using the mapping object. This would generally be used to compress an object for serialization. so that for instance "lineWidth" becomes "lw". This method is called recursively.

Parameters:
Name Type Description
obj object

Object to compress

mapping object

Object containing name value pairs. Each name will be replaced with its corresponding value in the object.

Returns:

The newly compressed object

Type
object

resizeObserver(element, listener [, resizeHandle] [, interval])

Creates a ResizeObserver to listen for resize changes on the specified element and execute the specified listener function.

Under certain conditions an interval check will be used instead. These are:

  • if a positive interval value has been specified in the function call arguments
  • if CIQ.resizeDetectInterval has been set to a positive number
  • if the ResizeObserver API is not available
Parameters:
Name Type Argument Description
element HTMLElement

The element to observe for resizing.

listener function | null

The function to be executed on a resize event.

resizeHandle object | number | null <optional>

A handle to the resizer, which is null the first time the function is called, or is the return value of the function for subsequent calls. Can be a ResizeObserver.

interval number <optional>

Optionally specify an interval to use for checking instead of a ResizeObserver. Set this value to 0 to turn off the observer. Defaults to 0 if listener is null and resizeHandle is available.

Since:
  • 7.4.0
  • 8.6.0 An interval will be used instead of a ResizeObserver if either the interval param or the CIQ.resizeDetectInterval is positive.
Returns:

A handle to the resizer, which can be passed again to the function to disable or reset the handle.

Type
object

reverseObject(obj)

This method reverses the fields and values in an object

Parameters:
Name Type Description
obj object

Object to reverse

Returns:

The reversed object

Type
object
Example
reverseObject({ one: "a", two: "b" }) // returns { a: "one", b: "two" }

round(number, decimals)

Convenience function to round a floating-point number.

This has better decimal accuracy than:

  • number.toFixed(decimals)
  • Math.round(number*decimals)/decimals
Parameters:
Name Type Description
number number

The number to round

decimals number

The number of decimal places

Since:
  • 7.0.0

Returns:

Rounded number

Type
number

roundRect(params [, edge])

Displays a floating label over the y-axis.

Draws a rectangle, with curved corners, on the canvas. It then calls CIQ.createLabel to print the text over this background shape; which can be customized to control the text format for these labels.

Visual Reference:
roundRect

Parameters:
Name Type Argument Description
params object
Properties
Name Type Argument Description
ctx object

A valid HTML Canvas Context

x number

Left position of drawing on canvas

top number

Top position of drawing on canvas

width number

Width of rectangle

height number

Height of rectangle

radius number

Radius of rounding

fill boolean <optional>

Whether to fill the background, or just draw the rectangle border.

txt number <optional>

Text for the label

y number <optional>

Y position of drawing on canvas

margin object <optional>

Margin around the text

Properties
Name Type Argument Description
left object <optional>

Left margin of text

top object <optional>

Top margin of text

backgroundColor number <optional>

background color. This is the background color of the rectangle.

color number <optional>

Text color

edge string <optional>

"flush","arrow"

Since:
  • 3.0.0 Function signature changed. This function now takes a params object and the drawing type instead of eight different parameters. Also, this function will draw the label if params.txt is present, otherwise just the floating label outline will be drawn.


roundRectArrow(params)

Displays a floating label over the y-axis.

Draws a rectangle on the canvas, with an arrowhead on the screen, using CIQ.roundRect with an edge setting of "arrow". It then calls CIQ.createLabel to print the text over this background shape; which can be customized to control the text format for these labels.

Visual Reference:
roundRectArrow

Parameters:
Name Type Description
params object
Properties
Name Type Argument Description
ctx object

A valid HTML Canvas Context

x number

Left position of drawing on canvas

top number

Top position of drawing on canvas

width number

Width of rectangle

height number

Height of rectangle

radius number

Radius of rounding

fill boolean <optional>

Whether to fill the background, or just draw the rectangle border.

txt number <optional>

Text for the label

y number <optional>

Y position of drawing on canvas

margin object <optional>

Margin around the text

Properties
Name Type Argument Description
left object <optional>

Left margin of text

top object <optional>

Top margin of text

backgroundColor number <optional>

Background color. This is the background color of the rectangle.

color number <optional>

Text color

Since:
  • 3.0.0 Function signature changed. This function now takes a params object instead of eight different parameters.


safeClickTouch(div, fc, params)

Use this instead of onclick or ontouch events. This function will automatically use the quickest available but also protect against being called twice. By default, any previous safeClickTouch listeners will be cleared (to allow re-use of the element).

Parameters:
Name Type Description
div object

The DOM element to attach an event.

fc function

The function to call when the object is pressed.

params object

Parameters to drive behavior.

Properties
Name Type Argument Default Description
safety object <optional>

An object generated from a CIQ.safeDrag association to prevent the click from being triggered when a drag operation is released.

allowMultiple boolean <optional>
false

If set, then multiple click events can be associated with the node.

preventUnderlayClick boolean <optional>
true

By default, prevents an underlying element from being "clicked" on a touch device 400ms after the overlay was tapped. Set to false for input fields or any div containing input fields (body).

absorbDownEvent boolean <optional>
true

Ensures that a mousedown, pointerdown, or touchstart event doesn't get passed to the parent.

preventClickEvent boolean <optional>
false

Prevents "click" event from firing. Potentially useful when bubbling events emanated from screen readers.

keyboardClick boolean <optional>
false

Sets a keyup listener to dispatch a click event when "Space" or "Enter" are pressed.

Since:
  • 11/01/2015 Removed timers in favor of a new algorithm. This algorithm allows only the first event to fire from a UI interaction to execute the fc function.
  • 8.8.3 Added params.preventClickEvent parameter.
  • 9.2.0 Added params.keyboardClick parameter,

safeDrag(div [, eventHandlers])

Safe function to handle dragging of objects on the screen.

This method is cross-device aware and can handle mouse or touch drags. This method does not actually move the objects but provides callbacks that explain when drag operations begin and cease, and what movements are made during the drag. Callbacks should be used to move the actual objects (if it is desired to move objects during a drag operation). For convenience, displacementX and displacementY are added to callback events to indicate the distance from the original starting point of the drag. A "safety" object is returned which can optionally be passed into CIQ.safeClickTouch to prevent errant click events from being triggered when a user lets go of a drag

Parameters:
Name Type Argument Description
div object

The draggable DOM element

eventHandlers object <optional>
Properties
Name Type Argument Description
down function <optional>

Callback function when a drag operation begins. Receives an event object.

move function <optional>

Callback function when a drag move occurs. Receives an event object.

up function <optional>

Callback function when the drag operation ends. Receives an event object.

Since:
  • 7.0.0 change function signature to accept eventHandlers object instead of three function arguments
  • 9.0.0 require 300ms delay between down and up events before allowing dragging
Returns:

Safety object which can be passed to CIQ.safeClickTouch

Type
object

safeMouseOut(node, fc)

Used in conjunction, safeMouseOut and safeMouseOver ensure just a single event when the mouse moves in or out of an element. This is important because simple mouseout events will fire when the mouse crosses boundaries within an element. Note that this function will do nothing on a touch device where mouseout is not a valid operation.

Parameters:
Name Type Description
node object

A valid DOM element

fc function

Function to call when the mouse has moved out


safeMouseOver(node, fc)

This method is guaranteed to only be called once when a user mouses over an object. @see CIQ.safeMouseOut

Parameters:
Name Type Description
node object

A valid DOM element

fc function

Function to call when mouse moves over the object


scrub(obj [, removeNulls])

Deletes (removes) nulls or undefined fields (names) from an object. This is useful when marshalling (saving) an object where you don't wish null or undefined values to show up in the marshalled object (such as when converting to JSON)

Parameters:
Name Type Argument Description
obj object

The object to scrub

removeNulls boolean <optional>

Whether or not to remove null values


semiRoundRect(params)

Displays a floating label over the y-axis.

Draws a rectangle on the canvas, with just the right side curved corners, using CIQ.roundRect with an edge setting of "flush". It then calls CIQ.createLabel to print the text over this background shape; which can be customized to control the text format for these labels.

Visual Reference:
semiRoundRect

Parameters:
Name Type Description
params object
Properties
Name Type Argument Description
ctx object

A valid HTML Canvas Context

x number

Left position of drawing on canvas

top number

Top position of drawing on canvas

width number

Width of rectangle

height number

Height of rectangle

radius number

Radius of rounding

fill boolean <optional>

Whether to fill the background, or just draw the rectangle border.

txt number <optional>

Text for the label

y number <optional>

Y position of drawing on canvas

margin object <optional>

Margin around the text

Properties
Name Type Argument Description
left object <optional>

Left margin of text

top object <optional>

Top margin of text

backgroundColor number <optional>

Background color. This is the background color of the rectangle.

color number <optional>

Text color

Since:
  • 3.0.0 Function signature changed. This function now takes a params object instead of eight different parameters.


setCaretPosition(ctrl, pos)

Sets the position of the cursor within a textarea box. This is used for instance to position the cursor at the end of the text that is in a textarea.

Parameters:
Name Type Description
ctrl object

A valid textarea DOM element

pos number

The position in the text area to position


setValueIfNotActive(el, value)

Sets the value of an input box only if it is not active. This prevents an input box from changing underneath a user, which can be extremely frustrating on touch devices.

Parameters:
Name Type Description
el HTMLElement

The input element

value string

The value to set


shallowClone(from)

Non recursive clone. This will only clone the top layer and is safe to use when objects contain DOM nodes.

Parameters:
Name Type Description
from object

Object to be cloned

Returns:

A shallow clone of the "from" object

Type
object

smartHover( [doc])

Adds or removes hover classes. This function will manage the hovers so they won't trigger when touching. adapted from http://www.javascriptkit.com/dhtmltutors/sticky-hover-issue-solutions.shtml We are relying on touchend being called before mouseover

Parameters:
Name Type Argument Description
doc Document <optional>

document to interact with

Since:
  • 6.3.0
  • 8.5.0 Added optional doc parameter.

standardUTCDate(dt)

Converts a date to YYYY-MM-DDTHH:MM:SSZ format (UTC).

Parameters:
Name Type Description
dt date

The JavaScript Date object to be converted.

Deprecated:
Returns:

The date in YYYY-MM-DDTHH:MM:SSZ format.

Type
string

strToDate(dt)

Converts a string form date into a JavaScript object. Only use if you know that the string will not include a time, otherwise use @see CIQ.strToDateTime

Parameters:
Name Type Description
dt string

Date in string format such as MM/DD/YY or YYYYMMDD or 2014-10-25T00:00:00+00:00 or 201506170635

Returns:

JavaScript date object -new Date()-

Type
date

strToDateTime(dt)

Converts a string form date into a JavaScript Date object with time. Supports various standard date formats

Parameters:
Name Type Description
dt string

String form of a date (such as yyyymmddhhmm, yyyy-mm-dd hh:mm, etc)

Returns:

A JavaScript Date object

Type
date

stripPX(text)

Strips the letters "px" from a string. This is useful for converting styles into absolutes.

Parameters:
Name Type Description
text string

String value with "px"

Returns:

The numeric value

Type
number
Example
var leftPosition=CIQ.stripPX(node2.style.left)

swapClassName(node, newClassName, oldClassName)

Convenience method for swapping two class names on a DOM node. Typically used to change state.

Parameters:
Name Type Description
node object

The DOM element on which the class names are swapped.

newClassName string

The class name to swap in.

oldClassName string

The class name to swap out.

Deprecated:

symbolEqual(left, right)

Returns true if two symbols match. Symbols can be strings or symbolObjects. By default, the "symbol" member is compared, and then a "source" member if one exists. If the objects have an "equals()" function member then that will be used for comparison. You can override this with your own method if you have other requirements.

Parameters:
Name Type Description
left object

Symbol object

right object

Symbol object

Returns:

true if the same

Type
boolean

tickedRect(params)

Displays a floating label over the y-axis.

Draws a 'ticked' rectangle on the canvas, using CIQ.roundRect. It then calls CIQ.createLabel to print the text over this background shape; which can be customized to control the text format for these labels.

Visual Reference:
tickedRect

Parameters:
Name Type Description
params object
Properties
Name Type Argument Description
ctx object

A valid HTML Canvas Context

x number

Left position of drawing on canvas

top number

Top position of drawing on canvas

width number

Width of rectangle

height number

Height of rectangle

radius number

Radius of rounding

fill boolean <optional>

Whether to fill the background, or just draw the rectangle border.

txt number <optional>

Text for the label

y number <optional>

Y position of drawing on canvas

margin object <optional>

Margin around the text

Properties
Name Type Argument Description
left object <optional>

Left margin of text

top object <optional>

Top margin of text

backgroundColor number <optional>

background color. This is the background color of the rectangle.

color number <optional>

Text color

Since:
  • 3.0.0 Function signature changed. This function now takes a params object instead of eight different parameters.


timeAsDisplay(dt [, stx] [, precision])

Displays a time in readable form. If Internationalization is in use then the time will be in 24 hour Intl numeric format

Parameters:
Name Type Argument Description
dt date

JavaScript Date object

stx object <optional>

Chart object if Internationalization is in use

precision number <optional>

Precision to use. If null then hh:mm. CIQ.SECOND then hh:mm:ss. If CIQ.MILLISECOND then hh:mm:ss.mmmmm

Returns:

Human friendly time, usually hh:mm

Type
string

toggleClassName(node, className)

Toggles the class name on or off on a DOM element.

Parameters:
Name Type Description
node HTMLElement

The DOM element on which the class name is toggled on or off.

className string

The class name to toggle on or off.

Deprecated:

transferObject(target, source)

Copies the contents of one object into another. This is useful if there are pointers to the target object and you want to "replace" it with another object while preserving the pointer.

Parameters:
Name Type Description
target object

The object being pointed to

source object

The object containing the values you want pointed at

Since:
  • 7.1.0

Returns:

Returns the modified target object

Type
object
Example
var target={"color":"red", "pattern":"solid"};
var source={"color":"blue", "shape":"triangle"};
CIQ.transferObject(target, source);
>> target==={"color":"blue", "shape":"triangle"};
>> target!==source;

translatableTextNode(stx, english [, language])

Creates a document node which facilitates translation to other languages, if stx.translationCallback callback function is set. If there is no translationCallback, a standard text node is returned.

Parameters:
Name Type Argument Description
stx CIQ.ChartEngine

The chart object

english string

The word to translate

language string <optional>

Language. Defaults to CIQ.I18N.language.

Deprecated:
Returns:

A node in the following form if translationCallback exists: translation If it does not exist, a text node is returned.

Type
HTMLElement

trulyVisible(node)

Determines the visibility of a DOM element based on the following CSS properties:

  • opacity
  • display
  • visibility
  • width
  • height

Replaces CIQ.UI.trulyVisible.

Parameters:
Name Type Description
node HTMLElement

The node for which visibility is determined.

Since:
  • 8.2.0

Returns:

Whether the element is visible.

Type
boolean

unappendClassName(node, className)

Removes a class name from a DOM node.

Parameters:
Name Type Description
node object

The DOM element from which the class name is removed.

className string

The class name to remove.

Deprecated:

uniqueID(generateUUID)

Convenience function for generating a unique ID. Defaults to a short, pseudo unique ID based on the current time. Radix 36 is used resulting in a compact string consisting only of letters and numerals. While not guaranteed to be unique, this function has a high probability of uniqueness when it is triggered by human activity even in a large user base. If called with true as the first argument, it will instead return an RFC4122 version 4 compliant UUID.

Parameters:
Name Type Description
generateUUID boolean

If true will return a UUID.

Since:
  • 8.7.0 Uses Web Crypto API to generate random values. If available, uses crypto.randomUUID.

Returns:

Either a RFC4122 version 4 compliant UUID or a unique string consisting of letters and numerals.

Type
string

waitForPlugins(plugins, cb [, doc])

Checks to see if the enabled plugins are done dynamically loading.

Parameters:
Name Type Argument Description
plugins array

An array of strings that define which plugins to check The plugin names provided must match the following format: if cq-scriptiq is enabled, 'scriptiq' is the plugin name entered into the array

cb function

Function to call when all the plugins are fully loaded

doc Document <optional>

document plugins are loaded in.

Since:
  • 6.1.0
  • 8.5.0 Added the doc parameter.

withinElement(node, x, y)

Returns true if a point, in absolute screen position, is within an element

Parameters:
Name Type Description
node object

A valid DOM element to check whether the point overlaps

x number

Absolute screen X position of pointer

y number

Absolute screen Y position of pointer

Returns:

True if the point lies inside of the DOM element

Type
boolean

withinRadius(origin, point, radius)

Determine if a point is within a given radius of another point.

Parameters:
Name Type Description
origin object

Initial x and y coodinates ( example {x:50, y:25} ).

point object

Final x and y coodinates ( example {x:50, y:25} ).

radius number

The radius value to check, indicating linear distance.

Since:
  • 8.9.0

Returns:

true if within the radius.

Type
boolean

xIntersection(vector, y)

Determines the X value at which point Y intersects a line (vector)

Parameters:
Name Type Description
vector object

Object of type {x0,x1,y0,y1}

y number

Y value

Returns:
  • X intersection point
Type
number

xor(a, b)

Convenience function to compute xor operation.

Parameters:
Name Type Description
a object

Operand.

b object

Operand.

Since:
  • 7.3.0

Returns:

true if only one of the operands is truthy.

Type
boolean

yIntersection(vector, x)

Determines the Y value at which point X intersects a line (vector)

Parameters:
Name Type Description
vector object

Object of type {x0,x1,y0,y1}

x number

X value

Returns:
  • Y intersection point
Type
number

yyyymmdd(dt)

Converts a JavaScript Date to yyyy-mm-dd format

Parameters:
Name Type Description
dt date

JavaScript Date object

Returns:

Date in yyyy-mm-dd format

Type
string

yyyymmddhhmm(dt)

Converts a date into yyyymmddhhmm format

Parameters:
Name Type Description
dt date

A JavaScript Date object

Returns:

Date in yyyymmddhhmm format

Type
string

yyyymmddhhmmssmmm(dt)

Converts a date into yyyymmddhhmmssmmm format

Parameters:
Name Type Description
dt date

A JavaScript Date object

Returns:

Date in yyyymmddhhmmssmmm format

Type
string