ChartIQ SDK Documentation Class: Drawing

new Drawing()

Base class for Drawing Tools. Use ciqInheritsFrom() to build a subclass for custom drawing tools. The name of the subclass should be CIQ.Drawing.yourname. Whenever CIQ.ChartEngine.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 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

annotation
average
BaseTwoPoint
callout
channel
continuous
crossline
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

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:
qmove 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 may be set for all drawings, 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:

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

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.

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:

Return true if the drawing is complete. Otherwise the kernel will continue 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

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, 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 and the 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 will highlight the drawing.

Type: object

measure()

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

move()

Called when the user moves while creating a drawing.

pointIntersection(tick, value, box)

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

Returns:

True if the tick and value are within the box

Type: boolean

reconstruct()

Reconstruct this drawing type from a serialization object

render()

Called to render the drawing

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 datSet for the mouse cursor

serialize()

Serialize a drawing into an object.

setLineColor(color)

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. If drawing is highlighted will use the highlight color as defined in stx_highlight_vector style.

Parameters:

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

Since:

4.0.0

Returns:

Color to use for the line drawing

Type: string

Example

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