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.
Add new BarChart to dashboard at specified location and span.
Throws an error if either column/row index is less than 0 or index + span is more than Dashboards numberOfColumns/Rows.
BarChart.
Options object for creating a BarChart.
Add new Chart3D to dashboard at specified location and span.
Throws an error if either column/row index is less than 0 or index + span is more than Dashboards numberOfColumns/Rows.
Chart3D.
Options object for creating a Chart3D.
Add new ChartXY to dashboard at specified location and span.
Throws an error if either column/row index is less than 0 or index + span is more than Dashboards numberOfColumns/Rows.
ChartXY.
Options object for creating a chartXY.
Add new DataGrid to dashboard at specified location and span.
Throws an error if either column/row index is less than 0 or index + span is more than Dashboards numberOfColumns/Rows.
DataGrid.
Options object for creating a DataGrid.
Add new FunnelChart to dashboard at specified location and span.
Throws an error if either column/row index is less than 0 or index + span is more than Dashboards numberOfColumns/Rows.
FunnelChart.
Options object for creating a FunnelChart.
Add new GaugeChart to dashboard at specified location and span.
Throws an error if either column/row index is less than 0 or index + span is more than Dashboards numberOfColumns/Rows.
GaugeChart.
Optional options: GaugeOptions<GaugeChartType>Options object for creating a GaugeChart.
Create a new legend box panel, a convenience component for placing legend box items from multiple different charts into a single row layout, to dashboard at specified location and span.
Refer to UILegendBoxPanel for more information, like example usage.
Throws an error if either column/row index is less than 0 or index + span is more than Dashboards numberOfColumns/Rows.
UILegendBoxPanel.
Options object for creating a legend box panel.
Factory for MapChart. This chart visualizes a Map of the selected part of the world. Defaults to the entire world.
It has built-in cursor functionality and supports dynamic region coloring.
To learn more about its features, refer to MapChart.
Dashboard cell configuration:
When inside a Dashboard, the chart location relative to the Dashboard must be supplied when it is created.
// Example, dashboard cell configuration.
const chart = Dashboard.createMapChart({
// X location, 0 = left.
columnIndex: 0,
// Y location, 0 = top.
rowIndex: 0,
// Amount of X cells allocated for this chart.
columnSpan: 1,
// Amount of Y cells allocated for this chart.
rowSpan: 1,
})
Readonly configuration:
Some properties of MapChart can only be configured when it is created. These arguments are all optional,
and are wrapped in a single object parameter:
// Example, specify map type.
const chart = LightningChart.Map({
type: MapTypes.Europe
})
For general chart properties, like specifying DOM container, rendering engine configuration, refer to EngineOptions.
For MapChart specific properties, refer to MapChartOptions.
Created chart.
Object with readonly configuration arguments for MapChart.
Add new PieChart to dashboard at specified location and span.
Throws an error if either column/row index is less than 0 or index + span is more than Dashboards numberOfColumns/Rows.
PieChart.
Options object for creating a PieChart.
Add new PolarChart to dashboard at specified location and span.
Throws an error if either column/row index is less than 0 or index + span is more than Dashboards numberOfColumns/Rows.
PolarChart.
Options object for creating a PolarChart chart.
Add new PyramidChart to dashboard at specified location and span.
Throws an error if either column/row index is less than 0 or index + span is more than Dashboard's numberOfColumns/Rows.
PyramidChart
Options object for creating a PyramidChart.
Add new SpiderChart to dashboard at specified location and span.
Throws an error if either column/row index is less than 0 or index + span is more than Dashboards numberOfColumns/Rows.
SpiderChart.
Options object for creating a Spider chart.
Create a container for UI objects on dashboard with specified location and span.
Throws an error if either column/row index is less than 0 or index + span is more than Dashboards numberOfColumns/Rows.
Panel.
Options object for creating a UIPanel.
Add new ZoomBandChart to dashboard at specified location and span.
Throws an error if either column/row index is less than 0 or index + span is more than Dashboards numberOfColumns/Rows.
ZoomBandChart.
Options object for creating a ZoomBandChart.
Readonly enginePublic, safe interface for Dashboards rendering engine.
Readonly pixelScale that represents dashboard area in pixels.
This method signature is deprecated since v4.2.0. Use coordsRelative instead. It works exactly the same.
Readonly uiScale that represents dashboard area in percents (0-100).
While it is not functionally equal to this, using coordsRelative coordinate system is preferred (more confidence for long term support)
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 })
Inside Dashboard, a UILegendBoxPanel can also be used for simplified creation of legendboxes for several charts.
LegendBox
LegendBoxBuilder. If omitted, VerticalLegendBox will be selected. Use LegendBoxBuilders for selection.
Optional 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.
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
Optional parameter for altering the coordinate system used for positioning the UIElement. Defaults to whole Dashboard 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
Get all defined cells in the dashboard.
Further action can be done by testing the cell.panel for the instance type that you want to be interacting with.
Example:
const cells = dashboard.getCells()
cells.forEach((cell) => {
if (cell.panel instanceof Chart3D) {
cell.panel.setBoundingBox({ x: 2, y: 1, z: 1 })
}
})
All cells with content in dashboard
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 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 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.
Subscribe onDispose event.
This event is triggered whenever the Control (Dashboards and all chart types) is disposed.
// Example usage
Dashboard.onDispose(() => {
console.log('Dashboard was disposed')
})
Dashboard.dispose()
Token of subscription
Subscribe to inViewChange event.
This event is triggered when the chart transitions from being off-screen to being on-screen and vice versa.
Token of subscription
Subscribe to resize event.
This event is triggered whenever the size of dashboard changes (due to document or dashboard resizing).
// Example usage,
Dashboard.onResize((_, width, height, engineWidth, engineHeight) => {
console.log('Dashboard resized', 'width', width, 'height', height, 'engineWidth', engineWidth, 'engineHeight', engineHeight)
})
This event is also triggered whenever dashboard splitter layout is changed, even if actual dashboard size is unchanged.
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'
Dashboard.saveToFile('screenshot')
// Attempt download 'maybeNotSupported.bmp'
Dashboard.saveToFile('maybeNotSupported', 'image/bmp')
// Attempt download jpeg.file with specified compression quality
Dashboard.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 component highlight animations enabled or not. For most components this is enabled by default.
// Example usage, disable highlight animations.
component.setAnimationHighlight(false)
Object itself
Animation enabled?
Set fillStyle of dashboard background.
Object itself
FillStyle or mutator to modify existing one
Set stroke style of dashboard background.
Object itself
LineStyle
Set width of a column in relation to other columns. By default all column widths are 1.
By changing one columns width to 2, it would make that column allocate twice as much width as others.
// Example, Dashboard with 3 columns with widths (20%, 20%, 60%) of dashboard width
dashboard.setColumnWidth( 0, 1 )
dashboard.setColumnWidth( 1, 1 )
dashboard.setColumnWidth( 2, 3 )
Index of the column (starts from 0)
Relative width of the column, can be any number.
Set the minimum and maximum boundaries for dashBoard vertical size.
Single value applied to both minimum and maximum size, or a tuple for [min, max] size in pixels.
Set height of a row in relation to other rows. By default all row heights are 1.
By changing one rows height to 2, it would make that row allocate twice as much height as others.
// Dashboard with 3 rows with heights (20%, 20%, 60%) of dashboard height
dashboard.setRowHeight( 0, 1 )
dashboard.setRowHeight( 1, 1 )
dashboard.setRowHeight( 2, 3 )
Index of the row (starts from 0)
Relative height of the row
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 style of Dashboard splitters.
Note, that highlighted splitters have a separate style setSplitterStyleHighlight.
Example usage:
// Specified LineStyle
Dashboard.setSplitterStyle(new SolidLine({ thickness: 2, fillStyle: new SolidFill({ color: ColorHEX('#F00') }) }))
// Changed thickness
Dashboard.setSplitterStyle((solidLine) => solidLine.setThickness(5))
// Hidden
Dashboard.setSplitterStyle(emptyLine)
Chart itself
Either a LineStyle object or a function, which will be used to create a new LineStyle based on current value.
Set the minimum and maximum boundaries for dashBoard horizontal size.
Single value for static engine size, or a tuple for size range [min, max] 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.
})
Dashboard is a component for flexible positioning of multiple Charts efficiently. It is created with Dashboard method.
Upon its creation an amount of columns and rows is specified. Charts and other components can then be placed in cells with given column and row-locations and sizes (using methods of Dashboard. For example: createChartXY.
The Dashboard will distribute the available space for columns and rows, which users can resize with mouse and touch interactions or programmatically.