API Reference
Namespaces
Classes
Events
Global
Externals

Namespace: UI

CIQ. UI

Namespace for UI helper objects designed to be used with the library web components.

Classes

BaseComponent
Chart
Context
ContextTag
CurveEdit
DialogContentTag
DrawingEdit
HeadsUp
Helper
Keystroke
KeystrokeHub
Layout
Lookup
Markers
ModalTag
Multichart
SidePanelPlugin
StudyEdit
TimeSpanEvent
UIManager
VisualEarnings

Members

addAttributeOnPropertyChange :boolean

Flag to reflect property changes into observed attributes even when they are not present. Normally attributes are only changed on property changes, not added.

Type:
  • boolean
Since:

  • 9.1.0

bypassBindings :Boolean

Set this flag to true to bypass bindings when adding a component to the DOM.

Designed to be used with the included WebComponents. A full tutorial on how to work with and customize the web components can be found here: Web Component Interface.

For instance, when components are created by html2canvas, we don't want them to do any heavy lifting.

Type:
  • Boolean

defaultSwatchColors :Array.<string>

Default colors codes used by the WebComponents.ColorPicker.

Type:
  • Array.<string>
Since:

  • 8.4.0

keyboardClaims :Set.<HTMLElement>

Set of components which are configured to respond to keyboard events. See CIQ.UI.BaseComponent#addClaim and CIQ.UI.BaseComponent#removeClaim.

Type:
  • Set.<HTMLElement>
Since:

  • 8.9.0

shadowComponents :Map.<HTMLElement, HTMLElement>

Map of components which use shadow DOM.

Type:
  • Map.<HTMLElement, HTMLElement>
Since:

  • 8.9.0

Methods

$(element, force)

Wraps a node or node list in a jQuery object or Faquery object.

If jQuery is enabled, performs $() on the argument and returns it. If jQuery is not enabled or the force parameter is true, uses the Faquery emulator.

Parameters:
Name Type Description
element Node | NodeList

Node or node list to be wrapped in a jQuery or Faquery object.
force boolean

If true, the function never uses jQuery, instead always uses Faquery.
Since:

  • 8.1.0

Returns:

A jQuery object if jQuery is enabled and force is false; otherwise, a Faquery object. The returned object wraps element.

Type
object

addComponentDefinition( [customTagName] [, classDefinition])

Adds a web component definition to the list of web components.

The component is ultimately registered as a custom element by CIQ.UI.registerComponents.

Separating registration of the component from addition of the component to the component list provides the ability to customize the web component via class extension. Customized classes can be re-added using the original tag name.

Parameters:
Name Type Argument Description
customTagName String <optional>

Tag name that identifies the web component class; for example, cq-abstract-marker.
classDefinition function <optional>

The class definition of the component; for example, the definition of the AbstractMarker class.
Since:

  • 7.5.0

addInheritance(target, source)

Utility method for adding multiple inheritances to a base object.

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
target Object

Target object.
source Object

Source object.

addResizeListener(element, fn)

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.
fn function

The listener function to attach to the DOM element.
Since:

allContexts()

Deprecated since 8.1.0. Use document.querySelectorAll("cq-context,*[cq-context]") instead.

Utility function that returns all contexts on the screen.

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.

Since:

  • 8.1.0 Deprecated.

Deprecated:

  • Use document.querySelectorAll("cq-context,*[cq-context]").

Returns:

A jQuery node with all contexts.

Type
jQuery

animatePrice(node, newPrice, oldPrice, fade)

Convenience function to display the changing price of a node (price flash green/red).

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.

This functionality, especially with the fade effect, can be CPU expensive if many updates per second or multiple charts on a screen exist. To disable simply set CIQ.UI.animatePrice = function () { };.

Parameters:
Name Type Description
node node

The HTML element on which to apply the changing price effect.
newPrice number

The new price; can be higher or lower than the previous price.
oldPrice number

The previous price.
fade boolean

If true, animate the price with a fade transition effect; otherwise, do not use a transition effect.
Since:

  • 7.2.0 Added the fade argument.

begin( [cb])

Starts the UI.

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 Argument Description
cb function <optional>

Optional callback returns when web components are scheduled for initialization.

classDefinitionAccessor(name)

Returns the class definition for a web component.

Parameters:
Name Type Description
name string

Name of the web component, either tag name or class name will work.
Since:

  • 9.8.0

