Cartesian chart control

The CartesianChart control is a 'ready to go' control to create plots using the Cartesian coordinate system, To get started all you need to do is assign the Series property with a collection of ICartesianSeries.

Drag a new CartesianChart control from your toolbox, then in the code behind assign the Series property:

cartesianChart1.Series = new ISeries[]
{
    new LineSeries<int>
    {
        Values = new int[] { 4, 6, 5, 3, -3, -1, 2 }
    },
    new ColumnSeries<double>
    {
        Values = new double[] { 2, 5, 4, -2, 4, -3, 5 }
    }
};

The main components of this control are:

• Series
• Axes
• Tooltip
• Legend

But notice in the previous code snippet we did not specify the Axes, Tooltip, Legend or the series colors, this is because LiveCharts will decide them based on the current theme of the library, you can also customize any of these properties when you require it, this article will cover the most common scenarios.

Series

There are multiple series available in the library, you can add one or mix them all in the same chart, every series has unique properties, any image bellow is a link to an article explaining more about them.

Line series

Column series

Scatter series

Step line series

Heat series

Candle sticks series

Stacked line series

Stacked column series

Stacked step line series

Box series

Error series

Bubble series

Axes

A CartesianChart has 2 axes, the YAxis and the XAxis properties, an IAxis besides de visual customization such as labels format and separators paints it also controls multiple important features such as the Zooming, the Panning, the Scale (log) and the Paging.

This is a brief sample about how to use the main features of the Axis class, you can find a more detailed article at the button below or at the API explorer.

Go to the full axes article

Axes.SeparatorsStyle

cartesianChart1.XAxes = new Axis[]
{
    new Axis
    {
        Name = "X Axis",
        NamePaint = new SolidColorPaint(SKColors.Black), // mark

        LabelsPaint = new SolidColorPaint(SKColors.Blue), // mark
        TextSize = 10,

        SeparatorsPaint = new SolidColorPaint(SKColors.LightSlateGray) { StrokeThickness = 2 } // mark
    }
};

cartesianChart1.YAxes = new Axis[]
{
    new Axis
    {
        Name = "Y Axis",
        NamePaint = new SolidColorPaint(SKColors.Red), // mark

        LabelsPaint = new SolidColorPaint(SKColors.Green), // mark
        TextSize = 20,

        SeparatorsPaint = new SolidColorPaint(SKColors.LightSlateGray) // mark
        { // mark
            StrokeThickness = 2, // mark
            PathEffect = new DashEffect(new float[] { 3, 3 }) // mark
        } // mark
    }
};

Axes.Labels and Axes.Labelers

Series = new ObservableCollection<ISeries>
{
    new ColumnSeries<int>
    {
        Values = new ObservableCollection<int> { 200, 558, 458, 249 },
    }
};

XAxes = new List<Axis>
{
    new Axis
    {
        // Use the labels property to define named labels.
        Labels = new string[] { "Anne", "Johnny", "Zac", "Rosa" } // mark
    }
};

YAxes = new List<Axis>
{
    new Axis
    {
        // Now the Y axis we will display labels as currency
        // LiveCharts provides some common formatters
        // in this case we are using the currency formatter.
        Labeler = Labelers.Currency // mark

        // you could also build your own currency formatter
        // for example:
        // Labeler = (value) => value.ToString("C")

        // But the one that LiveCharts provides creates shorter labels when
        // the amount is in millions or trillions
    }
};

Zooming and panning

It is disabled by default, to enable it you must set the ZoomMode property.

cartesianChart1.ZoomMode = LiveChartsCore.Measure.ZoomAndPanMode.X;

ZoomingSpeed property

Defines the zooming speed, it is of type double and goes from 0 to 1, where 0 is the slowest and 1 the fastest, do not confuse with animations seed, this property controls the new axis length (MaxLimit - MinLimit) when the Zoom() method is called.

cartesianChart1.ZoomingSpeed = 0;

Clearing the current zooming or panning

Setting MinLimit and MaxLimit properties to null will clear the current zooming or panning, and will let the chart fit the view of the chart to the available data in the chart, the default value of both properties is null.

AnimationsSpeed property

Defines the animations speed of all the chart elements (axes, series, sections).

cartesianChart1.AnimationsSpeed = TimeSpan.FromMilliseconds(500);

EasingFunction property

This property defines the way the shapes in the chart animate, in other words it controls the way the IMotionProperties of all the chart elements (axes, series, sections) in the chart move from a state 'A' to state 'B'.

