Class Tool<CacheType, Events>

*Example of an options definition with the most common attributes:

this.prototype.options = {
   'chartType': {
       type: 'number',
       [name: 'Name'],
       [_set: function],
       [value: 'line'],                    // options without value get forwarded to the _get callback
       [_get: function],                   // either _get or value must be specified
       [flags: BG.charts.Object.EOptionFlags.EXPOSED]   // various flags; e.g. exposed => hint for ui; this option can be shown
   },
};

Type Parameters

CacheType extends Record<string, unknown> = Record<string, unknown>
Events extends Record<string, (...args: any) => void> = Record<string, (...args: any) => void>

Hierarchy (View Summary)

BG.charts.Object<Events & BG.charts.Tool.Events>
- Tool

Index

Constructors

constructor

Properties

optionGroups options type

Constructors

constructor

new Tool<
    CacheType extends Record<string, unknown> = Record<string, unknown>,
    Events extends
        Record<string, (...args: any) => void> = Record<
        string,
        (...args: any) => void,
    >,
>(
    config: BG.charts.Tool.TConfig,
): BG.charts.Tool<CacheType, Events>
The base class for all kinds of tools used in technical analysis, such as trendlines, channels, fibonacci retracements etc.

All tools are represented by a set of "handles", which are basically 2d points that can be manipulated by the user to change the shape of the respective tool. Additionally, in addition to the common configuration options, tools can offer a set of so called "actions" for common tasks that offer shortcuts for often used features - these could for example be used to populate a context menu.
Type Parameters
- CacheType extends Record<string, unknown> = Record<string, unknown>
- Events extends Record<string, (...args: any) => void> = Record<string, (...args: any) => void>
Parameters
- config: BG.charts.Tool.TConfig
Returns BG.charts.Tool<CacheType, Events>
Overrides Object.constructor

Properties

optionGroups

optionGroups: OptionGroup[]

options

options: { [key: string]: any }

type

type: string

Methods

addListener

addListener<
    Type extends string
    | number
    | symbol,
    Callback extends (...args: any) => void,
>(
    type: Type,
    listener: Callback,
): this
Type Parameters
- Type extends string | number | symbol
- Callback extends (...args: any) => void
Parameters
- type: Type
- listener: Callback
Returns this
Description
adds a listener to the end of the listeners array for the specified event.

Inherited from Object.addListener

assignStyle

assignStyle(style: Style, parentStyle: string): void
assigns a new style object to the tool
Parameters
- style: Style
- parentStyle: string
Returns void
Overridable

attr

attr(this: BG.charts.Object, s: string, a: string, v?: any): any
returns or sets the attribute of an option this function should be used with care - modifications of internal properties might break stuff!
Parameters
- this: BG.charts.Object
- s: string
- a: string
- Optionalv: any
Returns any
Inherited from Object.attr

calculate

calculate(meta: TCalculateParams, context: BGContext): void
will be called before methods are called that need to access x/y-coordinates can be overriden to set up the cache values needed in the other methods The meta parameter passed to the method includes a reason for the redraw, and potentially the indices of the updated values
Parameters
- meta: TCalculateParams
- context: BGContext
Returns void
Overridable

clearCache

clearCache(): void
Helper-method to clear the cache

Returns void

clone

clone(): BG.charts.Tool<CacheType>
clone the tool

Returns BG.charts.Tool<CacheType>
Overridable

deserialize

deserialize(
interactivePlacement: boolean,
options: null | { [s: string]: any },
): void
called after each deserialization all handles have already been configured at this point or interactive placement has been started default implementation of this method applies all options via set
Parameters
- interactivePlacement: boolean
- options: null | { [s: string]: any }
Returns void
Overridable

didUpdateOptions

didUpdateOptions(this: BG.charts.Object): void
must be called after willUpdateOptions once all actions that might potentially changed values of any options are done

IMPORTANT: methods must be called in balance; e.g. for each call to willUpdateOptions, you must call didUpdateOptions exactly once.
Parameters
- this: BG.charts.Object
Returns void
Inherited from Object.didUpdateOptions

draw

draw(context: BGContext, highlighted: boolean, editing: boolean): void
draws the tool
Parameters
- context: BGContext
  the 2d canvas context
- highlighted: boolean
  flag indicating wether the tool is currently highlighted
- editing: boolean
  flag indicating wether the tool is currently being edited
Returns void
Overridable

emit

emit<
    Type extends string
    | number
    | symbol,
    Callback extends (...args: any) => void,
