Automatic updates Updates
LiveCharts is listening for any change in your data, the library is be able to update automatically, every time you change a property or you add, remove, replace, insert or clear your data collection you will see that change immediately in the user interface, for most cases automatic updates should not impact performance significantly.
LiveCharts changes detection is based on INotifyPropertyChanged
and INotifyCollectionChanged
interfaces, both
provided by the .Net framework, every time a property or a collection changes and the object implements any of these
interfaces, the chart throttles an update, this means that the library will not update every time a
change happens, it will only update once every 10 ms (by default).
LiveCharts changes detection is handled by the CollectionDeepObserver
class, this objects makes it easy for the library to listen and stop listening to changes in all the objects that
must fire an update in the library. Listeners must be removed automatically by the library, if not, then it is a bug,
you can call the CollectionDeepObserver.Dispose
method if you are facing memory leaks, but it is not the
intention, the library should handle that automatically.
The CollectionDeepObserver
class subscribes and unsubscribes a handler to INotifyCollectionChanged.CollectionChanged
event, this means
that any time you add, remove, replace, insert or clear the collection, the library will be able to update.
Also if any item in the collection implements INotifyPropertyChanged
, the library will also subscribe a handler
to the PropertyChanged
event for each item that implements the interface, this means that any time a property changes
LiveCharts will be able to update. The library should remove the subscriptions to both events once they are no longer
necessary, for example when you remove an item from the collection, the library should also unsubscribe the handler
to that item that was just removed.
All the objects provided by LiveCharts, when necessary implement INotifyCollectionChanged
or
INotifyPropertyChanged
, so normally after changing any property in your plot, you will see that immediately in
the user interface, but there are special cases where it is up to the developer whether the chart will update or
not, since the implementation of these interfaces depends on the data your provide to the library, this is
specially important to understand for the Chart.Series
and Series.Values
properties.
Enable automatic updates for the Series.Values and Chart.Series properties
Automatic updates for most cases should not impact performance significantly, so feel free to do it, LiveCharts will be able to detect a change in your data only when these interfaces are implemented.
INotifyCollectionChanged
The INotifyCollectionChanged
interface is provided by the .Net framework and it is widely used all over the
framework, there are some classes that already implement the interface such as the ObservableCollection
class,
this class notifies the subscriber when you add, remove, insert, replace or clear the collection.
// since valuesCollection is of type ObservableCollection
// LiveCharts will update when you add, remove, replace or clear the collection
var valuesCollection = new ObservableCollection<double>();
var lineSeries = new LineSeries<double>();
lineSeries.Values = valuesCollection;
valuesCollection.Add(4);
valuesCollection.Add(6);
valuesCollection.Add(2);
// you should see the values in the user interface.
// but in the following series, you will not see the change in the user interface.
var valuesCollection2 = new List<double>();
var lineSeries = new LineSeries<double>();
lineSeries.Values = valuesCollection2;
valuesCollection2.Add(4);
valuesCollection2.Add(6);
valuesCollection2.Add(2);
// the UI will not update automatically.
// it works the same for the Chart.Series property
// the library will be able to reflect when you add a new series
// to your plot, only if the collection implements INotifyCollectionChanged
var seriesCollection = new ObservableCollection<ISeries>();
myChartControl.Series = seriesCollection;
seriesCollection.Add(new LineSeries{ Values = new [] { 1, 2, 3 } });
// the previous block updated the chart when the Add method was called
// but the following will not:
var seriesCollection = new List<ISeries>();
myChartControl.Series = seriesCollection;
seriesCollection.Add(new LineSeries{ Values = new [] { 1, 2, 3 } });
INotifyPropertyChanged
You are probably already familiar with the INotifyPropertyChanged
interface, it is normally used to reflect
the changes of an object in the user interface, LiveCharts also uses this interface to detect when a property on your
data changed, but it is up to you to implement the interface.
The library already provides objects that implement the interface, you can use them to enable automatic property changed updates.
// The LiveChartsCore.Defaults.ObservableValue class is ready
// to update the user interface every time the Value property changes
var valuesCollection = new ObservableCollection<ObservableValue>();
valuesCollection.Add(new ObservableValue { Value = 1 });
valuesCollection.Add(new ObservableValue { Value = 2 });
valuesCollection.Add(new ObservableValue { Value = 3 });
// every time you update the Value property, you will also
// see that change in the user interface
valuesCollection[0].Value = 5;
// notice that valuesCollection is of type ObservableCollection
// this means that it is listening for add, remove, replace or clear changes
// in the collection, but in this case, the property changed update
// would have also worked if it was just a List<> or any other collection
var valuesCollection = new List<ObservableValue>();
valuesCollection.Add(new ObservableValue { Value = 1 });
valuesCollection.Add(new ObservableValue { Value = 2 });
valuesCollection.Add(new ObservableValue { Value = 3 });
// it also updates! but is not listening to add, remove, insert, replace and clear changes.
valuesCollection[0].Value = 5;
Finally you can also plot an object defined in you application (see Mappers), and the
logic is the same, the library will be able to reflect the changes in the user interface just when your
object implements INotifyPropertyChanged
, lets take the following City
class as an example.
public class City
{
public double Population { get; set; }
}
// now in our chart we will plot objects of type City
var valuesCollection = new List<City>();
valuesCollection.Add(new City { Population = 100 });
valuesCollection.Add(new City { Population = 200 });
valuesCollection.Add(new City { Population = 300 });
// this will not update the user interface, since the City class does not
// implement INotifyPropertyChanged
valuesCollection[0].Population = 500;
// Lets now change the City class definition to implement INotifyPropertyChanged
// so our chart can update once the Population property changes
using System.ComponentModel;
using System.Runtime.CompilerServices;
public class City : INotifyPropertyChanged
{
private double population;
public double Population { get => population; set { population = value; OnPropertyChanged(); } }
public event PropertyChangedEventHandler? PropertyChanged;
protected virtual void OnPropertyChanged([CallerMemberName] string? propertyName = null)
{
PropertyChanged?.Invoke(propertyName, new PropertyChangedEventArgs(propertyName));
}
}
// after this implementation the chart will update once the Population property changes