The property is of type Func<float, float>, it means that it is a function that takes a float argument (the time elapsed from 0 to 1), and returns float value as the result (the progress of the animation from 0 to 1), you can learn more about easing curves at this article.

cartesianChart1.EasingFunction = LiveChartsCore.EasingFunctions.BounceOut;

Now the chart will animate following the BounceOut curve.

Now try the LiveChartsCore.EasingFunctions.Lineal function, it will animate things lineally as the time elapses.

Finally you can also build your own function:

cartesianChart1.EasingFunction = time => time * time;

The library also provides some builders based on d3-ease easing curves, the builders.

Func easingCurve = LiveChartsCore.EasingFunctions.BuildCustomBackOut(0.8f);
Func easingCurve = LiveChartsCore.EasingFunctions.BuildCustomElasticOut(0.8f, 1.1f);
// there are more builders, check them out all, they start with Build{ function }({ args })

Disable animations

Settings the EasingFunction to null disables animations.

cartesianChart1.EasingFunction = null; // mark

DrawMargin property

Defines the distance from the axes (or edge of the chart if there is no axis) to the draw margin area.

// Notice the constructor of the Margin class has multiple overloads
// https://livecharts.dev/api/2.0.0-rc2/LiveChartsCore.Measure.Margin
cartesianChart1.DrawMargin = new LiveChartsCore.Measure.Margin(100);

Tooltips

Tooltips are popups that help the user to read a chart as the pointer moves.

This is a brief sample about how to use the main features of the IChartTooltip<T> interface, you can find a more detailed article at the button below or at the API explorer.

Go to the full tooltips article

You can place a tooltip at Top, Bottom, Left, Right, Center or Hidden positions, for now tooltips for the PieChart class only support the Center position, default value is Top.

cartesianChart1.Series = new ISeries[] { new LineSeries<int> { Values = new[] { 2, 5, 4 } } };
cartesianChart1.TooltipPosition = LiveChartsCore.Measure.TooltipPosition.Bottom;

Legends

A legend is a visual element that displays a list with the name, stroke and fills of the series in a chart:

This is a brief sample about how to use the main features of the IChartLegend<T> interface, you can find a more detailed article at the button below or at the API explorer.

Go to the full legends article

You can place a legend at Top, Bottom, Left, Right or Hidden positions, notice the Hidden position will disable legends in a chart, default value is Hidden.

cartesianChart1.TooltipPosition = LiveChartsCore.Measure.LegendPosition.Bottom; // mark
// or use Top, Left, Right or Hidden

DrawMarginFrame property

This property defines a visual border for the DrawMargin.

cartesianChart1.DrawMarginFrame = new DrawMarginFrame
{
    Fill = new SolidColorPaint(SKColors.AliceBlue),
    Stroke = new SolidColorPaint(SKColors.Black, 3)
};

Sections

A section is a visual area in a chart that highlights a range of values in an axis, to stablish the limits of a section you must use the Xi and Xj properties in the X axis, the Xi represents the start of the section while the Xj the end, the same goes for the Yi and Yj properties for the Y axis.

Xi: Gets or sets the xi, the value where the section starts at the X axis, set the property to null to indicate that the section must start at the beginning of the X axis, default is null.

Xj: Gets or sets the xj, the value where the section ends and the X axis, set the property to null to indicate that the section must go to the end of the X axis, default is null.

Yi: Gets or sets the yi, the value where the section starts and the Y axis, set the property to null to indicate that the section must start at the beginning of the Y axis, default is null.

Yj: Gets or sets the yj, the value where the section ends and the Y axis, set the property to null to indicate that the section must go to the end of the Y axis, default is null.

cartesianChart1.Sections = = new RectangularSection[]
{
    new RectangularSection
    {
        // creates a section from 3 to 4 in the X axis
        Xi = 3,
        Xj = 4,
        Fill = new SolidColorPaint(new SKColor(255, 205, 210))
    },

    new RectangularSection
    {
        // creates a section from 5 to 6 in the X axis
        // and from 2 to 8 in the Y axis
        Xi = 5,
        Xj = 6,
        Yi = 2,
        Yj = 8,
        Fill = new SolidColorPaint(new SKColor(187, 222, 251))
    },

        new RectangularSection
    {
        // creates a section from 8 to the end in the X axis
        Xi = 8,
        Fill = new SolidColorPaint(new SKColor(249, 251, 231))
    }
};