End-User Interaction

When you deal with a large amount of data, you need a handy tool that will allow you to track data changes and provide interaction capabilities. In this section, you will learn how to implement scrolling and zooming of the Chart widget, how to select points and series, handle clicks and hovering.

Scrolling

The dxChart and dxRangeSelector widgets can work together, allowing you to scroll the chart. This article will teach you to set up the dxChart and dxRangeSelector widgets so that they work together. Two scroll modes will be demonstrated: selecting a required range on a chart and scrolling the chart with a fixed range.

Follow the steps below to implement chart scrolling.

  • Set up dxChart Options
    Create and set up the dxChart widget using its configuration object.

    JavaScript
    $("#chartContainer").dxChart({
        //...   
    });
  • Set up dxRangeSelector Options

    Create and set up the dxRangeSelector using its configuration object. Since your range selector and chart must have the same argument axes, you must utilize the chart's data source as the range selector's data source by setting the former to the range selector's dataSource property. Optionally, you can place your chart view as the range selector's background. To do so, define the dxRangeSelector's chart configuration object. Set its series property to the series array of your chart.

    JavaScript
    var dataSource = [...];
    $("#chartContainer").dxChart({
        dataSource: dataSource,
    });
    $("#rangeSelectorContainer").dxRangeSelector({
        dataSource: dataSource,
        chart: {
            series: series
        }   
    });
  • Implement Widgets Interaction

    Implement a function that sets the visible range of the dxChart's argument axis to the range selected on the dxRangeSelector. Assign it to the dxRangeSelector's selectedRangeChanged property.

    JavaScript
    $("#rangeSelectorContainer").dxRangeSelector({
        behavior: {
            callSelectedRangeChanged: "onMoving"
        },
        selectedRangeChanged: function (e) {
            var zoomedChart = $("#zoomedChart").dxChart('instance');
            zoomedChart.zoomArgument(e.startValue, e.endValue);
        }       
    });

    As you can see in the code above, the selectedRangeChanged function will be called when moving range selector sliders, since the callSelectedRangeChanged property is set to onMoving.

  • Keep Value Axis Range

    To keep the visible range of the chart's value axis, set the dxChart's adjustOnZoom property to false when scrolling the argument axis.

    JavaScript
    $("#chartContainer").dxChart({
        adjustOnZoom: false,
    });

Free and Fixed Range Scrolling

When following the steps above, you get free scrolling. This means that an end user will be able to scroll to any part of the chart by selecting the required range in the range selector and dragging it to any side. You can fix the selected range in the range selector. In this instance, an end-user will be able to scroll the chart, dragging the predefined visible range. To do this, set the minRange and maxRange properties of the dxRangeSelector's scale configuration object to the same value.

JavaScript
$("#rangeSelectorContainer").dxRangeSelector({
    scale: {
        minRange: 10,
        maxRange: 10,
    },
    selectedRange: {startValue: 0, endValue:10}      
});

Using a similar technique, you can implement chart zooming. For details, refer to the Zooming topic.

Show Example:
jQuery

Zooming

The dxChart and dxRangeSelector widgets can work together, allowing you to zoom in and out the Chart. In this topic, you will learn how to set up the dxChart and dxRangeSelector widgets so that they work together and so that the dxRangeSelector can be used to zoom the dxChart.

To perform chart zooming, follow the steps below.

  • Set up dxChart Options

    Create the dxChart widget and set it up as required using its configuration object.

    JavaScript
    $("#chartContainer").dxChart({
        //...   
    });
  • Set up dxRangeSelector Options

    Create the dxRangeSelector widget and set it up as required. Since your dxRangeSelector and dxChart must have the same argument axes, use the chart's data source as the range selector's data source by setting the former to the dxRangeSelector's dataSource property. Optionally, you can place your chart view as the range selector's background. For this purpose, define the dxRangeSelector's chart configuration object. Set its series property to the series array of your chart.

    JavaScript
    var dataSource = [...];
    $("#chartContainer").dxChart({
        dataSource: dataSource,
        //...
    });
    $("#rangeSelectorContainer").dxRangeSelector({
        //...
        dataSource: dataSource,
        chart: {
            series: series
        }   
    });
  • Implement Widgets Interaction

    Implement a function that sets the visible range of the chart's argument axis to the range selected on the dxRangeSelector widget. Assign it to the dxRangeSelector's selectedRangeChanged property.

    JavaScript
    $("#rangeSelectorContainer").dxRangeSelector({
        //...
        behavior: {
            callSelectedRangeChanged: "onMoving"
        },
        selectedRangeChanged: function (e) {
            var zoomedChart = $("#zoomedChart").dxChart('instance');
            zoomedChart.zoomArgument(e.startValue, e.endValue);
        }       
    });

    As you can see in the code above, the selectedRangeChagned function will be called while moving the range selector sliders, since the callSelectedRangeChanged property is set to onMoving.

  • Value Axis adjustment To zoom the chart's selected region, the value axis' visible range must change based on current minimum and maximum chart values. For this purpose, the dxChart's adjustOnZoom property is set to true by default.

Using a similar technique, you can implement chart scrolling. For details, refer to the Scrolling topic.

Show Example:
jQuery

Click Handling

