How to: Handle Selection

This how-to guide shows you how enable and control user selection of series and points, and how to receive notifications of selection events.

Users can select series and points by tapping on them. In general this will cause them to be visually highlighted, and you may want your app to respond to these events.

In order to handle selection you need to do some or all of the following:

  1. Enable selection in the particular mode you require on the series and chart.
  2. Set series styling options to provide clear feedback to the user.
  3. Set a listener on the chart and provide your response behavior as you require.

The code in this guide is taken from the Handling Selection Sample app.

Selection Options

The selection options are simple in concept, but all the series are subtly different in detail, reflecting the different use cases they are commonly put to. In general:

  • You can turn selection on or off.
  • You can deal with selection at the level of whole series or individual points.
  • You can specify that selecting one series or point will deselect the others (POINT_SINGLE selection), or that they can be selected independently (POINT_MULTIPLE selection).

In detail:

  • All (see below) the selection options are controlled via the Series.GestureSelectionMode. This has the possible values NONE, SERIES, POINT_SINGLE and POINT_MULTIPLE.
  • You may have noticed the lack of SERIES_SINGLE and SERIES_MULTIPLE. This is controlled at the ShinobiChart level (otherwise the series could be inconsistent with each other), using setSeriesSelectionSingle.
  • All CartesianSeries, that is LineSeries, ColumnSeries, BarSeries, BandSeries, OHLCSeries and CandlestickSeries, support either series or point selection.
  • PieSeries and DonutSeries support point (slice) selection, but not series selection. This comes with an optional animation to rotate the most recently selected slice to the top of the chart, using setSelectedPosition.

So in this example you first set the selection mode of your series to SERIES.

Java

columnChart.setSeriesSelectionSingle(true);

series.setGestureSelectionMode(GestureSelectionMode.SERIES);

C#

columnChart.SeriesSelectionSingle = true;

series.SeriesGestureSelectionMode = Series.GestureSelectionMode.Series;

Selected Styles

All series have two associated style objects - the SeriesStyle returned by Series.getStyle() and the SeriesStyle returned by Series.getSelectedStyle(). It is the responsibility of the SeriesStyleProvider to provide a suitable SeriesStyle for each data point. The behavior of the default SeriesStyleProvider implementation for each Series type returns either of these style objects based on the GestureSelectionMode of the Series and selection status of the Series or individual point. Therefore, Series.getStyle() is used when the series or points are not selected and Series.getSelectedStyle() is used when the series or points are selected.

We also have a similar pattern with points on line series - each LineSeriesStyle has two PointStyle objects: one for non-selected points and a one for selected points. You should note here that if you select a whole series, all its points will be selected, so if you want to style those points you’ll need to use the LineSeriesStyle.getSelectedPointStyle() on the selected style of the LineSeries.

The styling is like any other styling operation in shinobicharts, so modify the selected style on both ColumnSeries to a flat-shaded bright red, so it stands right out:

Java

series.getSelectedStyle().setFillStyle(FillStyle.FLAT);
series.getSelectedStyle().setAreaColor(Color.RED);

C#

series.SelectedStyle.FillStyle = SeriesStyle.FillStyle.Flat;
series.SelectedStyle.AreaColor = Android.Graphics.Color.Red;

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

Programmatic Selection

It’s also possible to select series and points programmatically, without user interaction. After creating the chart set the selection state of the first series to true, so we start the app with one series already selected.

Java

columnChart.getSeries().get(0).setSelected(true);

C#

columnChart.Series[0].Selected = true;

Selection Notifications

The final part of the story involves setting up a listener for selection events. The listener is set on the chart, and must implement the OnSeriesSelectionListener interface.

The OnSeriesSelectionListener interface contains two methods:

  • onSeriesSelectionStateChanged is called when an entire series is selected or deselected
  • onPointSelectionStateChanged is called when a single point is selected or deselected

Which one is called depends on the selection mode you chose above.

In this example we will make the Activity listen to these events on the column chart, so make the Activity implement the OnSeriesSelectionListener interface.

Java

public class HandlingSelection extends Activity implements ShinobiChart.OnSeriesSelectionListener {

C#

public class MainActivity : Activity, IShinobiChartOnSeriesSelectionListener

Next set the Activity as the listener on the chart. Do this when creating the chart.

Java

columnChart.setOnSeriesSelectionListener(this);

C#

columnChart.SetOnSeriesSelectionListener (this);

Finally provide the Activity with an implementation for the interface methods. In this case we are using SERIES selection mode, so you only need a body for onSeriesSelectionStateChanged. In this example we have updated the title and swapped the data source on the pie chart.

Java

@Override
public void onPointSelectionStateChanged(Series<?> arg0, int arg1) {
}

@Override
public void onSeriesSelectionStateChanged(Series<?> series) {
    if (series.isSelected()) {
        pieChart.setTitle(series.getTitle());
        pieChart.getSeries().get(0).setDataAdapter(series.getDataAdapter());
    }
}

C#

public void OnPointSelectionStateChanged (Series p0, int p1)
{
}

public void OnSeriesSelectionStateChanged (Series p0)
{
    if (p0.Selected) {
        pieChart.Title = p0.Title;
        pieChart.Series[0].DataAdapter = p0.DataAdapter;
    }
}

This is a fairly simple response to a selection event. If you want to do something more complex involving point selection the callback method will tell you the index of the point whose selection state has changed. You can look this up in your data adapter to get the data values, and the axes supply methods for converting between data values and pixel positions on the screen, relative to the chart.

Tip: You can also receive notifications about the actual gestures that caused the selection events, using the ShinobiChart.OnGestureListener interface.

And that’s all you need to do. If you run the HandlingSelection sample app you will be able to tap on the columns of the column chart, see the series highlight, and see the pie chart updated with the same data as the highlighted series.

See related code sample: Handling Selection Sample, in the samples/handling-selection folder of your product download (Xamarin.Android/samples/HandlingSelection if you’re using Xamarin.Android).