>(
    type: Type,
    ...params: Parameters<Callback>,
): boolean
Type Parameters
- Type extends string | number | symbol
- Callback extends (...args: any) => void
Parameters
- type: Type
- ...params: Parameters<Callback>
Returns boolean
Description
execute each of the listeners in order with the supplied parameters.

Inherited from Object.emit

executeAction

executeAction<T extends BG.charts.Tool.Action>(
actionId: T["id"],
menuId?: string,
): any
executes the specified action
Type Parameters
- T extends BG.charts.Tool.Action
Parameters
- actionId: T["id"]
- OptionalmenuId: string
Returns any
Overridable

finishInitialize

finishInitialize(index: number): void
called after each initialization step only called when added via placeTool (not copy, not transform, not deserialize!)
Parameters
- index: number
  the index of the initialization step
Returns void
Overridable

flat

flat(
    readWriteOnly?: boolean,
    modifiedOnly?: boolean,
    nonEphemeralOnly?: boolean,
): { [key: string]: any }
returns a flat representation of all available config options in the form of a key-value-object optionally only values that are not read-only can be returned

IMPORTANT: this method will always convert I18NStrings to strings, so for displaying strings in a UI use individual calls to BG.charts.Object:get instead
Parameters
- OptionalreadWriteOnly: boolean
  default: true
- OptionalmodifiedOnly: boolean
  default: true
- OptionalnonEphemeralOnly: boolean
  default: true
Returns { [key: string]: any }
Inherited from Object.flat

get

get(s?: string, flags?: number): any
returns the value of the requested option, or a list of all available config options if no parameter is specified.
Parameters
- Optionals: string
- Optionalflags: number
Returns any
Inherited from Object.get

getActions

getActions(menuId?: string): BG.charts.Tool.Action[]
returns all available actions
Parameters
- OptionalmenuId: string
Returns BG.charts.Tool.Action[]
Overridable

getBounds

getBounds(): Bounds
returns the bounds of this tool

Returns Bounds
Overridable

getBoundsInRange

getBoundsInRange(xStart: number, xEnd: number): false | Bounds
returns the bounds of this tool in the specified range on the x-Axis currently only used to show/hide bound extension symbols - should probably be renamed
Parameters
- xStart: number
- xEnd: number
Returns false | Bounds
Overridable

getChart

getChart(): BG.charts.Chart
returns the tools chart

Returns BG.charts.Chart

getCursor

getCursor(): null | string
by implementing this methods tools can request a special mouse cursor to use in combination with custom event handling (e.g. for different actions such as buttons) the selection logic itself has to be implemented based on the values passed to handleEvents which is always called with the most recent values before this method

Returns null | string
desired cursor (all standard css cursors are supported) or null for default

Overridable

getGroups

getGroups(): OptionGroup[]
returns the categorization of the objects options can be used for displaying a more structured user interface

Returns OptionGroup[]
Inherited from Object.getGroups

getHandleIndexAtPoint

getHandleIndexAtPoint(x: number, y: number, range: number): null | number
returns index of handle at specified point, or null if none is in range
Parameters
- x: number
  the x coordinate of the point
- y: number
  the y coordinate of the point
- range: number
  maximum distance to the point
Returns null | number

getHandles

getHandles(): ToolHandle[]
Returns ToolHandle[]

getInitialHandleIndices

getInitialHandleIndices(): number[]
returns the indices of the tools initially selected handles

Returns number[]

getLegendEntryChunks

getLegendEntryChunks(pickerIndex: number): Chunk[]
Creates list of legend entry chunks to be displayed in the legend for the index pickerIndex
Parameters
- pickerIndex: number
Returns Chunk[]

getParallelValues

getParallelValues(
event: MouseEvent,
range?: number,
): { name: string; value: number }[]
Parameters
- event: MouseEvent
- Optionalrange: number
Returns { name: string; value: number }[]
Description
returns all values of lines parallel to the x-axis that are within the range of the mouseclick event

getPickerDimensions

getPickerDimensions(): EDimension
by implementing this methods tools can control the picker markers on the X- and Y-Axes that are shown when interacting with the tool should only be used in combination with custom event handling tools that are controlled via handles should not overwrite this method and stick to the default behaviour

Returns EDimension
desired picker dimensions

Overridable

getPrimaryColor

getPrimaryColor(): string
returns the primary color of this tool

Returns string
Overridable

getState

getState(): BG.charts.Object.State
returns the objects current state

