Options
All
  • Public
  • Public/Protected
  • All
Menu

Class MapChart<SelectedMapType, CursorPointMarkerType, CursorResultTableBackgroundType, CursorType>

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 of MapChart, please refer to:

MapChart features

  1. Map Types

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 the type argument:

 // Example, specify map type.
 const mapChart = lightningChart().Map({
     type: MapTypes.Europe,
 })
  1. Style and dynamic region coloring

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' }
 ])
  1. AutoCursor

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. When MapChart 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:

Map type Map data file
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'

Index

Properties

Methods

Properties

Readonly engine

engine : PublicEngine

Public, safe interface for Panels rendering engine.

pixelScale

pixelScale : LinearScaleXY

Scale for panel area in pixels.

uiScale

uiScale : LinearScaleXY

Scale for panel area in percentages (0-100).

Methods

addLegendBox

  • 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.

    1. LegendBox with default positioning coordinate system.
     addLegendBox( LegendBoxBuilders.VerticalLegendBox )
         // Position = [0, 100] as percentages.
         .setPosition({ x: 50, y: 50 })
    
    1. Position in pixel coordinate system.
     addLegendBox( LegendBoxBuilders.VerticalLegendBox, chart.pixelScale )
         // Position = pixels.
         .setPosition({ x: 300, y: 100 })
    
    1. Position on Axes.
     addLegendBox( LegendBoxBuilders.VerticalLegendBox, { x: chartXY.getDefaultAxisX(), y: chartXY.getDefaultAxisY() } )
         // Position = Axis values.
         .setPosition({ x: 5, y: 5 })
    

    Parameters

    • builder: UILegendBoxBuilder

      LegendBoxBuilder. If omitted, VerticalLegendBox will be selected. Use LegendBoxBuilders for selection.

    • scale: UserScaleDefinition

      Optional parameter for altering the coordinate system used for positioning the LegendBox. Defaults to whole Chart in percentages [0, 100].

    Returns LegendBox & UIElement

    Object with two interfaces: LegendBox and UIElement.

addUIElement

  • Add a stand-alone UIElement using a builder.

    Example usage:

    1. TextBox with default positioning coordinate system.
     addUIElement( UIElementBuilders.TextBox )
         // Position = [0, 100] as percentages.
         .setPosition({ x: 50, y: 50 })
    
    1. Position in pixel coordinate system.
     addUIElement( UIElementBuilders.TextBox, chart.pixelScale )
         // Position = pixels.
         .setPosition({ x: 300, y: 100 })
    
    1. Position on Axes.
     addUIElement( UIElementBuilders.TextBox, { x: chartXY.getDefaultAxisX(), y: chartXY.getDefaultAxisY() } )
         // Position = Axis values.
         .setPosition({ x: 5, y: 5 })
    

    Type parameters

    • UIElementType: UIPart = UITextBox

      Type of UIElement that is specified by 'builder'-parameter.

    Parameters

    • builder: UIElementBuilder<UIElementType>

      UIElementBuilder. If omitted, TextBoxBuilder will be selected. Use UIElementBuilders for selection.

    • scale: UserScaleDefinition

      Optional parameter for altering the coordinate system used for positioning the UIElement. Defaults to whole Chart in percentages [0, 100].

    Returns UIElementType & UIElement

    Object that fulfills interfaces: UIElementType (typeparam) and UIElement

attach

  • Attach object to an legendBox entry

    Parameters

    • entry: LegendBoxEntry

      Object which has to be attached

    • disposeOnClick: boolean

      Flag that indicates whether the Attachable should be disposed/restored, when its respective Entry is clicked.

    Returns this

    Series itself for fluent interface

disableAnimations

  • disableAnimations(): this
  • Disable all animations for the chart.

    All animations have to be re-enabled individually if you wish to re-enable animations.

    deprecated

    Deprecated in v3.1.0. Will be removed in v4.0.0. Use setAnimationsEnabled instead.

    Returns this

    Chart itself for fluent interface.

dispose

  • dispose(): this
  • 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
    

    Returns this

    Object itself for fluent interface

getAnimationsEnabled

  • getAnimationsEnabled(): boolean
  • Get animations disable/enable state.

    Returns boolean

    Animations default state.

getAutoCursor

  • getAutoCursor(): CursorType
  • Returns CursorType

    Auto cursor object

getAutoCursorMode

