public class

Annotation

extends Object
java.lang.Object
   ↳ com.shinobicontrols.charts.Annotation

Class Overview

An annotation allows a android.view.View to be displayed on the plot area of a chart. It can be fixed to a single point, in data terms, on the plot area. In this case, as the chart is panned and zoomed, its position is updated such that it remains at the specified point on the plot area. It will remain at a fixed size regardless of zoom level. It can also be set to span a specific range on each axis. In this case, as the chart is panned and zoomed it will scale accordingly as the axis ranges change. This is useful for highlighting areas of data.

An annotation is not created directly, instead the methods on AnnotationsManager should be used to create and add an appropriate annotation to a chart.

The position of an annotation will correspond to its X and Y value (or the min and max values of its X and Y range) on its respective X and Y axes. While it is permissible to associate an annotation with an axis that has not yet been added to the chart, that axis must be added to the chart before the chart is drawn otherwise an java.lang.IllegalStateException will be thrown. When an axis is removed from the chart, any annotations associated with that axis will also be removed from the chart.

An annotation can also be positioned in front of the data in the chart's plot area or below the data by using the setPosition(Position) method. By default annotations are place in front of the data. Note, annotations positioned behind the data in the chart will only be visible on devices running API 14 (Ice Cream Sandwich) and above. Annotations positioned in front of the data will appear on all devices down to API 9.

When created, an annotation is given an AnnotationStyle based on the annotation style in the current theme. This object can be manipulated to change the look and feel of the annotation. The only exception to this is for annotations created with addViewAnnotation(View, Object, Object, Axis, Axis). In this case, as a custom view is being used, all style settings are ignored.

Further advanced customization is possible through modification of the annotation's view and its layout params; the view can be obtained using getView(). Setting the width and height of the view's layout params to android.view.ViewGroup.LayoutParams#WRAP_CONTENT or a specific value will ensure the annotation remains at a fixed size during zoom gestures. Setting the width or height of the layout params to android.view.ViewGroup.LayoutParams#MATCH_PARENT will cause it to stretch across the whole of the width or height of the plot area. Finally, if an X range or Y range has been set on the annotation, using setXRange(Range) or setYRange(Range), then setting the width or height of the layout params to 0 will cause the annotation to stretch to that range on the relevant axis and will scale accordingly during zoom gestures.

Once an annotation has been created it is not possible to remove or swap the view held by it. Instead, the whole annotation should be removed using removeAnnotation(Annotation) and a new one added.

Annotations are a shinobicharts Premium Edition-only feature. Attempting to add annotations via the annotations manager with the Standard Edition will result in an java.lang.UnsupportedOperationException being thrown.

Summary

Nested Classes
enum Annotation.Position Defines whether the annotation is positioned into front of or behind the data on the chart's plot area. 
Public Methods
Annotation.Position getPosition()
Returns the position of this annotation: whether it is placed on top of or behind the data on the chart's plot area.
AnnotationStyle getStyle()
Returns the AnnotationStyle object that manages the look and feel of this annotation.
View getView()
Returns the android.view.View this annotation displays on the chart's plot area.
Axis<?, ?> getXAxis()
Returns the X axis associated with this annotation.
Range<?> getXRange()
Returns the range, in data terms, on the X axis which this annotation spans.
Object getXValue()
Returns the value, in data terms, on this annotation's X axis that it is centered on.
Axis<?, ?> getYAxis()
Returns the Y axis associated with this annotation.
Range<?> getYRange()
Returns the range, in data terms, on the Y axis which this annotation spans.
Object getYValue()
Returns the value, in data terms, on this annotation's Y axis that it is centered on.
void setPosition(Annotation.Position position)
Sets the position of this annotation: whether it is placed in front of or behind the data on the chart's plot area.
void setStyle(AnnotationStyle style)
Sets the AnnotationStyle object that will manage the look and feel of this annotation.
void setXRange(Range<?> range)
Sets the range, in data terms, on the X axis for this annotation to span.
void setXValue(Object value)
Sets the value, in data terms, on this annotation's X axis that it is centered on.
void setYRange(Range<?> range)
Sets the range, in data terms, on the Y axis for this annotation to span.
void setYValue(Object value)
Sets the value, in data terms, on this annotation's Y axis that it is centered on.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public Annotation.Position getPosition ()

Returns the position of this annotation: whether it is placed on top of or behind the data on the chart's plot area. By default the annotation is placed in front of the chart's data. Note, annotations positioned behind the data in the chart will only be visible on devices running API 14 (Ice Cream Sandwich) and above. Annotations positioned in front of the data will appear on all devices down to API 9.

