jQuery Common - 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.

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).

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().

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:

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

for type-specific series:

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

or for an individual series:

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.

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.

chartInstance.clearSelection();
// chartInstance.getSeriesByName('seriesName').clearSelection();

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).

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:

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

for type-specific series points:

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

or for points of an individual series:

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

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.

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.

To clear the point selection, call the clearSelection() method of the point.

// Access the point
point.clearSelection();