ChartCursor – amCharts Version 3 Documentation

Type class

Creates a cursor for the chart which follows the mouse movements. In case of AmSerialChart charts it shows the balloons of hovered data points.

Example

var chart = AmCharts.makeChart("chartdiv",{
  ...
  "chartCursor": {
    "oneBalloonOnly": true
  }
});

Inheritance

ChartCursor does not extend any other symbol.

ChartCursor is not extended by any other symbol.

Properties

adjustment #	Type `number` Default `0` If you set adjustment to -1, the balloon will be shown near previous, if you set it to 1 - near next data point.
animationDuration #	Type `number` Default `0.3` Duration of animation of a line, in seconds.
avoidBalloonOverlapping #	Type `boolean` Default `true` Specifies if cursor should arrange balloons so they won't overlap. If chart is rotated, it might be good idea to turn this off.
balloonPointerOrientation #	Type `string` Default `horizontal` defines if the balloon should be shown above the datapoint or sideways
bulletsEnabled #	Type `boolean` Default `false` Specifies if bullet for each graph will follow the cursor.
bulletSize #	Type `number` Default `8` Size of bullets, following the cursor.
categoryBalloonAlpha #	Type `number` Default `1` Opacity of the category balloon.
categoryBalloonColor #	Type `color` Color of the category balloon. cursorColor is used if not set.
categoryBalloonDateFormat #	Type `string` Default `MMM DD, YYYY` Category balloon date format (used only if category axis parses dates). Check this page for instructions on how to format dates.
categoryBalloonEnabled #	Type `boolean` Default `true` Specifies whether category balloon is enabled.
categoryBalloonFunction #	Allows formatting any category balloon text you want. categoryBalloonFunction should return a string which will be displayed in a balloon. When categoryBalloonFunction is called, category value (or date) is passed as an argument.
categoryBalloonText #	Type `string` Default `[[category]]` You can have [[category]] - [[toCategory]] tags in there and show category ranges this way.
color #	Type `color` Default `#FFFFFF` Text color.
cursorAlpha #	Type `number` Default `1` Opacity of the cursor line.
cursorColor #	Type `color` Default `#CC0000` Color of the cursor line.
cursorPosition #	Type `string` Default `middle` Specifies where the cursor line should be placed - on the beginning of the period (day, hour, etc) or in the middle (only when parseDates property of categoryAxis is set to true). If you want the cursor to follow mouse and not to glue to the nearest data point, set "mouse" here. Possible values are: start, middle, mouse.
enabled #	Type `boolean` Default `true` Specifies whether cursor is enabled.
fullWidth #	Type `boolean` Default `false` If set to true, instead of a cursor line user will see a fill which width will always be equal to the width of one data item. We'd recommend setting cursorAlpha to 0.1 or some other small number if using this feature.
graphBulletAlpha #	Type `number` If you make graph's bullets invisible by setting their opacity to 0 and will set graphBulletAlpha to 1, the bullets will only appear at the cursor's position.
graphBulletSize #	Type `number` Default `1.7` Size of a graph's bullet (if available) at the cursor position. If you don't want the bullet to change it's size, set this property to 1.
leaveAfterTouch #	Type `boolean` Default `true` This makes cursor and balloons to remain after user touches the chart.
leaveCursor #	Type `boolean` Default `false` Specifies if cursor should be left at it's last position. Useful for touch devices - user might want to see the balloons after he moves finger away.
limitToGraph #	Type `AmGraph` If set to an id or a reference to AmGraph object, CategoryAxis cursor line will be limited to this graph instead of being drawn through full height of plot area. Note, this works with serial chart only. Also, cursorPosition of ChartCursor must be set to middle.
listeners #	Type `object[]` You can add listeners of events using this property. Example: listeners = [{"event":"changed", "method":handleEvent}];
oneBalloonOnly #	Type `boolean` Default `false` If this is set to true, only one balloon at a time will be displayed. Note, this is quite CPU consuming.
pan #	Type `boolean` Default `false` If this is set to true, the user will be able to pan the chart instead of zooming.
selectionAlpha #	Type `number` Default `0.2` Opacity of the selection.
selectWithoutZooming #	Type `boolean` Default `false` Specifies if cursor should only mark selected area but not zoom-in after user releases mouse button.
showNextAvailable #	Type `boolean` Default `false` If true, the graph will display balloon on next available data point if currently hovered item doesn't have value for this graph.
tabIndex #	Type `number` In case you set it to some number, the chart will set focus on chart cursor (works only with serial chart) when user clicks tab key. When a focus is set user can move cursor using cursor keys. Note, not all browsers and readers support this.
valueBalloonsEnabled #	Type `boolean` Default `true` Specifies whether value balloons are enabled. In case they are not, the balloons might be displayed anyway, when the user rolls-over the column or bullet.
valueLineAlpha #	Type `number` Opacity of value line. Will use cursorAlpha value if not set.
valueLineBalloonEnabled #	Type `boolean` Default `false` Specifies if value balloon next to value axes labels should be displayed.
valueLineEnabled #	Type `boolean` Default `false` Specifies if cursor of Serial chart should display horizontal (or vertical if chart is rotated) line. This line might help users to compare distant values of a chart. You can also enable value balloons on this line by setting valueLineBalloonEnabled to true.
valueZoomable #	Type `boolean` Default `false` Specifies if the user can zoom-in value axess of a serial chart.
zoomable #	Type `boolean` Default `true` Specifies if the user can zoom-in the chart. If pan is set to true, zoomable is switched to false automatically.

