Custom Overlays

TradeX-chart allows you to build your own custom overlays to be used in any of the chart panes as defined in the Overlay documentation.

Defining a Custom Overlay

All overlays, whether default, custom and even indicators inherit the Overlay class.

This is exported by the TradeX for you to use in your own custom overlays.

import { Overlay } from "tradex-chart"

class CustomOverlay extends Overlay {

  constructor(target, xAxis=false, yAxis=false, theme, parent, params) {

    super(target, xAxis, yAxis, theme, parent, params)
  }

  // update position with chart scrolling / panning
  set position(p) { this.target.setPosition(p[0], p[1]) }
  // or when fixed position and does not scroll / pan with the chart
  // set position(p) { this.target.setPosition(0, 0) }

  // draw your overlay - invoked automatically by the chart
  draw() {
    // check if the overlay should draw
    if (!super.mustUpdate()) return

    // clear the layer provided to your overlay
    this.scene.clear()
    // HTML canvas context
    const ctx = this.scene.context
    ctx.save();

    // draw something on the canvas

    ctx.restore()
    // reset the draw status
    super.updated()
  }
}

Please refer to the default overlays in the repository as examples of what can be done with an overlay.

What Overlay Class Provides

The Overlay class provides everything needed to draw on or interact with the chart.

See: Overlay Data and Properties

Drawing on the Overlay

TODO:

Using plot() to Draw on the Overlay

The plot() method provides the following functions to draw on the overlay or any other canvas:

Registering an Overlay

Custom overlays must first be registered with the chart before they can be used.

import MyOverlayClass from './src/myOverlayClass.js'

const overlays = {
  myOverlay: {
    class: MyOverlayClass, 
    location: "chartPane"
  }
}
const result = chart0.setCustomOverlays(overlays)

setCustomOverlays() will return an object

Special Cases

You may occasionally have the need where your overlay appears on multiple panes of the chart. For instance the Price High Low overlay draws the price on the Price Scale / Y Axis, as well as on the Primary Chart Pane.

This overlay demonstrates how one overlay can insert other (related) overlays into other panes, start them and even modify the execution of the other.

./src/components/overlays/chart-highLow.js

Active Optional Overlays

Provide a list of optional overlays currently active on the chart.

The lists of available overlays are grouped by chart panes:

mainPane
primaryPane
secondaryPane
scale
timeline

chart0.customOverlays() returns all of the currently available custom overlays.

chart0.optionalOverlays() returns all of the currently available optional overlays, which also includes the custom overlays.

Each overlay entry is an object.

{
  class: overlayClass,
  instance: instanceOfOverlayClass,
  layer: {} // canvas layer object,
  location: "primaryPane" // any of the above chart panes
}

List of Available Overlays

There are a number of methods for revealing what optional overlays are available on the chart, including any registered custom overlays.

chart0.hasOverlay(key)

hasOverlay() returns a pointer to the overlay class or false

chart0.overlayKeys()

overlayKeys() returns an array of overlay keys (IDs)

chart0.overlayEntries(key)

ovrlayEntries() returns an object of key and overlay pairs

Adding an Overlay

chart0.addOverlay("custom", "chartPane")

Add an overlay from target graph (pane)

addOverlay(key, targetID)

Parameter	Type	Description
key	string	overlay ID
targetID	string	target pane ID - mainPane, chartPane, chartScale, timeline, ID

The key must be any of available optional overlays registered with the chart.

Removing an Overlay

chart0.removeOverlay("custom", "chartPane")

Remove an overlay from target graph (pane)

removeOverlay(key, targetID)

Parameter	Type	Description
key	string	overlay ID
targetID	string	target pane ID - mainPane, chartPane, chartScale, timeline, ID