Returns BG.charts.Object.State
Inherited from Object.getState

getStyle

getStyle(): ObjectStyle
returns the style object

Returns ObjectStyle

getTranslator

getTranslator(): Translator
return a BG.locale.Translator instance

Returns Translator

handleEvent

handleEvent(
    event: null | Event,
    type: string,
    button?: number,
    layerX?: number,
    layerY?: number,
    hovered?: boolean,
    editable?: boolean,
): boolean
handle events
Parameters
- event: null | Event
  the original mouse or touch event
- type: string
  the event to be handled
- Optionalbutton: number
  the pressed button
- OptionallayerX: number
  the x-coordinate
- OptionallayerY: number
  the y-coordinate
- Optionalhovered: boolean
  tool is hovered
- Optionaleditable: boolean
  tool is currently editable
Returns boolean
boolean indicating wether the event has been handled

Overridable

hasPoint

hasPoint(x: number, y: number, range: number): boolean
check if the tool contains the specified point
Parameters
- x: number
  the x coordinate of the point
- y: number
  the y coordinate of the point
- range: number
  maximum distance to the point
Returns boolean
Overridable

initialize

initialize(index: number, value: number): void
initialize the tool at the specified position only called when added via placeTool (not copy, not transform, not deserialize!)
Parameters
- index: number
  the index (x-coordinate)
- value: number
  the value (y-coordinate)
Returns void
Overridable

isInitializationFinished

isInitializationFinished(): boolean
returns whether the tool has finished its initialization

Returns boolean
Overridable

isInVisibleRange

isInVisibleRange(tool: BG.charts.Tool): boolean
checks if the tool is (at least partly) visible in the current viewport range always return false if tool has not been assigned to a chart yet or if it has no valid bounds

Note: This method does NOT account for value of the "visible" option; e.g. if visible is set to false, but the tool WOULD be visible in the current viewport range, this method returns true!
Parameters
- tool: BG.charts.Tool
Returns boolean

isPrunable

isPrunable(): boolean
check if the tool is prunable

Returns boolean
Overridable

listeners

listeners<
    Type extends string
    | number
    | symbol,
    Callback extends (...args: any) => void,
>(
    type: Type,
): Callback[]
Type Parameters
- Type extends string | number | symbol
- Callback extends (...args: any) => void
Parameters
- type: Type
Returns Callback[]
Description
returns an array of listeners for the specified event.

Inherited from Object.listeners

move

move(dX: number, dY: number, start: { x: number; y: number }[]): boolean
Parameters
- dX: number
- dY: number
- start: { x: number; y: number }[]
Returns boolean
Overridable

moveHandle

moveHandle(handleIndex: number, index: number, value: number): void
move the specified handle to a new position
Parameters
- handleIndex: number
  the index of the handle to be moved
- index: number
  the new index (x-coordinate) of the handle
- value: number
  the new value (y-coordinate) of the handle
Returns void
Overridable

on

on<
    Type extends string
    | number
    | symbol,
    Callback extends (...args: any) => void,
>(
    type: Type,
    listener: Callback,
): this
Type Parameters
- Type extends string | number | symbol
- Callback extends (...args: any) => void
Parameters
- type: Type
- listener: Callback
Returns this
Description
alias for addListener

Inherited from Object.on

once

once<
    Type extends string
    | number
    | symbol,
    Callback extends (...args: any) => void,
>(
    type: Type,
    listener: Callback,
): this
Type Parameters
- Type extends string | number | symbol
- Callback extends (...args: any) => void
Parameters
- type: Type
- listener: Callback
Returns this
Description
adds a one time listener for the event. This listener is invoked only the next time the event is fired, after which it is removed.

Inherited from Object.once

onDestroy

onDestroy(): void
called when an object will be permanently discarded no other methods will be called on it ever again after this point

IMPORTANT: this method should ONLY be called directly on the Controller all other objects will be destroyed automatically by the implementation

Returns void
Overridable
Inherited from Object.onDestroy

onRecover

onRecover(): void
life cycle method; called when the object should recover from an error and resume normal operation

this will only be called if the object encountered a RecoverableError, and is always triggered by a manual user interaction

always called between start and stop

Returns void
Overridable
Inherited from Object.onRecover

onStart

onStart(context: BG.charts.TContext): void
life cycle method; called when the object should start normal operation at this point is is already completely initialized
Parameters
- context: BG.charts.TContext
Returns void
Overridable
Inherited from Object.onStart

