Namespace: UI

CIQ. UI

Namespace for UI helper objects.

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

Classes

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

Namespaces

UIManager

Members


<static> 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

Methods


<static> $(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

<static> 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


<static> 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.


<static> 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:

<static> 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

<static> 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.


<static> 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 initialized.


<static> 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

<static> 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

<static> 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).


<static> contextsForEach(func)

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 Description
func function

Function to run.

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

<static> ensureComponentsRegistered()

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

Since:
  • 7.5.0

See:

<static> getMyContext(me)

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.

Returns:

The context or null if none found.

Type
CIQ.UI.Context

<static> getUIManager()

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.

Since:
  • 7.5.0

Returns:

A reference to the document's UI manager.

Type
CIQ.UI.UIManager

<static> 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

<static> 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-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

<static> 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 effect 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]);
	},
});

<static> 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:
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);

<static> 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


<static> 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:

<static> 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


<static> 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

<static> 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

Returns:

Whether the element is visible.

Type
boolean

<static> 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:

<static> 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