API Reference
Namespaces
Classes
Events
Global
Externals

Class: DrawingPalette

WebComponents. DrawingPalette

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

<cq-drawing-palette>

This component is used to facilitate drawing and annotating on the chart. It displays a palette for control and management of drawing tools.

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

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

Drawing tools support keystroke combinations by setting a cq-tool-shortcut attribute in the tool cq-item element. Combinations take the form Alt+key (upper- or lowercase); for example, Alt+a or Alt+A — in either case, the key combination works whether the key is shifted or not. Users can also add the modifier Ctrl to the keystroke combination. For example, both Alt+R and Ctrl+Alt+R activate the Rectangle tool. The added Ctrl modifier helps provide a unique keystroke combination in the event the Alt+key combination is assigned to a function in the web browser or to an application on the user's system.

Attributes

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

attribute description
view Palette display style: "grid" or "list".
active-tool Current active drawing tool.
docked The docked state of the palette. Set to "false" to float palette over the chart.

In addition, the following attributes are also supported:

attribute description
cq-keystroke-claim Enables processing of keyboard input.

If no markup is specified in the menu component, a default markup will be provided. It is strongly suggested to allow the default markup to be used. The default markup utilizes the drawing tools and grouping options set in the default configuration, which is customizable through the component's context.config property.

Emitters

A custom event will be emitted from the component when its view mode is changed. See CIQ.UI.BaseComponent#emitCustomEvent for details on how to listen for this event. The details of the event contain the following:

property value
effect "toggle"
view mode

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

property value
effect "select"
toolName tool name
activator button element pressed

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 DrawingPalette()

Since:
  • 7.1.0
  • 7.2.0 The drawing settings section has been moved into its own component, cq-drawing-settings.
  • 7.4.0 Drawing tools now support keystroke combinations by setting a cq-tool-shortcut attribute in the tool button.
  • 9.1.0 Observes attributes. Added emitter.
Example
<cq-drawing-palette
		class="palette-drawing grid palette-hide"
		docked="true"
		orientation="vertical"
		min-height="300"
		cq-drawing-edit="none"
		cq-keystroke-claim
		view="grid"
		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.

This markup contains placeholder values which the component replaces with values from its attributes. Variables are represented in double curly-braces, for example: {{text}}. The following variables are defined:

variable source
tools from context configuration object
Type:
  • String

Methods

activateTool( [activator], toolName)

Activate drawing tool. Called by tool function.

Parameters:
Name Type Argument Description
activator Object <optional>

Pass null when calling programmatically.

Properties
Name Type Argument Description
node HTMLElement <optional>

Element that triggered this function.
toolName string

Name of drawing tool to activate.
Returns:

Returns palette tool button element for the specified tool.

Type
HTMLElement

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:

addFavorite(toolName)

Add the tool to the list of favorites

Parameters:
Name Type Description
toolName string

Name of drawing tool

bindToolGroups(node)

Binding function for the Tool Groups filter.

Parameters:
Name Type Description
node HTMLElement

Node that owns the binding; usually, the filter menu.

changeView( [activator], modeName)

Change palette view mode

Parameters:
Name Type Argument Description
activator Object <optional>

Pass null when calling programmatically.

Properties
Name Type Argument Description
node HTMLElement <optional>

Element that triggered this function.
modeName string

Palette view mode. Either "list" or "grid".

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()

Sends clearDrawings message to other palettes.

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:

createContextMenu()

Create palette context menu for adding/removing favorite tool assignment in grid view.

Returns:

The context menu element.

Type
HTMLElement

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:

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:

dock()

Fix palette position along edge of chart.

Inherited From:
Overrides:

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

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

getMarkup(config)

Injects tool button markup, set in the chart config, into component markup.

Parameters:
Name Type Description
config object

Chart configuration object
Returns:

Modified markup.

Type
string

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:

handleFavoriteClick(event)

Handle tool favorite button click

Parameters:
Name Type Description
event Event

Button click event.

handleMessage(id, message)

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:

hidePalette()

Used in break-sm context to hide the palette for mobile layout

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:

