End-User Interaction

To make your widgets fully interactive, they should respond to an end-user actions. These actions are tracked by a number of events. You can subscribe to an event and execute any code in an event handler. In this section, you will learn how to handle clicks, hovering and selection of chart elements.

Click Handling

This topic explains how to handle user clicks. To learn about hover and selection, refer to the Hover Handling and Selection Handling topics, respectively.

Series Click

You can handle a series click. To do this, implement a callback function and assign it to the chart's onSeriesClick option.

JavaScript
$("#chartContainer").dxChart({
    onSeriesClick: function (info) {
        //...
    }
});

The onSeriesClick callback function accepts an object that contains information on the click event. Fields of this object are described in the onSeriesClick option description. Among these fields, you can find the clicked series. An object that represent this series is described in the Series section.

NOTE: There are series that consist of points only, e.g., the bar-like and candleStick series of the dxChart widget, and the pie and doughnut series of the dxPieChart widget. The onSeriesClick function is not called when clicking a point (a bar or a slice) in these types of series. To handle the click operation for these series, implement the onPointClick callback function and access the series of the clicked point (see the Point Click topic).

Below is an example on how to handle series clicks. In this example, when clicking a series, the maximum point value is calculated and displayed below the chart. To get the points of the series that was clicked, the series' getAllPoints function is used.

Show Example:
jQuery

Point Click

You can handle the click on a data point of any type (point, bar, pie slice, etc.). To do this, implement a callback function and assign it to the onPointClick option of the chart's configuration object.

JavaScript
$("#chartContainer").dxChart({
    onPointClick: function(info){
        //...
    }
});

The onPointClick callback function accepts an object that contains information on the click event. Fields of this object are described in the onPointClick option description of dxChart and dxPieChart. Among these fields, you can find the clicked point. An object that represent this point is described in the Point section.

Below is an example on how to handle point clicks. In this example, when clicking a point, information on the point's argument is displayed below the chart. This information is taken from the tag field that is provided for each argument in the chart's data source.

Show Example:
jQuery

Legend Click

In addition to a click on a point or a series, you can handle a click on a legend item. To do this, implement a callback function and assign it to the onLegendClick option of the chart's configuration object.

JavaScript
$("#chartContainer").dxChart({
    onLegendClick: function(info) {
        //...
    }   
});

The onLegendClick callback function accepts an object that contains information on the legend click event. Fields of this object are described in the onLegendClick option description of dxChart and dxPieChart. Among these fields, you can find the series (in dxChart) or the point (in dxPieChart) that corresponds to the clicked legend item. Objects that represent them are described in the Series and Point sections respectively.

NOTE: If the onLegendClick option is not specified, a click on the legend will invoke the function assigned to the onSeriesClick (in dxChart) or onPointClick (in dxPieChart) option. To prevent this behavior, assign at least an empty function to the onLegendClick field.

Below is an example on how to handle legend clicks. In this example, when clicking a legend item, the maximum point value of the corresponding series is calculated and displayed under the chart. To get the points of the series to which the clicked legend item belongs, use the series' getAllPoints function.

Show Example:
jQuery

Hover Handling

This topic explains how to handle series and point hovering. To learn about selection and click handling, refer to the Selection Handling and Click Handling topics, respectively.

Series Hover

When a series is hovered over, its appearance is changed to a specific hover style. To customize the default hover style, use the series hoverStyle configuration object. There are hover style options that are common for all series types, which are defined by the commonSeriesSettings | hoverStyle configuration object. In addition, there are series hover options that are specific to a particular series type, which are defined by the commonSeriesSettings | line (or another series type) | hoverStyle configuration object. Any of the options provided by the objects mentioned above can be used to specify the hover style for an individual series within a series configuration object.

JavaScript
$("#chartContainer").dxChart({
    commonSeriesSettings: {
        line: {
            hoverStyle: {
                width: 4
            }
        }
    }
});

Determine which appearance to change when hovering on the series together with all its points, on the series excluding points, or on nothing. To do this, specify the series hoverMode configuration option.

JavaScript
$("#chartContainer").dxChart({
    commonSeriesSettings: {
        hoverMode: 'includePoints'
    }
});

In the code above, the hover mode is specified within the commonSeriesSettings object. This means that regardless of which series in a chart is hovered, points will always be highlighted as well. To set a hover mode for all series of a particular type, set the hoverMode property within the commonSeriesSettings | line (or another series type name) configuration object. In addition, you can specify a hover mode for individual series within a series configuration object.

