Figures and text

This section covers a number of different series - so called "Figure Series". These can be used inside ChartXY to draw various custom shapes in the chart. For example, Text, Rectangles, Polygons, Ellipses, Line segments, Box and whiskers.

Different shapes are created using their own respective series type. However, the API for all figure series is almost completely same. The only differences are found in styling and specifying the figure dimensions.

Text

const textSeries = chart.addTextSeries()
const textFigure = textSeries.add({
        // All these properties are optional and can later be changed. For example `TextFigure.setText`
        text: 'Hello',
        location: { x: 0, y: 0 },
        alignment: { x: -1, y: -1 },
        margin: { left: 100, top: 0, right: 0, bottom: 0 },
        rotation: 0,
        fillStyle: new SolidFill({ color: ColorRGBA(255, 0, 0) }),
        font: new FontSettings({ size: 18, weight: 'bold' }),
    })

TextFigure also has helper methods:

• getBoundingBox (get boundaries in axis coordinates) and
• getSizePixels (get size in pixels)

Rectangles

const rectangleSeries = chart.addRectangleSeries()
const rectangleFigure = rectangleSeries
    .add({ x1: 0, y1: 0, x2: 10, y2: 10 })
    setCornerRadius(10)
    // Optional, changing default style
    .setFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
    .setStrokeStyle(new SolidLine({ thickness: 1, fillStyle: new SolidFill({ color: ColorRGBA(0, 0, 255) }) }))

Polygons

const polygonSeries = chart.addPolygonSeries()
const polygonFigure = polygonSeries
    // Polygon geometry is defined as list of coordinates. Even high resolution polygons with tens of thousands of coordinates are supported.
    .add([
        { x: 0, y: 0 },
        { x: 5, y: 10 },
        { x: 7, y: 3 }
    ])
    // Optional, changing default style
    .setFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
    .setStrokeStyle(new SolidLine({ thickness: 1, fillStyle: new SolidFill({ color: ColorRGBA(0, 0, 255) }) }))

Ellipses

const ellipseSeries = chart.addEllipseSeries()
const ellipseFigure = ellipseSeries
    .add({ x: 5, y: 5, radiusX: 4, radiusY: 3 })
    // Optional, changing default style
    .setFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
    .setStrokeStyle(new SolidLine({ thickness: 1, fillStyle: new SolidFill({ color: ColorRGBA(0, 0, 255) }) }))

For more details about style API, please see Styles, colors and fonts.

Segments (Line)

const segmentSeries = chart.addSegmentSeries()
const segmentFigure = segmentSeries
    .add({ startX: 0, startY: 0, endX: 10, endY: 10 })
    // Optional, changing default style
    .setStrokeStyle(new SolidLine({ thickness: 1, fillStyle: new SolidFill({ color: ColorRGBA(0, 0, 255) }) }))

For more details about style API, please see Styles, colors and fonts.

Box and whiskers

const boxSeries = chart.addBoxSeries()
const boxFigure = boxSeries
    .add({
        // X position in chart, as well as width of box figure
        start: 1,
        end: 2,
        // Y dimensions
        lowerExtreme: 1,
        lowerQuartile: 2,
        extreme: 3,
        upperQuartile: 4,
        upperExtreme: 5
    })
    // Optional, changing default style
    .setBodyFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
    .setStrokeStyle(new SolidLine({ thickness: 1, fillStyle: new SolidFill({ color: ColorRGBA(0, 0, 255) }) }))
    .setMedianStrokeStyle(new SolidLine({ thickness: 1, fillStyle: new SolidFill({ color: ColorRGBA(0, 0, 255) }) }))

For more details about style API, please see Styles, colors and fonts.

Optimizing performance

Figures are managed under a series, which can house any number of individual figures. For performance reasons, it is best to create 1 series and all figures under it, rather than creating a large number of individual series.

Another detail which can affect performance if your application has a large number of figures is sharing styles:

❌ bad:

for (...) {
    rectangleSeries
        .add({ ... })
        // Each figure will receive a new instance of SolidFill, even though color is same (!)
        .setFillStyle(new SolidFill({ color: ColorRGBA(255, 0, 0) }))
}

❎ good:

const fillRed = new SolidFill({ color: ColorRGBA(255, 0, 0) })
for (...) {
    rectangleSeries
        .add({ ... })
        .setFillStyle(fillRed)
}

User interactions

Custom user interactions can be added using the Events API:

rectangleFigure.addEventListener('click', event => {
    console.log('user clicked figure', event)
})

More examples

An example of combining text, rectangle and segment series to show time series annotations can be found in our online examples gallery, here.