onStop

onStop(): void
life cycle method; called when the object should stop normal operation if objects have any pending subscriptions/requests, they should all be stopped here

the object is also responsible for clearing the loading flag from it's state if it is currently active failing to do so will trigger a fatal error

object might be started again afterwards (start) or destroyed (destroy) this is not known yet at this point

called after start or restart

Returns void
Overridable
Inherited from Object.onStop

readCache

readCache<Key extends string | number | symbol>(cacheKey: Key): CacheType[Key]
Method that allows reading of values in an instance-specific cache Can be used to reduce the amount of necessary calculations (e.g. x/y-coordinates) by storing/retrieving them only when necessary Keys and values need to be defined in a type that will be passed to the parent BG.charts.Tool class
Type Parameters
- Key extends string | number | symbol
Parameters
- cacheKey: Key
Returns CacheType[Key]

recover

recover(): boolean
can be called to tell the object that it should recover from an error and resume will have no effect if no retryable error is currently associated with the object

Returns boolean
Inherited from Object.recover

releaseStyle

releaseStyle(style: Style): void
release all references to the specified style object
Parameters
- style: Style
Returns void
Overridable

removeAllListeners

removeAllListeners<Type extends string | number | symbol>(type?: Type): this
Type Parameters
- Type extends string | number | symbol
Parameters
- Optionaltype: Type
Returns this
Description
removes all listeners, or those of the specified event.

Inherited from Object.removeAllListeners

removeListener

removeListener<
    Type extends string
    | number
    | symbol,
    Callback extends (...args: any) => void,
>(
    type: Type,
    listener: Callback,
): this
Type Parameters
- Type extends string | number | symbol
- Callback extends (...args: any) => void
Parameters
- type: Type
- listener: Callback
Returns this
Description
remove a listener from the listener array for the specified event.

Inherited from Object.removeListener

set

set(
    s: null | string | { [key: string]: any },
    v?: any,
    flags?: BG.charts.Object.EFlags,
): boolean
will set validate and then set the specified option(s) to the provided value(s) after validation

NOTE: if multiple options are used, will return false if at least one value is not valid values are applied individually however, so one option might be set even if the value for another is invalid
Parameters
- s: null | string | { [key: string]: any }
- Optionalv: any
- Optionalflags: BG.charts.Object.EFlags
Returns boolean
Inherited from Object.set

setHandles

setHandles(this: BG.charts.Tool, handles: number[][]): boolean
Programatically change the layout of the tool.

Handles are specified as an array of numbers, either in the format [timestamp, value], or [timestamp, offset, value]. The number and layout constraints of handles depends on the type of the tool being added. See the documentation of the respective tool class for detailed information.
Parameters
- this: BG.charts.Tool
- handles: number[][]
Returns boolean

setInitialHandleIndices

