Selection Handling

This topic provides an overview of fields and methods that will help you configure selection and handle selection-related events in the Chart and PieChart widgets.

Series Selection

To select a series, call the select() method of the series object. For instance, you can select a series when it is clicked within the chart onSeriesClick handler (see Click Handling).

JavaScript
var chartOptions = {
    onSeriesClick: function (info) {
        var clickedSeries = info.target;
        clickedSeries.select();
    }
};

Alternatively, you can access a series when required, using one of the following chart methods: getAllSeries(), getSeriesByName() and getSeriesByPos().

NOTE: There are series that consist of points only, e.g., the bar-like and candleStick series of the Chart widget, and the pie and doughnut series of the PieChart widget. To select these series types on click, implement the onPointClick handler. Use the target.series field of the object passed to this handler as the parameter to access the series of the clicked point (bar or slice).

A series has a distinctive style when selected. To customize it, use the series selectionStyle configuration object. This object can specify settings for all series:

JavaScript
var chartOptions = {
    commonSeriesSettings: {
        selectionStyle: {
            // Common selection style configuration    
        }
    }
};

for type-specific series:

JavaScript
var chartOptions = {
    commonSeriesSettings: {
        line: { // or 'bar', 'spline', etc.
            selectionStyle: {
                // Type-specific selection style configuration    
            }
        }
    }
};

or for an individual series:

JavaScript
var chartOptions = {
    series: [{
        selectionStyle: {
            // Individual selection style configuration
        }
    }, {
        // ...
    }]
};

To choose which series elements to highlight in the selected state, specify the selectionMode option. Like the selection style, this option can be specified for all, type-specific or an individual series. There are several selection modes in the chart widgets. Available modes depend on the series type you use.

You can also allow the user to select multiple series. For this purpose, set the seriesSelectionMode option to 'multiple'.

To handle the series selection event, assign a function to the onSeriesSelectionChanged option of the chart.

JavaScript
var chartOptions = {
    onSeriesSelectionChanged: function (info) {
        //...
    }
};

The onSeriesSelectionChanged function accepts an object that contains information on the selection event. Among fields of this object, you can find the series whose selection state has been changed. An object that represents this series is described in the Series section. Use the isSelected() method of this object to check the selection state of a series.

To clear the series selection, call the clearSelection() method of the series or the same method of the chart instance.

JavaScript
chartInstance.clearSelection();
// chartInstance.getSeriesByName('seriesName').clearSelection();
Show Example:
AngularJS
Knockout
jQuery

In this example, clicking a series selects it. The onSeriesSelectionChanged event handler calculates the maximum point value of the selected series and outputs it below the chart. To get the points of the selected series, its getAllPoints() method is used.


                                    

                                    

In this example, clicking a series selects it. The onSeriesSelectionChanged event handler calculates the maximum point value of the selected series and outputs it below the chart. To get the points of the selected series, its getAllPoints() method is used.


                                    

                                    

In this example, clicking a series selects it. The onSeriesSelectionChanged event handler calculates the maximum point value of the selected series and outputs it below the chart. To get the points of the selected series, its getAllPoints() method is used.


                                    

                                    

Point Selection

To select a data point, use its select() method. For instance, you can select a point on a click using the chart's onPointClick handler (see Click Handling).

JavaScript
var chartOptions = {
    onPointClick: function (info) {
        var clickedPoint = info.target;
        clickedPoint.select();
    }
};

In addition, you can select a specific point in a series using the series' selectPoint(point) function. The series object exposes methods that can help you find the required point to be selected: getAllPoints(), getPointByPos() and getPointsByArg().

A point has a distinctive style when selected. To customize it, use the selectionStyle configuration object. This object can specify settings for all chart points:

JavaScript
var chartOptions = {
    commonSeriesSettings: {
        point: {
            selectionStyle: {
                // Common selection style configuration    
            }
        }
    }
};

for type-specific series points:

JavaScript
var chartOptions = {
    commonSeriesSettings: {
        line: { // or 'bar', 'spline', etc.
            point: {
                selectionStyle: {
                    // Type-specific selection style configuration    
                }
            }
        }
    }
};

or for points of an individual series:

JavaScript
var chartOptions = {
    series: [{
        point: {
            selectionStyle: {
                // Individual selection style configuration
            }
        }
    }, {
        // ...
    }]
};

NOTE: The point configuration object defines the points of the line-like, scatter and area-like series only. To set the selection style for points of other series, use the series | selectionStyle object.

By default, the chart highlights the selected point only. But in some scenarios, you may need several points to be highlighted. To specify this, use the selectionMode option. Like the selection style, this option can be specified for all, type-specific or points of an individual series. It can accept one of the following values.

  • onlyPoint — highlights only the selected point
  • allSeriesPoints — highlights all points from the parent series
  • allArgumentPoints — highlights all points with the same argument
  • none — does not highlight anything

You can also allow the user to select multiple points. For this purpose, set the pointSelectionMode option to 'multiple'.

To handle the point selection event, assign a function to the onPointSelectionChanged option of the chart.

JavaScript
var chartOptions = {
    onPointSelectionChanged: function (info) {
        //...
    }
};

The onPointSelectionChanged function accepts an object that contains information on the selection event. Among fields of this object, you can find the point whose selection state has been changed. An object that represents this point is described in the Point section. Use the isSelected() method of this object to check the selection state of a point.

NOTE: Frequently, points that appear selected are not actually so, due to the 'allArgumentPoints' or 'allSeriesPoints' selection mode having been set. For these points, the pointSelectionChanged event does not occur and their isSelected() method returns false.

To clear the point selection, call the clearSelection() method of the point or the same method of its parent series.

JavaScript
// Access the point
point.clearSelection();

// or access its parent series
series.clearSelection();
Show Example:
AngularJS
Knockout
jQuery

In this example, clicking a point selects that point as well as all the points with the same argument. Information about this argument appears below the chart. This information is taken from the tag field that is provided in the chart data source.


                                    

                                    

In this example, clicking a point selects that point as well as all the points with the same argument. Information about this argument appears below the chart. This information is taken from the tag field that is provided in the chart data source.


                                    

                                    

In this example, clicking a point selects that point as well as all the points with the same argument. Information about this argument appears below the chart. This information is taken from the tag field that is provided in the chart data source.