You can handle series hover by implementing a callback function and assigning it to the chart's onSeriesHoverChanged option.

JavaScript
$("#chartContainer").dxChart({
    onSeriesHoverChanged: function (info) {
        //...
    }
});

The onSeriesHoverChanged callback function accepts an object that contains information on the hover event. Fields of this object are described in the onSeriesHoverChanged option description. Among these fields, you can find the series whose hover state has been changed. An object that represent this series is described in the Series section. Use the isHovered() method of this object to identify whether the series has been hovered over or hovered out.

NOTE: There are series that consist of points only, e.g., the bar-like and candleStick series of the dxChart widget, and the pie and doughnut series of the dxPieChart widget. The onSeriesHoverChanged function is not called when hovering over a point (a bar or a slice) in these types of series. To handle hovering for these series, implement the onPointHoverChanged callback function and access the series of the point whose hover state has been changed (see the Point Hover topic).

Below is an example on how to handle series hover. In this example, when hovering a series, the maximum point value is calculated, and displayed below the chart. To get the points of the series that was hovered, the series' getAllPoints() function is used.

Show Example:
jQuery

Point Hover

A point has a specific style when it is hovered over. To customize the default hover style, use the point's hoverStyle configuration object. There are hover style options that are common for points of all series types, which are defined by the commonSeriesSettings | point | hoverStyle configuration object. In addition, there are point hover options that are specific to a particular series type. Specify them within the commonSeriesSettings | line (or another series type) | point | hoverStyle configuration object. Any of the options provided by the objects mentioned above can be used to specify the point hover style for an individual series within a series | %seriesType% | point configuration object.

JavaScript
$("#chartContainer").dxChart({
    commonSeriesSettings: {
        point: {
            hoverStyle: {
                width: 3
            }
        }
    }
});

NOTE: The point configuration object defines the points of the line-, scatter and area-like series only. To set the hover style for points of other series types, use the series' hoverStyle configuration object.

Determine whose appearance to change when hovering: on the hovered point, on all points in the same series, on all points corresponding to the same argument, or on nothing. To do this, specify the series hoverMode configuration option.

JavaScript
$("#chartContainer").dxChart({
    commonSeriesSettings: {
        hoverMode: 'allArgumentPoints'
    }
});

In the code above, the hover mode is specified within the commonSeriesSettings object. This means that regardless of which point in a series is hovered, all points that correspond to the argument of the hovered point will appear hovered as well. To set a hover mode for all series of a particular type, set the hoverMode option within the commonSeriesSettings | line (or another series type name) configuration object. In addition, you can specify a hover mode for an individual series within a series configuration object.

You can handle the hovering of a data point of any type (point, bar, pie slice, etc.) by implementing a callback function and assigning it to the chart's onPointHoverChanged option.

JavaScript
$("#chartContainer").dxChart({
    onPointHoverChanged: function (info) {
        //...
    }
});

The onPointHoverChanged callback function accepts an object that contains information on the hover event. Fields of this object are described in the onPointHoverChanged option description. Among these fields, you can find the series point whose hover state has been changed. An object that represent this point is described in the Point section. Use the isHovered() method of this object to identify whether the series point has been hovered over or hovered out.

Below is an example on how to handle point hover. In this example, when hovering a point, information on the point's argument is displayed below the chart. This information is taken from the tag field that is provided for each argument in the chart's data source.

View Demo

Show Example:
jQuery

Selection Handling

This topic explains how to implement and handle series and point selection. To learn about hover and click handling, refer to the Hover Handling and Click Handling topics, respectively.

Series Selection

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

