End-User Interaction

To be fully interactive, the widgets must respond to 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 to handle click, hover and selection events. Further, you will implement zooming and scrolling in the Chart widget.

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 represents 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 Chart widget, and the pie and doughnut series of the PieChart widget. The onSeriesClick function is not called when clicking a point (a bar or a slice) in these types of series. To handle click for these series, implement the onPointClick callback function and access the series of the clicked point (see the Point Click topic).
Show Example:
AngularJS
Knockout
jQuery

In this example, when you click a series, the chart calculates the maximum point value from this series and outputs it below. To get all points of the clicked series, the series' getAllPoints method is used.


                                    

                                    

In this example, when you click a series, the chart calculates the maximum point value from this series and outputs it below. To get all points of the clicked series, the series' getAllPoints method is used.


                                    

                                    

In this example, when you click a series, the chart calculates the maximum point value from this series and outputs it below. To get all points of the clicked series, the series' getAllPoints method is used.


                                    

                                    

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 Chart and PieChart. Among these fields, you can find the clicked point. An object that represents this point is described in the Point section.

Show Example:
AngularJS
Knockout
jQuery

In this example, when you click a point, information about the argument of this point appears below the chart. This information is taken from the tag field that is specified for each argument in the chart data source.


                                    

                                    

In this example, when you click a point, information about the argument of this point appears below the chart. This information is taken from the tag field that is specified for each argument in the chart data source.


                                    

                                    

In this example, when you click a point, information about the argument of this point appears below the chart. This information is taken from the tag field that is specified for each argument in the chart data source.


                                    

                                    

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 Chart and PieChart. Among these fields, you can find the series (in Chart) or the argument of the points (in PieChart) that correspond to the clicked legend item.

NOTE
If the onLegendClick option is not specified, a click on the legend will invoke the function assigned to the onSeriesClick option in Chart. To prevent this behavior, assign at least an empty function to the onLegendClick field.
Show Example:
AngularJS
Knockout
jQuery

In this example, when you click a legend item, the chart calculates the maximum point value from this series and outputs it below. To get the points of the series to which the clicked legend item belongs, the series' getAllPoints method is used.


                                    

                                    

In this example, when you click a legend item, the chart calculates the maximum point value from this series and outputs it below. To get the points of the series to which the clicked legend item belongs, the series' getAllPoints method is used.


                                    

                                    

In this example, when you click a legend item, the chart calculates the maximum point value from this series and outputs it below. To get the points of the series to which the clicked legend item belongs, the series' getAllPoints method is used.


                                    

                                    

Hover Handling

This topic explains how to handle series and point hover events in the Chart and PieChart widgets.

Series Hover

When an end-user hovers the mouse pointer over a series, its appearance assumes a specific hover style. To customize the default hover style, use the series hoverStyle configuration object. This object can specify settings for all series:

JavaScript
var chartOptions = {
    commonSeriesSettings: {
        hoverStyle: {
            // Common hover style configuration    
        }
    }
};

for type-specific series:

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

or for an individual series:

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

To choose which series elements to highlight when the series is hovered over, specify the hoverMode option. Like the hover style, this option can be specified for all, type-specific or an individual series. There are several hover modes in the chart widgets. Available modes depend on the series type you use.

To handle the series hover event, assign a function to the onSeriesHoverChanged option of the chart.

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

The onSeriesHoverChanged function accepts an object that contains information on the hover event. Among fields of this object, you can find the series whose hover state has been changed. An object that represents 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 Chart widget, and the pie and doughnut series of the PieChart widget. The onSeriesHoverChanged function is not called when hovering over a point (a bar or a slice) in these types of series. To handle the hover event for these series, implement the onPointHoverChanged function and access the series of the point whose hover state has been changed (see the Point Hover topic).
Show Example:
AngularJS
Knockout
jQuery

In this example, when you hover the mouse pointer over a series, the chart calculates the maximum point value from this series and outputs it below. To get all the points of the series the mouse is currently hovering over, the series' getAllPoints method is used.


                                    

                                    

In this example, when you hover the mouse pointer over a series, the chart calculates the maximum point value from this series and outputs it below. To get all the points of the series the mouse is currently hovering over, the series' getAllPoints method is used.


                                    

                                    

In this example, when you hover the mouse pointer over a series, the chart calculates the maximum point value from this series and outputs it below. To get all the points of the series the mouse is currently hovering over, the series' getAllPoints method is used.


                                    

                                    

Point Hover

When an end-user rests the mouse pointer over a series point, its appearance assumes a specific hover style. To customize the default hover style, use the point hoverStyle configuration object. This object can specify settings for all series:

JavaScript
var chartOptions = {
    commonSeriesSettings: {
        point: {
            hoverStyle: {
                // Hover style configuration    
            }
        }
    }
};

for type-specific series:

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

or for an individual series:

JavaScript
var chartOptions = {
    series: [{
        point: {
            hoverStyle: {
                // Individual hover style configuration
            }
        }
    }, {
        // ...
    }]
};
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 the parent series.

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

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

To handle the point hover event, assign a function to the onPointHoverChanged option of the chart.

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

The onPointHoverChanged function accepts an object that contains information on the hover event. Among fields of this object, you can find the 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 point has been hovered over or hovered out.

