API Reference
Namespaces
Classes
Events
Global
Externals

Class: Drawing

CIQ. Drawing


new Drawing()

Base class for Drawing Tools. Use CIQ.inheritsFrom to build a subclass for custom drawing tools. The name of the subclass should be CIQ.Drawing.yourname. Whenever CIQ.ChartEngine.currentVectorParameters.vectorType==yourname, then your drawing tool will be the one that is enabled when the user begins a drawing. Capitalization of yourname must be an exact match otherwise the kernel will not be able to find your drawing tool.

Each of the CIQ.Drawing prototype functions may be overridden. To create a functioning drawing tool, you must override the functions below that create alerts.

Drawing clicks are always delivered in adjusted price. That is, if a stock has experienced splits, then the drawing will not display correctly on an unadjusted price chart unless this is considered during the rendering process. Follow the templates to assure correct rendering under both circumstances.

If no color is specified when building a drawing, then the color will be set to "auto" and the chart will automatically display white or black depending on the background.

Permanent drawings:
To make a particular drawing permanent, set its permanent property to true once created.
Example:
drawingObject.permanent=true;

See Using and Customizing Drawing Tools for more details.

Classes

BaseTwoPoint
annotation
average
callout
channel
continuous
crossline
elliottwave
ellipse
fibarc
fibfan
fibonacci
fibprojection
fibtimezone
freeform
gannfan
gartley
horizontal
line
measure
measurementline
pitchfork
quadrant
ray
rectangle
regression
retracement
segment
shape
speedarc
speedline
timecycle
tirone
trendline
vertical
volumeprofile

Members


chartsOnly :boolean

Set this parameter to true to restrict drawing from being rendered on a study panel.

This parameter may be set for all drawings, for a specific drawing type, or for a specific drawing instance. See examples.

Type:
  • boolean
Example
// Set drawing instance to chartsOnly. Only this one drawing will be affected.
drawing.chartsOnly=true;
// Set a particular drawing prototype to chartsOnly. All drawings to type "difference" will be affected.
CIQ.Drawing["difference"].prototype.chartsOnly=true;
// Set all drawings to chartsOnly.
CIQ.Drawing.prototype.chartsOnly=true;

dragToDraw :boolean

Used to set the user behavior for creating drawings.

By default, a drawing is created with this sequence:
move crosshair to staring pointclickmove crosshair to ending pointclick.

On a touch device this would be:
move crosshair to staring pointtapmove crosshair to ending pointtap.

Set dragToDraw to true to create the drawing with the following alternate sequence:
move crosshair to staring pointmousedowndragmouseup

On a touch device this would be:
move crosshair to staring pointpressdragrelease.

This parameter is not compatible with drawings requiring more than one drag movement to complete, such as:

  • Channel
  • Continuous Line
  • Elliott Wave
  • Gartley
  • Pitchfork
  • Fibonacci Projection

Line and Ray have their own separate parameter, which also needs to be set in the same way, if this option is desired: CIQ.Drawing.line.prototype.dragToDraw=true;

This parameter may be set for all drawings compatible with it, for a specific drawing type, or for a specific drawing instance. See examples.

Type:
  • boolean
Example
// set drawing instance to dragToDraw. Only this one drawing will be affected
drawing.dragToDraw=true;
// Set particular drawing prototype to dragToDraw. All drawings to type "difference" will be affected
CIQ.Drawing["difference"].prototype.dragToDraw=true;
// Set all drawings to dragToDraw
CIQ.Drawing.prototype.dragToDraw=true;

permanent :boolean

Set this to true to disable selection, repositioning, and deletion by the end user.

This parameter may be set for all drawings, for a specific drawing type, or for a specific drawing instance. See examples.

Type:
  • boolean
Example
// set drawing instance to permanent. Only this one drawing will be affected
drawing.permanent=true;
// Set particular drawing prototype to permanent. All drawings to type "difference" will be affected
CIQ.Drawing["difference"].prototype.permanent=true;
// Set all drawings to permanent
CIQ.Drawing.prototype.permanent=true;