getBackgroundFillStyle

  • Get fillstyle of chart background.

    Returns FillStyle

    FillStyle

getBackgroundStrokeStyle

  • Get stroke style of chart background.

    Returns LineStyle

    LineStyle

getCursorResultTableFormatter

  • Get ResultTable Formatter.

    Returns MapChartFormatter

    Function which builds ResultTable content for MapChart.

getFillStyle

  • Get Fill Style of Map regions.

    Returns FillStyle

    FillStyle.

getMinimumSize

  • getMinimumSize(): Point | undefined
  • Get minimum size of Panel. Depending on the type of class this value might be automatically computed to fit different elements.

    Returns Point | undefined

    Vec2 minimum size or undefined if unimplemented

getMouseInteractions

  • getMouseInteractions(): boolean
  • Get mouse interactions enabled or disabled.

    Returns boolean

    Mouse interactions state

getOutlierRegionFillStyle

  • Get FillStyle of outlier regions (parts of map that are visible, but not interactable with active map type).

    Returns FillStyle

    FillStyle

getOutlierRegionStrokeStyle

  • Get LineStyle of outlier regions (parts of map that are visible, but not interactable with active map type).

    Returns LineStyle

    LineStyle

getPadding

  • Get padding around Chart in pixels.

    Returns Margin

    Padding datastructure

getSeparateRegionFillStyle

  • Get FillStyle of Separate regions, which are visual components surrounding areas such as Alaska and Hawaii.

    Separate regions are present in following Map types:

    Returns FillStyle

    FillStyle

getSeparateRegionStrokeStyle

  • Get LineStyle of Separate regions, which are visual components surrounding areas such as Alaska and Hawaii.

    Separate regions are present in following Map types:

    Returns LineStyle

    LineStyle

getStrokeStyle

getTheme

  • Returns the Theme currently being used.

    Returns Theme

    An object containing the Theme.

getTitle

  • getTitle(): string
  • Get text of Chart title.

    Returns string

    Chart title as a string.

getTitleFillStyle

  • Get fill style of Chart Title.

    Returns FillStyle

    FillStyle object

getTitleFont

  • Get font of Chart title.

    Returns FontSettings

    FontSettings object

getTitleMarginBottom

  • getTitleMarginBottom(): number
  • Returns number

    Padding after Chart title

getTitleMarginTop

  • getTitleMarginTop(): number
  • Returns number

    Padding before Chart title

getTitleRotation

  • getTitleRotation(): number
  • Get rotation of Chart title.

    Returns number

    Rotation in degrees

invalidateRegionValues

  • invalidateRegionValues(callback: function): this
  • invalidateRegionValues(values: Array<Partial<MapTypeRegionProperties[SelectedMapType]> & object | undefined>): this
  • 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:

    • DataCursor:

    The values can be displayed when user puts the mouse above a region. Modify DataCursor parsing with MapChart.setCursorResultTableFormatter

    • FillStyle:

    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
             })
         })
    

    Parameters

    • callback: function

      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.

        • Parameters

          • region: MapTypeRegionProperties[SelectedMapType]
          • prev: undefined | number

          Returns number | undefined

    Returns this

    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:

    • DataCursor:

    The values can be displayed when user puts the mouse above a region. Modify DataCursor parsing with MapChart.setCursorResultTableFormatter

    • FillStyle:

    Each region can be styled based on its assigned value, by setting the MapCharts' fill style to a PalettedFill

    Example usage:

    • Select region by name or other property supported by the used MapTypes.
     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' }
     ])
    
    • For quick access, you can also refer to the region list of the used MapType that is accessed through MapRegions.
     MapChart.invalidateRegionValues([
         { value: 0, ...MapRegions[ MapTypes.World ].Finland }
     ])
    

    Parameters

    • values: Array<Partial<MapTypeRegionProperties[SelectedMapType]> & object | undefined>

      Array of identifier-value objects.

    Returns this

    MapChart itself.

