API Reference
Namespaces
Classes
Events
Global
Externals

Class: DrawingSettings

WebComponents. DrawingSettings

This is a custom HtmlElement (Web Component). The tag name is the following:

<cq-drawing-settings>

Drawing Settings palette web component used to draw and annotate on the chart. Displays a palette along the top of the chart for managing tool settings.

Inherits from <cq-palette>. Palette components must be placed within a <cq-palette-dock> component.

This works in conjunction with the cq-drawing-palette component and replaces the cq-toolbar component, providing additional functionality and an improved user experience.

Attributes

This component observes the following attributes and will change behavior if these attributes are modified:

attribute description
docked The docked state of the palette. Set to "false" to float palette over the chart.
hide The hidden state of the palette. Set to "false" to show palette.
active-tool Current active drawing tool.
axis-label "true" to enable axis label.
line-color Current line color in hex format, or "auto" to select color from theme.
fill-color Current fill color in hex format, or "auto" to select color from theme.
font-family Current font name. Note: specified font must be available in the end-user's system.
font-size Current font size in valid css units.
font-italic "true" to enable font italics style.
font-bold "true" to enable font bold style.
line-width Line width in pixels.
line-pattern Line pattern: "solid", "dotted" or "dashed".
show-callout "true" to enable display of callout.
span-panels "true" to enable span panels.

Emitters

A custom event will be emitted by the component when it is clicked. See CIQ.UI.BaseComponent#emitCustomEvent for details on how to listen for this event. The details of the event contain the following:

property value
emitter this component
cause "useraction"
effect "select"
action "click"
name property
value value

cause and action are set only when the value is changed as a direct result of clicking on the component.

This component comes with a default markup which is used when the component tag contains no other markup when it is added to the DOM. The default markup provided has accessibility features.

<protected> new DrawingSettings()

Since:
  • 7.2.0
  • 9.1.0 Observes attributes. Added emitter.
Example
<cq-drawing-settings
		class="palette-settings"
		docked="true"
		hide="true"
		orientation="horizontal"
		min-height="40"
		cq-drawing-edit="none"
		line-pattern="solid"
		font-size="12px"
		font-family="Helvetica, sans-serif"
		fill-color="#7DA6F5"
		line-color="auto"
		active-tool="notool"
	></cq-drawing-settings>

Extends

Members

<static> markup :String

Default markup for the component's innerHTML, to be used when the component is added to the DOM without any innerHTML.

Type:
  • String

Methods

addClaim()

Claim any keystrokes that come in. Once claimed, any keystrokes that come in are passed to the element. The element can then choose to capture or propagate the keystrokes. This enables an element to capture keystrokes even if it doesn't have mouse focus.

Inherited From:
Overrides:

addDefaultMarkup(component [, markup])

Adds default markup to a web component if the component does not have any child nodes.

Parameters:
Name Type Argument Description
component HTMLElement

The component to which the markup is added.
markup String <optional>

The markup to add to the web component. Unused if the component has a static markup property that specifies the markup; for example, MyComponent.markup.
Since:

  • 7.5.0

Inherited From:
Overrides:

channelMergeObject(path, value, stx)

Merges an object in the chart engine communication channel.

Parameters:
Name Type Description
path String

The channel path.
value Object

The value merged to the channel.
stx CIQ.ChartEngine

A reference to the chart engine.
Since:

  • 7.5.0

Inherited From:
Overrides:

channelRead(path [, stx])

Reads the current value in the chart engine communication channel.

Parameters:
Name Type Argument Description
path String

The channel path.
stx CIQ.ChartEngine <optional>

Unused.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

The current value in channel.

Type
*

channelSubscribe(path, cb, stx)

Subscribes to the chart engine messaging channel.

Parameters:
Name Type Description
path *

The channel path.
cb *

A callback invoked upon subscribing and whenever a new message is posted in the channel.
stx CIQ.ChartEngine

A reference to the chart engine.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

A callback invoked when unsubscribing from the channel.

Type
function

channelWrite(path, value, stx)

Writes in the chart engine communication channel.

Parameters:
Name Type Description
path String

The channel path.
value *

The value written to the channel.
stx CIQ.ChartEngine

A reference to the chart engine.
Since:

  • 7.5.0

Inherited From:
Overrides:

checkPosition()

Get the offset position of the palette and call setTransformPosition to clamp the palette position in the event of a chartContainer resize

Inherited From:
Overrides:

clearDrawings()

Remove all drawings from the chart.

clickFocusedItem(items, e)