Returns:

Class definition of the component.

Type
function

closestContextContainer(el [, options])

Finds within an element's ancestry the closest cq-context or cq-context-wrapper tag. This is like the native HTMLElement.closest() function except it pierces through shadow roots.

Parameters:
Name Type Argument Description
el HTMLElement

The element whose ancestry to check
options object <optional>

Selection options

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

If true, will check for a cq-context-wrapper element instead of a cq-context element.
includeSelf boolean <optional>
 false

If true, will check itself before checking ancestry.
Since:

  • 8.9.0

Returns:

The ancestor context or wrapper element.

Type
HTMLElement

componentMarkup(identifier, markup)

Getter and setter for component markup.

Parameters:
Name Type Description
identifier String | function

Tag, class name, or class definition that identifies a component.
markup String

If provided, sets the markup for the identified component.
Since:

  • 7.5.0

Returns:

An object containing the tag, name, registration status, and markup of the identified component. If an identifier is not provided, returns data for all registered components. If an identifier is provided, but a registered component cannot be found, returns undefined.

Type
Object | undefined

components(identifier)

Gets an array of components from the list of registered components.

Parameters:
Name Type Description
identifier string | function

Tag, class name, or class definition used to identify registered components.
Since:

  • 8.0.0

Returns:

An array of components identified by identifier. The array elements contain the tag, name, registration status, and markup of the matched components. If an identifier is not provided, data for all registered components is returned.

Type
array

containerExecute(self, fn, args)

Executes a function in the nearest parent component (container). For instance, a cq-close component might call "close" on its containing component.

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
self object

A reference to a web component. The function is called on a parent of the component.
fn string

The name of the function to execute.
args array

Arguments array (a "spread" is also supported).

contextsForEach(func [, node])

Utility to run a function across all contexts.

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.

The value of this is set to the context.

Parameters:
Name Type Argument Description
func function

Function to run.
node HTMLElement <optional>

A node within the context.
Since:

  • 8.5.0 Added node parameter.

Example
CIQ.UI.contextsForEach(function(){
 	this.stx.doSomething();
 });

ensureComponentsRegistered()

Ensures that all web components in the web component list (see addComponentDefinition) have been registered.

Since:

  • 7.5.0

See:

flattenInheritance(component, classDefinition)

Moves functions from the superclass into the current class.

Used by a component's adoptedCallback method when moving a component to a new document and the browser implementation decides to lose track of the inheritance chain once the document has been added to the new document (Firefox).

Parameters:
Name Type Description
component object

A web component instance.
classDefinition function

Class definition that identifies a component.
Since:

  • 8.5.0

getMyContext(me, preferContextNode)

Utility to get the context for a tag.

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.

It traverses up the parent stack looking for a parent with a context member, or the actual cq-context. If no context can be found then returns null.

Parameters:
Name Type Description
me HTMLElement

The element for which to get the context.
preferContextNode boolean

If true, use context from closest cq-context node before using element's context member
Since:

  • 8.4.0

Returns:

The context or null if none found.

Type
CIQ.UI.Context

getUIManager( [element])

Obtains a reference to the document's cq-ui-manager instance or, if one does not exist, creates an instance.

Avoids the need for a cq-ui-manager singleton when multiple charts are present in one document.

Parameters:
Name Type Argument Description
element Element <optional>

Pass an element to give a hint as to where to find the UI Manager.
Since:
  • 7.5.0
  • 8.5.0 Added element parameter.
Returns:

A reference to the document's UI manager.

Type
CIQ.UI.UIManager

makeFromTemplate(node [, appendTo])

Convenience function for making a new node collection from an HTML5 template.

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 Argument Description
node string | HTMLElement | object

The template from which the node collection is created, can be a jQuery object.
appendTo HTMLElement | boolean <optional>

