Class: Drawing

Classes

annotation

average

BaseTwoPoint

callout

channel

continuous

crossline

elliottwave

ellipse

fibarc

fibfan

fibonacci

fibprojection

fibtimezone

freeform

gannfan

gartley

horizontal

line

measure

pitchfork

quadrant

ray

rectangle

regression

retracement

segment

shape

speedarc

speedline

timecycle

tirone

trendline

vertical

volumeprofile

Members

---

chartsOnly

Set this 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.

Example

// set drawing instance to chartsOnly. Only this one drawing will be affected
drawing.chartsOnly = true;
// Set 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

Used to set the user behavior for creating drawings.

By default, a drawing is created with this sequence:
move crosshair to staring point → click → move crosshair to ending point → click.

On a touch device this would be:
move crosshair to staring point → tap → move crosshair to ending point → tap.

Set dragToDraw to true to create the drawing with the following alternate sequence:
move crosshair to staring point → mousedown → drag → mouseup

On a touch device this would be:
move crosshair to staring point → press → drag → release.

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

• Channel
• Continues 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.

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

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.

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

---

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 tool box 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	Chart object
drawingName	string	Name of drawing, e.g. "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 ( e.g. {"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	Chart object
toolName	string	Name of active drawing tool, e.g. "ray", "segment", "fibonacci"
all	boolean	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	Chart object
toolName	string	Name of drawing tool, e.g. "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

---

abort(forceClear)

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 has 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 [, isLabel])

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.
isLabel	boolean	<optional>	True if determining color for a yaxis label (and therefore, ignore highlighting)

Since:

• 7.0.0 Replaces setLineColor. Will return source line's color if auto.
• 8.4.0 Added isLabel parameter.

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

---

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:

• Use CIQ.Drawing#getLineColor instead.

---

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-axis pixel. 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