Selects (clicks) the first element in items that has a cq-focused attribute.

Parameters:
Name Type Description
items NodeList

A list of elements that are selectable via keyboard navigation.
e Event

The keystroke event.
Since:

  • 8.3.0

Inherited From:
Overrides:

crosshairs(activator)

Enable crosshairs.

Parameters:
Name Type Description
activator Object
Properties
Name Type Description
node HTMLElement

Element that triggered this function.

deactivateItem(item)

Blurs and removes the cq-keyboard-active attribute from item.

Parameters:
Name Type Description
item HTMLElement
Since:

  • 8.4.0

Inherited From:
Overrides:

defaultElements(drawingParameters, toolName)

Array of element selectors for drawing setting UI elements used by the specified tool.

Parameters:
Name Type Description
drawingParameters object

Drawing parameters object.
toolName string

Name of drawing tool.
Returns:

Array of drawing setting element selectors

detach(xPos, yPos, scale)

Detach palette from dock, positioning it over the chart.

Parameters:
Name Type Description
xPos number

X coordinate of palette relative to palette dock.
yPos number

Y coordinate of palette relative to palette dock.
scale number

Palette height relative to its current height.
Inherited From:
Overrides:

dirty( [on])

Sets active state of drawing settings Save Config button

Parameters:
Name Type Argument Default Description
on boolean <optional>
 true

Set to true to set active.

dock()

Fix palette position along edge of chart.

Inherited From:
Overrides:

emit()

Emits a change event.

emitCustomEvent(params)

Emits a custom event from the webcomponent. The event type of the emitted event is determined by the particular user action taken. Up to two events are emitted when this function is executed. The first is an event with the type of action performed, if there is one. For example, events which are spawned without user action will not emit this first event. The second event will have a type derived from the component name. For example, the cq-study-legend component will emit a "StudyLegend" type event. The payload of the event will contain a detail section specifying the component which emitted the event as well as the effect - which more clearly defines the type of action causing the emittance. The detail section may also include custom fields further categorizing the event and providing additional information. These details are documented within the web component's documentation.

Parameters:
Name Type Description
params object
Properties
Name Type Argument Default Description
cause string <optional>

The cause of the event. e.g., useraction, timeout, alert. Defaults to "useraction" if not set and action parameter is set.
effect string <optional>

The effect of the user's action. Required if not provided in detail. e.g., open, help, toggle, select.
action string | null <optional>
 "click"

The action a user performed, if applicable. e.g. click, longpress, drag. Set to null if no user action was performed.
detail Object <optional>
 {}

Optional extra parameters to include in the detail of the Custom Event.
Since:
  • 8.9.0
  • 9.1.0 Changed params object's property names.
Inherited From:
Overrides:

findFocused(items)

Finds the elements in items that have a cq-focused attribute.

Parameters:
Name Type Description
items NodeList

A list of elements that are selectable via keyboard navigation.
Since:

  • 8.3.0

Inherited From:
Overrides:
Returns:

The elements in items that have a cq-focused attribute, or an empty array if no elements are found.

Type
array

findKeyboardActive(items)

Finds the elements in items that have a cq-keyboard-active attribute.

Parameters:
Name Type Description
items NodeList

A list of elements that are selectable via keyboard navigation
Since:

  • 8.4.0

Inherited From:
Overrides:
Returns:

The elements in items that have a cq-keyboard-active attribute, or an empty array if no elements are found.

Type
Array

focusItem(item)

Adds a cq-focused attribute to item and highlights item.

Parameters:
Name Type Description
item HTMLElement

Element that receives keyboard focus and is highlighted.
Since:

  • 8.3.0

Inherited From:
Overrides:

focusNextItem(items [, reverse] [, loop])

Focuses the next item in the tab order.

Locates the first element in items that has a cq-focused attribute. If an element is found, the attribute is removed from all elements in items, and cq-focused is applied to the element that follows (in the tab order) the element that was found.

If no elements are found with the cq-focused attribute, the attribute is applied to the first element in items (last element if reverse is true). If the last element in items (first element if reverse is true) is found to have the cq-focused attribute, focus remains on that element. Unless loop is set to true, then focus is applied to first element.

Parameters:
Name Type Argument Description
items NodeList

A list of elements that are selectable via keyboard navigation.
reverse boolean <optional>

If true, the operation is performed in reverse order; that is, from the last element in items to the first.
loop boolean <optional>

Loops back to the first item if the last element in items is selected.
Since:

  • 8.4.0 Added loop parameter. Return element, instead of true, if focus is changed.