JavaScript
$("#chartContainer").dxChart({
    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 only consist of points, e.g., the bar-like and candleStick series of the dxChart widget, and the pie and doughnut series of the dxPieChart widget. To select these types of series when clicking, implement the onPointClick function. Use the target.series field of the object passed to this function as the parameter to access the series of the clicked point (bar or slice).

Determine which appearance to change upon selection: of the series together with all its points, of the series excluding points, or of nothing. To do this, specify the series selectionMode configuration option.

JavaScript
$("#chartContainer").dxChart({
    onSeriesClick: function (info) {
        var clickedSeries = info.target;
        clickedSeries.select();
    },
    commonSeriesSettings: {
        selectionMode: 'includePoints'
    }
});

In the code above, the selection mode is specified within the commonSeriesSettings object. This means that regardless of which series in a chart is selected, points will always be highlighted as well. To set a selection mode for all series of a particular type, set the selectionMode option within the commonSeriesSettings | line (or another series type name) configuration object. In addition, you can specify a selection mode for an individual series within a series configuration object.

When a series is selected, its appearance is changed to a specific selection style. To customize the default selection style, use the series selectionStyle configuration object. There are selection style options that are common for all series types defined by the commonSeriesSettings | selectionStyle configuration object. In addition, some series selection options are specific to a particular series type. These are defined by the commonSeriesSettings | line (or another series type) | selectionStyle configuration object. Any of the options provided by the objects mentioned above can be used to specify a selection style for an individual series within a series configuration object.

JavaScript
$("#chartContainer").dxChart({
    onSeriesClick: function(info){
        var clickedSeries = info.target;
        clickedSeries.select();
    },
    commonSeriesSettings: {
        line: {
            selectionStyle: {
                width: 4
            }
        }
    }
});

You can set whether or not multiple series selection is allowed by specifying the seriesSelectionMode option.

You can handle the selection of a series by implementing a callback function and assigning it to the chart's onSeriesSelectionChanged option.

JavaScript
$("#chartContainer").dxChart({
    onSeriesSelectionChanged: function (info){
        //...
    }
});

The onSeriesSelectionChanged callback function accepts an object that contains information on the selection event. Fields of this object are described in the onSeriesSelectionChanged option description. Among these fields, you can find the series whose selection state has been changed. An object that represent this series is described in the Series section. Use the isSelected() method of this object to identify whether the series was selected or deselected.

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

JavaScript
//...
var chart = $("#chartContainer").dxChart("instance");
chart.clearSelection();
//chart.getSeriesByName('Austria').clearSelection();
//...

Below is an example on how to select a series and handle the selection. In this example, when clicking a series, the series is selected and the maximum point value is calculated. To get the points of the selected series, the series' getAllPoints function is used.

View Demo

Show Example:
jQuery

Point Selection

To select a data point regardless of its appearance (point, bar or other), use its select() method. For instance, you can select a point when it is clicked within the chart's onPointClick handler (see Click Handling).

JavaScript
$("#chartContainer").dxChart({
    onPointClick: function (info) {
        var clickedPoint = info.target;
        clickedPoint.select();
    }
});

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

Determine whose appearance to change upon the selection of the selected point, of all points in a single series, of all points corresponding to the same argument, or of nothing. To do this, specify the series selectionMode configuration option.

JavaScript
$("#chartContainer").dxChart({
    onPointClick: function (info) {
        var clickedPoint = info.target;
        clickedPoint.select();
    },
    commonSeriesSettings: {
        point: {
            selectionMode: 'allArgumentPoints'
        }
    }
});

A selected point has a specific selection style. To customize the default selection style, use the point's selectionStyle configuration object. There are selection style options that are common for points of all series types defined by the commonSeriesSettings | point | selectionStyle configuration object. In addition, there can be point selection options that are specific to a particular series type. Specify them within the commonSeriesSettings | line (or another series type) | point | selectionStyle configuration object. Any of the options provided by the objects mentioned above can be used to specify a point selection style for an individual series, within a series | point configuration object.

JavaScript
$("#chartContainer").dxChart({
    onPointClick: function (info) {
        var clickedPoint = info.target;
        clickedPoint.select();
    },
    commonSeriesSettings: {
        point: {
            selectionStyle: {
                width: 3
            }
        }
    }
});

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

You can set whether or not multiple sequential point selection is allowed by specifying the pointSelectionMode option.

You can handle the selection of a data point of any type (point, bar, pie slice, etc.) by implementing a callback function and assigning it to the chart's onPointSelectionChanged option.

JavaScript
$("#chartContainer").dxChart({
    onPointSelectionChanged: function (info) {
        //...
    }
});

The onPointSelectionChanged callback function accepts an object that contains information on the selection event. Fields of this object are described in the onPointSelectionChanged option description. Among these fields, you can find the series 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 identify if the series point was selected or deselected.

To clear point selection, call the clearSelection() method of the point or the same method of the point's series when required.

JavaScript
//access the required point
point.clearSelection();

//or access the series that contains the required point
series.clearSelection();

Below is an example on how to select a point and handle the selection. In this example, when selecting a point, information on the point's argument is displayed below the chart. This information is taken from the tag field that is provided for each argument in the chart's data source.

Show Example:
jQuery