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
- 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 theforce
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 wrapselement
.- 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:
-
7.4.0 Replaces CIQ.addResizeListener.
-
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 initialized.
-
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
CIQ.UI.observe({selector:".toggle", obj:stx.layout, member:"crosshair", action:"class", value:"active"});
CIQ.UI.observe({selector:".toggle", obj:stx.layout, member:"chartType", condition:"candle", action:"class", value:"active"});
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:
-
7.2.0 Replaces CIQ.UI.observe.
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
-
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:
-
7.4.0 Replaces CIQ.removeResizeListener.
-
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 inconfig.ariaActive
, which adds them to the accessibility tree and sets all of their children toaria-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
- By default, adds the
-
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:
-
See CIQ.trulyVisible.
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:
-
7.2.0 Replaces CIQ.UI.unobserve.
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).