Methods


abort(forceClear)

This function is called to tell a drawing to abort itself. It should clean up any rendered objects such as DOM elements or toggle states. It does not need to clean up anything that it drew on the canvas.

Parameters:
Name Type Description
forceClear boolean

Indicates that the user explicitly deleted the drawing (advanced usage).


adjust()

Called whenever periodicity changes so that drawings can adjust their rendering.


boxToPixels(stx, panelName, box [, yAxis])

Converts a box represented by two corner coordinates [tick0,value0] and [tick1,value1] into pixel coordinates. This is important for drawing tools or any other device that requires the actual underlying price. This function is preferred over CIQ.convertBoxToPixels when used by drawing functions because it automatically returns the pixel values based off the values of the box as if they were values of the plot corresponding to the drawing's field property. CIQ.convertBoxToPixels usually returns the pixel values of the box assuming those values are the main series plot's values.

Parameters:
Name Type Argument Description
stx CIQ.ChartEngine

The chartEngine

panelName string

Panel on which the coordinates reside

box object

Box to convert

Properties
Name Type Argument Description
x0 number <optional>
y0 number <optional>
x1 number <optional>
y1 number <optional>
yAxis CIQ.ChartEngine.YAxis <optional>
Since:
  • 8.4.0

Returns:

A converted box

Type
object

click(context, tick, value)

Called when a user clicks while drawing.

Parameters:
Name Type Description
context object

The canvas context.

tick number

The tick in the dataSet.

value number

The value (price) of the click.

Returns:

True if the drawing is complete. Otherwise the kernel continues accepting clicks.

Type
boolean

construct(stx, panel)

Initializes the drawing

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object.

panel CIQ.ChartEngine.Panel

The panel reference.


copyConfig(withPreferences)

Instance function used to copy the relevant drawing parameters into itself. It just calls the static function.

Parameters:
Name Type Description
withPreferences boolean

set to true to return previously saved preferences

Since:
  • 3.0.0


getLineColor(color [, ignoreHighlight])

Compute the proper color to use when rendering lines in the drawing.

Will use the color but if set to auto or transparent, will use the container's defaultColor. However, if color is set to auto and the drawing is based off a series or study plot, this function will return that plot's color. If drawing is highlighted will use the highlight color as defined in stx_highlight_vector style.

Parameters:
Name Type Argument Description
color string

Color string to check and use as a basis for setting. If not supplied, uses this.color.

ignoreHighlight boolean <optional>

True to ignore highlighting status when determining color (for example, if a label, or if determining fill color).

Since:
  • 7.0.0 Replaces setLineColor. Will return source line's color if auto.
  • 8.4.0 Added isLabel parameter.
  • 9.1.2 Changed name of isLabel parameter to ignoreHighlight.
Returns:

Color to use for the line drawing

Type
string
Example
var trendLineColor=this.getLineColor();
		this.stx.plotLine(x0, x1, y0, y1, trendLineColor, "segment", context, panel, parameters);

highlight(highlighted)

Returns the highlighted state. Set this.highlighted to the highlight state. For simple drawings the highlighted state is just true or false. For complex drawings with pivot points for instance, the highlighted state may have more than two states. Whenever the highlighted state changes a draw() event will be triggered.

Parameters:
Name Type Description
highlighted Boolean

True to highlight the drawing, false to unhighlight


intersected(tick, value, box)

Called to determine whether the drawing is intersected by either the tick/value (pointer location) or box (small box surrounding the pointer). For line-based drawings, the box should be checked. For area drawings (rectangles, circles) the point should be checked.

Parameters:
Name Type Description
tick number

The tick in the dataSet representing the cursor point.

value number

The value (price) representing the cursor point.

box object

x0, y0, x1, y1, r representing an area around the cursor, including radius.