setInitialHandleIndices(indices: number[]): boolean
updates the indices of the tools initially selected handles indices have to be valid (e.g. in range [0, #handles[)
Parameters
- indices: number[]
Returns boolean

setMaxListeners

setMaxListeners(maxListeners: number): this
Parameters
- maxListeners: number
Returns this
Description
by default EventEmitters will print a warning if more than 10 listeners are added for a particular event. This is a useful default which helps finding memory leaks. Obviously not all Emitters should be limited to 10. This function allows that limit to be increased. Set to zero for unlimited.

Inherited from Object.setMaxListeners

setTypeAndName

setTypeAndName(objType?: string, objName?: string): void
Sets the objName and objType of the Object reverts to the default ones if no arguments are given
Parameters
- OptionalobjType: string
- OptionalobjName: string
Returns void
Inherited from Object.setTypeAndName

snap

snap(point: Point, range: number): false | Point
Overridable interface to snap the crosshair to a point on the tool
Parameters
- point: Point
- range: number
Returns false | Point

toString

toString(): string
Returns a string representation of an object.

Returns string
Inherited from Object.toString

validate

validate(
    s: string | { [key: string]: any },
    v?: any,
    flags?: BG.charts.Object.EFlags,
): boolean
will set validate value(s) for the specified option(s)

NOTE: if multiple options are used, will return false if at least one value is not valid
Parameters
- s: string | { [key: string]: any }
- Optionalv: any
- Optionalflags: BG.charts.Object.EFlags
Returns boolean
Inherited from Object.validate

validateChart

validateChart(chart: BG.charts.Chart): boolean
Helper method, must not be called directly Used for validating if a specified chart is suitable for placement of this tool instance

e.g. charts that require a reference OHLC input can check if one is available, and if it uses the correct aggregation, etc.
Parameters
- chart: BG.charts.Chart
Returns boolean
Overridable

validateHandles

validateHandles(newHandles: ToolHandle[]): boolean
Helper method, must not be called directly. Used for validating new layouts provided to BG.charts.Tools.setHandles method

When implementing a custom tool, you can overwrite this function to validate specific constraints

This method is explicitly allowed to change options depending on provided layout.
Parameters
- newHandles: ToolHandle[]
Returns boolean
Overridable

willUpdateOptions

willUpdateOptions(options?: string | string[]): void
when using custom getters/setters (via _get/_set) in options, the values of options can change without .set being called - or there might not even be a setter for readonly options; for example, if the getter simply returns the value of a member variable this variable could be modified directly. In this case, events such as optionChanged would not be fired, and listeners would not be informed about the change.

To account for such cases, the methods willUpdateOptions and didUpdateOptions should be called directly BEFORE and AFTER actions that might potentially change values of options. the correct events will then automatically be triggered when calling didUpdateOptions.

if the options that could change are known, they can be supplied via the optional parameter. This provides a small performance gain in most situations.

IMPORTANT: methods must be called in balance; e.g. for each call to willUpdateOptions, you must call didUpdateOptions exactly once.
Parameters
- Optionaloptions: string | string[]
Returns void
Inherited from Object.willUpdateOptions

writeCache

writeCache<Key extends string | number | symbol>(
cacheKey: Key,
value: CacheType[Key],
): void
Method that allows storing of values in an instance-specific cache Can be used to reduce the amount of necessary calculations (e.g. x/y-coordinates) by storing/retrieving them only when necessary Keys and values need to be defined in a type that will be passed to the parent BG.charts.Tool class
Type Parameters
- Key extends string | number | symbol
Parameters
- cacheKey: Key
- value: CacheType[Key]
Returns void

`Static`getAlternatives

getAlternatives(): {
    identifier: string;
    replace: (
        object: Record<string, any>,
    ) => {
        identifier: string;
        input?: string;
        objType: string;
        state: Record<string, any>;
    };
}[]
Method for plugins to describe which other plugins they want to replace

Returns {
    identifier: string;
    replace: (
        object: Record<string, any>,
    ) => {
        identifier: string;
        input?: string;
        objType: string;
        state: Record<string, any>;
    };
}[]

`Static`guard

guard(cb: Function): void
Parameters
- cb: Function
Returns void
Description
set custom error handler for event listeners

Inherited from Object.guard

`Static`listenerCount

listenerCount<
    EvType extends BG.events.Events,
    Type extends string | number | symbol,
>(
    emitter: EventEmitter<EvType>,
    type: Type,
): number
Type Parameters
- EvType extends BG.events.Events
- Type extends string | number | symbol
Parameters
- emitter: EventEmitter<EvType>
- type: Type
Returns number
Description
returns number of listeners on specified emitter for specified type

Inherited from Object.listenerCount

`Static`setDefaultMaxListeners

setDefaultMaxListeners(maxListeners: number): void
Parameters
- maxListeners: number
Returns void
Description
set default amount for limit warning

Inherited from Object.setDefaultMaxListeners

Class Tool<CacheType, Events>

Type Parameters

Hierarchy (View Summary)

Index

Constructors

Properties

Methods

Constructors

constructor

Type Parameters

Parameters

Returns BG.charts.Tool<CacheType, Events>

Properties

optionGroups

options

type

Methods

addListener

Type Parameters

Parameters

Returns this

Description

assignStyle

Parameters

Returns void

Overridable

attr

Parameters

Returns any

calculate

Parameters

Returns void

Overridable

clearCache

Returns void

clone

Returns BG.charts.Tool<CacheType>

Overridable

deserialize

Parameters

Returns void

Overridable

didUpdateOptions

Parameters

Returns void

draw

Parameters

Returns void

Overridable

emit

Type Parameters

Parameters

Returns boolean

Description

executeAction

Type Parameters

Parameters

Returns any

Overridable

finishInitialize

Parameters

Returns void

Overridable

flat

Parameters

Returns { [key: string]: any }

get

Parameters

Returns any

getActions

Parameters

Returns BG.charts.Tool.Action[]

Overridable

getBounds

Returns Bounds

Overridable

getBoundsInRange

Parameters

Returns false | Bounds

Overridable