NOTE
Frequently, points that appear hovered over are not actually so, due to the 'allArgumentPoints' or 'allSeriesPoints' hover mode being set. For these points, the pointHoverChanged event does not occur and their isHovered() method returns false.
Show Example:
AngularJS
Knockout
jQuery

In this example, when you hover the mouse pointer over a point, information about the argument of this point appears below the chart. This information is taken from the tag field that is provided for each argument in the chart data source. Additionally, the point hover mode is set to 'allArgumentPoints'.


                                    

                                    

In this example, when you hover the mouse pointer over a point, information about the argument of this point appears below the chart. This information is taken from the tag field that is provided for each argument in the chart data source. Additionally, the point hover mode is set to 'allArgumentPoints'.


                                    

                                    

In this example, when you hover the mouse pointer over a point, information about the argument of this point appears below the chart. This information is taken from the tag field that is provided for each argument in the chart data source. Additionally, the point hover mode is set to 'allArgumentPoints'.


                                    

                                    

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.


                                    

                                    

Zooming and Scrolling

When you deal with a large amount of data, providing an efficient way of navigating this data is essential. In this section, you will learn how to implement scrolling and zooming in the Chart widget.

Using dxRangeSelector

The Chart and RangeSelector widgets can operate together, allowing an end-user to zoom and scroll through a chart. Follow the steps below to implement these capabilities.

  • Configure Chart

    Create and configure the Chart widget using one of the available data-binding approaches. For details, see the "Create and Configure a Widget" guide for jQuery, AngularJS or Knockout.

    JavaScript
    var chartOptions = {
        // Chart configuration
    };
  • Configure RangeSelector

    Create and configure the RangeSelector widget in a similar manner. Chart and RangeSelector must have completely identical argument axes. Hence, you need to assign the same data source to both widgets.

    JavaScript
    var dataSource = [...];
    var chartOptions = {
        dataSource: dataSource,
        // ...
    };
    var rangeSelectorOptions = {
        dataSource: dataSource,
        // ...
    };

    Optionally, you can display the chart in miniature in the background of RangeSelector. For this purpose, assign the same array of series configurations to both widgets.

    JavaScript
    var dataSource = [...];
    var series = [...];
    var chartOptions = {
        dataSource: dataSource,
        series: series
        // ...
    };
    var rangeSelectorOptions = {
        dataSource: dataSource,
        chart: {
            series: series    
        }
        // ...
    };
  • Implement Widget Interaction

    To make Chart and RangeSelector interact with each other, handle the selectedRangeChanged event. For this purpose, assign a function to the onSelectedRangeChanged option of RangeSelector. Within this function, call the zoomArgument method of the chart instance. This method accepts the start and end range values as its parameters.

    JavaScript
    var rangeSelectorOptions = {
        // ...
        onSelectedRangeChanged: function (e) {
            chartInstance.zoomArgument(e.startValue, e.endValue);
        },
        behavior: { callSelectedRangeChanged: 'onMoving' }
    };
    NOTE
    The selectedRangeChanged event can fire either when an end-user keeps dragging the sliders or when he/she has released them. This depends on the value of the behavior | callSelectedRangeChanged option. When implementing zooming/scrolling, make sure that this option is set to 'onMoving'.

    By default, the chart adjusts its value axis to the currently selected minimum and maximum values. To change this behavior, set the adjustOnZoom option to false.

Free and Fixed Range Scrolling

Following the steps above, you get free range scrolling. It means that an end-user scrolls the chart by selecting a range in RangeSelector and dragging it to any side. You can fix the selected range. In this instance, an end-user will be able to scroll the chart dragging the predefined range. For this purpose, set the minRange and maxRange option of the scale configuration object to the same value. Then, specify the initial range using the selectedRange option.

JavaScript
var rangeSelectorOptions = {
    // ...
    scale: {
        minRange: 10,
        maxRange: 10,
    },
    selectedRange: { startValue: 0, endValue: 10 }      
};
Show Example:
AngularJS
Knockout
jQuery

Using Mouse or Touch Gestures

The Chart widget allows you to enable built-in scrolling and zooming. You can use the mouse wheel or the "pinch" gesture for zooming and the horizontal slide gesture across the chart (using mouse or touch interface) for scrolling.

DevExtreme ChartJS Zooming Scrolling

You can enable mouse support, touch support or both by assigning corresponding values to the scrollingMode and/or zoomingMode options.

JavaScript
var chartOptions = {
    // ...
    scrollingMode: "all", // "touch", "mouse"
    zoomingMode: "all"    // "touch", "mouse"
};

View Demo

Using the Scroll Bar

In addition to scrolling by mouse and touch gestures, you can display a separate visual element for scrolling called scroll bar.

The scroll bar is configured using the scrollBar object. Set the visible field of this object to true to display the scroll bar.

NOTE
Before displaying the scroll bar, make sure that scrolling and zooming features are enabled, otherwise the scroll bar will not be operational.
JavaScript
var chartOptions = {
    // ...
    scrollingMode: "all",
    zoomingMode: "all",

    scrollBar: {
        visible: true,
        //...
    }
};

View Demo

To learn more about the scroll bar as a visual element, refer to the Chart Elements | Scroll Bar topic.