Still have questions?
Contact support
You are looking at an outdated 7.10.0 version of this document. Switch to the 7.13.0 version to see the up to date information.

Pointers and Data

Overview

Pointers are elements of the Gauge charts, which are necessary for the data representation.

Connection with the Data

By default, when a pointer is added to the JavaScript gauge chart, it shows the first value from the DataSet (if you've got more than one) or the only one. In case you need the second pointer with the same value to display or you have more than one value in your dataSet and you need one of your pointers to show this particular value different from the first one, you need to connect the data with the pointer in some way. On the other hand, the situation when you need to show any value from your dataSet on the axis which is not the only and the first might take place as well.

These problems are to be easily resolved using the .dataIndex() and the .axisIndex methods. You can find more information about these methods below.

Bind to Data

In case you have more that one value in your dataset, you should use the .dataIndex() method to each pointer showing any other value but the first. Note that numeration of the values starts from 0. There's no need in use of this method if you have an only value in your dataSet.

Let's add the second point to the data and enable two pointers: the bar and the marker. Let's bind the bar pointer to the new data point:

  //add the second data point
  var dataSet = anychart.data.set([60,110]);

  //marker
  var marker = gauge.marker();
  marker.enabled(true);
  marker.dataIndex();
  marker.size(7);
       
  //bar
  var bar = gauge.bar(0);
  bar.width(3);
  bar.dataIndex(1);

JsFiddle Playground

When you apply for the .dataIndex() method, you change the value that will be represented by the pointer you add this method to. However, using this means only if you have more than one value in the dataSet and more than one axis, because the only axis shows the only (or the first) value from your dataSet by default. So, there is no need in this method if your chart has an only axis and your data looks like this:

  var dataSet = anychart.data.set([60]);

Bind to Axis

To bind the pointer to the axis use the .axisIndex() method. Note that the count starts from 0. There's no need in using this method if your chart contains an only axis.

Let's enable one more axis and bind the bar pointer to this new axis:

JsFiddle Playground

To reach the result as in the sample above we need to add the following:

  // second axis settings
  var axis_1 = gauge.axis(1);
  axis_1.radius(50);
  axis_1.width(3);
  
  // second scale settings
  var scale_1 = gauge.axis(1).scale();
  scale_1.minimum(0);
  scale_1.maximum(300);
  var ticks_1 = gauge.axis(1).scale().ticks();
  ticks_1.interval(30);
  var minorTicks_1 = gauge.axis(1).scale().minorTicks();
  minorTicks_1.interval(10);
  
  // second ticks settings
  var axisTicks_1 = gauge.axis(1).ticks();
  axisTicks_1.type("trapezoid");
  axisTicks_1.length("8");
  
  // second minor ticks settings
  var axisMinorTicks_1 = gauge.axis(1).minorTicks();
  axisMinorTicks_1.enabled(true);
  axisMinorTicks_1.length("3");

  // marker
  var marker = gauge.marker();
  marker.enabled(true);
  marker.dataIndex(0);
  marker.axisIndex(0);
  marker.size(7);
      
  // bar
  var bar = gauge.bar();
  bar.width(3);
  bar.dataIndex(0);
  bar.axisIndex(1);

Let's add the second value to our dataSet and bind the bar pointer with the new value to the new axis:

  // add the second data point
  var dataSet = anychart.data.set([60,120]);

  // bar
  var bar = gauge.bar();
  bar.width(3);
  bar.dataIndex(1);
  bar.axisIndex(1);

JsFiddle Playground

Multiple pointers

You can add not only different pointers but the same. Look at the example below:

JsFiddle Playground

All we need to do is to change the value of the .marker() itself. This value means the pointer's numbers and counts from 0.

  // add the second data point
  var dataSet = anychart.data.set([60,120,170]);
  
  // marker_1
  var marker = gauge.marker(0);
  marker.enabled(true);
  marker.dataIndex(0);
  marker.axisIndex(0);
  marker.size(5);
      
  // marker_2
  var marker_1 = gauge.marker(1);
  marker_1.dataIndex(1);
  marker_1.axisIndex(0);
  marker_1.size(6);

  // marker_3
  var marker_2 = gauge.marker(2);
  marker_2.dataIndex(2);
  marker_2.axisIndex(0);
  marker_2.size(7);

Types

There are 4 different types of pointers avaliable: bar, marker, needle and knob. They all act as an entity that points to the value, but look different.

Bar

Bar is a pointer that looks like a bold line (for Linear Gauges) or curve (for Circular Gauges) colored rather brightly. It is usually situated next to the axis and shown with the marker pointer. Below you can see a simple example Gauge with the bar pointer and the code for the example.

JsFiddle Playground

  //bar
  var bar = gauge.bar();
  bar.enabled(true);

In the sample above we have only enabled the bar. Let's now change its width and radius.

  //bar
  var bar = gauge.bar(0);
  //you can remove this if you add any parameters to the bar
  bar.enabled(true);
  bar.width(3);
  bar.radius(100);
JsFiddle Playground

There's a lot of parameters to be adjusted else. For example, a bar pointer can be colored with a single color or with a gradient, we can set the position of the bar according to the defined radius, snap it to the exact data point and axis, set the stroke.


Now let's look at the position of the bar according to its radius. As our bar is more than 1px width it can be positioned outside, in the center or inside the circle of the defined radius. To set the position use the .position() method. The value is to be "outside", "inside" or "center". Let's put our bar inside the circle of the defined radius:

  var bar = gauge.bar();
  bar.position("inside");

It's possible to use only the first letters of the position as a value, e.g.:

  var bar = gauge.bar();
  bar.position("i");

JsFiddle Playground

Marker

Marker is a pointer that is more demonstrative when used with a bar pointer. It can be of a plenty types, which you can read about in Marker tutorial. Let's first enable a marker:

  //marker
  var marker = gauge.marker();
  marker.enabled(true);

The marker size is rather small by default, so we need to use the .size() method to make the marker visible, so the code will look as below:

  //marker
  var marker = gauge.marker();
  marker.enabled(true);
  marker.size(7);

JsFiddle Playground

It's not the best view when the marker covers the value on the axis, so now let's adjust the position of the marker according to the circle of the default or defined radius. As with bars, the marker might be in its center, outside or inside it. Let's set the marker's position to outside and look how will it change the view:

  //marker
  var marker = gauge.marker();
  marker.position("outside");
  marker.size(7);

JsFiddle Playground

Now our marker is outside the axis, but it doesn't point at the value. Let's change its type:

  //marker
  var marker = gauge.marker();
  marker.position("outside");
  marker.type("triangledown");
  marker.size(7);

JsFiddle Playground

Needle

Let's now look at the needles - the most common pointer used with Gauges.

  //needle
  var needle = gauge.needle();
  needle.enabled(true);

JsFiddle Playground

Needle can be a thin stick or a pointer of a complex form - you can regulate its width using three similar methods: .startWidth(), .middleWidth() and .endWidth().

Let's make our needle thiner to the end, wider to the center and a bit thiner to the start:

  //needle
  var needle = gauge.needle(8);
  needle.startWidth(1);
  needle.middleWidth(3);
  needle.endWidth(0);

JsFiddle Playground

As we can see, the needle starts not from the gauge center. Let's adjust the start, the middle and the end of our needle with methods .startRadius(), .middleRadius() and .endRadius(). The value transmitted to this method can be in pixels or percents.

  //needle
  var needle = gauge.needle(8);
  needle.startRadius("0%");
  needle.endRadius("80%");
  needle.middleRadius("50%");
  needle.startWidth(1);
  needle.middleWidth(3);
  needle.endWidth(0);

JsFiddle Playground

Knob

Knob is a full-curcle pointer that is nice to use with a needle or marker pointer. It looks like a switcher on microwaves or the audio tuner. You can see the example of the default enabled knob pointer below.

JsFiddle Playground

As you can see, this pointer is completely different from others. The first thing we'll adjust will be the number of the knob's projections (vertices). For that we use the .verticesCount() method.

  //knob
  var knob = gauge.knob(0);
  knob.verticesCount(15);

JsFiddle Playground

The curvature of vertices can be adjusted too. Use the .verticesCurvature() method and set the value from 0 to 1 (0.5 is set by default). The less the value is the more convex the vertices are. The more the value the more concave they are.

  //knob
  var knob = gauge.knob();
  knob.verticesCount(15);
  knob.verticesCurvature(.1);

JsFiddle Playground

The next feature we can adjust is the ratio, which spilts into the .topRatio() and .bottomRatio() methods. The values for these methods might be from 0 to 1 as well.

  //knob
  var knob = gauge.knob(0);
  knob.verticesCount(15);
  knob.verticesCurvature(.1);
  knob.topRatio(0);
  knob.bottomRatio(1);

JsFiddle Playground

If you set the .verticesCurvature() and the .bottomRatio() values to default (0.5), the vertices would look like triangles directed up from the knob:

  //knob
  var knob = gauge.knob(0)
  knob.verticesCount(15)
  knob.verticesCurvature(.5)
  knob.topRatio(0)
  knob.bottomRatio(.5);

JsFiddle Playground

If you set .verticesCurvature() and the .bottomRatio() values to default (0.5), the vertices would look like triangles directed down to the knob. Try to do it yourself, using the playground.

The last feature avaliable at the moment for only the knob pointers is radius, which is split the same way as ratio. Use the .topRadius() and the .bottomRadius() methods to set the radius for the outer side (height of the vertices) and the inner side (depth of dimples) accordingly. For clearer representation let's get rid of the ratio settings.

  //knob
  var knob = gauge.knob(0);
  knob.verticesCount(15);
  knob.verticesCurvature(.5);
  knob.topRadius(80);
  knob.bottomRadius(50);

JsFiddle Playground