offBackgroundMouseClick

  • offBackgroundMouseClick(token: Token): boolean
  • Remove subscription from mouse-click event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offBackgroundMouseDoubleClick

  • offBackgroundMouseDoubleClick(token: Token): boolean
  • Remove subscription from mouse-doubleClick event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offBackgroundMouseDown

  • offBackgroundMouseDown(token: Token): boolean
  • Remove subscription from mouse-down event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offBackgroundMouseDrag

  • offBackgroundMouseDrag(token: Token): boolean
  • Remove subscription from mouse-drag event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offBackgroundMouseDragStart

  • offBackgroundMouseDragStart(token: Token): boolean
  • Remove subscription from mouse-dragStart event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offBackgroundMouseDragStop

  • offBackgroundMouseDragStop(token: Token): boolean
  • Remove subscription from mouse-dragStop event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offBackgroundMouseEnter

  • offBackgroundMouseEnter(token: Token): boolean
  • Remove subscription from mouse-enter event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offBackgroundMouseLeave

  • offBackgroundMouseLeave(token: Token): boolean
  • Remove subscription from mouse-leave event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offBackgroundMouseMove

  • offBackgroundMouseMove(token: Token): boolean
  • Remove subscription from mouse-move event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offBackgroundMouseTouchStart

  • offBackgroundMouseTouchStart(token: Token): boolean
  • Remove subscription from touch-start event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offBackgroundMouseUp

  • offBackgroundMouseUp(token: Token): boolean
  • Remove subscription from mouse-up event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offBackgroundMouseWheel

  • offBackgroundMouseWheel(token: Token): boolean
  • Remove subscription from mouse-wheel event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offBackgroundTouchEnd

  • offBackgroundTouchEnd(token: Token): boolean
  • Remove subscription from touch-end event on Panel background

    Parameters

    • token: Token

      Event listener

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offBackgroundTouchMove

  • offBackgroundTouchMove(token: Token): boolean
  • Remove subscription from touch-move event on Chart background

    Parameters

    • token: Token

      Event listener

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offDispose

  • offDispose(token: Token): boolean
  • Remove event listener from dispose event.

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offMapDataReady

  • offMapDataReady(token: Token): boolean
  • Remove event listener from Map Data Ready event.

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offMouseClick

  • offMouseClick(token: Token): boolean
  • Remove event listener from Mouse Click Event

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offMouseDoubleClick

  • offMouseDoubleClick(token: Token): boolean
  • Remove event listener from Mouse Double Click Event

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offMouseDown

  • offMouseDown(token: Token): boolean
  • Remove event listener from Mouse Down Event

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offMouseDrag

  • offMouseDrag(token: Token): boolean
  • Remove event listener from Mouse Drag Event

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offMouseDragStart

  • offMouseDragStart(token: Token): boolean
  • Remove event listener from Mouse Drag Start Event

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offMouseDragStop

  • offMouseDragStop(token: Token): boolean
  • Remove event listener from Mouse Drag Stop Event

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offMouseEnter

  • offMouseEnter(token: Token): boolean
  • Remove event listener from Mouse Enter Event

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offMouseLeave

  • offMouseLeave(token: Token): boolean
  • Remove event listener from Mouse Leave Event

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offMouseMove

  • offMouseMove(token: Token): boolean
  • Remove event listener from Mouse Move Event

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offMouseUp

  • offMouseUp(token: Token): boolean
  • Remove event listener from Mouse Up Event

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offMouseWheel

  • offMouseWheel(token: Token): boolean
  • Remove event listener from Mouse Wheel Event

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offResize

  • offResize(token: Token): boolean
  • Remove event listener from resize event.

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offTouchEnd

  • offTouchEnd(token: Token): boolean
  • Remove event listener from Touch End Event

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offTouchMove

  • offTouchMove(token: Token): boolean
  • Remove event listener from Touch Move Event

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offTouchStart

  • offTouchStart(token: Token): boolean
  • Remove event listener from Touch Start Event

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

offViewChange

  • offViewChange(token: Token): boolean
  • Remove event listener from View Change event.

    Parameters

    • token: Token

      Token of event listener which has to be removed

    Returns boolean

    True if the listener is successfully removed and false if it is not found

onBackgroundMouseClick

  • Subscribe to mouse-click event on Chart background

    Parameters

    Returns Token

onBackgroundMouseDoubleClick

  • Subscribe to mouse-doubleClick event on Chart background

    Parameters

    Returns Token

onBackgroundMouseDown

  • Subscribe to mouse-down event on Chart background

    Parameters

    Returns Token

onBackgroundMouseDrag

  • Subscribe to mouse-drag event on Chart background

    Parameters

    Returns Token

onBackgroundMouseDragStart

onBackgroundMouseDragStop

onBackgroundMouseEnter

  • Subscribe to mouse-enter event on Chart background

    Parameters

    Returns Token