If set to an element, then the template is automatically appended to the element. If set to true, then the new node collection is automatically added in place (appended to the template's parent). A falsey value prevents the contents of the template from being added to the DOM.
Since:

  • 8.1.0 Input parameters continue to support jQuery elements. If node is a jQuery element, then the return type is also a jQuery element.

Returns:

The node collection extracted from the template as a jQuery, if available, or Faquery object.

Type
object

markupDependencies()

Returns the dependencies of all web components based on the web component markup.

Any web component that has markup that relies on another web component is listed in the returned object along with an array of the component's dependencies.

Note: Call this function after all web components have been loaded, otherwise the results will not accurately reflect the dependencies.

Since:

  • 8.0.0

Returns:

An object with the following properties:

  • dependencies — An object whose properties are the names of web components that have dependencies. The value of each property is an array of the dependencies.
  • timesNeeded — An object whose properties are the names of the web components that are dependencies for other web components. The value of each property is the number of times the component is needed as a dependency.

For example:

{
    dependencies: {
        cq-aggregation-dialog: ["cq-close"],
        cq-chartcontrol-group: ["cq-clickable", "cq-lookup", "cq-menu", "cq-menu-container", "cq-toggle", "cq-menu-dropdown"],
        cq-chart-legend: ["cq-comparison", "cq-study-legend", "cq-swatch"],
        cq-comparison-lookup: ["cq-comparison", "cq-lookup", "cq-menu", "cq-swatch"],
        cq-drawing-context: ["cq-menu", "cq-menu-dropdown"],
        cq-fib-settings-dialog: ["cq-scroll"],
        cq-info-toggle: ["cq-toggle"],
        cq-language-dialog: ["cq-close"],
        cq-lookup: ["cq-scroll"],
        cq-share-dialog: ["cq-close"],
        cq-study-dialog: ["cq-menu", "cq-scroll", "cq-study-input", "cq-study-output", "cq-study-parameter", "cq-swatch",
                          "cq-menu-dropdown"],
        cq-theme-dialog: ["cq-close", "cq-scroll", "cq-swatch", "cq-theme-piece"],
        cq-themes: ["cq-close"],
        cq-timezone-dialog: ["cq-close", "cq-scroll"],
        cq-views: ["cq-heading"],
        cq-drawing-palette: ["cq-menu", "cq-redo", "cq-scroll", "cq-toggle", "cq-undo", "cq-menu-dropdown"],
        cq-drawing-settings: ["cq-clickable", "cq-cvp-controller", "cq-menu", "cq-wave-parameters", "cq-menu-dropdown"]
    },
    timesNeeded: {
        cq-close: 6,
        cq-clickable: 2,
        cq-lookup: 2,
        cq-menu: 6,
        cq-menu-container: 1,
        cq-toggle: 3,
        cq-menu-dropdown: 5,
        cq-comparison: 2,
        cq-study-legend: 1,
        cq-swatch: 4,
        cq-scroll: 5,
        cq-study-input: 1,
        cq-study-output: 1,
        cq-study-parameter: 1,
        cq-theme-piece: 1,
        cq-heading: 1,
        cq-redo: 1,
        cq-undo: 1,
        cq-cvp-controller: 1,
        cq-wave-parameters: 1
    }
}
Type
object

observe(params)

Static method to create an observable.

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
params Object

Parameters.

Properties
Name Type Argument Description
selector String <optional>

The selector to affect the observable (adding class, setting value).
obj Object

The object to observe.
member String <optional>

The member of the object to observe. Pass an array to observe multiple members. Or pass nothing to observe any change to the object.
condition String <optional>

Optional condition for the member to trigger the action.
action String

The action to take: "class" - add or remove a class, "callback" - calls back with params.
value String

The value for the action (for example, class name or callback function).
Since:

  • 7.1.0 Returns the handler.

Deprecated:
Returns:

Handler for use when unobserving.

Type
function
Examples

Add or remove a class based on whether stx.layout.crosshair is true or false.

CIQ.UI.observe({selector:".toggle", obj:stx.layout, member:"crosshair", action:"class", value:"active"});

Add or remove a class based on whether stx.layout.chartType=="candle".

CIQ.UI.observe({selector:".toggle", obj:stx.layout, member:"chartType", condition:"candle", action:"class", value:"active"});

Get a callback from a change in value.

CIQ.UI.observe({selector:".toggle", obj:stx.layout, member:"chartType", condition:"candle", action:"callback", value:function(params){
   console.log("new value is" + params.obj[params.member]);
}});

observeProperty(property, obj, listener)

Observes an object's property. The listener receives an object of the form: {obj, property, value}. This uses getters and setters. Thus, you should not attempt to observe a property which already has a getter or setter.

Note: The listener is only executed when the property is assigned a different value than it already has.

Parameters:
Name Type Description
property String

Name of the observed property.
obj Object

Object that contains the property.
listener function

Function to execute when the property changes.
Since:

  • 9.8.0 returns unobserve function that removes attached listener

Returns:

Parameterless function to remove the attached listener

Type
function
Example
var stx=this.context.stx, className=this.params.activeClassName;
var listener=function(obj){
		if(obj.value) node.classList.add(className);
		else node.classList.remove(className);
};
CIQ.UI.observeProperty("flipped", stx.layout, listener);

pickSwatchColor(node, swatch)

Associates a cq-swatch component with given node. Keeps track of which colors have been used for the node so they are not repeated.

Parameters:
Name Type Description
node HTMLElement
swatch HTMLElement

Swatch web component to associate with the node
Since:

  • 8.4.0

registerComponents(config)

Registers components added with CIQ.UI.addComponentDefinition.

Parameters:
Name Type Description
config object

Configuration

Properties
Name Type Argument Default Description
except Array.<String> <optional>
 []

A list of tags that should not be registered, reserving the tag names for an alternative use.
Since:

  • 7.5.0

registerSingleComponent(tagName)

Registers a single component.

Parameters:
Name Type Description
tagName String

Component tag name
Since:

  • 9.7.0

Returns:

Registered component class definition, if exists

Type
function

removeResizeListener(element)

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.
Since:

removeUIManager(doc)

Removes the UI Manager and associated event listeners from the specified document if there are no more cq-context components. This method is called automatically when the last cq-context component is removed from the document.

Parameters:
Name Type Description
doc Document

The document from which to remove the UI Manager.
Since:

  • 9.8.0

setDefaultStates(context)

Specifies the default aria-hidden state for chart elements, which indicates whether an element is exposed to an accessibility API.

  • By default, adds the aria-hidden=true attribute to chart elements, removing them and all of their children from the accessibility tree.
  • Adds the aria-hidden=false attribute to elements listed in config.ariaActive, which adds them to the accessibility tree and sets all of their children to aria-hidden=true.
  • To expose all elements, set config.ariaActive to null.
Parameters:
Name Type Description
context CIQ.UI.Context

uiContext to operate on. Will traverse down from topNode
Since:

  • 8.7.0

stxtap(element, listener [, selector])

Attaches an event listener to the supplied 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 Argument Description
element HTMLElement

The DOM element to which the listener is attached.
listener function

The listener function to attach to the DOM element.
selector string <optional>

A CSS selector to apply to element to obtain the descendant element to which the listener is attached.
Since:
  • 8.1.0
  • 8.9.0 only one stxtap event allowed per element. If an additional one is added, the existing one is removed.

supportedInputType(type)

Utility method for checking if an HTML5 input type is supported.

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.

Returns the type passed in if it's supported or a fallback type if it is not.

Parameters:
Name Type Description
type String

HTML5 input type to be tested.
Since:

  • 6.3.0

Returns:

The supported input type, or the fallback input type (usually "text").

Type
String

trulyVisible(node)

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

  • opacity
  • display
  • visibility
  • width
  • height
Parameters:
Name Type Description
node HTMLElement

The node for which visibility is determined.
Since:
  • 8.1.0
  • 8.2.0 Deprecated
Deprecated:
Returns:

Whether the element is visible.

Type
boolean

unobserve(params)

Static method to remove an observable.

Parameters:
Name Type Description
params Object

Parameters.

Properties
Name Type Description
obj Object

The object being observed.
handler function

The handler to remove.
Since:

  • 7.1.0

Deprecated:

unobserveProperty(property, obj [, listener])

Removes the listener from an object's property.

Parameters:
Name Type Argument Description
property String

Name of the property from which the listener is removed.
obj Object

Object that contains the property.
listener function <optional>

Optional listener to remove; otherwise, the entire object will be removed and made unobservable.
Since:

Type Definitions

Loader

Web component instance to show loading status and having show and hide methods.

Type:
  • object
Properties:
Name Type Description
show function
hide function

Setter

The data object for the first parameter of the stxsetget attribute callback.

Type:
  • object
Properties:
Name Type Description
node HTMLElement

The user interface element that was activated.
e Event

The event that triggered the function.
params CIQ.UI~SetterParams

Additional params.

SetterParams

The data object for the first parameter of the stxsetget attribute callback.

Type:
  • object
Properties:
Name Type Description
parent HTMLElement

Context binding container (cq-context).