Methods

addListener( `type`, `handler` ) #	Returns `void` Adds event listener to the object. type - string like 'changed' (should be listed in 'events' section of this class or classes which extend this class). handler - function which is called when event happens
clearSelection() #	Returns `void` This method can be used when selectWithoutZooming is set to true and you need to clear the selection made by user.
hideCursor() #	Returns `void` Hides cursor.
removeListener( `obj`, `type`, `handler` ) #	Returns `void` Removes event listener from the object.
showCursorAt( `category` ) #	Returns `void` You can force cursor to appear at specified cateogry or date.
syncWithCursor( `cursor` ) #	Returns `void` Allows to sync one serial chart’s cursor with another chart’s cursor. Important! This method will work correctly only if plot area of both charts is identically equal in width.

addListener(
type,
handler
)

Returns void

Adds event listener to the object.

type - string like 'changed' (should be listed in 'events' section of this class or classes which extend this class). handler - function which is called when event happens

clearSelection()

Returns void

This method can be used when selectWithoutZooming is set to true and you need to clear the selection made by user.

hideCursor()

Returns void

Hides cursor.

removeListener(
  obj,
  type,
  handler
)

Returns void

Removes event listener from the object.

showCursorAt(
category
)

Returns void

You can force cursor to appear at specified cateogry or date.

syncWithCursor(
cursor
)

Returns void

Allows to sync one serial chart’s cursor with another chart’s cursor.

Important! This method will work correctly only if plot area of both charts is identically equal in width.

Events

#changed	Param `{type:"changed", index:Number, zooming:Boolean, mostCloseGraph:AmGraph, chart:AmChart, target:ChartCursor}` Dispatched when cursor position is changed. "index" is a series index over which chart cursors currently is. "zooming" specifies if user is currently zooming (is selecting) the chart. mostCloseGraph property is set only when oneBalloonOnly is set to true.
#draw	Param `{type: "draw", target: ChartCursor, chart: AmChart, initialX: Number, initialY: Number, finalX: Number, finalY: Number, target:ChartCursor}` Dispatched when user draws a trend line with mouse.
#moved	Param `{type:"moved", x:Number, y:Number, zooming:Boolean, chart:AmChart, target:ChartCursor}` Dispatched when mouse is moved over the chart. X and Y are coordinates of the mouse, relative to the plot area of the chart.
#onHideCursor	Param `{type:"onHideCursor", chart:AmChart, target:ChartCursor}` Dispatched when cursor is hidden.
#onShowCursor	Param `{type:"onShowCursor", chart:AmChart, target:ChartCursor}` Dispatched when cursor is shown.
#panning	Param `{type:"zoomStarted", x:Number, y:Number, index:Number, chart:AmChart, target:ChartCursor, index:Number, deltaX:Number, deltaY:Number, delta2X:Number, delta2Y:Number}` Dispatched when user pans the chart (also when user pinch-zooms the chart). deltaX, deltaY, delta2X, delta2Y are relative values. delta2X and delta2Y has values when pinching with two fingers.
#selected	Param `{type:"changed", start:Number, end:Number, chart:AmChart, target:ChartCursor}` Dispatched if selectWithoutZooming is set to true and when user selects some period. start and end are indices or time stamp (when categoryAxis.parseDates is true) of selection start/end.
#zoomed	Param `{type:"changed", start:Number, end:Number, chart:AmChart, target:ChartCursor}` Dispatched when user zooms to some period. start and end are indices or time stamp (when categoryAxis.parseDates is true) of selection start/end.
#zoomStarted	Param `{type:"zoomStarted", x:Number, y:Number, index:Number, chart:AmChart, target:ChartCursor}` Dispatched when user starts selecting chart area to zoom-in. x and y are relative values (0-1). Index is current category index (of Serial chart)

Adapters

ChartCursor does not have any adapters.