Inherited From:
Overrides:
See:
Returns:

The newly focused element if a cq-focused attribute has changed.

Type
HTMLElement | undefined

getChartContainer( [el])

Searches the DOM for the chart container element. Begins the search with el (or this) and proceeds parent-by-parent up the ancestry tree until an element is found.

Parameters:
Name Type Argument Description
el HTMLElement <optional>

The element on which to start the search. If not provided, this is used.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

The chart container element or undefined if an element is not found.

Type
HTMLElement | undefined

getColor(activator, mode)

Gets the current drawing color and updates display in palette.

Parameters:
Name Type Description
activator Object
Properties
Name Type Description
node HTMLElement

Element that triggered this function.
mode string

Type of color: fill, line, or annotation.

getContextContainer( [el])

Searches the DOM for the chart context element. Begins the search with el (or this if el is not provided) and proceeds up the ancestry tree until an element is found or the root of the tree has been reached.

Parameters:
Name Type Argument Description
el HTMLElement <optional>

The element on which to start the search. If not provided, this is used.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

The chart context element or undefined if an element is not found.

Type
HTMLElement | undefined

getHeight()

Get the current height of the palette.

Inherited From:
Overrides:
Returns:

The element height in pixels.

Type
number

getWidth()

Get the current width of the palette.

Inherited From:
Overrides:
Returns:

The element width in pixels.

Type
number

handleDragResize(method, event)

Sets dragging property in dock for this palette for mouse and touch events.

Parameters:
Name Type Description
method string

Optional type of drag action, either "dragging" (default) or resizing
event object

Event that triggerd this function
Inherited From:
Overrides:

handleMessage(id, message)

Overloaded from palette class. Handler for responding to messaging sent from other palettes sendMessage function.

Parameters:
Name Type Description
id string

Identifier for the message
message object | string

Optional data accompanying the message
Overrides:

handlePropertyChange(name, oldValue, newValue)

Processes attribute changes. This is called whenever an observed attribute has changed.

Parameters:
Name Type Description
name string

Attribute name
oldValue string

Original attribute value
newValue string

new Attribute value
Overrides:

inputEntry(node, cb)

Attaches a keyboard input entry event.

Parameters:
Name Type Description
node HTMLElement

The element to which the input entry event is attached.
cb function

The callback function invoked when input entry occurs.
Inherited From:
Overrides:

pickColor(activator, mode)

Enables colorPicker and provides callback to setColor, depending on mode value.

Parameters:
Name Type Description
activator Object
Properties
Name Type Description
node HTMLElement

Element that triggered this function.
mode string

Type of color: fill or line.

qs(path, context)

Adapts the querySelector method.

Parameters:
Name Type Description
path String

The CSS selectors for which to search.
context HTMLElement | String

The chart context element, which is the starting point of the DOM query, or "thisChart" to indicate the chart context in which this function is called.
Since:

  • 7.5.0

Inherited From:
Overrides:
Returns:

The selected DOM element or undefined if an element is not found.

Type
HTMLElement | undefined

qsa(path, root, bustShadowRoots)

Adapts the querySelectorAll method. Returns an array instead of a node list to enable chaining of the array map, filter, forEach, and reduce functions.

Parameters:
Name Type Description
path String

The CSS selectors to find.
root HTMLElement | String

The root element, which is the starting point of the DOM query, or "thisChart" to indicate the chart context in which this function is called.
bustShadowRoots boolean

Set to true to penetrate shadow root boundaries.
Since:
  • 7.5.0
  • 8.9.0 Added bustShadowRoots parameter
Inherited From:
Overrides:
Returns:

An array of selected DOM element.

Type
Array.<HTMLElement>

removeClaim()

Remove a claim on keystrokes.

Inherited From:
Overrides:

removeFocused(items)

Removes the cq-focused attribute from all elements in items.

Parameters:
Name Type Description
items NodeList

A list of elements that are selectable via keyboard navigation.
Since:

  • 8.3.0

Inherited From:
Overrides:

restoreDefaultConfig(activator, all)

Restore drawing settings default configuration.

Parameters:
Name Type Description
activator Object
Properties
Name Type Description
node HTMLElement

Element that triggered this function.
all boolean

Set to true to restore default for all drawing objects. Otherwise only the active drawing object's defaults are restored.

saveConfig()

Save current drawing settings as default configuration.

setActiveToolLabel(activeToolLabel)

Set text of palette active tool label element.

