Version

Data Legend

The XamDataLegend is a component that works much like the Legend, but it shows values of series and provides many configuration properties for filtering series rows and values columns, styling and formatting values. This legend updates when moving the mouse inside of the plot area of the XamCategoryChart and has a persistent state that remembers the last hovered point when the user’s mouse pointer exits the plot area. It displays this content using a set of three type of rows and four types of columns.

Data Legend Rows

The rows of the XamDataLegend include the header row, series row(s), and the summary row.

The header row displays the axis label of the point that is hovered, and can be changed using the HeaderText property.

The series row can actually be a set of rows corresponding to each series plotted in the chart. These rows will display the legend badge, series title, actual/abbreviated value of the the series, and abbreviation symbol and unit, if specified.

Finally, there is a summary row that displays the total of all series values. The default summary title can be changed using the SummaryTitleText property of the legend. Also, you can use the SummaryType property to customize whether you display the Total, Min, Max, or Average of series values in the summary row.

The following code snippet demonstrates setting the properties mentioned above to have a XamDataLegend with a Total summary type with a custom title for the summary and a custom header:

In XAML:

<ig:XamDataLegend Target="{Binding ElementName=chart}"
                  HeaderText="My Custom Data Legend Header"
                  SummaryType="Total"
                  SummaryTitleText="Grand Total"/>

<ig:XamCategoryChart x:Name="chart" />

In C#:

dataLegend1.Target = categoryChart1;
dataLegend1.HeaderText = "My Custom Data Legend Header";
dataLegend1.SummaryType = Infragistics.Controls.Charts.DataLegendSummaryType.Total;
dataLegend1.SummaryTitleText = "Grand Total";

Data Legend Columns

The columns of the XamDataLegend include the title, label, value, and units columns. Each series in the chart can have multiple columns for label, value, and units depending on the IncludedColumns or ExcludedColumns collections of the legend.

The title column displays legend badges and series titles, which come from the Title property of the different Series plotted in the chart.

The label column displays the name or abbreviation of the different property paths in the IncludedColumns or ExcludedColumns collections of the legend.

The value column displays series values as abbreviated text which can be formatted using the ValueFormatAbbreviation property to apply the same abbreviation for all numbers by setting this property to Auto or Shared. Alternatively, a user can select other abbreviations such as Independent, Kilo, Million, etc. Precision of abbreviated values is controlled using the ValueFormatMinFractions and ValueFormatMaxFractions for minimum and maximum digits, respectively.

The units column displays an abbreviation symbol and/or unit text, which can be set either on the XamDataLegend by setting the UnitsText property.

The following code snippet demonstrates the UnitsText and the minimum/maximum fractions set on the XamDataLegend:

In XAML:

<ig:XamDataLegend Target="{Binding ElementName=chart}"
                  UnitsText="K"
                  ValueFormatMinFractions="2"
                  ValueFormatMaxFractions="4"/>

<ig:XamCategoryChart x:Name="chart" />

In C#:

dataLegend1.Target = categoryChart1;
dataLegend1.UnitsText = "K";
dataLegend1.ValueFormatMinFractions = 2;
dataLegend1.ValueFormatMaxFractions = 4;

Data Legend Styling

The XamDataLegend provides properties for styling each type of column. Each of these properties begins with Title, Label, Value, or Units, and you can style the text’s color, font, and margin. For example, if you wanted to set the text color of each of these, you would set the TitleTextColor, LabelTextColor, ValueTextColor, and UnitsTextColor properties.

The following code snippet demonstrates how to set the styling properties mentioned above:

In XAML:

<ig:XamDataLegend Target="{Binding ElementName=chart}"
                  TitleTextColor="LightGray"
                  LabelTextColor="LightGray"
                  ValueTextColor="Green"
                  UnitsTextColor="Green"
                  UnitsText="K"/>

<ig:XamCategoryChart x:Name="chart" />

In C#:

dataLegend1.Target = categoryChart1;
dataLegend1.TitleTextColor = Brushes.LightGray;
dataLegend1.LabelTextColor = Brushes.LightGray;
dataLegend1.ValueTextColor = Brushes.Green;
dataLegend1.UnitsTextColor = Brushes.Green;
dataLegend1.UnitsText = "K";

Data Legend Value Formatting

The XamDataLegend provides automatic abbreviation of large numbers using its ValueFormatAbbreviation property. This adds a multiplier in the units column such as kilo, million, billion, etc.

You can customize the number of fractional digits that are displayed by setting the ValueFormatMinFractions and ValueFormatMaxFractions. This will allow you to determine the minimum and maximum number of digits that appear after the decimal point, respectively.

The following code snippet demonstrates how to set the minimum and maximum fractions of the XamDataLegend:

In XAML:

<ig:XamDataLegend Target="{Binding ElementName=chart}"
                          ValueFormatMinFractions="2"
                          ValueFormatMaxFractions="4"/>

<ig:XamCategoryChart x:Name="chart" />

In C#:

dataLegend1.Target = categoryChart1;
dataLegend1.ValueFormatMinFractions = 2;
dataLegend1.ValueFormatMaxFractions = 4;

Data Legend Value Mode

You have the ability to change the default decimal display of values within the XamDataLegend to be currency by changing the ValueFormatMode property of the control. The XamDataLegend also exposes the ability to modify the culture of the displayed currency symbol by using its ValueFormatCulture property and setting it to its corresponding culture tag.

For example, the following code snippet will create a XamDataLegend with the ValueFormatCulture set to "en-GB" and the ValueFormatMode set to "Currency":

In XAML:

<ig:XamDataLegend Target="{Binding ElementName=chart}"
                  ValueFormatMode="Currency"
                  ValueFormatCulture="en-GB"/>

<ig:XamCategoryChart x:Name="chart" />

In C#:

dataLegend1.Target = categoryChart1;
dataLegend1.ValueFormatMode = Infragistics.Controls.Charts.DataLegendValueMode.Currency;
dataLegend1.ValueFormatCulture = "en-GB";

Data Legend Styling Events

The XamDataLegend has three events that fire when rendering their corresponding row. These events are listed below with a description of what they are designed to be used for:

  • StyleHeaderRow: This event fires once when rendering the header row.

  • StyleSeriesRow: This event fires once for each series row which allows conditional styling of the values of the series.

  • StyleSeriesColumn: This event fires once for each series column, which allows conditional styling of the different columns for the series in the chart.

  • StyleSummaryRow: This event fires once when rendering the summary row.

  • StyleSummaryColumn: This event fires once when rendering the summary column.

Each of the above events exposes a DataLegendStylingRowEventArgs parameter as its arguments, which lets you customize each item’s text, text color, and the overall visibility of the row. The event arguments also expose event-specific properties. For example, since the StyleSeriesRow event fires for each series, the event arguments will return the series index and series title for the row that represents the series.

The following code snippet demonstrates usage of the above row styling events:

In C#:

private void Legend_StyleSummaryRow(object sender, Infragistics.Controls.Charts.DataLegendStylingRowEventArgs row)
{
    row.TitleText = "Grand Total: ";
    row.TitleTextColor = Brushes.DimGray;
}

private void Legend_StyleSeriesRow(object sender, Infragistics.Controls.Charts.DataLegendStylingRowEventArgs row)
{
    row.BadgeShape = Infragistics.Controls.Charts.LegendItemBadgeShape.Square;
    row.TitleText = (row.SeriesIndex + 1) + ". " + row.SeriesTitle;
    row.TitleTextColor = new SolidColorBrush(Colors.DimGray);
}

private void Legend_StyleHeaderRow(object sender, Infragistics.Controls.Charts.DataLegendStylingRowEventArgs row)
{
    row.TitleText = "Date: " + row.TitleText;
    row.TitleTextColor = Brushes.DimGray;
}