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.

See Also

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
var chartOptions = {
    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
var chartOptions = {
    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
var chartOptions = {
    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
var chartOptions = {
    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
var chartOptions = {
    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
var chartOptions = {
    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 hovered point is a point to which an end-user is pointing by the mouse pointer. 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 point within a series | %seriesType% | point configuration object.

JavaScript
var chartOptions = {
    commonSeriesSettings: {
        point: {
            hoverStyle: {
                width: 3
            }
        }
    }
};
NOTE
The point configuration object defines the points of the line-like, scatter and area-like series only. To set the hover style for points of other series types, use the hoverStyle configuration object of a corresponding series.

When a point is hovered over, you can choose whose appearance to change when hovering. There are four different hovering modes:

  • onlyPoint — when hovering a mouse pointer over a point, change only the hovered point style;
  • allSeriesPoints — when hovering a mouse pointer over a point, change the style of all points in the same series;
  • allArgumentPoints — when hovering a mouse pointer over a point, change the style of all points corresponding to the same argument;
  • nothing — do not change the style of hovered points.

To configure the hovering mode, specify the series hoverMode configuration option. For instance, in the code below, the hover mode is specified as 'allArgumentPoints', which means that all points of the series will be marked as hovered if any of them will be actually hovered over by a mouse pointer.

JavaScript
var chartOptions = {
    commonSeriesSettings: {
        hoverMode: 'allArgumentPoints'
    }
};

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.

To handle the hovering of a data point of any type (point, bar, pie slice, etc.), implement a callback function and assign it to the chart's onPointHoverChanged option; see below:

JavaScript
var chartOptions = {
    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 represents 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.

NOTE
Points that appear hovered (for instance, due to the 'allArgumentPoints' or 'allSeriesPoints' mode) are not actually hovered: the 'pointHoverChanged' event does not occur for them and the 'isHovered()' method returns false.

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
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 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
var chartOptions = {
    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
var chartOptions = {
    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
var chartOptions = {
    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 = var chartOptions ="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
var chartOptions = {
    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 getPointsByArg().

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
var chartOptions = {
    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
var chartOptions = {
    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
var chartOptions = {
    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.

NOTE
Points that appear selected (for instance, due to the 'allArgumentPoints' or 'allSeriesPoints' mode) are not actually selected: the 'pointSelectionChanged' event does not occur for them and the 'isSelected()' method returns false.

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