How to: Add a Legend

This how-to guide shows you how to display a legend on your chart, highlighting the various customization options available.

In order to display a legend you need to do the following:

  1. Retrieve the Legend object from your chart and make it visible
  2. Give the legend and the series titles
  3. Change the placement and position of the legend

A legend can be useful to identify what each series on your chart is representing.

Looking for a Legend

The ShinobiChart object will automatically create a legend for you which you can get hold of by using its getLegend method:

Java

Legend legend = shinobiChart.getLegend();

C#

Legend legend = shinobiChart.Legend;

However, by default it is hidden. As the Legend is an ordinary Android View object, to make it visible you have to call the setVisibility method:

Java

legend.setVisibility(View.VISIBLE);

C#

legend.Visibility = ViewStates.Visible;

You can give this method one of three constants defined in the View class: VISIBLE, INVISIBLE or GONE - see the Android documentation for more details.

What’s in a Name?

The legend will list each series in the chart in the order they were added. Without a specific title, each series will be referred to as Series n (where n is the one-based position in the chart’s list of series).

Legend populated with default series titles

To make it a bit more meaningful you can give each series a title:

Java

BarSeries smartphoneSales = new BarSeries();
smartphoneSales.setTitle("Smartphones");

C#

BarSeries smartphoneSales = new BarSeries();
smartphoneSales.Title = "Smartphones";

Tip: For `PieSeries` and `DonutSeries`, the legend will display the X value for each slice in the first series added to the chart, rather than showing the series titles.

You can also give the legend itself a title which is displayed at the top:

Java

legend.setTitle("Device Type");

C#

legend.Title = "Device Type";

The Place (and Position) To Be!

By default the legend will be placed outside the plot area and positioned in the top right hand corner but you’re not stuck with this choice!

You can place the legend outside the plot area, inside the plot area or even on the plot area border using the setPlacement method and the Legend.Placement enum. Calling this will automatically re-layout the chart to fit the legend in the correct place with respect to the canvas.

Similarly you can position the legend in a number of set positions around the chart by calling the setPosition method with a value from the Legend.Position enum. Again, calling this will automatically re-layout the chart.

So, for example, to put the legend in the bottom-center of the chart so that it is placed inside the plot area you would call:

Java

legend.setPlacement(Legend.Placement.INSIDE_PLOT_AREA);

C#

legend.LegendPlacement = Legend.Placement.InsidePlotArea;

Note that when the legend is positioned in the top or bottom center position, by default the series labels are laid out horizontally in one row whereas in any other position they are laid out vertically in one column. You can change this behavior by calling the setMaxSeriesPerRow method.

Java

legend.setMaxSeriesPerRow(2);

C#

legend.MaxSeriesPerRow = 2;

This tells the legend to put at most two labels in each row. If you want the default behavior back you can call the method with the Legend.VARIABLE constant. If you want all of the series to be laid out in one row you can use the Legend.ALL constant.

Legend Sample App

Stylish Legends

The legend has a LegendStyle object which controls its look and feel. You can obtain this style object using legend.getStyle(). There are many styling options but we’ll just make use of a select few. Checkout the API docs to see all of the options available to you!

Java

LegendStyle legendStyle = legend.getStyle();
legendStyle.setBackgroundColor(Color.argb(150, 255, 255, 255));
legendStyle.setBorderWidth(6.0f);
legendStyle.setBorderColor(Color.argb(255, 153, 153, 153));
legendStyle.setCornerRadius(10.0f);
legendStyle.setTextSize(12.0f);
legendStyle.setSymbolAlignment(Legend.SymbolAlignment.RIGHT);
legendStyle.setPadding(14.0f);

shinobiChart.redrawChart();

C#

LegendStyle legendStyle = legend.Style;
legendStyle.BackgroundColor = Color.Argb(150, 255, 255, 255);
legendStyle.BorderWidth = 6.0f;
legendStyle.BorderColor = Color.Argb(255, 153, 153, 153);
legendStyle.CornerRadius = 10.0f;
legendStyle.TextSize = 12.0f;
legendStyle.SymbolAlignment = Legend.SymbolAlignment.Right;
legendStyle.Padding = 14.0f;

shinobiChart.RedrawChart();

In order for these style changes to take effect you have to call redrawChart on your ShinobiChart.

Legend with styles applied

Take a look at the Legend sample code project to see a chart displaying a legend. Have a play with the code, changing the legend’s style properties and putting it in the different positions (and placements!) around the chart.

See related code sample: Legend Sample, in the samples/legend folder of your product download (Xamarin.Android/samples/Legend if you’re using Xamarin.Android) .