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

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> 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, callback)

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.

Since:

<static> allContexts()

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.

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> 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 jquery node from a 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 Selector

Selector or HTMLElement.

appendTo Selector <optional>

If set, then the template will automatically be appended to this node. If appendTo==true, then the new node will automatically be added in place (appended to the template's parent).

Returns:

A jquery node representing what was extracted from the template.

Type
JQuery

<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( [except])

Registers components added with CIQ.UI.addComponentDefinition.

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