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, clickEvent){
        //...
    }   
});

As you can see from the code above, the series that was clicked is accessible as the function's first parameter. You can also obtain the clicked series using the function's this object. In addition, you can access the jQuery-event object with the function's second parameter.

The methods and fields of the object passed as the first parameter allow you to select/unselect the series, get the required points, access the info that is provided for the series via the tag option, etc. To learn more on the members of series object, refer to the Series class 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 option of the chart's configuration object.

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

As you can see from the code above, the point that was clicked is accessible as the function's first parameter. You can also obtain this point using the function's this object. In addition, you can access the jQuery-event object with the function's second parameter.

The methods and fields of the object passed as the first parameter allow you to access the parent series, select/unselect the point, access the info that is provided for the point via the tag field, etc. To learn more on the members of point object, refer to the Point class 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

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 legendClick option of the chart's configuration object.

JavaScript
$("#chartContainer").dxChart({
    legendClick: function(clickedItem, clickEvent){
        //...
    }   
});

As you can see from the code above, the item that was clicked is accessible as the function's first parameter. This item represents a corresponding series (in dxChart) or a point (in dxPieChart). You can also obtain this item using the function's this object. In addition, you can access the jQuery-event object with the function's second parameter.

The methods and fields of the object passed as the first parameter allow you to select/deselect the point or series, access the parent series of a point, etc. To learn more about the members of the point or series objects, refer to the Point or Series class definition, respectively.

NOTE: If the legendClick option is not specified, a click on the legend will invoke the function assigned to the seriesClick (in dxChart) or pointClick (in dxPieChart) option. To prevent this behavior, assign at least an empty function to the legendClick 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

To make the dxChart and dxPieChart widgets interactive, you can handle click and hover operations for a series or a point. In addition, you can make a series or a 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 | seriesType 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 seriesHoverChanged option.

JavaScript
$("#chartContainer").dxChart({
    seriesHoverChanged: 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 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 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 seriesHoverChanged 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 pointHoverChanged callback function and access the series of the clicked point (see below).

The callback function assigned to the seriesHoverChanged option is called when a series changes its hovered state. To identify, whether the series has been hovered over or hovered out, use the series' isHovered() method.

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 | 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 pointHoverChanged option.

JavaScript
$("#chartContainer").dxChart({
    pointHoverChanged: 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.

The callback function assigned to the pointHoverChanged option is called when a point changes its hovered state. To identify, whether the point has been hovered over or hovered out, use the point's isHovered() method.

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 dxChart and dxPieChart widgets interactive, you can handle the click and hover operations for a series or a point. In addition, you can make a series or a 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 option.

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

JavaScript
$("#chartContainer").dxChart({
    seriesClick: function(clickedSeries){
        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 seriesSelectionChanged option.

JavaScript
$("#chartContainer").dxChart({
    seriesSelectionChanged: 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.

The function assigned to the seriesSelectionChanged option is called when a series changes its selection state. To identify, whether a series has been selected or unselected, use the series' isSelected() method.

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 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({
    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 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 | 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 | 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 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 pointSelectionChanged option.

JavaScript
$("#chartContainer").dxChart({
    pointSelectionChanged: 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.

The callback function assigned to the pointSelectionChanged option is called when a point changes its selection state. To identify, whether the point has been selected or unselected, use the point's isSelected() method.

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