onBackgroundMouseLeave

  • Subscribe to mouse-leave event on Chart background

    Parameters

    Returns Token

onBackgroundMouseMove

  • Subscribe to mouse-move event on Chart background

    Parameters

    Returns Token

onBackgroundMouseUp

  • Subscribe to mouse-up event on Chart background

    Parameters

    Returns Token

onBackgroundMouseWheel

  • Subscribe to mouse-wheel event on Chart background

    Parameters

    Returns Token

onBackgroundTouchEnd

  • Subscribe to touch-end event on Chart background

    Parameters

    Returns Token

onBackgroundTouchMove

  • Subscribe to touch-move event on Chart background

    Parameters

    Returns Token

onBackgroundTouchStart

  • Subscribe to touch-start event on Chart background

    Parameters

    Returns Token

onDispose

  • onDispose(handler: function): Token
  • Subscribe onDispose event. This event is triggered whenever the Control (Dashboards and all chart types) is disposed.

     // Example usage
    
    Chart.onDispose(() => {
      console.log('chert was disposed')
    })
    
    Chart.dispose()
    

    Parameters

    • handler: function

      Handler function for event

        • Returns unknown

    Returns Token

    Token of subscription

onMapDataReady

  • onMapDataReady(clbk: function): Token
  • 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.

    Parameters

    • clbk: function

      Event listener for Map Data Ready Event

        • Returns void

    Returns Token

    Token of the event listener

onMouseClick

  • Add event listener to Mouse Click Event

    Parameters

    Returns Token

    Token of the event listener

onMouseDoubleClick

  • Add event listener to Mouse Double Click Event

    Parameters

    Returns Token

    Token of the event listener

onMouseDown

  • Add event listener to Mouse Down Event

    Parameters

    Returns Token

    Token of the event listener

onMouseDrag

onMouseDragStart

onMouseDragStop

onMouseEnter

  • Add event listener to Enter Event

    Parameters

    Returns Token

    Token of the event listener

onMouseLeave

  • Add event listener to Mouse Leave Event

    Parameters

    Returns Token

    Token of the event listener

onMouseMove

  • Add event listener to Mouse Move Event

    Parameters

    Returns Token

    Token of the event listener

onMouseUp

  • Add event listener to Mouse Up Event

    Parameters

    Returns Token

    Token of the event listener

onMouseWheel

  • Subscribe to Mouse Wheel event

    Parameters

    Returns Token

    Token of subscription

onResize

  • onResize(handler: function): Token
  • 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)
     })
    

    Parameters

    • handler: function

      Handler function for event

        • Parameters

          • obj: this
          • width: pixel
          • height: pixel
          • engineWidth: pixel
          • engineHeight: pixel

          Returns void

    Returns Token

    Token of subscription

onTouchEnd

  • Subscribe to Touch End event

    Parameters

    Returns Token

    Token of subscription

onTouchMove

  • Subscribe to Touch Move event

    Parameters

    Returns Token

    Token of subscription

onTouchStart

  • Subscribe to Touch Start event

    Parameters

    Returns Token

    Token of subscription

onViewChange

  • onViewChange(clbk: function): Token
  • Subscribe to on View Change event.

    This event is triggered when the geographical view of the Map chart is changed as a side effect of chart resize, padding change, or other reason.

    It is also fired when the Map chart is first displayed.

    The view change event can be used for aligning other geographically positioned components over the Map chart. Mainly, it is designed for convenience of usage with ChartXY that is laid over a MapChart.

    See our Interactive Examples gallery for examples of this.

     // Example syntax.
     mapChart.onViewChange((view) => {
         console.log(view)
     })
    

    Parameters

    • clbk: function

      Callback to trigger when the event is fired.

    Returns Token

    Token of the event listener

saveToFile

  • saveToFile(fileName: string, type?: undefined | string, encoderOptions?: undefined | number): this
  • 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)
    
    sideeffect

    If 'type' is not supported by browser, an Error will be thrown.

    Parameters

    • fileName: string

      Name of prompted download file as string. File extension shouldn't be included as it is automatically detected from 'type'-argument.

    • type: undefined | string

      A DOMString indicating the image format. The default format type is image/png.

    • encoderOptions: undefined | number

      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.

    Returns this

