wpf-6339-controls-and-libraries-charts-suite-chart-control-series-series.md
A series is a group of data points that have the same argument and value types. The series type determines the number of values that are required to define a point; it also specifies point appearance. Series can also have additional series elements that help analyze data and provide extra information; series also allow you to filter data before displaying it in a chart.
The following image displays the Area, Line and Side-by-Side Bar series in a 2D XY Diagram:
This document consists of the following sections:
Use one of the approaches below to add series to a chart.
The following example shows how to add an empty series to a chart:
<dxc:ChartControl x:Name="chart">
<dxc:XYDiagram2D>
<dxc:PointSeries2D DisplayName="New Series"/>
</dxc:XYDiagram2D>
</dxc:ChartControl>
The table below lists classes and properties used by the markup above:
|
|
The diagram series’ collection. The context property: you can declare series directly after a diagram’s declaration in XAML.
| |
|
The base class for all individual series in the chart.
|
The following code generates series from a data source:
<dxc:ChartControl DataSource="{Binding AnnualSales}">
<dxc:ChartControl.DataContext>
<local:AnnualSalesViewModel>
</dxc:ChartControl.DataContext>
<dxc:ChartControl.Diagram>
<dxc:XYDiagram2D SeriesDataMember="Year">
<dxc:XYDiagram2D.SeriesTemplate>
<dxc:BarSideBySideSeries2D ArgumentDataMember="Region"
ValueDataMember="Value"/>
</dxc:XYDiagram2D.SeriesTemplate>
</dxc:XYDiagram2D>
</dxc:ChartControl.Diagram>
</dxc:ChartControl>
public class AnnualSalesViewModel {
public IReadOnlyList<AnnualSalesItem> AnnualSales { get; }
public AnnualSalesViewModel() {
AnnualSales = new List<AnnualSalesItem>() {
new AnnualSalesItem(2015, "Asia", 4.23D),
new AnnualSalesItem(2015, "North America", 3.485D),
new AnnualSalesItem(2015, "Europe", 3.088D),
new AnnualSalesItem(2015, "Australia", 1.78D),
new AnnualSalesItem(2015, "South America", 1.602D),
new AnnualSalesItem(2016, "Asia", 4.768D),
new AnnualSalesItem(2016, "North America", 3.747D),
new AnnualSalesItem(2016, "Europe", 3.357D),
new AnnualSalesItem(2016, "Australia", 1.957D),
new AnnualSalesItem(2016, "South America", 1.823D),
new AnnualSalesItem(2017, "Asia", 5.289D),
new AnnualSalesItem(2017, "North America", 4.182D),
new AnnualSalesItem(2017, "Europe", 3.725D),
new AnnualSalesItem(2017, "Australia", 2.272D),
new AnnualSalesItem(2017, "South America", 2.117D)
};
}
}
public class AnnualSalesItem {
public int Year { get; }
public String Region { get; }
public decimal Value { get; }
public AnnualSalesItem(int year, string region, decimal value) {
this.Year = year;
this.Region = region;
this.Value = value;
}
}
Public Class AnnualSalesViewModel
Public ReadOnly Property AnnualSales As IReadOnlyList(Of AnnualSalesItem)
Public Sub New()
AnnualSales = New List(Of AnnualSalesItem) From {
New AnnualSalesItem(2015, "Asia", 4.23D),
New AnnualSalesItem(2015, "North America", 3.485D),
New AnnualSalesItem(2015, "Europe", 3.088D),
New AnnualSalesItem(2015, "Australia", 1.78D),
New AnnualSalesItem(2015, "South America", 1.602D),
New AnnualSalesItem(2016, "Asia", 4.768D),
New AnnualSalesItem(2016, "North America", 3.747D),
New AnnualSalesItem(2016, "Europe", 3.357D),
New AnnualSalesItem(2016, "Australia", 1.957D),
New AnnualSalesItem(2016, "South America", 1.823D),
New AnnualSalesItem(2017, "Asia", 5.289D),
New AnnualSalesItem(2017, "North America", 4.182D),
New AnnualSalesItem(2017, "Europe", 3.725D),
New AnnualSalesItem(2017, "Australia", 2.272D),
New AnnualSalesItem(2017, "South America", 2.117D)
}
End Sub
End Class
Public Class AnnualSalesItem
Public ReadOnly Property Year As Integer
Public ReadOnly Property Region As String
Public ReadOnly Property Value As Decimal
Public Sub New(Year As Integer, Region As String, Value As Decimal)
Me.Year = Year
Me.Region = Region
Me.Value = Value
End Sub
End Class
The markup above uses the following classes and properties:
|
Member
|
Description
| | --- | --- | |
|
Gets or sets the chart control’s data source.
| |
|
Specifies the series template settings.
| |
|
Gets or sets the name of the data field whose values are used to automatically generate and populate series.
|
The Chart control performs the following to generate series from a data source:
The series displays data you provide. This section describes methods you can use to populate series with data:
The following markup adds a Line series with five manually added series points:
<dxc:ChartControl>
<dxc:ChartControl.DataContext>
<local:AnnualSalesViewModel>
</dxc:ChartControl.DataContext>
<dxc:XYDiagram2D>
<dxc:LineSeries2D DisplayName="2017">
<dxc:SeriesPoint Argument="Asia" Value="5.289"/>
<dxc:SeriesPoint Argument="North America" Value="4.182"/>
<dxc:SeriesPoint Argument="Europe" Value="3.725"/>
<dxc:SeriesPoint Argument="Australia" Value="2.272"/>
<dxc:SeriesPoint Argument="South America" Value="2.117"/>
</dxc:LineSeries2D>
</dxc:XYDiagram2D>
</dxc:ChartControl>
The markup above uses the following classes and properties:
|
Member
|
Description
| | --- | --- | |
|
The series’s collection of points.
| |
|
An individual point.
|
Note that several series require more than one Value per point to display data. These series provide attached properties to specify additional values:
|
Series
|
Attached Property
| | --- | --- | |
|
| |
|
Note that the point’s value should not be specified for the financial series.
| |
|
| |
|
| |
|
| |
|
|
The following code populates a new series with points from the item collection that the chart’s data context object provides:
<dxc:ChartControl>
<dxc:ChartControl.DataContext>
<local:SalesViewModel>
<dxc:ChartControl.DataContext>
<dxc:ChartControl.Diagram>
<dxc:XYDiagram2D>
<dxc:XYDiagram2D.Series>
<dxc:BarSideBySideSeries2D DisplayName="2017"
DataSource="{Binding SalesIn2017}"
ArgumentDataMember="Region"
ValueDataMember="Value"/>
</dxc:XYDiagram2D.Series>
</dxc:XYDiagram2D>
</dxc:ChartControl.Diagram>
</dxc:ChartControl>
public class SalesViewModel {
public IReadOnlyList<SalesItem> SalesIn2017 { get; }
public SalesViewModel() {
SalesIn2017 = new List<SalesItem>() {
new SalesItem("Asia", 5.289D),
new SalesItem("North America", 4.182D),
new SalesItem("Europe", 3.725D),
new SalesItem("Australia", 2.272D),
new SalesItem("South America", 2.117D)
}
}
}
public class SalesItem {
public string Region { get; }
public decimal Value { get; }
public SalesItem(string region, decimal value) {
this.Region = region
this.Value = value
}
}
Public Class SalesViewModel
Public ReadOnly Property SalesIn2017 As IReadOnlyList(Of SalesItem)
Public Sub New()
SalesIn2017 = New List(Of SalesItem) From {
New SalesItem("Asia", 5.289D),
New SalesItem("North America", 4.182D),
New SalesItem("Europe", 3.725D),
New SalesItem("Australia", 2.272D),
New SalesItem("South America", 2.117D)
}
End Sub
End Class
Public Class SalesItem
Public ReadOnly Property Region As String
Public ReadOnly Property Value As Decimal
Public Sub New(Region As String, Value As Decimal)
Me.Region = Region
Me.Value = Value
End Sub
End Class
This code utilizes the following classes and properties:
|
Member
|
Description
| | --- | --- | |
|
Specifies the series’s data source.
| |
|
Gets or sets the name of the data field which contains arguments for generated series points.
| |
|
Gets or sets the name of the data field which contains values for generated series points.
|
To populate series with points from a data source, the chart control generates a series point for each data item. Then, series points use the argument data member’s values as Argument values and the value data member’s values as Value values.
Note that several series require more than one ValueDataMember specified to display data. The following table lists series that have specific ValueDataMember parameters:
|
Series
|
Parameters
| | --- | --- | |
|
BubbleSeries2D.WeightDataMember
| |
|
FinancialSeries2D.OpenValueDataMember
FinancialSeries2D.HighValueDataMember
FinancialSeries2D.LowValueDataMember
FinancialSeries2D.CloseValueDataMember
| |
|
RangeBarSeries2D.Value2DataMember
| |
|
RangeAreaSeries2D.Value2DataMember
| |
|
CircularRangeAreaSeries2D.Value2DataMember
|
Important
The Series.Points property returns series points that represent data source values on a chart. The first time you access this property, the series generates series points when the chart/series is bound to data. It is recommended that you avoid using this property, because series point generation requires additional time to convert internal data objects to series points, which in turn can lead to control freezes.
Refer to the Lesson 3 - Bind Chart Series to Data topic for a step-by-step guide that explains how to create a chart, and bind it to a data source.
Use the Diagram.SeriesItemsSource property to bind a chart to a collection of series view models when your application uses the MVVM (Model-View-ViewModel) architecture. The Diagram.SeriesItemTemplate and Diagram.SeriesItemTemplateSelector properties specify how the chart converts view model objects to series.
The following code uses the MVVM architecture to populate the Chart Control with series:
<dxc:ChartControl>
<dxc:ChartControl.Legends>
<dxc:Legend HorizontalPosition="Left" VerticalPosition="Top" Orientation="Horizontal"/>
</dxc:ChartControl.Legends>
<dxc:XYDiagram2D SeriesItemsSource="{Binding GdpSeries}">
<dxc:XYDiagram2D.SeriesItemTemplate>
<DataTemplate>
<dxc:LineSeries2D DisplayName="{Binding CountryName}"
DataSource="{Binding Values}"
ArgumentDataMember="Year"
ValueDataMember="Value"/>
</DataTemplate>
</dxc:XYDiagram2D.SeriesItemTemplate>
</dxc:XYDiagram2D>
</dxc:ChartControl>
public class ChartViewModel {
public IEnumerable<GdpSeries> GdpSeries { get; private set; }
public ChartViewModel() {
GdpSeries = new Collection<GdpSeries> {
new GdpSeries {
CountryName = "USA",
Values = new Collection<Gdp> {
new Gdp { Year = 2015, Value = 18.037},
new Gdp { Year = 2014, Value = 17.393},
new Gdp { Year = 2013, Value = 16.692},
new Gdp { Year = 2012, Value = 16.155},
new Gdp { Year = 2011, Value = 15.518},
new Gdp { Year = 2010, Value = 14.964},
new Gdp { Year = 2009, Value = 14.419},
new Gdp { Year = 2008, Value = 14.719}
}
},
new GdpSeries {
CountryName = "China",
Values = new Collection<Gdp> {
new Gdp { Year = 2015, Value = 11.065},
new Gdp { Year = 2014, Value = 10.482},
new Gdp { Year = 2013, Value = 9.607},
new Gdp { Year = 2012, Value = 8.561},
new Gdp { Year = 2011, Value = 7.573},
new Gdp { Year = 2010, Value = 6.101},
new Gdp { Year = 2009, Value = 5.11},
new Gdp { Year = 2008, Value = 4.598}
}
},
new GdpSeries {
CountryName = "Japan",
Values = new Collection<Gdp> {
new Gdp { Year = 2015, Value = 4.383},
new Gdp { Year = 2014, Value = 4.849},
new Gdp { Year = 2013, Value = 5.156},
new Gdp { Year = 2012, Value = 6.203},
new Gdp { Year = 2011, Value = 6.157},
new Gdp { Year = 2010, Value = 5.7},
new Gdp { Year = 2009, Value = 5.231},
new Gdp { Year = 2008, Value = 5.038}
}
}
};
}
}
Public Class ChartViewModel
Private privateGdpSeries As IEnumerable(Of GdpSeries)
Public Property GdpSeries() As IEnumerable(Of GdpSeries)
Get
Return privateGdpSeries
End Get
Private Set(ByVal value As IEnumerable(Of GdpSeries))
privateGdpSeries = value
End Set
End Property
Public Sub New()
GdpSeries = New Collection(Of GdpSeries) From { _
New GdpSeries With { _
.CountryName = "USA", .Values = New Collection(Of Gdp) From { _
New Gdp With {.Year = 2015, .Value = 18.037}, _
New Gdp With {.Year = 2014, .Value = 17.393}, _
New Gdp With {.Year = 2013, .Value = 16.692}, _
New Gdp With {.Year = 2012, .Value = 16.155}, _
New Gdp With {.Year = 2011, .Value = 15.518}, _
New Gdp With {.Year = 2010, .Value = 14.964}, _
New Gdp With {.Year = 2009, .Value = 14.419}, _
New Gdp With {.Year = 2008, .Value = 14.719} _
} _
}, _
New GdpSeries With { _
.CountryName = "China", .Values = New Collection(Of Gdp) From { _
New Gdp With {.Year = 2015, .Value = 11.065}, _
New Gdp With {.Year = 2014, .Value = 10.482}, _
New Gdp With {.Year = 2013, .Value = 9.607}, _
New Gdp With {.Year = 2012, .Value = 8.561}, _
New Gdp With {.Year = 2011, .Value = 7.573}, _
New Gdp With {.Year = 2010, .Value = 6.101}, _
New Gdp With {.Year = 2009, .Value = 5.11}, _
New Gdp With {.Year = 2008, .Value = 4.598} _
} _
}, _
New GdpSeries With { _
.CountryName = "Japan", .Values = New Collection(Of Gdp) From { _
New Gdp With {.Year = 2015, .Value = 4.383}, _
New Gdp With {.Year = 2014, .Value = 4.849}, _
New Gdp With {.Year = 2013, .Value = 5.156}, _
New Gdp With {.Year = 2012, .Value = 6.203}, _
New Gdp With {.Year = 2011, .Value = 6.157}, _
New Gdp With {.Year = 2010, .Value = 5.7}, _
New Gdp With {.Year = 2009, .Value = 5.231}, _
New Gdp With {.Year = 2008, .Value = 5.038} _
} _
} _
}
End Sub
End Class
public class GdpSeries {
public String CountryName { get; set; }
public IEnumerable<Gdp> Values { get; set; }
}
public class Gdp {
public int Year { get; set; }
public double Value { get; set; }
}
Public Class GdpSeries
Public Property CountryName() As String
Public Property Values() As IEnumerable(Of Gdp)
End Class
Public Class Gdp
Public Property Year() As Integer
Public Property Value() As Double
End Class
The code above utilizes the properties below:
|
Member
|
Description
| | --- | --- | |
|
Gets or sets the collection of objects used to generate series.
| |
|
Gets or sets the DataTemplate that specifies how to convert a model object to a series.
| |
Diagram.SeriesItemTemplateSelector
|
Gets or sets the custom logic for selecting a data template that converts a model object to a series.
|
The Chart Control provides 2D and 3D series. The following sections list all available series:
Note that series of each type have unique specifics and settings. The control can only simultaneously display different types of series if they are compatible.
|
Element
|
Image
| | --- | --- | |
You can show points with labels to provide extra information, such as point arguments or values.
|
| |
Total labels display summary values of several Bar Stacked or Pie series’ points.
|
| |
Indicators help you to analyze and process series data visually.
|
| |
A series title provides additional information on a series.
|
|
The XYSeries.Brush property allows you to specify series color. The Area Series and Funnel Series provide the Border properties that contain the Brush property. This property specifies the series’ border brush:
The following markup demonstrates how to specify a custom color for a series:
<dxc:ChartControl Padding="0">
<dxc:ChartControl.DataContext>
<local:MainViewModel/>
</dxc:ChartControl.DataContext>
<dxc:ChartControl.Diagram>
<dxc:XYDiagram2D>
<dxc:XYDiagram2D.Series>
<dxc:SplineAreaSeries2D DataSource="{Binding History}"
ArgumentDataMember="Date"
ValueDataMember="Balance"
Brush="#43a047">
<dxc:SplineAreaSeries2D.Border>
<dxc:SeriesBorder Brush="#88000000"/>
</dxc:SplineAreaSeries2D.Border>
</dxc:SplineAreaSeries2D>
</dxc:XYDiagram2D.Series>
</dxc:XYDiagram2D>
</dxc:ChartControl.Diagram>
</dxc:ChartControl>
class HistoryItem {
public DateTime Date { get; set; }
public double Balance { get; set; }
}
class MainViewModel {
public IReadOnlyList<HistoryItem> History { get; }
public MainViewModel() {
DateTime initDate = DateTime.Now;
History = new List<HistoryItem> {
new HistoryItem { Date = initDate, Balance = 277 },
new HistoryItem { Date = initDate.AddYears(-1), Balance = 328.5 },
new HistoryItem { Date = initDate.AddYears(-2), Balance = 297 },
new HistoryItem { Date = initDate.AddYears(-3), Balance = 255.3 },
new HistoryItem { Date = initDate.AddYears(-4), Balance = 173.5 },
new HistoryItem { Date = initDate.AddYears(-5), Balance = 131.8 },
};
}
}
Class HistoryItem
Public Property Date As DateTime
Public Property Balance As Double
End Class
class MainViewModel {
Public Property History As IReadOnlyList(Of HistoryItem)
Public Sub New()
Dim initDate As DateTime = DateTime.Now
History = New List(Of HistoryItem) From {
New HistoryItem { .Date = initDate, .Balance = 277 },
New HistoryItem { .Date = initDate.AddYears(-1), .Balance = 328.5 },
New HistoryItem { .Date = initDate.AddYears(-2), .Balance = 297 },
New HistoryItem { .Date = initDate.AddYears(-3), .Balance = 255.3 },
New HistoryItem { .Date = initDate.AddYears(-4), .Balance = 173.5 },
New HistoryItem { .Date = initDate.AddYears(-5), .Balance = 131.8 },
}
End Sub
End Class
The classes and properties below configure series’ colors:
|
Symbol
|
Description
| | --- | --- | |
|
Gets or sets the color of the XY-series.
| |
|
Provides access to a series border’s settings.
| |
|
Contains settings the specify the appearance of a series border.
|
Important
The Chart Control can use only SolidColorBrush objects to draw series.
Note
The pie/donut series and funnel series do not provide series color and you should utilize series points’ brushes
Tip
Use the ChartControl.BoundDataChanged event to specify colors of series generated via the Series Template.
See Also