keyStroke(hub, key, e)

Handler for keyboard interaction.

Key combinations defined in the context config will activate select tools.

Parameters:
Name Type Description
hub CIQ.UI.KeystrokeHub

The hub that processed the key
key string

Key that was stroked
e object

The event object
Returns:

true if keystroke was processed

Type
boolean
Example

Configuration of a shortcut in context (Alt-w will activate Annotation tool):

stxx.uiContext.config.drawingTools = [
	{ type: "dt", tool: "annotation", group: "text", label: "Annotation", shortcut: "w" },
 ...
];

loadToolSettings()

Retrieve list of tools from local storage.

noTool( [activator])

Activate No Tool. Disables any active drawing tools.

Parameters:
Name Type Argument Description
activator Object <optional>

Pass null when calling programmatically.

Properties
Name Type Argument Description
node HTMLElement <optional>

Element that triggered this function.

pairUndoRedo()

Pair undo and redo buttons

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>

registerCallback(fc)

Register callback function

Parameters:
Name Type Description
fc function

Callback function

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:

resetScroller()

Resets the tool scrollbar. Use if the container size or contents have changes.

Returns:

Returns false when scroller element is not found.

Type
boolean

restoreDefaultConfig( [activator], all)

Restore drawing settings default configuration.

Parameters:
Name Type Argument Description
activator Object <optional>

Pass null when calling programmatically.

Properties
Name Type Argument Description
node HTMLElement <optional>

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.

setActiveButton(activeNode)

Set tool button as active.

Parameters:
Name Type Description
activeNode HTMLElement

Tool button element.

setActiveTool(toolName)

Set the active tool.

Parameters:
Name Type Description
toolName string

Name of drawing tool to activate.

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.

setEvenOdd()

Set palette palette tool button even/odd class for styling in grid view mode.

setFavorites(propagateSettings)

Add the favorite badge to relevant tools. Add a favorite toggle star to each tool for use in list view and mobile layout.

Parameters:
Name Type Default Description
propagateSettings boolean true

Effect the settings on all charts in a multichart environment. Defaults to true.

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:

setMode(mode)

Set palette view mode

Parameters:
Name Type Description
mode string

Palette view mode. Either "list" or "grid".

setToolGroup( [activator], groupName)

Change displayed tool group.

Parameters:
Name Type Argument Description
activator Object <optional>

Pass null when calling programmatically.

Properties
Name Type Argument Description
node HTMLElement <optional>

Element that triggered this function.
groupName string

Name of tool group to display.

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:

setupKeyboardActivation(context)

Enable keyboard shortcuts for tools that have a shortcut defined in the chart config. Add keyboard shortcut text to tooltip.

Parameters:
Name Type Description
context object

Chart context

showPalette()

Used in break-sm context to show the palette for mobile layout

showToolContextMenu(toolName, top, left)

Display the tool context menu.

Parameters:
Name Type Description
toolName string

Name of drawing tool.
top number

Top coordinate of context menu position relative to chart context.
left number

Left coordinate of context menu position relative to chart context.

sortToolButtons()

Sort buttons in order defined by the config, grouping those marked favorite first.

storeToolSettings()

Save tool settings to local storage

toggleFavorite(toolName)

Toggle favorite state of drawing tool.

Parameters:
Name Type Description
toolName string

Name of drawing tool.

togglePalette()

Used in break-sm context to show/hide the palette for mobile layout

tool( [activator], toolName)

Activate drawing tool. Sends changeTool message to other palettes.

Parameters:
Name Type Argument Description
activator Object <optional>

Pass null when calling programmatically.

Properties
Name Type Argument Description
node HTMLElement <optional>

Element that triggered this function.
toolName string

Name of drawing tool to activate.

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

<static> itemInterior(label [, icon] [, helpId])

Default markup for the innerHTML of a cq-item tag. Used by DrawingPalette.markup.

Parameters:
Name Type Argument Description
label string

text to be displayed or read.
icon string <optional>

icon class.
helpId string <optional>

value of the help-id attribute.
Returns:

HTML markup for the tag's interior.

Type
string