setAnimationsEnabled

  • setAnimationsEnabled(animationsEnabled: boolean | undefined): this
  • Disable/Enable all animations of the Chart.

    Parameters

    • animationsEnabled: boolean | undefined

      Boolean value to enable or disable animations.

    Returns this

    Chart itself for fluent interface.

setAutoCursor

  • setAutoCursor(mutator: Mutator<CursorType>): this
  • Mutator function for charts auto cursor.

    Parameters

    • mutator: Mutator<CursorType>

      Mutator function for a Cursor

    Returns this

    Object itself for fluent interface

setAutoCursorMode

setBackgroundFillStyle

  • Set FillStyle of chart background.

     // Example usage,
     ChartXY.setBackgroundFillStyle(new SolidFill({ color: ColorRGBA( 80, 0, 0 ) }))
    

    Related API:

    • Use SolidFill to describe a solid fill color.
    • Use ColorRGBA to create a color from Red, Green, Blue (and optionally) Alpha values in range [0, 255].

    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) }))
    

    Parameters

    Returns this

    Object itself

setBackgroundStrokeStyle

  • 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:

    • Use SolidLine to describe a solid line style.
    • Use SolidFill to describe a solid fill color.
    • Use ColorRGBA to create a color from Red, Green, Blue (and optionally) Alpha values in range [0, 255].

    Parameters

    Returns this

    Object itself

setCursorResultTableFormatter

  • Set ResultTable formatter. Can be used to specify the information that is displayed, when hovering mouse/pointer over a Map region.

    Example usage:

    • Display country name and ISO_A3 code.
     MapChart.setCursorResultTableFormatter( ( tableContentBuilder, mapRegion, mapRegionValue, longitude, latitude, mapChart ) => tableContentBuilder
         .addRow( mapRegion.name )
         .addRow( mapRegion.ISO_A3 )
     )
    

    Parameters

    Returns this

    Object itself

setFillStyle

  • Set Fill Style of Map regions.

    Example usage:

    SolidFill:

    All Map regions are filled with a single color.

     // Example, solid color MapChart.
     MapChart.setFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
    

    PalettedFill:

    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) },
             ]
         })
     }))
    

    LinearGradientFill:

    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) }
         ]
     }))
    

    RadialGradientFill:

    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) }
         ]
     }))
    

    emptyFill:

    Map regions are not filled.

    Parameters

    Returns this

    MapChart itself.

setMouseInteractions

  • setMouseInteractions(state: boolean): this
  • 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.

    Parameters

    • state: boolean

      Specifies state of mouse interactions

    Returns this

    Object itself for fluent interface

setOutlierRegionFillStyle

  • 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 ) }))
    

    Parameters

    Returns this

    Object itself

setOutlierRegionStrokeStyle

  • 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) })
     }))
    

    Parameters

    Returns this

    Object itself

setPadding

  • setPadding(padding: Partial<Margin> | number): this
  • 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 })
    

    Parameters

    • padding: Partial<Margin> | number

      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.

    Returns this

    Object itself

setSeparateRegionFillStyle

  • 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 ) }))
    

    Parameters

    Returns this

    Object itself

setSeparateRegionStrokeStyle

  • 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) })
     }))
    

    Parameters

    Returns this

    Object itself

setStrokeStyle

  • Set Stroke style of Map regions.

    Example usage:

    SolidLine:

    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) })
     }))
    

    emptyLine:

    Regions edges are not drawn with a stroke.

    Parameters

    Returns this

    Object itself

setTitle

  • setTitle(title: string): this
  • Set text of Chart title.

    Parameters

    • title: string

      Chart title as a string.

    Returns this

    Object itself for fluent interface.

setTitleFillStyle

  • 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)
    

    Parameters

    Returns this

    Chart itself

setTitleFont

  • 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'))
    

    Parameters

    Returns this

    Chart itself

setTitleMarginBottom

  • setTitleMarginBottom(marginPixels: pixel): this
  • 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)
    

    Parameters

    • marginPixels: pixel

      Gap after the chart title in pixels.

    Returns this

    Chart itself for fluent interface

setTitleMarginTop

  • setTitleMarginTop(marginPixels: pixel): this
  • 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)
    

    Parameters

    • marginPixels: pixel

      Gap between the top of chart and its title in pixels.

    Returns this

    Chart itself for fluent interface

setTitleRotation

  • setTitleRotation(value: number): this
  • Set rotation of Chart title.

    Parameters

    • value: number

      Rotation in degrees

    Returns this

    Object itself