To make the Chart and PieChart widgets interactive, you can handle end-user clicks and hover over a series or a point. In addition, you can make a series or point selected and handle the selection. 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 seriesClick option.

JavaScript
$("#chartContainer").dxChart({
var chartOptions = {
    seriesClick: function(clickedSeries){
        //...
    }   
});

As you can see from the code above, the series that was clicked is accessible as the function's parameter. In addition, you can access it using the function's this object. The series object's members allow you to select the series, clear the selection, get the required points, and access the info that is provided for the series via the tag property. To learn more on the series object's members, refer to the Series object definition.

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 seriesClick 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 pointClick callback function and access the series of the clicked point (see below).

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 of a data point of any type (point, bar, pie slice, etc.). To do this, implement a callback function and assign it to the pointClick property of the chart's configuration object.

JavaScript
$("#chartContainer").dxChart({
    pointClick: function(clickedPoint){
        //...
    }   
});

As you can see from the code above, the point that was clicked is accessible as the function's parameter. In addition, you can access it using the function's this object. The point object's members allow you to access the parent series, select the point, clear the selection, access the info that is provided for the point via the tag field. To learn more on the point object's members, refer to the Point object definition.

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

Hover Handling

To make the Chart and PieChart widgets interactive, you can handle click and hover operations for series or a point. In addition, you can make a series or point selected and handle that selection. 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 hovering a series, 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 | series configuration object.

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

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

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 an individual series within a series | series configuration object.

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

JavaScript
$("#chartContainer").dxChart({
    seriesHover: function(hoveredSeries){
        //...
    }   
});

As you can see from the code above, the series that was hovered over is accessible as the function's parameter. In addition, you can access it using the function's this object. The series object's members allow you to get the required points and access the info that is provided for the series via the tag property. To learn more on the series object's members, refer to the Series object definition.

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 seriesHover 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 pointHover callback function and access the series of the clicked point (see below).

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 has a specific hover style. 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 | series | 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: of the hovered point, of all points in the same series, of all points corresponding to the same argument, or of nothing. To do this, specify the series hoverMode configuration property.

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

In the code above, 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 property 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 | 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 pointHover option.

JavaScript
$("#chartContainer").dxChart({
    pointHover: function(hoveredPoint){
        //...
    }   
});

As you can see from the code above, the point that was hovered is accessible as the function's parameter. In addition, you can access it using the function's this object. The point object's members allow you to access the parent series or the information that is provided for the point via the tag field. To learn more on the point object's members, refer to the Point class definition.

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.

Show Example:
jQuery

Selection Handling

To make the Chart and PieChart widgets interactive, you can handle the click and hover operations for a series or a point. In addition, you can make a series or point selected and handle the selection. 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 seriesClick handler (see Click Handling).

JavaScript
$("#chartContainer").dxChart({
    seriesClick: function(clickedSeries){
        clickedSeries.select();
    }   
});

Alternatively, you can access a series when required, using one of the following functions of the chart instance: 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, use the pointClick function. Use the point object passed as the parameter to access and select 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 property.

JavaScript
$("#chartContainer").dxChart({
    pointClick: function(clickedPoint){
        clickedPoint.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 highligted as well. To set a selection mode for all series of a particular type, set the selectionMode property 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 | series configuration object.

When selecting a series, 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 | series configuration object.

JavaScript
$("#chartContainer").dxChart({
    seriesClick: function(clickedSeries){
        clickedSeries.select();
    },
    commonSeriesSettings: {
        line: {
            selectionStyle: {
                width: 4
            }
        }
    }
});

You can set whether 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 seriesSelected option.

JavaScript
$("#chartContainer").dxChart({
    seriesSelected: function(selectedSeries){
        //...
    }   
});

As you can see from the code above, the series that was selected is accessible as the function's parameter. In addition, you can access it using the function's this object. The series object's members allow you to get the required points, and access the info that is provided for the series using the tag property. To learn more about the series object's members, refer to the Series object definition.

To clear series selection, call the clearSelection() function of the series or the clearSelection() function of the chart instance when required.

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.

Show Example:
jQuery

Point Selection

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

JavaScript
$("#chartContainer").dxChart({
    pointClick: function(clickedPoint){
        clickedPoint.select();
    }   
});

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

Determine whose appearance to change upon 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 property.

JavaScript
$("#chartContainer").dxChart({
    pointClick: function(clickedPoint){
        clickedPoint.select();
    },
    commonSeriesSettings: {
        selectionMode: 'allArgumentPoints'
    }
});

In the code above, the selection mode is specified within the commonSeriesSettings object. This means that regardless of which point in a series is selected, all points that correspond to the argument of the selected point will be selected. To set a selection mode for all series of a particular type, set the selectionMode property 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 | series configuration object.

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 | series | point configuration object.

JavaScript
$("#chartContainer").dxChart({
    pointClick: function(clickedPoint){
        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 multiple sequentional 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 pointSelected option.

JavaScript
$("#chartContainer").dxChart({
    pointSelected: function(selectedPoint){
        //...
    }   
});

As you can see from the code above, the point that has been selected is accessible as the function's parameter. In addition, you can access it using the function's this object. The point object's members allow you to access the parent series, as well as the info that is provided for the point via the tag field. To learn more on the point object's members, refer to the Point object definition.

To clear point selection, call the clearSelection() function of the point or the clearSelection() function 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