JavaScript Charting Documentation - SciChart JavaScript Charts SDK v3.x
What's New? > Breaking Changes in SciChart.js v2.x from v1.x
Breaking Changes in SciChart.js v2.x from v1.x

SciChart.js v2 is a big release with many new features and many fixes and improvements that have required some breaking changes to the api from v1.

Formatting Enums

Improvements to label formatting options have required a change to the ENumericFormat Enum for numeric formatting. ENumericFormat.Decimal_0, ENumericFormat.Decimal_1, ENumericFormat.Decimal_2, ENumericFormat.Decimal_3 have been removed and there is now just ENumericFormat.Decimal. The number of decimal places is determined by the new precision property, which can be passed to the numeric axis, or set directly on the LabelProvider.

Defaults for the Numeric Axis are ENumericFormat.Decimal with precision 1. To format as integer, use precision = 0;

SciChartSurface.create

widthAspect and heightAspect are now passed in an options object, which also allows you to configure many aspects of the surface.

SciChartSurface.create
Copy Code 
// before
SciChartSurface.create(divElementId: string,  widthAspect: number = 0,  heightAspect: number = 0);
// after
SciChartSurface.create(divElementId: string,  options?: I2DSurfaceOptions);
// where
export interface I2DSurfaceOptions {
    /**
     * Optional - the width aspect ratio of the SciChartSurface. By default SciChart will scale to fit the parent Div.
     * However if height of the div is not provided it will use width/height aspect ratio to calculate the height. The default ratio is 3/2.
     */
    widthAspect?: number;
    /**
     * Optional - the height aspect ratio of the SciChartSurface. By default SciChart will scale to fit the parent Div.
     * However if height of the div is not provided it will use width/height aspect ratio to calculate the height. The default ratio is 3/2.
     */
    heightAspect?: number;
    /**
     * Optional - The theme applied to the SciChartSurface on startup
     * @remarks see IThemeProvider for properties which can affect SciChart theme. Two default
     * themes are included out of the box  SciChartJSLightTheme and SciChartJSDarkTheme.
     * Custom themes may be created by implementing IThemeProvider
     */
    theme?: IThemeProvider | { type: string | EThemeProviderType; overrides?: IThemePartial };
    /**
     * Allows you to customize the loading elements or animation as part of the HTML page / DOM when a SciChartSurface
     * or SciChart3DSurface is loading WebAssembly
     */
    loader?: ISciChartLoader | { type: string; options?: any };
    /**
     * Optional - Prove a layoutManager to customise the axis layout.  Use CentralAxesLayoutManager for an easy way to configure central axes.
     */
    layoutManager?: ILayoutManager;
    /**
     * Optional - Padding between the SciChartSurface and its inner elements. Default 10
     */
    padding?: Thickness;
    /**
     * Optional - Properties of the viewport border (where series are drawn)
     */
    viewportBorder?: TBorder;
    /**
     * Optional - Properties of the canvas border
     */
    canvasBorder?: TBorder;
}

SciChartPieSurface.create

Similar change to SciChartSurface.create, aspect options now passed within an options object:

SciChartSurface.create
Copy Code 
// before
SciChartPieSurface.create(divElementId: string, widthAspect: number = 0, heightAspect: number = 0);
// after
SciChartPieSurface.create(divElementId: string, options?: IPieSurfaceOptions);
// where
export interface I2DSurfaceOptions {
    /**
     * Optional - the width aspect ratio of the SciChartPieSurface. By default SciChart will scale to fit the parent Div.
     * However if height of the div is not provided it will use width/height aspect ratio to calculate the height. The default ratio is 3/2.
     */
    widthAspect?: number;
    /**
     * Optional - the height aspect ratio of the SciChartPieSurface. By default SciChart will scale to fit the parent Div.
     * However if height of the div is not provided it will use width/height aspect ratio to calculate the height. The default ratio is 3/2.
     */
    heightAspect?: number;
    /**
     * Optional - The theme applied to the SciChartPieSurface on startup
     * @remarks see IThemeProvider for properties which can affect SciChart theme. Two default
     * themes are included out of the box  SciChartJSLightTheme and SciChartJSDarkTheme.
     * Custom themes may be created by implementing IThemeProvider
     */
    theme?: IThemeProvider | { type: string | EThemeProviderType; overrides?: IThemePartial };
    /** Optional - whether this is a pie or donut chart. Default Pie.  */
    pieType?: EPieType;
    /** Optional - the radius of the hole for a donut chart. */
    holeRadius?: number;
    /** Optional - Whether to animate the chart as it is initially drawn.  Default true */
    animate?: boolean;
    /** Optional - how the hole radius is interpreted, either absolute, or relative to the total radius */
    holeRadiusSizingMode?: ESizingMode;
    /** Optional - whether to show the legend.  Default true */
    showLegend?: boolean;
    /** Optional - whether to animate the appearance of the legend.  Default true */
    animateLegend?: boolean;
    /** Optional - whether to show checkboxes on the legend.  Default false */
    showLegendCheckBoxes?: boolean;
    /** Optional - whether to show series markers on the legend.  Default true */
    showLegendSeriesMarkers?: boolean;
}

Label Formatting

LabelProvider.formatLabel and LabelProvider.formatCursorLabel changed from class method to property. Moreover for LabelProvider.formatLabel last optional parameter was removed.

Label Formatting method changes
Copy Code 
// Before
export abstract class LabelProvider {
    ...
    public abstract formatLabel(dataValue: number, format?: ENumericFormat): string; 
    public abstract formatCursorLabel(dataValue: number): string;
    ...
}
// After
export type TFormatLabelFn = (dataValue: number) => string;
export abstract class LabelProvider {
...
    protected formatLabelProperty: TFormatLabelFn;
    protected formatCursorLabelProperty: TFormatLabelFn;
...
}

IThemeProvider additional fields

IThemeProvider additional fields
Copy Code 
    /**
     * The background color of the loading animation dots,
     * which can also be customized by overriding the {@link loader}
     */
    loadingAnimationBackground: string;
    /**
     * The foreground color of the loading animation dots,
     * which can also be customized by overriding the {@link loader}
     */
    loadingAnimationForeground: string;

This defines the background/foreground for the loader animation which is shown while loading webassembly.

UniformHeatmapDataSeries constructor

UniformHeatmapDataSeries constructor now takes an options parameter of type IUniformHeatmapSeriesOptions which contains all the parameters which used to be passed individually.  This is to support the new bulder api.

UniformHeatmapDataSeries constructor
Copy Code 
// Before
const heatmap2dArrayValues = new Array<number[]>(arraySize);
const heatmapSeries = new UniformHeatmapDataSeries(wasmContext, 0, 1, 0, 1, heatmap2dArrayValues);
// After
const heatmapSeries = new UniformHeatmapDataSeries(wasmContext, {
    xStart: 0,
    xStep: 1,
    yStart: 0,
    yStep: 1,
    zValues: heatmap2dArrayValues
});

Shader effects

There are now seperate classes for GlowEffect and ShadowEffect, which extend the now abstract ShaderEffect.  These have options interfaces specific to the effect:

GlowEffect and ShadowEffect Options
Copy Code 
export interface IGlowEffectOptions {
    intensity?: number;
    range?: number;
}
export interface IShadowEffectOptions {
    range?: number;
    brightness?: number;
    offset?: Point;
}

Hit-Test

Hit Test function signature has changed.

HitTest changes
Copy Code 
// Before
hitTest(point: Point, logic: ENearestPointLogic, hitTestRadius: number, interpolate: boolean): HitTestInfo;
// After
hitTest(x: number, y: number, hitTestRadius?: number): HitTestInfo;

Additional functions have been added to handle different cases of hit-testing the actual data-points, the series body or to perform a vertical hit-test. Function signatures are below:

HitTest functions
Copy Code 
     /**
     * @description Performs a hit-test for series body at the specific mouse point (X,Y coordinate on the parent SciChartSurface),
     * returning a HitTestInfo type with the results
     * @remarks For Retina displays and Browser zoom, ensure that X,Y points are scaled by DpiHelper.PIXEL_RATIO
     * @param x The mouse point X coordinate on the parent SciChartSurface.
     * NOTE: For Retina displays and Browser zoom, ensure that X,Y points are scaled by DpiHelper.PIXEL_RATIO
     * @param y The mouse point Y coordinate on the parent SciChartSurface.
     * NOTE: For Retina displays and Browser zoom, ensure that X,Y points are scaled by DpiHelper.PIXEL_RATIO
     * @param hitTestRadius The radius in pixels to determine whether a mouse is over a data-point
     */
    hitTest(x: number, y: number, hitTestRadius?: number): HitTestInfo;
    /**
     * @description Performs a hit-test for the data point at the specific mouse point (X,Y coordinate on the parent SciChartSurface),
     * returning a HitTestInfo type with the results
     * @remarks For Retina displays and Browser zoom, ensure that X,Y points are scaled by DpiHelper.PIXEL_RATIO
     * @param x The mouse point X coordinate on the parent SciChartSurface.
     * NOTE: For Retina displays and Browser zoom, ensure that X,Y points are scaled by DpiHelper.PIXEL_RATIO
     * @param y The mouse point Y coordinate on the parent SciChartSurface.
     * NOTE: For Retina displays and Browser zoom, ensure that X,Y points are scaled by DpiHelper.PIXEL_RATIO
     * @param hitTestRadius The radius in pixels to determine whether a mouse is over a data-point
     */
    hitTestDataPoint(x: number, y: number, hitTestRadius?: number): HitTestInfo;
    /**
     * @description Performs a hit-test for the vertical slice at the specific mouse point (X,Y coordinate on the parent SciChartSurface),
     * only X value is taken into account, it is used for CursorModifier and RolloverModifier.
     * returns a HitTestInfo type with the results,
     * Only for sorted values
     * @remarks For Retina displays and Browser zoom, ensure that X,Y points are scaled by DpiHelper.PIXEL_RATIO
     * @param x The mouse point X coordinate on the parent SciChartSurface.
     * NOTE: For Retina displays and Browser zoom, ensure that X,Y points are scaled by DpiHelper.PIXEL_RATIO
     * @param y The mouse point Y coordinate on the parent SciChartSurface.
     * NOTE: For Retina displays and Browser zoom, ensure that X,Y points are scaled by DpiHelper.PIXEL_RATIO
     * @param hitTestRadius The radius in pixels to determine whether a mouse is over a data-point
     */
    hitTestXSlice(x: number, y: number, hitTestRadius?: number): HitTestInfo;
    /**
     * @description Performs a hit-test for the DataPointSelectionModifier. This calls IHitTestProvider.hitTestDataPoint by default.
     * The hitTestProvider for the renderableSeries can override this if different behaviour is desired, eg for columSeries we call hitTest instead.
     * returns a HitTestInfo type with the results,
     * Only for sorted values
     * @remarks For Retina displays and Browser zoom, ensure that X,Y points are scaled by DpiHelper.PIXEL_RATIO
     * @param x The mouse point X coordinate on the parent SciChartSurface.
     * NOTE: For Retina displays and Browser zoom, ensure that X,Y points are scaled by DpiHelper.PIXEL_RATIO
     * @param y The mouse point Y coordinate on the parent SciChartSurface.
     * NOTE: For Retina displays and Browser zoom, ensure that X,Y points are scaled by DpiHelper.PIXEL_RATIO
     * @param hitTestRadius The radius in pixels to determine whether a mouse is over a data-point
     */
    hitTestForDataPointSelectionModifier(x: number, y: number, hitTestRadius: number): HitTestInfo;

In addition, due to DPI handling in SciChart.js v2.x if you subscribe to events on the domCanvas2d, these must be scaled before passing to Hit-Test.  For example:

HitTest example
Copy Code 
sciChartSurface.domCanvas2D.addEventListener("mousedown", (mouseEvent: MouseEvent) => {
    const newHitTestsList: HitTestInfo[] = [];
    const dpiScaledPoint = new Point(
        mouseEvent.x * DpiHelper.PIXEL_RATIO, // DpiHelper.PIXEL_RATIO = 1 by default,
        mouseEvent.y * DpiHelper.PIXEL_RATIO
    ); // = 2 for retina displays. Also changes as user zooms browser
    sciChartSurface.renderableSeries.asArray().forEach(rs => {
        if (rs.hitTestProvider) {
            const hitTestInfo = rs.hitTestProvider.hitTest(dpiScaledPoint.x, dpiScaledPoint.y, HIT_TEST_RADIUS);
        }
    });
});

RolloverModifier

  • MarkerSvgAnnotation renamed to RolloverMarkerSvgAnnotation
  • ITooltipSvgAnnotationOptions renamed to IRolloverTooltipSvgAnnotationOptions
  • TooltipSvgAnnotation renamed to RolloverTooltipSvgAnnotation
  • isVerticalChart removed. This is now calculated based on the orientation of the x Axis. If you have multiple xAxes, set the xAxisId property.

tooltipTemplate API changed:

tooltipTemplate API change
Copy Code 
// before
renderableSeries.rolloverModifierProps.tooltipTemplate = (
    id: string,
    tooltipProps: RolloverModifierRenderableSeriesProps,
    seriesInfo: SeriesInfo,
    updateSize: (width: number, height: number) => void
) => {
    const { tooltipTitle, tooltipColor, tooltipTextColor } = tooltipProps;
    const width = 120;
    const height = 120;
    updateSize(width, height);
    // tooltip template code
};
// after
renderableSeries.rolloverModifierProps.tooltipTemplate = (
    id: string,
    seriesInfo: SeriesInfo,
    rolloverTooltip: RolloverTooltipSvgAnnotation
) => {
    const { tooltipTitle, tooltipColor, tooltipTextColor } = rolloverTooltip.tooltipProps;
    const width = 120;
    const height = 120;
    rolloverTooltip.updateSize(width, height);
    // tooltip template code
};

CursorModifier

CursorModifier.axisLabelsStroke renamed to CursorModifier.axisLabelStroke

CursorModifier changes
Copy Code 
// Before
const cursorModifier = new CursorModifier();
cursorModifier.axisLabelsStroke = "#00FF00";
// After
const cursorModifier = new CursorModifier();
cursorModifier.axisLabelStroke = "#00FF00";

Ignore fs should be removed or updated in webpack.config

In v1 it was recommended that webpack.config include

new webpack.IgnorePlugin(/(fs)/)

This is no longer required due to upgrades to our build, and may cause problems (especially with the filters api) as it ignores any file containing the string fs.  If you do still need to ignore the fs package specifically (as some packages depend on it for node.js support but this breaks when in a browser), then use this line:

new webpack.IgnorePlugin(/^fs$/);

TGridLineStyle.strokeDasharray renamed

TGridLineStyle.strokeDasharray renamed to TGridLineStyle.strokeDashArray

TGridLineStyle changes
Copy Code 
// Before
xAxis.majorGridLineStyle.strokeDasharray = [4, 2];
// After
xAxis.majorGridLineStyle.strokeDashArray = [4, 2];

TEasing type renamed

Renamed from TEasing to TEasingFn 

TEasing changes
Copy Code 
// Before
import { TEasing } from "../../Core/Animations/EasingFunctions";
// After
import { TEasingFn } from "../../Core/Animations/EasingFunctions";

ICandlestickSeriesOptions renamed

Renamed from ICandlestickSeriesOptions to ICandlestickRenderableSeriesOptions

RubberBandSvgRect renamed

Renamed from RubberBandRect to RubberBandSvgRect and moved from src/Charting/Visuals/RubberBandRect/RubberBandRect.ts to src/Charting/Visuals/RubberBandSvgRect/RubberBandSvgRect.ts

 

See Also
What's New in SciChart.js SDK v2.x