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 enginePublic, safe interface of rendering engine.
Add a series to the ZoomBandChart.
This creates a duplicate of the supplied series that is displayed in the ZoomBandChart. The method returns a reference to the duplicate in ZBC that is usually the same type as the attached series (exception being OHLCSeries which is returned as LineSeries). This duplicate reference can be styled separately from the original series.
The ZoomBandChart automatically matches the data from the original series.
// Example usage
const zbcSeries = ZoomBandChart.add(myLineSeries)
.setStrokeStyle((stroke) => stroke.setThickness(2))
Series can be removed from ZoomBandChart with disposeSeries method.
Reference to duplicate series created in ZoomBandChart.
Series to attach.
Add a legendbox.
Legendbox is a type of UI element, that floats inside the chart/component it is created inside. It can be freely moved around with user interactions, as well as positioned in application code.
The purpose of legendbox is to describe the series and other visual components of the chart, by displaying their names and colors. Hovering over a series' legendbox entry will highlight that series, and clicking on the entry will toggle that series' visibility.
Legendbox alignment:
Alignment of legendbox can be selected by supplying one of the available LegendBoxBuilders to addLegendBox:
// Default (vertical) LegendBox.
const legendBox = ChartXY.addLegendBox()
// Horizontal LegendBox.
const horizontalLegendBox = ChartXY.addLegendBox(LegendBoxBuilders.HorizontalLegendBox)
Custom Legendbox positioning:
By default LegendBoxes are placed on the right side, or bottom of the chart (depending on alignment).
A custom location can be configured with UIElement API:
Position coordinate system is specified when creating legendbox.
addLegendBox( LegendBoxBuilders.VerticalLegendBox )
// Position = [0, 100] as percentages.
.setPosition({ x: 50, y: 50 })
addLegendBox( LegendBoxBuilders.VerticalLegendBox, chart.coordsRelative )
// Position = pixels.
.setPosition({ x: 300, y: 100 })
addLegendBox( LegendBoxBuilders.VerticalLegendBox, { x: chartXY.getDefaultAxisX(), y: chartXY.getDefaultAxisY() } )
// Position = Axis values.
.setPosition({ x: 5, y: 5 })
LegendBox
Optional builder: UILegendBoxBuilder<InternalBackground>LegendBoxBuilder. If omitted, VerticalLegendBox will be selected. Use LegendBoxBuilders for selection.
Optional scale: UserScaleDefinitionOptional parameter for altering the coordinate system used for positioning the LegendBox. Defaults to whole Chart in percentages [0, 100].
Add a stand-alone UIElement using a builder.
Object that fulfills interfaces: UIElementType (typeparam) and UIElement
Type of UIElement that is specified by 'builder'-parameter.
Optional uiElementBuilder: UIElementBuilder<UIElementType>Optional scale: LinearScaleXYOptional custom scale to position UIElement on. Defaults to whole component in percentages [0, 100].
Permanently destroy 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
Remove series from being display in the ZoomBandChart.
This method only needs to be called when you want to not display a series in the ZoomBandChart, but don't want to completely destroy it in the source chart.
You do not need to call this method if you are destroying the original series using the dispose method.
Object itself.
Series object.
Get fill style of "defocus overlay". This is formed of 2 separate rectangles, 1 on left and another on right side of the visible data range. By default its transparent dark to help user understand which part of data is visible.
FillStyle
Get Array of all legend boxes created using addLegendBox method.
This will not include any legend boxes that were destroyed with dispose method.
Array of legend boxes.
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 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 font of Chart title.
FontSettings object
Subscribe onDispose event.
This event is triggered whenever the Zoom BandChart is disposed.
// Example usage
zoomBandChart.onDispose(() => {
console.log('zoomBandChart was disposed')
})
zoomBandChart.dispose()
Token of subscription
Event handler function
Subscribe to resize event.
This event is triggered whenever the area of chart changes (due to document or dashboard resizing).
// Example usage,
ChartXY.onResize((chart, width, height, engineWidth, engineHeight) => {
console.log('Chart resized', 'width', width, 'height', height, 'engineWidth', engineWidth, 'engineHeight', engineHeight)
})
Token of subscription
Handler function for event
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'
saveToFile('screenshot')
// Attempt download 'maybeNotSupported.bmp'
saveToFile('maybeNotSupported', 'image/bmp')
// Attempt download jpeg.file with specified compression quality
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.
Set fillStyle of panel background.
Object itself
FillStyle or function which modifies it
Set stroke style of panel background.
Object itself
LineStyle or function which modifies it
Set fill style of "defocus overlay". This is formed of 2 separate rectangles, 1 on left and another on right side of the visible data range. By default its transparent dark to help user understand which part of data is visible.
Object itself.
FillStyle or function which modifies current fill style.
Set fill style of zoom band chart knobs. These are just UX indicators to help users understand you can drag the ZBC area left/right.
Object itself.
FillStyle or function which modifies current fill style.
Set size of zoom band chart knobs. These are just UX indicators to help users understand you can drag the ZBC area left/right.
Object itself.
Size as pixels
Set stroke style of zoom band chart knobs. These are just UX indicators to help users understand you can drag the ZBC area left/right.
Object itself.
LineStyle or function which modifies current LineStyle.
Set padding around Chart in pixels.
Object itself for fluent interface
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 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 FillStyle of series background (area behind series).
// Example usage,
ChartXY.setSeriesBackgroundFillStyle(new SolidFill({ color: ColorRGBA( 60, 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 series background border stroke.
// Example usage,
ChartXY.setSeriesBackgroundStrokeStyle(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 Zoom band chart splitter stroke style. This separates the visible data set from full data set.
Object itself.
LineStyle or function which modifies current LineStyle.
Set text of Chart title.
Object itself for fluent interface.
Chart title as a string.
Set fill style of Chart Title.
Example usage:
// Create a new style
ZoomBandChart.setTitleFillStyle(new SolidFill({ color: ColorHEX('#F00') }))
// Change transparency
ZoomBandChart.setTitleFillStyle((solidFill) => solidFill.setA(80))
// Set hidden
ZoomBandChart.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
ZoomBandChart.setTitleFont(new FontSettings({ size: 24, style: 'italic' }))
// Change existing settings
ZoomBandChart.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 Margins after chart title.
This does not have an effect if title is hidden (empty FillStyle).
// Example 1, specify complete margin for Title (four sides).
ZoomBandChart.setTitleMargin({ left: 16, right: 16, top: 32, bottom: 8 })
// Example 2, specify only single margin for Title.
ZoomBandChart.setTitleMargin({ right: 64 })
// Example 2, specify margins for all sides with same value for Title.
ZoomBandChart.setTitleMargin(40)
Chart itself for fluent interface
Gap after the chart title in pixels.
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.
})
Chart that is used to display a fully zoomed out view of 1 or more charts or series. It also provides convenient built-in user interactions for interacting with the attached chart(s) that show the zoomed in view.
By nature, ZoomBandChart does not host any original data. Rather, it is a duplicate of other data sets in order to simultaneously show both zoomed in view and fully zoomed out view.
ZoomBandChartcan be created in two different ways - to learn more about creation time configuration ofZoomBandChart, please refer to:ZoomBandChart features