Returns:

An object that contains information about the intersection. This object is passed back to CIQ.Drawing.reposition when repositioning the drawing. Return false or null if not intersected. Simply returning true highlights the drawing.

Type
object

isAllowed(stx [, field])

Decides if a drawing can be created on the specified field.

Parameters:
Name Type Argument Description
stx CIQ.ChartEngine

The chart object.

field string <optional>

Field in the dataset, if something other than default.

Since:
  • 8.6.0

Returns:

Whether a drawing can be made on the field.

Type
boolean

measure()

Should call this.stx.setMeasure() with the measurements of the drawing if supported.


move(context, tick, value)

Called when the user moves while creating a drawing.

Parameters:
Name Type Description
context CanvasRenderingContext2D

Canvas context on which to render.

tick number

Tick in the dataSet.

value number

Value at position.


pixelFromValue(panel, tick, value [, yAxis])

Returns the Y pixel location for the (split) unadjusted price rather than the displayed price for a drawing. This is important for drawing tools or any other device that requires the actual underlying price. This function is preferred over CIQ.ChartEngine#pixelFromValueAdjusted when used by drawing functions because it automatically returns the pixel based off the value of the plot corresponding the drawing's field property. CIQ.ChartEngine#pixelFromValueAdjusted usually returns the pixel of the main series plot's value.

Parameters:
Name Type Argument Description
panel CIQ.ChartEngine.Panel

The panel to get the value from

tick number

The tick location (in the dataSet) to check for an adjusted value

value number

The value

yAxis CIQ.ChartEngine.YAxis <optional>

The yaxis to use

Since:
  • 8.4.0

Returns:

The pixel location of the plot whose field matches the field property of the drawing

Type
number

pointIntersection(tick, value, box, isPixels)

Returns true if the tick and value are inside the box

Parameters:
Name Type Description
tick number

The tick

value number

The value

box object

The box

isPixels boolean

True if tick and value are in pixels; otherwise, they assumed to be in ticks and untransformed y-axis values, respectively

Since:
  • 7.0.0 Added isPixels.

Returns:

True if the tick and value are within the box

Type
boolean

reconstruct(stx, obj)

Reconstruct this drawing type from a serialization object

Parameters:
Name Type Description
stx CIQ.ChartEngine

Instance of the chart engine

obj object

Serialized data about the drawing from which it can be reconstructed.


render(context)

Called to render the drawing.

Parameters:
Name Type Description
context CanvasRenderingContext2D

Canvas context on which to render.


reposition(context, repositioner, tick, value)

Called when the user attempts to reposition a drawing. The repositioner is the object provided by CIQ.Drawing.intersected and can be used to determine which aspect of the drawing is being repositioned. For instance, this object may indicate which point on the drawing was selected by the user. It might also contain the original coordinates of the point or anything else that is useful to render the drawing.

Parameters:
Name Type Description
context object

The canvas context.

repositioner object

The repositioner object.

tick number

Current tick in the dataSet for the mouse cursor.

value number

Current value in the dataSet for the mouse cursor.


serialize()

Serialize a drawing into an object.


setLineColor()

Compute the proper color to use when rendering lines in the drawing.

Since:
  • 4.0.0
  • 7.0.0 Deprecated
Deprecated:

setPoint(point, x, y [, chart])

Sets the internal properties of the drawing points where x is a tick or a date and y is a value.

Parameters:
Name Type Argument Description
point number

index to point to be converted (0,1)

x number | string

index of bar in dataSet (tick) or date of tick (string form)

y number

price

chart CIQ.ChartEngine.Chart <optional>

Optional chart object

Since:
  • 04-2015
  • 8.3.0 x tick values outside an allowable range will be replaced by values at the edge of the range. This is to prevent performance problems when switching periodicities.

valueFromPixel(pixel [, panel] [, yAxis])

