Callback function that is triggered when event is fired.
Optional info: unknownOptional options: LCJSAddEventListenerOptionsOptional extra configuration options.
Alter existing samples in the data set by identifying them with their sample index.
This simply refers to a incrementing counter of when each sample was first introduced.
For example, 0 refers to first sample that was added to data set.
When data cleaning is enabled, sample indexes do NOT shift. They always point to unique samples, even if old samples are removed.
// Example, alter by sample index
dataSet.alterSamplesByIndex([0, 10], {
yValues: [20, 30]
})
See also:
Object itself.
Array of sample indexes to alter.
Values that are placed into selected samples, replacing previous values. Can be arrays, or a number to use same value for all altered samples.
Alter existing samples in the data set.
This method alters existing samples after selecting them based on:
"x", "id") // Example, basic usage
const dataSet = new DataSetXY()
dataSet.appendSamples({
ids: [0, 1, 2],
yValues: [10, 12, 7],
})
dataSet.alterSamplesByMatch("ids", [1], {
yValues: [20]
})
// result yValues = [10, 20, 7]
// Example, apply same value to all altered samples
dataSet.alterSamplesByMatch("ids", [0, 1, 2], { size: 5 })
See also:
Object itself.
Data property that is used to select samples that should be altered.
Array of values that are checked from matchKey data values to select samples that should be altered.
Values that are placed into selected samples, replacing previous values. Can be arrays, or a number to use same value for all altered samples.
Alter a continuous range of existing samples in the data set. This method also supports automatically appending samples when attempting to alter samples that don't exist in data set.
This method alters existing samples by referencing sample indexes.
This simply refers to a incrementing counter of when each sample was first introduced.
For example, 0 refers to first sample that was added to data set.
When data cleaning is enabled, sample indexes do NOT shift. They always point to unique samples, even if old samples are removed.
// Example, basic usage - set first sample to { x: 0, y: 0 }
DataSetXY.alterSamples(0, {
x: [0],
y: [1]
})
// Example, alter several samples at once - set first sample to { x: 0, y: 10 }, second sample to { x: 1, y: 11 } and so on.
DataSetXY.alterSamples(0, {
x: [0, 1, 2],
y: [10, 11, 12]
})
// Example, alter last sample to have y = 0.
DataSetXY.alterSamples(DataSetXY.getNextSampleIndex() - 1, {
y: [0]
})
See also:
Object itself.
First altered sample index.
Object with new sample values. Behaves same as appendSamples.
Optional opts: { Extra options. Behaves same as appendSamples.
Optional count?: numberOptional offset?: numberOptional start?: numberOptional step?: numberAdd several samples by reading from an Array of JavaScript objects.
// Example, read x + y
const arr = [{ x: 0, y: 0 }]
DataSetXY.appendJSON(arr)
// Example, property names can be anything
const arr = [{ timestamp: 0, voltage: 0 }]
DataSetXY.appendJSON(arr)
// Input type can also be list of tuples
const arr = [
[0, 100],
[1, 110]
]
DataSetXY.appendJSON(arr)
appendJSON will by default store all supplied data properties.
If you only want to load specific properties into the data set, then you should whitelist them:
DataSetXY.appendJSON(data, { whitelist: ['index', 'value'] })
Important: the supplied objects' keys refer to keys of the data sets schema. If schema is not defined, then this operation will set it according to supplied keys with default values.
This operation will push data to a DataSetXY object (either directly or via series).
By default, series will connect to data properties that seem logical.
It is, however, recommended to explicitly connect X and Y (etc.) to the correct, specific data properties using data mapping:
// Data mapping is specified on a series
series.setDataMapping({ x: 'timestamp', y: 'voltage' })
Supported data property types:
numberDate objectColor objectnumber (uint32, least significant byte = red). Using Color objects in large quantities should be avoided for performance reasons.nonNumeric: true; any value (string, boolean, etc.)For more detailed documentation, please see Developer documentation.
Object itself.
Array with JSON objects which represent samples.
Optional opts: { Optional extra arguments.
Optional blacklist?: string[]Optional start?: numberOptional step?: numberOptional whitelist?: string[]Optional fill: Record<string, number | Color>Optional data values to act as "fill behavior", i.e. fill same value for all added samples during this operation.
Add 1 sample to data set.
// Example, basic usage
DataSetXY.appendSample({ x: 0, y: 0 })
// Example, only 1 value
DataSetXY.appendSample({ temperature: 0 })
appendSample will by default store all supplied data properties.
If you only want to load specific properties into the data set, then you should whitelist them:
DataSetXY.appendSample(sample, { whitelist: ['index', 'value'] })
Important: the supplied objects keys refer to keys of the data sets schema. If schema is not defined, then this operation will set it according to supplied keys with default values.
This operation will push data to a DataSetXY object (either directly or via series).
By default, series will connect to data properties that seem logical.
It is, however, recommended to explicitly connect X and Y (etc.) to the correct, specific data properties using data mapping:
// Data mapping is specified on a series
series.setDataMapping({ x: 'index', y: 'value' })
Supported data property types:
numberDate objectColor objectnumber (uint32, least significant byte = red). Using Color objects in large quantities should be avoided for performance reasons.nonNumeric: true; any value (string, boolean, etc.)For more detailed documentation, please see Developer documentation.
Object itself.
Optional opts: { Optional extra arguments.
Optional blacklist?: string[]Optional start?: numberOptional step?: numberOptional whitelist?: string[]Add a list of samples to data set.
// Example, basic usage.
DataSetXY.appendSamples({
xValues: [0, 1, 2],
yValues: [100, 101, 102],
})
Important: the object keys ("xValues" in above example) refer to keys of the data sets schema. If schema is not defined, then this operation will set it according to supplied keys with default values.
This operation will push data to a DataSetXY object (either directly or via series).
By default, series will connect to data properties that seem logical.
It is, however, recommended to explicitly connect X and Y (etc.) to the correct, specific data properties using data mapping:
// Data mapping is specified on a series
series.setDataMapping({ x: 'xValues', y: 'yValues' })
More examples:
// Example, only 1 value
DataSetXY.appendSamples({
temperatures: [100, 101, 102],
})
// Example, typed array input.
DataSetXY.appendSamples({
temperatures: new Float32Array([100, 101, 102]),
})
// Example, uint32 colors
DataSetXY.appendSamples({
x: [0, 1, 2],
y: [100, 101, 102],
colors: [0xff0000ff, 0xff00ff00, 0xffff0000]
})
Passing arrays or single values can be freely alternated between, as long as at least one Array-like argument is supplied. Single value means using same argument for every new sample defined in the method call.
// Example, use same color for every sample
DataSetXY.appendSamples({
yValues: [0, 10, 5],
color: ColorRGBA(255, 0, 0)
})
Supported data property types:
number[]numberDate[]Color object or Color[]number (uint32, least significant byte = red). Using Color objects in large quantities should be avoided for performance reasons.nonNumeric: true; any value (string, boolean, etc.)offset property can optionally be used to start reading values from middle of input array.
Can be situationally useful.
For more detailed documentation, please see Developer documentation.
Object itself.
Optional opts: { Optional extra arguments.
Optional count?: numberOptional offset?: numberOptional start?: numberOptional step?: numberClear all samples in the data set.
Object itself.
Load same value or many values to all samples that currently exist in the data set.
// Example, set "size" of all samples to 5
DataSetXY.fill({ size: 5 })
Supported data property types:
numberDate objectColor objectnumber (uint32, least significant byte = red). Using Color objects in large quantities should be avoided for performance reasons.nonNumeric: true; any value (string, boolean, etc.)Object itself.
Object with data properties.
Get current configured maximum sample count. See setMaxSampleCount for more information.
Number of undefined.
Remove event listener added using addEventListener.
The expected argument should be the exact same callback function that was supplied using addEventListener:
// Basic example syntax
const listener = () => {}
obj.addEventListener('click', listener)
obj.removeEventListener('click', listener)
// Basic boilerplate of custom interaction when user drags on an object
obj.addEventListener('pointerdown', (eventDown) => {
let prevCoord = eventDown
const handlePointerMove: LCJSInteractionEventListener<'pointermove'> = (eventMove) => {
const delta = { x: eventMove.clientX - prevCoord.clientX, y: eventMove.clientY - prevCoord.clientY }
prevCoord = eventMove
console.log(delta, eventMove.clientX, eventMove.clientY)
}
const handlePointerUp: LCJSInteractionEventListener<'pointerup'> = (eventUp) => {
window.removeEventListener('pointermove', handlePointerMove)
window.removeEventListener('pointerup', handlePointerUp)
}
window.addEventListener('pointermove', handlePointerMove)
window.addEventListener('pointerup', handlePointerUp)
})
Listener that was added using addEventListener.
Optional info: unknownAll real-time use cases (where data points are pushed in periodically) must define a "max sample count".
// Example, keep maximum 1 million samples
PointLineAreaSeries.setMaxSampleCount(1_000_000)
This allocates the required amount of memory beforehand, which is crucial to get the best performance. After 1 million samples are reached, the oldest samples will start dropping out.
Alternatively, if you are uncertain what value to use and don't want to allocate too much memory up-front, you can start small and automatically increase the buffer size as samples flow in:
PointLineAreaSeries.setMaxSampleCount({ mode: 'auto', max: 10_000_000 })
This would first allocate only small amount of memory, progressively increase memory allocation as samples come in until eventually limiting sample count to 10 million.
Object itself.
Max sample count.
All real-time use cases (where data points are pushed in periodically) must define a "max sample count".
// Example, keep maximum 1 million samples
PointLineAreaSeries.setMaxSampleCount(1_000_000)
This allocates the required amount of memory beforehand, which is crucial to get the best performance. After 1 million samples are reached, the oldest samples will start dropping out.
Alternatively, if you are uncertain what value to use and don't want to allocate too much memory up-front, you can start small and automatically increase the buffer size as samples flow in:
PointLineAreaSeries.setMaxSampleCount({ mode: 'auto', max: 10_000_000 })
This would first allocate only small amount of memory, progressively increase memory allocation as samples come in until eventually limiting sample count to 10 million.
Object itself.
Optional initial?: numberOptional max?: numberRe-specify all values in the data set. This is a convenience method that is fundamentally equal to:
DataSetXY.clear().appendSamples({ ... })
There are currently no performance differences between using "setSamples" versus "clear + append".
However, in future it is possible that setSamples can receive optimizations which would make it recommended over "clear + append".
In the mean-time, setSamples is recommended for simplicity and clarity in end user applications.
For parameters documentation, refer to appendSamples method.
Object itself.
Optional opts: { Optional count?: numberOptional offset?: numberOptional start?: numberOptional step?: number
Add callback function to be triggered when specified event is fired.
Some classes also report extra information about the interacted object with the second parameter:
Optional third parameter allows registering event handlers that will automatically remove themselves after first trigger:
Each class has its own list of supported events. Some events are from HTML standard (
click,pointerdown, etc.), while others are own events from LightningChart JS (dispose,resize, etc.)To find what events are available, you can try following:
TypeScriptenabled, just writeaddEventListenerand see what possible event types the IDE suggests. These APIs are strongly typed, and even the callback event will be correctly typed.Ktype parameter extends.