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 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
- 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
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
-
<static> 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
.
-
<static> 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
-
<static> 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
-
<static> 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.
-
<static> 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
-
<static> 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
-
<static> 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.
-
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)
-
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 Description color
string Color string to check and use as a basis for setting. If not supplied, uses this.color.
- Since:
-
7.0.0 Replaces
setLineColor
. Will return source line's color if auto.
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);
-
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.
-
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.