Returns the value (price) of a drawing given a y-axispixel. The value is relative to the panel or the canvas. This function is preferred over CIQ.ChartEngine#valueFromPixel when used by drawing functions because it automatically returns the value based off the plot corresponding the drawing's field property. CIQ.ChartEngine#valueFromPixel usually returns the value of the main series plot.

Parameters:
Name Type Argument Description
pixel number

The y pixel position

panel CIQ.ChartEngine.Panel <optional>

A panel object. If passed then the value will be relative to that panel. If not passed then the value will be relative to the panel that is in the actual Y location.

yAxis CIQ.ChartEngine.YAxis <optional>

Which yAxis. Defaults to panel.yAxis.

Since:
  • 8.4.0

Returns:

The value relative to the panel, of the plot whose field matches the field property of the drawing

Type
number

copyConfig(drawingInstance, withPreferences)

Static function used to copy the relevant drawing parameters into the drawing instance. Use this when overriding the Instance function, to perform basic copy before performing custom operations.

Parameters:
Name Type Description
drawingInstance CIQ.Drawing

to copy into

withPreferences boolean

set to true to return previously saved preferences

Since:
  • 3.0.0
  • 6.0.0 Overwrites parameters with those stored in preferences.drawings.

getDrawingParameters(stx, drawingName)

Since not all drawings have the same configuration parameters, this is a helper function intended to return the relevant drawing parameters and default settings for the requested drawing type.

For example, you can use the returning object as your template for creating the proper UI toolbox for that particular drawing. Will you need a line width UI element, a fill color, etc.? Or you can use it to determine what values you should be setting if enabling a particular drawing type programmatically with specific properties.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object.

drawingName string

Name of drawing; for example: "ray", "segment".

Since:
  • 3.0.0

Returns:

Map of parameters used in the drawing type, with their current values.

Type
object

getDrawingToolList(excludeList)

Function to determine which drawing tools are available.

Parameters:
Name Type Description
excludeList object

Exclusion list of tools in object form; for example, {"vertical":true,"annotation":true}.

Since:
  • 3.0.0

Returns:

Map of tool names and types.

Type
object

initializeSettings(stx, drawingName)

Static method to call optional initializeSettings instance method of the drawing whose name is passed in as an argument.

Parameters:
Name Type Description
stx CIQ.ChartEngine

Chart object

drawingName string

Name of drawing, e.g. "ray", "segment", "fibonacci"

Since:
  • 5.2.0 Calls optional instance function instead of doing all the work internally.


restoreDefaultConfig(stx, toolName, all)

Static method for restoring default drawing parameters and removing custom preferences.

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object.

toolName string

Name of active drawing tool; for example: "ray", "segment", "fibonacci".

all boolean

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

Since:
  • 6.0.0


saveConfig(stx, toolName)

Static method for saving drawing parameters to preferences.

Values are stored in stxx.preferences.drawings and can be saved together with the rest of the chart preferences, which by default are placed in the browser's local storage under "myChartPreferences".

Parameters:
Name Type Description
stx CIQ.ChartEngine

The chart object.

toolName string

Name of drawing tool; for example: "ray", "segment", "fibonacci".

Since:
  • 6.0.0


updateSource(stx, name, newName, newPanel)

Updates the drawing's field or panelName property to the passed in argument if the field of the drawing is "sourced" from the passed in name.

This is used when moving a series or study, and there is a drawing based upon it.
It will be called based on the following occurrences:

  • Panel of series changed
  • Panel of study changed
  • Default panel of study changed due to field change
  • Outputs of study changed due to field change
  • Outputs of study changed due to name change (due to field of field change)
Parameters:
Name Type Description
stx CIQ.ChartEngine

Chart object

name string

Name of study or symbol of series to match with

newName string

Name of new field to use for the drawing field if a name match is found

newPanel string

Name of new panel to use for the drawing if a name match is found, ignored if `newName`` is set

Since:
  • 7.0.0