Parameters:
Name Type Description
activeToolLabel string

Name of drawing tool.

setColor(color, mode)

Sets the default line or fill color, depending on mode value.

Parameters:
Name Type Description
color string

A Valid css color value.
mode string

Type of color: fill, line, or annotation.

setContext(context)

Called for a registered component when the context is constructed. Sets the context property of the component.

Parameters:
Name Type Description
context CIQ.UI.Context

The chart user interface context.

setFibs(width, pattern)

Set drawing settings for fibonacci drawing tools.

Parameters:
Name Type Description
width number

Line width
pattern string

Line pattern

setFontFamily(activator, fontFamily)

Sets the default font family.

Parameters:
Name Type Description
activator Object
Properties
Name Type Description
node HTMLElement

Element that triggered this function.
fontFamily string

A Valid css font-family value.

setFontSize(activator, fontSize)

Sets the default font size.

Parameters:
Name Type Description
activator Object
Properties
Name Type Description
node HTMLElement

Element that triggered this function.
fontSize string

A Valid css font-size value.

setFontStyle(fontStyle, state)

Set drawing tool font style

Parameters:
Name Type Description
fontStyle string

Style to set, "bold" or "italic".
state boolean

Active state, set to "true" to enable.

setHeight(nextHeight)

Set the palette height property explicitly.

Parameters:
Name Type Description
nextHeight number

Height in pixels.
Inherited From:
Overrides:

setHeightByScale(scale)

Set the palette height property relative to its current height property. For example, a scale of 0.5 will set the palette height to one half of its current height.

Parameters:
Name Type Description
scale number

Size multiplier.
Inherited From:
Overrides:

setHeightToPosition(yPosition)

Set the palette height property based on location.

Parameters:
Name Type Description
yPosition number

Y coordinate of palette bottom
Inherited From:
Overrides:

setLine(activator, width, pattern)

Set drawing line style.

Parameters:
Name Type Description
activator Object
Properties
Name Type Description
node HTMLElement

Element that triggered this function.
width number

Line width
pattern string

Line pattern

setTransform(x, y)

Set the palette transform property explicitly.

Parameters:
Name Type Description
x number

X coordinate of palette relative to palette dock.
y number

Y coordinate of palette relative to palette dock.
Inherited From:
Overrides:

setTransformPosition(x, y)

Set the palette transform position clamping palette within the chart area. Calls setTransform.

Parameters:
Name Type Description
x number

X coordinate of palette relative to palette dock.
y number

Y coordinate of palette relative to palette dock.
Inherited From:
Overrides:

sync( [cvp])

Synchronizes the drawing toolbar with stx.currentVectorParameters. Poor man's data binding.

Parameters:
Name Type Argument Default Description
cvp object <optional>
 stx.currentVectorParameters

A new drawing object, otherwise defaults to the current one

toggleCheckbox(activator, id [, forceValue])

Toggle checked state of checkbox element and update associated drawing setting.

Parameters:
Name Type Argument Default Description
activator Object
Properties
Name Type Description
node HTMLElement

Element that triggered this function.
id string

Drawing setting property name
forceValue boolean <optional>
 null

If set, will force the toggle to that value.

toggleFontStyle(activator, fontStyle)

Toggle active state of font "bold" and "italic" styles and update drawing settings.

Parameters:
Name Type Description
activator Object
Properties
Name Type Description
node HTMLElement

Element that triggered this function.
fontStyle string

Style to toggle, "bold" or "italic".

toggleMagnet(activator)

Toggle grabbing magnet state

Parameters:
Name Type Description
activator Object
Properties
Name Type Description
node HTMLElement

Element that triggered this function.

togglePalette()

Sends toggleDrawingPalette message to other palettes.

tool(activator, toolName)

Enable settings UI for specified drawing tool. Sends changeToolSettings message to other palettes.

Parameters:
Name Type Description
activator Object
Properties
Name Type Description
node HTMLElement

Element that triggered this function.
toolName string

Name of drawing tool.

toolSettings(activator, toolName)

Enable settings UI for specified drawing tool. Called by tool function.

Parameters:
Name Type Description
activator Object
Properties
Name Type Description
node HTMLElement

Element that triggered this function.
toolName string

Name of drawing tool.

trimInnerHTMLWhitespace()

Returns a copy of the innerHTML of an element, with leading and trailing characters stripped. The following characters are stripped: newline, carriage return, tab.

Since:

  • 9.1.0

Inherited From:
Overrides:
Returns:

Trimmed innerHTML

Type
String