Public, safe interface for Panels rendering engine.
Scale for panel area in pixels.
Scale for panel area in percentages (0-100).
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.pixelScale )
// Position = pixels.
.setPosition({ x: 300, y: 100 })
addLegendBox( LegendBoxBuilders.VerticalLegendBox, { x: chartXY.getDefaultAxisX(), y: chartXY.getDefaultAxisY() } )
// Position = Axis values.
.setPosition({ x: 5, y: 5 })
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].
Object with two interfaces: LegendBox and UIElement.
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.pixelScale )
// Position = pixels.
.setPosition({ x: 300, y: 100 })
addUIElement( UIElementBuilders.TextBox, { x: chartXY.getDefaultAxisX(), y: chartXY.getDefaultAxisY() } )
// Position = Axis values.
.setPosition({ x: 5, y: 5 })
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].
Object that fulfills interfaces: UIElementType (typeparam) and UIElement
Attach object to an legendBox entry
Object which has to be attached
Flag that indicates whether the Attachable should be disposed/restored, when its respective Entry is clicked.
Series itself for fluent interface
Disable all animations for the chart.
All animations have to be re-enabled individually if you wish to re-enable animations.
Chart itself for fluent interface.
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 animations disable/enable state.
Animations default state.
Auto cursor object
Get fillstyle of chart background.
FillStyle
Get stroke style of chart background.
LineStyle
Get ResultTable Formatter.
Function which builds ResultTable content for MapChart.
Get Fill Style of Map regions.
FillStyle.
Get minimum size of Panel. Depending on the type of class this value might be automatically computed to fit different elements.
Vec2 minimum size or undefined if unimplemented
Get mouse interactions enabled or disabled.
Mouse interactions state
Get padding around Chart in pixels.
Padding datastructure
Returns the Theme currently being used.
An object containing the Theme.
Get text of Chart title.
Chart title as a string.
Get fill style of Chart Title.
FillStyle object
Get font of Chart title.
FontSettings object
Padding after Chart title
Padding before Chart title
Get rotation of Chart title.
Rotation in degrees
Invalidate numeric values associated with each region of the Map using a callback function that is called for every region.
Region values can be used in conjuction with:
The values can be displayed when user puts the mouse above a region. Modify DataCursor parsing with MapChart.setCursorResultTableFormatter
Each region can be styled based on its assigned value, by setting the MapCharts' fill style to a PalettedFill.
Example usage:
// Example, Set a random value [0, 100] for each region.
MapChart.invalidateRegionValues( ( region, prev ) => Math.random() * 100 )
In a more realistic application, you would look up a value from an external data set based on the region
.
The properties available from region
are based on the used [[MapType]], see MapTypeRegionProperties for a list of supported properties.
// Example, invalidate region values by external data set.
fetch(...)
.then((data) => {
MapChart.invalidateRegionValues((region) => {
// Look up value for `region`.
const value = data[region.name]
return value || 0
})
})
Function that is called for each region. First parameter is a region data structure, that can be used to identify each region. Second parameter is the previous value if any.
MapChart itself.
Invalidate numeric values associated with each region of the Map using an Array of identifier-value objects.
Region values can be used in conjuction with:
The values can be displayed when user puts the mouse above a region. Modify DataCursor parsing with MapChart.setCursorResultTableFormatter
Each region can be styled based on its assigned value, by setting the MapCharts' fill style to a PalettedFill
Example usage:
MapChart.invalidateRegionValues([
{ value: 0, name: 'Finland' }
])
In place of 'name', any property supported by the used [[MapType]] can be supplied. Look up MapTypeRegionProperties for a map of supported properties per MapType.
// MapTypes that plot *Countries* (for example, 'World', 'Europe') also support 'ISO_A3' country codes.
MapChart.invalidateRegionValues([
{ value: 0, ISO_A3: 'FIN' }
])
MapChart.invalidateRegionValues([
{ value: 0, ...MapRegions[ MapTypes.World ].Finland }
])
Array of identifier-value objects.
MapChart itself.
Remove subscription from mouse-click event on Chart background
Event listener
True if the listener is successfully removed and false if it is not found
Remove subscription from mouse-doubleClick event on Chart background
Event listener
True if the listener is successfully removed and false if it is not found
Remove subscription from mouse-down event on Chart background
Event listener
True if the listener is successfully removed and false if it is not found
Remove subscription from mouse-drag event on Chart background
Event listener
True if the listener is successfully removed and false if it is not found
Remove subscription from mouse-dragStart event on Chart background
Event listener
True if the listener is successfully removed and false if it is not found
Remove subscription from mouse-dragStop event on Chart background
Event listener
True if the listener is successfully removed and false if it is not found
Remove subscription from mouse-enter event on Chart background
Event listener
True if the listener is successfully removed and false if it is not found
Remove subscription from mouse-leave event on Chart background
Event listener
True if the listener is successfully removed and false if it is not found
Remove subscription from mouse-move event on Chart background
Event listener
True if the listener is successfully removed and false if it is not found
Remove subscription from touch-start event on Chart background
Event listener
True if the listener is successfully removed and false if it is not found
Remove subscription from mouse-up event on Chart background
Event listener
True if the listener is successfully removed and false if it is not found
Remove subscription from mouse-wheel event on Chart background
Event listener
True if the listener is successfully removed and false if it is not found
Remove subscription from touch-end event on Panel background
Event listener
True if the listener is successfully removed and false if it is not found
Remove subscription from touch-move event on Chart background
Event listener
True if the listener is successfully removed and false if it is not found
Remove event listener from Map Data Ready event.
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from Mouse Click Event
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from Mouse Double Click Event
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from Mouse Down Event
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from Mouse Drag Event
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from Mouse Drag Start Event
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from Mouse Drag Stop Event
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from Mouse Enter Event
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from Mouse Leave Event
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from Mouse Move Event
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from Mouse Up Event
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from Mouse Wheel Event
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from resize event.
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from Touch End Event
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from Touch Move Event
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Remove event listener from Touch Start Event
Token of event listener which has to be removed
True if the listener is successfully removed and false if it is not found
Subscribe to mouse-click event on Chart background
Subscribe to mouse-doubleClick event on Chart background
Subscribe to mouse-down event on Chart background
Subscribe to mouse-drag event on Chart background
Subscribe to mouse-drag start event on Chart background
Subscribe to mouse-drag stop event on Chart background
Subscribe to mouse-enter event on Chart background
Subscribe to mouse-leave event on Chart background
Subscribe to mouse-move event on Chart background
Subscribe to mouse-up event on Chart background
Subscribe to mouse-wheel event on Chart background
Subscribe to touch-end event on Chart background
Subscribe to touch-move event on Chart background
Subscribe to touch-start event on Chart background
Add event listener to Map Data Ready.
If map data is ready when event is attached the callback will be called on the next JS event loop cycle.
Event listener for Map Data Ready Event
Token of the event listener
Add event listener to Mouse Click Event
Event listener for Mouse Click Event
Token of the event listener
Add event listener to Mouse Double Click Event
Event listener for Mouse Double Click Event
Token of the event listener
Add event listener to Mouse Down Event
Event listener for Mouse Down Event
Token of the event listener
Subscribe to Mouse Drag event
Subscribe to Mouse Drag Start event
Subscribe to Mouse Drag Stop event
Add event listener to Enter Event
Event listener for Mouse Enter Event
Token of the event listener
Add event listener to Mouse Leave Event
Event listener for Mouse Leave Event
Token of the event listener
Add event listener to Mouse Move Event
Event listener for Mouse Move Event
Token of the event listener
Add event listener to Mouse Up Event
Event listener for Mouse Up Event
Token of the event listener
Subscribe to Mouse Wheel event
Event handler function
Token of subscription
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)
})
Handler function for event
Token of subscription
Subscribe to Touch End event
Event handler function
Token of subscription
Subscribe to Touch Move event
Event handler function
Token of subscription
Subscribe to Touch Start event
Event handler function
Token of subscription
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)
Name of prompted download file as string. File extension shouldn't be included as it is automatically detected from 'type'-argument.
A DOMString indicating the image format. The default format type is image/png.
A 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.
Disable/Enable all animations of the Chart.
Boolean value to enable or disable animations.
Chart itself for fluent interface.
Mutator function for charts auto cursor.
Mutator function for a Cursor
Object itself for fluent interface
Set mode of charts Auto cursor
Either AutoCursorModes.onHover or AutoCursorModes.disabled.
Object itself for fluent interface
Set FillStyle of chart background.
// Example usage,
ChartXY.setBackgroundFillStyle(new SolidFill({ color: ColorRGBA( 80, 0, 0 ) }))
Related API:
FillStyle
or function which mutates the active FillStyle
.
Object itself
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:
LineStyle
or function which mutates the active LineStyle
.
Object itself
Set ResultTable formatter. Can be used to specify the information that is displayed, when hovering mouse/pointer over a Map region.
Example usage:
MapChart.setCursorResultTableFormatter( ( tableContentBuilder, mapRegion, mapRegionValue, longitude, latitude, mapChart ) => tableContentBuilder
.addRow( mapRegion.name )
.addRow( mapRegion.ISO_A3 )
)
Function which builds ResultTable content. See definition of MapChartFormatter for supplied formatting information.
Object itself
Set Fill Style of Map regions.
Example usage:
All Map regions are filled with a single color.
// Example, solid color MapChart.
MapChart.setFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
Each Map region is colored with an individual color.
Coloring basis is further based on lookUpProperty
of the PalettedFill
:
lookUpProperty: 'value'
:
Each region is colored with a solid color that is looked up from the attached LUT by the active value of that region, as configured with invalidateRegionValues method.
// Example, MapChart color look-up based on region values.
const mapChart = lightningChart().Map({
type: MapTypes.Europe
})
mapChart.setFillStyle(new PalettedFill({
lookUpProperty: 'value',
lut: new LUT({
interpolate: true,
steps: [
{ value: 0, color: ColorRGBA(0, 0, 0) },
{ value: 100, color: ColorRGBA(0, 255, 0) }
]
})
}))
// Assign value for "Finland" region.
mapChart.invalidateRegionValues([{ value: 100, ISO_A3: 'FIN' }])
lookUpProperty: 'x' | 'y'
:
Each pixel color of the map is looked up from the attached LUT by the respective
longitude ('x'
), or latitude ('y'
) coordinate.
// Example, MapChart color look-up based on longitude.
const mapChart = lightningChart().Map({
type: MapTypes.Europe
})
mapChart.setFillStyle(new PalettedFill({
lookUpProperty: 'x',
lut: new LUT({
interpolate: false,
steps: [
{ value: -180, color: ColorRGBA(0, 0, 0) },
{ value: 20, color: ColorRGBA(0, 255, 0) },
{ value: 32, color: ColorRGBA(0, 0, 0) },
]
})
}))
Each pixel color of the map is colored according to a linear gradient.
// Example, color MapChart with linear gradient.
MapChart.setFillStyle(new LinearGradientFill({
angle: 45,
stops: [
{ offset: 0.0, color: ColorRGBA(255, 0, 0) },
{ offset: 1.0, color: ColorRGBA(0, 255, 0) }
]
}))
Each pixel color of the map is colored according to a radial gradient.
// Example, color MapChart with radial gradient.
MapChart.setFillStyle(new RadialGradientFill({
position: { x: 0.8, y: 0.7 },
stops: [
{ offset: 0.0, color: ColorRGBA(255, 0, 0) },
{ offset: 1.0, color: ColorRGBA(0, 0, 255) }
]
}))
Map regions are not filled.
Either a FillStyle object or a function, which will be used to create a new FillStyle based on current Fill Style.
MapChart itself.
Set mouse interactions enabled or disabled.
Disabling mouse interactions will also disable auto-cursor and triggering of events such as:
onMouseClick
, onMouseMove
.
Disabling mouse interactions can have a positive impact on performance.
Specifies state of mouse interactions
Object itself for fluent interface
Set FillStyle of outlier regions (parts of map that are visible, but not interactable with active map type).
// Example usage,
MapChart.setOutlierRegionFillStyle(new SolidFill({ color: ColorRGBA( 80, 0, 0 ) }))
FillStyle
or function which mutates the active FillStyle
.
Object itself
Set LineStyle of outlier regions (parts of map that are visible, but not interactable with active map type).
// Example usage,
MapChart.setOutlierRegionStrokeStyle(new SolidLine({
thickness: 2,
fillStyle: new SolidFill({ color: ColorRGBA(255, 0, 0) })
}))
LineStyle
or function which mutates the active LineStyle
.
Object itself
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 })
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.
Object itself
Set FillStyle of separate regions, which are visual components surrounding areas such as Alaska and Hawaii.
Separate regions are present in following Map types:
// Example usage,
MapChart.setSeparateRegionFillStyle(new SolidFill({ color: ColorRGBA( 80, 0, 0 ) }))
FillStyle
or function which mutates the active FillStyle
.
Object itself
Set LineStyle of Separate regions, which are visual components surrounding areas such as Alaska and Hawaii.
Separate regions are present in following Map types:
// Example usage,
MapChart.setSeparateRegionStrokeStyle(new SolidLine({
thickness: 2,
fillStyle: new SolidFill({ color: ColorRGBA(255, 0, 0) })
}))
LineStyle
or function which mutates the active LineStyle
.
Object itself
Set Stroke style of Map regions.
Example usage:
All Map regions edges are drawn with a stroke.
// Example, solid region stroke
MapChart.setStrokeStyle(new SolidLine({
thickness: 2,
fillStyle: new SolidFill({ color: ColorRGBA(255, 0, 0) })
}))
Regions edges are not drawn with a stroke.
LineStyle
or function which mutates the active LineStyle
.
Object itself
Set text of Chart title.
Chart title as a string.
Object itself for fluent interface.
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)
Either a FillStyle object or a function, which will be used to create a new FillStyle based on current value.
Chart itself
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'))
Either a FontSettings object or a function, which will be used to create a new FontSettings based on current value.
Chart itself
Specifies padding after chart title.
This does not have an effect if title is hidden (empty FillStyle).
// Example usage,
// Add empty space between title and series.
ChartXY.setTitleMarginBottom(32)
Gap after the chart title in pixels.
Chart itself for fluent interface
Specifies padding before chart title.
This does not have an effect if title is hidden (empty FillStyle).
// Example usage,
// Add empty space at top of chart, before title.
ChartXY.setTitleMarginTop(32)
Gap between the top of chart and its title in pixels.
Chart itself for fluent interface
Set rotation of Chart title.
Rotation in degrees
Object itself
Chart class for visualizing a Map of a selected part of the world. Defaults to the entire world.
MapChart
can be created in two different ways - to learn more about creation time configuration ofMapChart
, please refer to:MapChart features
MapChart
supports 9 different map types, each of which depicts a different part of the world. Map types can also be split based on different types of regions, like countries, states, territories, provinces, etc.Supported map types:
Map type is selected when the
MapChart
is created, with thetype
argument:// Example, specify map type. const mapChart = lightningChart().Map({ type: MapTypes.Europe, })
MapChart
has two style properties: region fill style and stroke style. The style is shared for all regions.Style is configured with
Dynamic region coloring is possibly by configuring fill style with PalettedFill.
// Example, enable dynamic region coloring based on a color look-up table. MapChart.setFillStyle(new PalettedFill({ lut: new LUT({ interpolate: true, steps: [ { value: 0, color: ColorRGBA(255, 0, 0) }, { value: 100, color: ColorRGBA(0, 255, 0) } ] }) }))
Region values used for color look-up are configured with MapChart.invalidateRegionValues. This method is very flexible and can be used in a variety of ways - refer to the method documentation for more examples.
// Example, set value of "Finland" region to `0`. MapChart.invalidateRegionValues([ { value: 0, ISO_A3: 'FIN' } ])
MapChart
has built-in AutoCursor functionality, which is activated when user pointer is above any region.Auto cursor can be configured in a variety of ways:
Required resources:
MapChart
requires external file resources in order to work. These resources are distributed along with the LightningChart JS package (node_modules/@arction/lcjs/dist/resources
).In order to use
MapChart
the map resources need to be hosted on a file server. WhenMapChart
is created, a GET request will be issued to URL:<resourcesBaseUrl>/maps/<mapDataFile>
.The file server location can be specified by supplying a
resourcesBaseUrl
, please see LightningChartOptions.resourcesBaseUrl for general information and troubleshooting on LCJS resources.The following table documents which resource files are required based on used Map type:
MapTypes.World
'countries_world.json'
MapTypes.Europe
'countries_europe.json'
MapTypes.NorthAmerica
'countries_northAmerica.json'
MapTypes.SouthAmerica
'countries_southAmerica.json'
MapTypes.Africa
'countries_africa.json'
MapTypes.Asia
'countries_asia.json'
MapTypes.USA
'states_usa.json'
MapTypes.Canada
'territoriesProvinces_canada.json'
MapTypes.Australia
'territories_australia.json'