Protected _isFlag that is set whenever Panel or any scale is resized.
Will be handled before plot to update scale and trigger resize event just once per frame.
Readonly backgroundInterface for attaching listeners to user interaction events (click, pointerenter, etc.) on chart background.
// Example syntax
chart.background.addEventListener('click', (event) => {
console.log(event)
})
For syntax examples, refer to EventInterface. Available event keys are listed under LCJSInteractionEventMap
Please note that many chart types have a separate "series background" (area enclosed by axes), which has its own separate events. This is accessed via seriesBackground property.
Readonly coordsSelector for "client" Coordinate System.
This references the coordinate system used in HTML.
It starts at top left of the web page and is measured in pixels.
For example, { x: 100, y: 20 } corresponds to 100 pixels from left and 20 pixels from top.
JavaScript events are tracked and HTML elements are positioned in the client coordinate system.
This selector can be used for translating client coordinates to other coordinate systems and vice versa. For example, in order to:
See translateCoordinate for more detailed use case information and example usage.
Readonly coordsSelector for "relative" Coordinate System.
This coordinate system is relative to the bottom left corner of the Control (chart/dashboard/etc.), and is measured as pixels.
For example, { x: 100, y: 20 } corresponds to 100 pixels from left and 20 pixels from bottom.
This selector can be used for two purposes:
Positioning LCJS UI elements in pixels:
// Position UI element in pixels by supplying `Control.coordsRelative` as its positioning system.
const textBox = Control.addUIElement(UIElementBuilders.TextBox, Control.coordsRelative)
.setOrigin(UIOrigins.LeftBottom)
.setPosition({ x: 100, y: 20 })
Translations between coordinate systems:
Use with translateCoordinate method to translate coordinates from "relative" to another coordinate system.
Readonly engineInterface for end user API of the LCJS engine. It provides some useful capabilities over the area enclosed by a single LCJS context (which can be just a single chart, or a Dashboard with several charts).
Readonly legendThe default Legend reference of the panel.
Readonly titleInterface for attaching listeners to user interaction events (click, pointerenter, etc.) on chart title.
// Example syntax
chart.title.addEventListener('click', (event) => {
console.log(event)
})
For syntax examples, refer to EventInterface. Available event keys are listed under LCJSInteractionEventMap
Scale for panel area in percentages (0-100).
While it is not functionally equal to this, using coordsRelative coordinate system is preferred (more confidence for long term support).
Add callback function to be triggered when specified event is fired.
// Example syntax
object.addEventListener('click', (event) => {
console.log(event)
})
Some classes also report extra information about the interacted object with the second parameter:
// Most series share information about interacted data point
series.addEventListener('click', (event, info) => {
console.log(info)
})
Optional third parameter allows registering event handlers that will automatically remove themselves after first trigger:
// Example this listener will only fire once
object.addEventListener('click', (event) => {})
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:
TypeScript enabled, just write addEventListener and see what possible event types the IDE suggests. These APIs are strongly typed, and even the callback event will be correctly typed.K type parameter extends.Callback function that is triggered when event is fired.
Optional options: LCJSAddEventListenerOptionsOptional extra configuration options.
Add a new legend to the chart.
Optional options: LegendOptions & { Add a stand-alone UIElement using a builder.
Example usage:
addUIElement( UIElementBuilders.TextBox )
// Position = [0, 100] as percentages.
.setPosition({ x: 50, y: 50 })
addUIElement( UIElementBuilders.TextBox, chart.coordsRelative )
// Position = pixels.
.setPosition({ x: 300, y: 100 })
addUIElement( UIElementBuilders.TextBox, { x: chartXY.getDefaultAxisX(), y: chartXY.getDefaultAxisY() } )
// Position = Axis values.
.setPosition({ x: 5, y: 5 })
Object that fulfills interfaces: UIElementType (typeparam) and UIElement
Type of UIElement that is specified by 'builder'-parameter.
UIElementBuilder. If omitted, TextBoxBuilder will be selected. Use UIElementBuilders for selection.
Optional parameter for altering the coordinate system used for positioning the UIElement. Defaults to whole Chart in percentages [0, 100].
Permanently dispose the component.
To fully allow Garbage-Collection to free the resources used by the component, make sure to remove any references to the component and its children in application code.
let chart = ...ChartXY()
let axisX = chart.getDefaultAxisX()
// Dispose Chart, and remove all references so that they can be garbage-collected.
chart.dispose()
chart = undefined
axisX = undefined
Object itself for fluent interface
Get theme effect enabled on component or disabled.
A theme can specify an Effect to add extra visual oomph to chart applications, like Glow effects around data or other components.
Whether this effect is drawn above a particular component can be configured using the setEffect method.
// Example, disable theme effect from a particular component.
Component.setEffect(false)
For the most part, theme effects are enabled by default on most components.
Theme effect is configured with effect property.
Boolean that describes whether drawing the theme effect is enabled around the component or not.
Get theme effect enabled on component or disabled.
A theme can specify an Effect to add extra visual oomph to chart applications, like Glow effects around data or other components.
Whether this effect is drawn above a particular component can be configured using the setEffect method.
// Example, disable theme effect from a particular component.
Component.setEffect(false)
For the most part, theme effects are enabled by default on most components.
Theme effect is configured with effect property.
Boolean that describes whether drawing the theme effect is enabled around the component or not.
Get linear gauge ranges.
Linear gauge ranges
Get size of control as pixels.
For stand-alone component, the size will be equal to the size of its containing HTML <div> (Control.engine.container)
For component inside Dashboard, the size will only include the component itself, so size can be less than the size of containing HTML <div>.
Object with x and y properties { x: number, y: number }, where both are pixel values.
Get the font of gauge ticks.
FontSettings object
Not to be confused with GlowEffect
Get theme effect enabled on component or disabled.
A theme can specify an Effect to add extra visual oomph to chart applications, like Glow effects around data or other components.
Whether this effect is drawn above a particular component can be configured using the setEffect method.
// Example, disable theme effect from a particular component.
Component.setEffect(false)
For the most part, theme effects are enabled by default on most components.
Theme effect is configured with effect property.
Boolean that describes whether drawing the theme effect is enabled around the component or not.
Get font of Chart title.
FontSettings object
Not to be confused with GlowEffect
Get the font of value label.
FontSettings object
Not to be confused with GlowEffect
Get value marker shape.
PointShape
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.
Capture rendered state in an image file. Prompts the browser to download the created file.
NOTE: The download might be blocked by browser/plugins as harmful. To prevent this, only call the method in events tied to user-interactions. From mouse-event handlers, for example.
Has two optional parameters which directly reference JavaScript API HTMLCanvasElement.toDataURL. For supported image formats, compression quality, Etc. refer to:
https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/toDataURL
Example usage:
// Download 'screenshot.png'
Panel.saveToFile('screenshot')
// Attempt download 'maybeNotSupported.bmp'
Panel.saveToFile('maybeNotSupported', 'image/bmp')
// Attempt download jpeg.file with specified compression quality
Panel.saveToFile('fileName', 'image/jpeg', 0.50)
If 'type' is not supported by browser, an Error will be thrown.
Name of prompted download file as string. File extension shouldn't be included as it is automatically detected from 'type'-argument.
Optional type: stringA DOMString indicating the image format. The default format type is image/png.
Optional encoderOptions: numberA Number between 0 and 1 indicating the image quality to use for image formats that use lossy compression such as image/jpeg and image/webp. If this argument is anything else, the default value for image quality is used. The default value is 0.92.
Optional scale: numberConvenience output scaling factor. This doesn't actually stretch the result, but instead draws an altered scaled version and captures that.
Disable/Enable all animations of the Chart.
chart.setAnimationsEnabled(true)
Chart itself for fluent interface.
Boolean value to enable or disable animations.
Set FillStyle of chart background.
// Example usage,
ChartXY.setBackgroundFillStyle(new SolidFill({ color: ColorRGBA( 80, 0, 0 ) }))
Related API:
Transparent chart backgrounds:
LightningChart JS charts can be configured to be fully or partially transparent.
// Example, partially transparent chart
// Engine background exists under all LCJS components. In case of Dashboard, there is only 1 shared engine background.
chart.engine.setBackgroundFillStyle(emptyFill)
// Chart background covers every 1 chart. In case of Dashboard, every chart has its own chart background.
chart.setBackgroundFillStyle(new SolidFill({ color: ColorRGBA(0, 0, 0, 100) }))
// Some charts also have a separate series background.
chart.setSeriesBackgroundFillStyle(new SolidFill({ color: ColorRGBA(0, 0, 0, 100) }))
Object itself
FillStyle or function which mutates the active FillStyle.
Set LineStyle of chart background border stroke.
// Example usage,
ChartXY.setBackgroundStrokeStyle(new SolidLine({
thickness: 2,
fillStyle: new SolidFill({ color: ColorRGBA( 0, 255, 0 ) })
}))
Related API:
Object itself
LineStyle or function which mutates the active LineStyle.
Set theme effect enabled on component or disabled.
A theme can specify an Effect to add extra visual oomph to chart applications, like Glow effects around data or other components.
Whether this effect is drawn above a particular component can be configured using the setEffect method.
// Example, disable theme effect from a particular component.
Component.setEffect(false)
For the most part, theme effects are enabled by default on most components.
Theme effect is configured with effect property.
Object itself.
Theme effect enabled
Set the StrokeStyle of the gauge bar, i.e., the gauge bar border.
chart.setBarStrokeStyle(
new SolidLine({
thickness: 2,
fillStyle: new SolidFill({ color: ColorRGBA(255, 0, 0) }),
}),
)
Object itself
LineStyle or mutator to modify existing one
Set the thickness of the gauge bar.
chart.setBarThickness(20)
Object itself
Thickness in pixels
Set color interpolation enabled.
If color interpolation is enabled, the chart will automatically assign each bar a linear gradient fill rather than just solid color.
Object itself
Boolean
Set auto gradients enabled.
Gradients are only applied if color interpolation is disabled (setColorInterpolation)
If gradients are enabled, and color interpolation disabled, the chart will automatically assign each bar a linear gradient fill rather than just solid color.
Object itself
Boolean
Set theme effect enabled on component or disabled.
A theme can specify an Effect to add extra visual oomph to chart applications, like Glow effects around data or other components.
Whether this effect is drawn above a particular component can be configured using the setEffect method.
// Example, disable theme effect from a particular component.
Component.setEffect(false)
For the most part, theme effects are enabled by default on most components.
Theme effect is configured with effect property.
Object itself.
Theme effect enabled
Set padding around Chart in pixels.
// Example 1, specify complete padding (four sides).
ChartXY.setPadding({ left: 16, right: 16, top: 32, bottom: 8 })
// Example 2, specify only single padding.
ChartXY.setPadding({ right: 64 })
Object itself
Number with pixel margins for all sides or datastructure with individual pixel paddings for each side. Any side can be omitted, only passed values will be overridden.
Set whether all rendering of this component should temporarily be paused.
While an LCJS component is paused, you can use all its APIs normally, but there will be no visual updates what so ever. This is mainly intended to be used for performance saving to put charts into hibernation when they wouldn't be visible in the application either way.
While paused, charts postpone many heavy computations that would be otherwise done in order to re-render.
Object itself
Boolean
Optional opts: RenderingPauseOptionsSet ranges displayed by the linear gauge chart.
// Example with solid stepping gauge
gauge.setRanges([
{ start: 0, color: ColorCSS('red') },
{ start: 4, color: ColorCSS('green') },
{ start: 7, end: 10, color: ColorCSS('blue') },
])
gauge.setColorInterpolation(false)
// Example with interpolated gauge steps
gauge.setRanges([
{ start: 0, color: ColorCSS('red') },
{ start: 5, color: ColorCSS('green') },
{ start: 10, color: ColorCSS('blue') },
])
gauge.setColorInterpolation(true)
Object itself
linear gauge ranges
Enable or disable rounded edges.
chart.setRoundedEdges(false)
Object itself
Boolean flag
Set the FillStyle of gauge ticks.
chart.setTickFillStyle(
new SolidFill({
color: ColorRGBA(255, 0, 0),
}),
)
Object itself
FillStyle or mutator to modify existing one
Set the FontSettings of gauge ticks.
// Example, set font size
chart.setTickFont((font) => font.setSize(16))
Object itself
FontSettings or mutator to modify existing one
Set the formatter function of gauge ticks.
chart.setTickFormatter((value) => value.toFixed(1))
Object itself
Callback function to format tick values
Set pixel margin between tick labels and bar.
Object itself
number
Not to be confused with GlowEffect
Set text of Chart title.
Object itself for fluent interface.
Chart title as a string.
Set theme effect enabled on component or disabled.
A theme can specify an Effect to add extra visual oomph to chart applications, like Glow effects around data or other components.
Whether this effect is drawn above a particular component can be configured using the setEffect method.
// Example, disable theme effect from a particular component.
Component.setEffect(false)
For the most part, theme effects are enabled by default on most components.
Theme effect is configured with effect property.
Object itself.
Theme effect enabled
Set fill style of Chart Title.
Example usage:
// Create a new style
Chart.setTitleFillStyle(new SolidFill({ color: ColorHEX('#F00') }))
// Change transparency
Chart.setTitleFillStyle((solidFill) => solidFill.setA(80))
// Set hidden
Chart.setTitleFillStyle(emptyFill)
Chart itself
Either a FillStyle object or a function, which will be used to create a new FillStyle based on current value.
Set font of Chart Title.
Example usage:
// Create a new FontSettings
Chart.setTitleFont(new FontSettings({ size: 24, style: 'italic' }))
// Change existing settings
Chart.setTitleFont((fontSettings) => fontSettings.setWeight('bold'))
Chart itself
Either a FontSettings object or a function, which will be used to create a new FontSettings based on current value.
Specifies padding after chart title.
This does not have an effect if title is hidden (empty FillStyle).
// Example 1, specify vertical margins
ChartXY.setTitleMargin({ top: 0, bottom: 10 })
// Example 2, specify margins for all sides with same value for Title.
ChartXY.setTitleMargin(40)
Chart itself for fluent interface
Gap after the chart title in pixels.
Set rotation of Chart title.
Object itself
Rotation in degrees
Not to be confused with GlowEffect
Set the value of the gauge.
chart.setValue(100)
Object itself
Gauge value
Enable or disable value animations.
// Slow down animation
chart.setValueAnimation(true, 0.75)
// Speed up animation
chart.setValueAnimation(true, 1.25)
// Disable animation
chart.setValueAnimation(false)
Object itself
Boolean flag
Optional value for adjusting the speed of the animation
Set the text or formatting of the value label.
chart.setValueFormatter((value) => value.toFixed(1))
Object itself
String value or callback function to format the value label
Set value marker label alignment in dimension opposite to bar orientation.
For example, in case of a vertical linear gauge:
0 = position value marker label at center of bar-1 = position value marker label at left edge of bar1 = position value marker label at right edge of bar2 = position value marker label 50% bar thickness away from right edge of bar // Example syntax
gauge.setValueLabelAlignment(0)
Object itself
Number
Set the FillStyle of the value label.
chart.setValueLabelFillStyle(
new SolidFill({
color: ColorRGBA(255, 0, 0),
}),
)
Object itself
FillStyle or mutator to modify existing one
Set the FontSettings of the value label.
// Example, set font size
chart.setValueLabelFont((font) => font.setSize(16))
Object itself
FontSettings or mutator to modify existing one
Not to be confused with GlowEffect
Set value marker alignment in dimension opposite to bar orientation.
For example, in case of a vertical linear gauge:
0 = position value marker at center of bar-1 = position value marker at left edge of bar1 = position value marker at right edge of bar2 = position value marker 50% bar thickness away from right edge of bar // Example syntax
gauge.setValueMarkerAlignment(0)
Object itself
Number
Set value marker fill style.
// Example syntax
gauge.setValueMarkerFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
Object itself
FillStyle or function which modifies existing value.
Set value marker rotation as degrees
// Example syntax
gauge.setValueMarkerRotation(45)
Object itself
rotation as degrees
Set value marker shape.
// Example syntax
gauge.setValueMarkerShape(PointShape.Arrow)
Object itself
PointShape or Icon
Set value marker size as pixels.
// Example syntax
gauge.setValueMarkerSize(10)
Object itself
Size as pixels
Set value marker stroke style.
// Example syntax
gauge.setValueMarkerStrokeStyle(new SolidLine({ thickness: 1, fillStyle: new SolidFill({ color: ColorRGBA(255, 0, 0) }) }))
Object itself
LineStyle or function which modifies existing value.
Translate a coordinate in HTML client coordinate system to relative coordinates within the component.
const locationClient = { clientX: document.body.clientWidth * 0.2, clientY: document.body.clientHeight * 0.5 }
const locationRelative = chart.translateCoordinate(locationClient, chart.coordsRelative)
// locationRelative is in pixels relative to bottom left corner of the chart
Relative coordinates can be used for positioning LightningChart JS UI components:
const textBox = chart.addUIElement(UIElementBuilders.TextBox, chart.coordsRelative)
// Left bottom of TextBox is positioned 20 pixels right and 20 pixels up from charts bottom left corner
.setOrigin(UIOrigins.LeftBottom)
.setPosition({ x: 20, y: 20 })
NOTE: Currently coordinate translations can't be guaranteed to be in sync with latest updates to charts.
For example, if you change axis interval, or add data to a series, you need to wait for 1 frame to be displayed before translateCoordinate will behave as expected.
LineSeries.add(myData)
requestAnimationFrame(() => {
// translateCoordinate should now consider data added just now.
})
Translate a coordinate from relative control coordinates to HTML client coordinate system.
// 10 pixels left and 20 pixels up from controls bottom left corner
const locationRelative = { x: 10, y: 20 }
const locationClient = chart.translateCoordinate(locationRelative, chart.coordsRelative, chart.coordsClient)
Client coordinates can be used to absolute position HTML elements using CSS, for example.
myHTMLElement.style.position = 'absolute'
myHTMLElement.style.left = locationClient.clientX
myHTMLElement.style.top = locationClient.clientY
NOTE: Currently coordinate translations can't be guaranteed to be in sync with latest updates to charts.
For example, if you change axis interval, or add data to a series, you need to wait for 1 frame to be displayed before translateCoordinate will behave as expected.
LineSeries.add(myData)
requestAnimationFrame(() => {
// translateCoordinate should now consider data added just now.
})
Linear gauge chart component