Returns
  • the position of this annotation: on top of or behind the data on the chart's plot area

public AnnotationStyle getStyle ()

Returns the AnnotationStyle object that manages the look and feel of this annotation. Any changes to properties on the style are not reflected visually until redrawChart() is called.

Returns
  • the style object that manages the look of this annotation

public View getView ()

Returns the android.view.View this annotation displays on the chart's plot area.

Returns
  • the view this annotation displays on the chart's plot area

public Axis<?, ?> getXAxis ()

Returns the X axis associated with this annotation. It is used to convert the X value (or min and max of the X range) to a pixel position on screen.

Returns
  • the X axis associated with this annotation

public Range<?> getXRange ()

Returns the range, in data terms, on the X axis which this annotation spans. The X range will only be used when the width of the layout params of this annotation's view is set to 0. This is the case for vertical band annotations; by using addVerticalBandAnnotation(Range, Axis, Axis) suitable layout params are automatically given to this annotation's view.

Returns
  • the range on the X axis this annotation spans
See Also

public Object getXValue ()

Returns the value, in data terms, on this annotation's X axis that it is centered on. While returned as an Object, this value is in data terms and should be of a type that is compatible with the X axis.

Returns
  • the value on the X axis that this annotation is centered on

public Axis<?, ?> getYAxis ()

Returns the Y axis associated with this annotation. It is used to convert the Y value (or min and max of the Y range) to a pixel position on screen.

Returns
  • the Y axis associated with this annotation

public Range<?> getYRange ()

Returns the range, in data terms, on the Y axis which this annotation spans. The Y range will only be used when the height of the layout params of this annotation's view is set to 0. This is the case for horizontal band annotations; by using addHorizontalBandAnnotation(Range, Axis, Axis) suitable layout params are automatically given to this annotation's view.

Returns
  • the range on the Y axis this annotation spans
See Also

public Object getYValue ()

Returns the value, in data terms, on this annotation's Y axis that it is centered on. While returned as an Object, this value is in data terms and should be of a type that is compatible with the Y axis.

Returns
  • the value on the Y axis that this annotation is centered on

public void setPosition (Annotation.Position position)

Sets the position of this annotation: whether it is placed in front of or behind the data on the chart's plot area. By default the annotation is placed in front of the chart's data. Note, annotations positioned behind the data in the chart will only be visible on devices running API 14 (Ice Cream Sandwich) and above. Annotations positioned in front of the data will appear on all devices down to API 9.

Parameters
position the position for this annotation: on top of or behind the data on the chart's plot area
See Also

public void setStyle (AnnotationStyle style)

Sets the AnnotationStyle object that will manage the look and feel of this annotation. The new style is not reflected visually until redrawChart() is called.

Parameters
style the style object that will manage the look of this annotation
See Also

public void setXRange (Range<?> range)

Sets the range, in data terms, on the X axis for this annotation to span. The X range will only be used when the width of the layout params of this annotation's view is set to 0. This is the case for vertical band annotations; by using addVerticalBandAnnotation(Range, Axis, Axis) suitable layout params are automatically given to this annotation's view.

Parameters
range the range on the X axis for this annotation to span
See Also

public void setXValue (Object value)

Sets the value, in data terms, on this annotation's X axis that it is centered on. value should be of a suitable type for the X axis. For example, if the X axis is a NumberAxis any subclass of java.lang.Number will be suitable. Setting an object whose type is incompatible with the X axis will result in a java.lang.ClassCastException being thrown when the chart is drawn.

If value is null and this annotation is not set to span the width of the plot area a java.lang.NullPointerException will be thrown when the chart tries to layout its annotations.

Parameters
value the value on the X axis to center this annotation on
See Also

public void setYRange (Range<?> range)

Sets the range, in data terms, on the Y axis for this annotation to span. The Y range will only be used when the height of the layout params of this annotation's view is set to 0. This is the case for horizontal band annotations; by using addHorizontalBandAnnotation(Range, Axis, Axis) suitable layout params are automatically given to this annotation's view.

Parameters
range the range on the Y axis for this annotation to span
See Also

public void setYValue (Object value)

Sets the value, in data terms, on this annotation's Y axis that it is centered on. value should be of a suitable type for the Y axis. For example, if the Y axis is a NumberAxis any subclass of java.lang.Number will be suitable. Setting an object whose type is incompatible with the Y axis will result in a java.lang.ClassCastException being thrown when the chart is drawn.

If value is null and this annotation is not set to span the height of the plot area a java.lang.NullPointerException will be thrown when the chart tries to layout its annotations.

Parameters
value the value on the Y axis to center this annotation on
See Also