Scroller

Overview

Sometimes we've got so much data that we cannot display it all, keeping it comfortable for understanding. In this case we can enable the scroller for the chart axes.

All X / Y Axes based charts (Bar, Line, Area, Candlestick, OHLC, Combinations, etc.) can have Axes with scroll bar.

Enable

We use standard enabled() method to switch the scroller on and off. Let's create a simple column chart and enable the scroller on it:

	// turn it on
	var chart = anychart.column();
	chart.xScroller(true);

JsFiddle Playground

Also, we can pass the "true" value straight to the xScroller() method.

Now you can see that there is a scroller shown up, but the general view has not changed (though, you can drag it). That's because we should zoom the chart - set the area we'd like to display.

Adjust

In this section we will consider the zoom and scroll settings of a chart.

Zoom

First of all, we need to define that area of the chart that we'd like to have being displayed. We can do it differently, in accordance with our needs and preferences.

Set the limits by ratio

The simplest way of limiting the show area is using the ratio. We have the setTo() method for that. Use two values with this method: the start ratio value (e.g. 0) and the end one (e.g. 0.3). Look at the following sample.

	// turn it on
	var xZoom = chart.xZoom();
	xZoom.setTo(0, 0.3);

JsFiddle Playground

Set the limits by values

Another option is to define the particular values which exist on the scale. In this case you have to set the scale as the third parameter, unless you do this, the default xScale is used. So, if we'd like to zoom the chart to the area from Part 1 to Part 4 by Y-axis, we should use the setToValue() method and write the following:

	// set the yZoom
    var yZoom = chart.yZoom();

    // turn it on
    yZoom.setToValues("Part 1", "Part 4");

JsFiddle Playground

Note that it's only Heat maps which can be scrolled or zoomed by Y-scale.

Set the limits by the points count

The third way of setting the limits is to set the number of points from the beginning or end of the scale. We set the number of points, the second boolean parameter defines if the points should be counted from the end of the scale and the third parameter is the scale. The point will be counted from start by default, if you need them to be counted from end, set "true" as se second value. Let's consider this feature in the next sample, showing us the information about new Internet users in the Initech company.

// set the xZoom
var xZoom = chart.xZoom();

// turn it on
xZoom.setToPointsCount(10, true);

JsFiddle Playground

Screen scrolling

Note that this method works only with ordinal scales.

By default, the chart is changing while being scrolled. We can prevent this and redraw chart only when the mouse button is released, this may improve user experience when you show very large data sets. For this option we've got the continuous() method:

// set the xZoom
var xZoom = chart.xZoom();

// prevent the scrolling while the button is not released yet
 xZoom.continuous(false);

JsFiddle Playground

Get the limits ratio

You can also get the limiting points ratio using getStartRatio() and getEndRatio() methods. They will return the limiting ratio values.

	// set the xZoom
	var xZoom = chart.xZoom();

	// Zooms series by defined points count
	xZoom.setToPointsCount(5);

	// get the limits ratio
    chart.title("The chart shows the part from " + xZoom.getStartRatio() + " and ends at " + xZoom.getEndRatio());

JsFiddle Playground

Let's now talk about the scroller itself. Look through the next paragraph.

Scroll

The scroll bar is rather flexible in its look and behavior. We can change the colors, sizes, positioning, etc. Let's make some changes with a couple of previous samples.

Orientation

With the orientation() method we can set the orientation of the scroller. Let's create a simple bar chart with zoom and a scroller with orientation to the right.

    // change the scroller orientation
    chart.xScroller().orientation("right");

JsFiddle Playground

Position

Scroller can be displayed in "afterAxes" or "beforeAxes" positions. The afterAxes position is set by default.

    // change the scroller orientation
    chart.xScroller().position("beforeAxes");

JsFiddle Playground

Autohide

You can prevent the scroller from showing if there is no need in it. For example, if your dataSet has 20 points while you allow to show only 15 and you've removed five or more points by clicking on them, there's no need in scroll bar anymore. This is the example of a situation when you might need this function. We use autoHide() method for it:

    // autoHide the scroller
    chart.xScroller().autoHide(true);

JsFiddle Playground

Changing the range

While your chart displays only a part of all information, you might want to manage the amount of displayed using allowRangeChange(). This method is used to allow and prevent changing the amount of displayed by lengthening of shortening the scroll bar range. It's allowed by default; let's prevent this using the allowRangeChange() method.

    // change the scroller orientation
    chart.xScroller().allowRangeChange(false);

JsFiddle Playground

Colors

Colors of the scroll bar can be easily changed with simple methods fill(), selectedFill() and outlineStroke(). Let's now create an example of a column chart with modified scroll bar. The fill() method colors the background of the scroll bar and the selectedFill() method colors the bar itself.

	// set the fill color
    chart.xScroller().fill("#33CC33");

    // set the selected fill color
    chart.xScroller().selectedFill("#339966");

    // set the stroke of the bar
    chart.xScroller().outlineStroke("#33CC33", 2);

JsFiddle Playground

Dimensions

Now, let's adjust the scroll bar for the previous sample. We can set the scroll bar's height using the height() setter method. There are also methods maxHeight() and minHeight() which are rather useful when your charts are being resized - these methods help to control the dimensions of the scroll bar and the charts' general view as a consequence. Let's look at the following sample.

    // set the bar height
    xScroller.minHeight(5);

    // set the bar height
    xScroller.maxHeight(35);

JsFiddle Playground

Thumbs

The scroll bar thumbs can be adjusted too. We can change its look, dimensions or enable/disable them. There are several methods help us to do that:

  • enabled() method needs a boolean value: when "true", thumbs are enabled. It returns "true" by default.
    • autoHide() method needs a value of boolean type as well, when "true", thumbs are displayed only when the scroll bar is hovered. Returns "false" by default.
    • fill() colors the thumbs.
    • stroke() method is being used for stroking the thumbs.
    • {api:anychart.core.ui.Scroller.Thumbs#hoverFillhoverFill(){api} and hoverStroke() are used for coloring and stroking the thumbs in hovered state accordingly.

Let's create an example with thumbs adjusted.

// set the thumbs
    var thumbs = xScroller.thumbs();

    // adjusting the thumbs
    thumbs.autoHide(true);
    thumbs.hoverFill("#FFD700");
	

JsFiddle Playground

Open any sample in our playground and try to use other methods to see and understand how they work.

Events

As the scroller is an interactive object, which changing affects the view of the chart, it dispatches some events. You can find a lot of information about event listeners in the Event Listeners tutorial.

There are three events, which our scroller can dispatch due to changes made on it: scrollerchange, scrollerchangestart, and scrollerchangefinish. These events are dispatched when we drag the scrollbar itself or its limits, making it show us more or less of the chart. All of them provide information about the source of changes (thumbDrag, selectedRangeDrag or backgroundClick), the startRatio and endRatio values, which then can be somehow used. Let's show this in a sample.

Here we created a listener of the scrollerchangefinish event. The values it returns then are shown in the chart title.

// adding a listener
        scroller.listen("scrollerchangefinish", function(e){
            var startRatio = e.startRatio;
            var endRatio = e.endRatio;
            // change the chart title
            chart.title("The chart shows the part from " + startRatio + " and ends " + endRatio);
        });
    

JsFiddle Playground

You are looking at an outdated 7.12.0 version of this document. Switch to the 8.0.1 version to see the up to date information.