~/cartesianChart/overview.md

Cartesian chart control

This article is a quick guide to use the CartesianChart control, you can explore all the properties and the source code at the ApiExplorer.

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.

<CartesianChart
    Series="series">
</CartesianChart>
private ISeries[] 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 }
    }
};

image

The main components of this control are:

image

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.

series
Line series
series
Column series
series
Scatter series
series
Step line series
series
Heat series
series
Candle sticks series
series
Stacked line series
series
Stacked column series
series
Stacked step line 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

<CartesianChart
    Series="series"
    XAxes="xAxes"
    YAxes="yAxes">
</CartesianChart>
@using LiveChartsCore;
@using LiveChartsCore.SkiaSharpView;
@using LiveChartsCore.SkiaSharpView.Painting;
@using LiveChartsCore.SkiaSharpView.Painting.Effects;
@using SkiaSharp;

private ISeries[] series { get; set; }
    = new ISeries[] { new ColumnSeries<int> { Values = new[] { 2, 5, 4, -2, 4, -3, 5 } } };

private Axis[] xAxes { get; set; }
    = 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
        }
    };

private Axis[] yAxes { get; set; }
    = 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
        }
    };

image

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

image

Zooming and panning

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

<CartesianChart
    Series="series"
    ZoomMode="LiveChartsCore.Measure.ZoomAndPanMode.X"> <!-- mark -->
</CartesianChart>

image

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.

<CartesianChart
    Series="series"
    ZoomingSpeed="0"> <!-- mark -->
</CartesianChart>

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

<lvc:CartesianChart
    Series="{Binding Series}"
    AnimationsSpeed="speed"> <!-- mark -->
</lvc:CartesianChart>
private TimeSpan speed = 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.

<lvc:CartesianChart
    Series="{Binding Series}"
    AnimationsSpeed="speed"
    EasingFunction=""> <!-- mark -->
</lvc:CartesianChart>
private Func<float, float> easing = LiveChartsCore.EasingFunctions.BounceOut; // mark

Now the chart will animate following the BounceOut curve.

image

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

image

Finally you can also build your own function:

<lvc:CartesianChart
    Series="{Binding Series}"
    AnimationsSpeed="speed"
    EasingFunction="easing"> <!-- mark -->
</lvc:CartesianChart>
private Func<float, float> easing = time => time * time; // mark

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.

<lvc:CartesianChart
    EasingFunction="null"> <!-- mark -->
</lvc:CartesianChart>

Disabling animations will not improve performance drastically: if you come from LiveCharts 0.x version then maybe you are thinking that disabling animations will improve the performance of the library, in most of the cases that is not true, animations are not the bottle neck in performance in LiveCharts 2.x, normally you must need to clean your code somewhere else, not here, plus we put a lot of effort building the animations of the library, please just do not disable them 😭, instead try to make them run faster, animating data visualization normally brings an excellent user experience.

DrawMargin property

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

<lvc:CartesianChart
    Series="{Binding Series}"
    AnimationsSpeed="speed"
    DrawMargin="margin"> <!-- mark -->
</lvc:CartesianChart>
// Notice the constructor of the Margin class has multiple overloads
// https://lvcharts.com/api/2.0.0-beta.330/LiveChartsCore.Measure.Margin
private LiveChartsCore.Measure.Margin margin = new LiveChartsCore.Measure.Margin(100); // mark

image

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

tooltips

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.

Notice the Hidden position will disable tooltips in a chart.

<CartesianChart
    Series="series"
    TooltipPosition="LiveChartsCore.Measure.TooltipPosition.Top"><!-- mark -->
</CartesianChart>
<CartesianChart
    Series="series"
    TooltipPosition="LiveChartsCore.Measure.TooltipPosition.Bottom"><!-- mark -->
</CartesianChart>
<CartesianChart
    Series="series"
    TooltipPosition="LiveChartsCore.Measure.TooltipPosition.Left"><!-- mark -->
</CartesianChart>
<CartesianChart
    Series="series"
    TooltipPosition="LiveChartsCore.Measure.TooltipPosition.Right"><!-- mark -->
</CartesianChart>
<CartesianChart
    Series="series"
    TooltipPosition="LiveChartsCore.Measure.TooltipPosition.Center"><!-- mark -->
</CartesianChart>
<CartesianChart
    Series="series"
    TooltipPosition="LiveChartsCore.Measure.TooltipPosition.Hidden"><!-- mark -->
</CartesianChart>

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

legends

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.

<CartesianChart
    Series="series"
    LegendPosition="LiveChartsCore.Measure.LegendPosition.Top"><!-- mark -->
</CartesianChart>
<CartesianChart
    Series="series"
    LegendPosition="LiveChartsCore.Measure.LegendPosition.Bottom"><!-- mark -->
</CartesianChart>
<CartesianChart
    Series="series"
    LegendPosition="LiveChartsCore.Measure.LegendPosition.Left"><!-- mark -->
</CartesianChart>
<CartesianChart
    Series="series"
    LegendPosition="LiveChartsCore.Measure.LegendPosition.Right"><!-- mark -->
</CartesianChart>
<CartesianChart
    Series="series"
    LegendPosition="LiveChartsCore.Measure.LegendPosition.Hidden"><!-- mark -->
</CartesianChart>

DrawMarginFrame property

This property defines a visual border for the DrawMargin.

<CartesianChart
    Series="series"
    DrawMarginFrame="drawMarginFrame"><!-- mark -->
</CartesianChart>
private DrawMarginFrame drawMarginFrame { get; set; }
    = new DrawMarginFrame
    {
        Fill = new SolidColorPaint(SKColors.AliceBlue),
        Stroke = new SolidColorPaint(SKColors.Black, 3)
    };

sections

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.

<CartesianChart
    Series="series"
    Sections="sections"><!-- mark -->
</CartesianChart>
private RectangularSection[] sections { get; set; }
    = 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))
        }
    };

sections