Skip to main content
Version: 5.0

Annotation plugin

Charba provides out of the box the feature to enable Annotation which can add annotations on a chart instance.

It can draw lines, boxes, points and ellipses on the chart area.

The annotation plugin work with line, bar, scatter and bubble charts that use linear, logarithmic, time or category scales.

info

The annotation plugin will not work on any chart that does not have exactly two axes, including pie, radar and polar area charts.

Activation

The annotation plugin is injected directly in the document.

The plugin ID is a constant everywhere available, AnnotationPlugin.ID, in AnnotationPlugin entry point.

This plugin registers itself globally, meaning that once injected, all charts will display annotations. In case you want it enabled only for a few charts, you can enable it as following:

// --------------------------------------
// enabling the plugin without any parameter
// the plugin is NOT registered to all charts
// --------------------------------------
AnnotationPlugin.enable();

// --------------------------------------
// enabling the plugin with `true` parameter
// the plugin is registered to all charts
// --------------------------------------
AnnotationPlugin.enable(true);

To activate the plugin in a specific chart, it's enough to provide the configuration options (see below) or enabling it by:

// --------------------------------------
// ENABLING the plugin to a chart instance
// storing a plugin options
// --------------------------------------
// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// sets default draw time
options.setDrawTime(DrawTime.BEFORE_DRAW);
// stores the plugin options directly by the options
options.store(chart);

// --------------------------------------
// ENABLING the plugin to a chart instance
// by a boolean using default plugin
// options
// --------------------------------------
chart.getOptions().getPlugins().setEnabled(AnnotationPlugin.ID, true);

Configuration

The plugin options can be changed at 2 different levels and are evaluated with the following priority:

  • per chart by chart.getOptions().getPlugins().setOptions method
  • or globally by Defaults.get().getGlobal().getPlugins().setOptions method

The configuration AnnotationOptions class is the entry point of plugin configuration.

// -------------------------
// CONFIGURES the annotation
// by AnnotationId id
// -------------------------
// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
LineAnnotation line = new LineAnnotation();
... // additional label configuration
// sets the line annotation to the options
options.setAnnotations(line);
// stores the plugin options directly by the options
options.store();

You can also change the default for all charts instances, as following:

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
LineAnnotation line = new LineAnnotation();
... // additional label configuration
// sets the line annotation to the options
options.setAnnotations(line);

// --------------------------------------
// STORING plugin options
// --------------------------------------
// stores the plugin options by plugin ID
Defaults.get().getGlobal().getPlugin().setOptions(AnnotationPlugin.ID, options);
// stores the plugin options without plugin ID
Defaults.get().getGlobal().getPlugin().setOptions(options);
// stores the plugin options directly by the options
options.store();

If you need to read the plugin options, there is the specific factory, AnnotationOptionsFactory as static reference inside the AnnotationPlugin entry point which can be used to retrieve the options from chart as following:

// gets options reference
AnnotationOptions options;

// --------------------------------------
// GETTING plugin options from chart
// --------------------------------------
if (chart.getOptions().getPlugin().hasOptions(AnnotationPlugin.ID)){
// retrieves the plugin options by plugin ID
options = chart.getOptions().getPlugin().getOptions(AnnotationPlugin.ID, AnnotationPlugin.FACTORY);
//retrieves the plugin options without plugin ID
options = chart.getOptions().getPlugin().getOptions(AnnotationPlugin.FACTORY);
}

Identifier

Every annotation configuration can be add to the AnnotationOptions, assigning a unique identifier.

The identifier of a label configuration can be set by a string or by a specific class, AnnotationId.

// -------------------------
// CONFIGURES the annotation
// by AnnotationId id
// -------------------------
// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates annotation id
AnnotationId annotationId = AnnotationId.create("myAnnotation1");
// creates and adds a line annotation by "myAnnotation1" id
LineAnnotation line = new LineAnnotation(annotationId);
// configures the line annotation
line.setDrawTime(DrawTime.AFTER_DATASETS_DRAW);
line.setBorderColor(HtmlColor.BLACK);
line.setBorderWidth(5);
... // additional label configuration
// sets the line annotation to the options
options.setAnnotations(line);
// stores the plugin options directly by the options
options.store();
caution

If the annotation id is not provided, a unique id for the annotation is created automatically, which can be retrieve by getId() method of the annotation.

You can access to the configured annotations configurations as following:

// ------------------------
// GETS the configured
// annotations
// ------------------------
// retrieves the plugin options by plugin ID
AnnotationOptions options = chart.getOptions().getPlugin().getOptions(AnnotationPlugin.FACTORY);
// gets all annotations configurations
List<AbstractAnnotation> allAnnotations = options.getAnnotations();
// gets "myAnnotation1" annotation configuration
AbstractAnnotation annotation1 = options.getAnnotation(AnnotationId.create("myAnnotation1"));
// gets "myAnnotation2" annotation configuration
AbstractAnnotation annotation2 = options.getAnnotation("myAnnotation2");

Options

The configuration class AnnotationOptions contains all properties needed to configure the plugin.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// sets default draw time
options.setDrawTime(DrawTime.BEFORE_DRAW);

The following options are available at the top level. They apply to all annotations unless they are overwritten on a per-annotation basis:

NameTypeDefaultDescription
drawTimeDrawTimeDrawTime.AFTER_DATASETS_DRAWDefines when the annotations are drawn. This allows positioning of the annotation relative to the other elements of the graph.
dblClickSpeedint350Double-click speed in milliseconds used to distinguish single-clicks from double-clicks whenever you need to capture both. When listening for both click and dblclick, click events will be delayed by this amount.
eventsEvent[]Defaults.get().getGlobal()
.getEvents()
The events option defines the browser events that the plugin should listen to. This overrides the options at chart level.

Draw time

The DrawTime option for an annotation determines where in the chart life cycle the drawing occurs. Four potential options are available:

OptionDescription
BEFORE_DRAWOccurs before any drawing takes place
BEFORE_DATASETS_DRAWOccurs after drawing of axes, but before data sets
AFTER_DATASETS_DRAWOccurs after drawing of data sets but before items such as the tooltip
AFTER_DRAWAfter other drawing is completed.

Box

Box annotations are used to draw rectangles on the chart area. This can be useful for highlighting different areas of a chart.

Every plugin options can have an unlimited number of boxes annotations.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
// without id (a unique one is created automatically)
BoxAnnotation box = new BoxAnnotation();
box.setDrawTime(DrawTime.BEFORE_DATASETS_DRAW);
box.setXScaleID(DefaultScaleId.X);
box.setYScaleID(DefaultScaleId.Y);
box.setXMin("January");
box.setXMax("April");
box.setBackgroundColor(GwtMaterialColor.YELLOW_LIGHTEN_3.alpha(0.3D));
box.setBorderWidth(0);
// stores the annotation in the main options
options.setAnnotations(box);

If one of the axes does not match an axis in the chart, the box will take the entire chart dimension.

The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the box is expanded out to the edges in the respective direction.

The complete options are described by following table:

NameTypeDefaultScriptableDescription
adjustScaleRangebooleantrueYesIf true, the scale range should be adjusted if this annotation is out of range.
backgroundColorString - IsColorDefaults.get().getGlobal()
.getColorAsString()
YesThe fill color of the box.
See default colors.
borderColorString - IsColorDefaults.get().getGlobal()
.getColorAsString()
YesThe stroke color of the box.
See default colors.
borderDashint[][]YesThe length and spacing of dashes. See MDN.
borderDashOffsetdouble0YesThe offset for line dashes. See MDN.
borderWidthint1YesThe stroke width of the box.
borderRadiusint - BarBorderRadius0YesThe radius in pixels of box rectangle.
displaybooleantrueYesWhether or not this annotation is visible.
drawTimeDrawTimeDrawTime.
AFTER_DATASETS_DRAW
YesDefines when the annotation is drawn. This allows positioning of the annotation relative to the other elements of the graph.
xMaxString - double - DatenullYesRight edge of the box in units along the x axis.
xMinString - double - DatenullYesLeft edge of the box in units along the x axis.
xScaleIDString - ScaleIdDefaultScaleId.X-The ID of the X scale to bind onto.
yMaxString - double - DatenullYesTop edge of the box in units along the y axis.
yMinString - double - DatenullYesBottom edge of the box in units along the y axis.
yScaleIDString - ScaleIdDefaultScaleId.Y-The ID of the Y scale to bind onto.

Box scriptable options

Some options also accept a callback which is called at runtime and that takes the context as single argument, see here the details, which is representing contextual information and chart instance.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
BoxAnnotation box = new BoxAnnotation();
// sets callback for border width options
box.setBorderWidth(new WidthCallback<AnnotationContext>(){

@Override
public Integer invoke(DatasetContext context){
// logic
return borderWidth;
}
});
// stores the annotation in the main options
options.setAnnotations(box);

The following options can be set by a callback:

NameCallbackReturned types
adjustScaleRangeAdjustScaleRangeCallbackboolean
backgroundColorColorCallback<AnnotationContext>String - IsColor - Pattern
borderColorColorCallback<AnnotationContext>String - IsColor
borderDashBorderDashCallback<AnnotationContext>List<Integer>
borderDashOffsetBorderDashOffsetCallback<AnnotationContext>double
borderWidthWidthCallback<AnnotationContext>int
borderRadiusBorderRadiusCallback<AnnotationContext>int - - BarBorderRadius
displayDisplayCallback<AnnotationContext>boolean
drawTimeDrawTimeCallbackDrawTime
xMaxValueCallbackString - double - Date
xMinValueCallbackString - double - Date
yMaxValueCallbackString - double - Date
yMinValueCallbackString - double - Date

Ellipse

Ellipse annotations are used to draw ellipses on the chart area. This can be useful for highlighting different areas of a chart.

Every plugin options can have an unlimited number of ellipses annotations.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
// without id (a unique one is created automatically)
EllipseAnnotation ellipse = new EllipseAnnotation();
ellipse.setDrawTime(DrawTime.BEFORE_DATASETS_DRAW);
ellipse.setXScaleID(DefaultScaleId.X);
ellipse.setYScaleID(DefaultScaleId.Y);
ellipse.setXMin("February");
ellipse.setXMax("April");
ellipse.setYMin(10);
ellipse.setYMax(60);
ellipse.setBackgroundColor(GwtMaterialColor.INDIGO_LIGHTEN_3.alpha(0.3D));
ellipse.setBorderWidth(4);
ellipse.setBorderColor(GwtMaterialColor.INDIGO_LIGHTEN_3);
ellipse.setBorderDash(3,3);
// stores the annotation in the main options
options.setAnnotations(ellipse);

If one of the axes does not match an axis in the chart, the ellipse will take the entire chart dimension.

The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the ellipse is expanded out to the edges in the respective direction.

The complete options are described by following table:

NameTypeDefaultScriptableDescription
adjustScaleRangebooleantrueYesIf true, the scale range should be adjusted if this annotation is out of range.
backgroundColorString - IsColorDefaults.get().getGlobal()
.getColorAsString()
YesThe fill color of the ellipse.
See default colors.
borderColorString - IsColorDefaults.get().getGlobal()
.getColorAsString()
YesThe stroke color of the ellipse.
See default colors.
borderDashint[][]YesThe length and spacing of dashes. See MDN.
borderDashOffsetdouble0YesThe offset for line dashes. See MDN.
borderWidthint1YesThe stroke width of the ellipse.
displaybooleantrueYesWhether or not this annotation is visible.
drawTimeDrawTimeDrawTime.
AFTER_DATASETS_DRAW
YesDefines when the annotation is drawn. This allows positioning of the annotation relative to the other elements of the graph.
rotationdouble0YesThe rotation of label, in degrees.
xMaxString - double - DatenullYesRight edge of the ellipse in units along the x axis.
xMinString - double - DatenullYesLeft edge of the ellipse in units along the x axis.
xScaleIDString - ScaleIdDefaultScaleId.X-The ID of the X scale to bind onto.
yMaxString - double - DatenullYesTop edge of the ellipse in units along the y axis.
yMinString - double - DatenullYesBottom edge of the ellipse in units along the y axis.
yScaleIDString - ScaleIdDefaultScaleId.Y-The ID of the Y scale to bind onto.

Ellipse scriptable options

Some options also accept a callback which is called at runtime and that takes the context as single argument, see here the details, which is representing contextual information and chart instance.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
EllipseAnnotation ellipse = new EllipseAnnotation();
// sets callback for border width options
ellipse.setBorderWidth(new WidthCallback<AnnotationContext>(){

@Override
public Integer invoke(DatasetContext context){
// logic
return borderWidth;
}
});
// stores the annotation in the main options
options.setAnnotations(ellipse);

The following options can be set by a callback:

NameCallbackReturned types
adjustScaleRangeAdjustScaleRangeCallbackboolean
backgroundColorColorCallback<AnnotationContext>String - IsColor - Pattern
borderColorColorCallback<AnnotationContext>String - IsColor
borderDashBorderDashCallback<AnnotationContext>List<Integer>
borderDashOffsetBorderDashOffsetCallback<AnnotationContext>double
borderWidthWidthCallback<AnnotationContext>int
displayDisplayCallback<AnnotationContext>boolean
drawTimeDrawTimeCallbackDrawTime
rotationRotationCallback<AnnotationContext>double
xMaxValueCallbackString - double - Date
xMinValueCallbackString - double - Date
yMaxValueCallbackString - double - Date
yMinValueCallbackString - double - Date

Line

Line annotations are used to draw lines on the chart area. This can be useful for highlighting information such as a threshold.

Every plugin options can have an unlimited number of lines annotations.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
// without id (a unique one is created automatically)
LineAnnotation line = new LineAnnotation();
line.setDrawTime(DrawTime.AFTER_DRAW);
line.setScaleID(DefaultScaleId.X.value());
line.setBorderColor(HtmlColor.DARK_GRAY);
line.setBorderWidth(2);
line.setValue(new Date());
// sets label configuration
line.getLabel().setDisplay(true);
line.getLabel().setContent("Now");
line.getLabel().setPosition(LabelPosition.START);
// stores the annotation in the main options
options.setAnnotations(line);

If one of the axes does not match an axis in the chart, the line will take the entire chart dimension.

The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the line is expanded out to the edges in the respective direction.

The line can be positioned in two different ways:

  • if scaleID is set, then value and endValue must also be set to indicate the end points of the line. The line will be perpendicular to the axis identified by scaleID.
  • if scaleID is unset, then xScaleID and yScaleID are used to draw a line from (xMin, yMin) to (xMax, yMax).

The complete options are described by following table:

NameTypeDefaultScriptableDescription
adjustScaleRangebooleantrueYesIf true, the scale range should be adjusted if this annotation is out of range.
borderColorString - IsColorDefaults.get().getGlobal()
.getColorAsString()
YesThe stroke color of the line.
borderDashint[][]Yesthe line dash pattern used when stroking lines, using an array of values which specify alternating lengths of lines and gaps which describe the pattern.
borderDashOffsetint0YesOffset for line dashes. See MDN
borderWidthint1YesThe stroke width of the line.
displaybooleantrueYesWhether or not this annotation is visible.
drawTimeDrawTimeDrawTime.
AFTER_DATASETS_DRAW
YesDefines when the annotation is drawn. This allows positioning of the annotation relative to the other elements of the graph.
endValueString - double - DatenullYesEnd two of the line when a single scale is specified.
scaleIDString - ScaleIdDefaultScaleId.Y-ID of the scale in single scale mode. If unset, xScaleID and yScaleID are used.
valueString - double - DatenullYesEnd one of the line when a single scale is specified.
xMaxString - double - DatenullYesX coordinate of end two of the line in units along the x axis.
xMinString - double - DatenullYesX coordinate of end one of the line in units along the x axis.
xScaleIDString - ScaleIdDefaultScaleId.X-The ID of the X scale to bind onto.
yMaxString - double - DatenullYesY coordinate of end one of the line in units along the y axis.
yMinString - double - DatenullYesY coordinate of end one of the line in units along the y axis.
yScaleIDString - ScaleIdDefaultScaleId.Y-The ID of the Y scale to bind onto.

Line scriptable options

Some options also accept a callback which is called at runtime and that takes the context as single argument, see here the details, which is representing contextual information and chart instance.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
LineAnnotation line = new LineAnnotation();
// sets callback for border width options
line.setBorderWidth(new WidthCallback<AnnotationContext>(){

@Override
public Integer invoke(DatasetContext context){
// logic
return borderWidth;
}
});
// stores the annotation in the main options
options.setAnnotations(line);

The following options can be set by a callback:

NameCallbackReturned types
adjustScaleRangeAdjustScaleRangeCallbackboolean
borderColorColorCallback<AnnotationContext>String - IsColor
borderDashBorderDashCallback<AnnotationContext>List<Integer>
borderDashOffsetBorderDashOffsetCallback<AnnotationContext>double
borderWidthWidthCallback<AnnotationContext>int
displayDisplayCallback<AnnotationContext>boolean
drawTimeDrawTimeCallbackDrawTime
endValueValueCallbackString - double - Date
valueValueCallbackString - double - Date
xMaxValueCallbackString - double - Date
xMinValueCallbackString - double - Date
yMaxValueCallbackString - double - Date
yMinValueCallbackString - double - Date

Label

A line annotation can have a label to draw on the line.

Every line annotation can have ONLY 1 label.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
// without id (a unique one is created automatically)
LineAnnotation line = new LineAnnotation();
// sets label configuration
line.getLabel().setDisplay(true);
line.getLabel().setContent("My threshold");
line.getLabel().setBackgroundColor(HtmlColor.RED);
// stores the annotation in the main options
options.setAnnotations(line);

The complete options are described by following table:

NameTypeDefaultScriptableDescription
autoRotationbooleanfalse-If true, the rotation option is ignored and the label uses the degrees of the line.
backgroundColorString - IsColorrgba(0,0,0,0.8) -         YesBackground color of the label container.
colorString - IsColor#fff -         YesThe text color of the label.
contentString - String[] - ImgnullYesThe content to show in the label. Provide an array to display values on a new line.
borderCapStyleCapStyleCapStyle.BUTTYesCap style of the line. See MDN.
borderColorString - IsColorHtmlColor.BLACK -         YesThe color of the line.
borderDashint[][]YesLength and spacing of dashes. See MDN.
borderDashOffsetdouble0YesOffset for line dashes. See MDN.
borderJoinStyleJoinStyleJoinStyle.MITERYesLine joint style. See MDN.
borderWidthint0YesThe width of the line in pixels.
borderRadiusint - BarBorderRadius6YesThe radius of label box in pixels.
displaybooleanfalseYesWhether or not the label is shown.
drawTimeDrawTimeSee description-Defines when the label is drawn.
Defaults to the line annotation draw time if unset.
fontFontSee descriptionYesThe text font of the label. The default value is the global font with the style set to FontStyle.BOLD.
See Font.
imageHeightint - StringUndefined.INTEGER - nullYesOverrides the height of the image. Could be set in pixel by a number, or in percentage of current height of image by a string. If uset, uses the height of the image. It is used only when the content is an image.
imageWidthint - StringUndefined.INTEGER - nullYesOverrides the width of the image. Could be set in pixel by a number, or in percentage of current width of image by a string. If unset, uses the width of the image. It is used only when the content is an image.
positionLabelPositionLabelPosition.CENTERYesAnchor position of label on line.
rotationdouble0YesThe rotation of label, in degrees.
textAlignTextAlignTextAlign.CENTERYesHorizontal alignment on the label content when is set as a multiple lines text.
xAdjustdouble0YesAdjustment along x-axis (left-right) of label relative to computed position. Negative values move the label left, positive right.
xPaddingint6YesPadding of label to add left/right.
yAdjustdouble0YesAdjustment along y-axis (top-bottom) of label relative to computed position. Negative values move the label up, positive down.
yPaddingint6YesPadding of label to add top/bottom.

Label scriptable options

Some options also accept a callback which is called at runtime and that takes the context as single argument, see here the details, which is representing contextual information and chart instance.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
LineAnnotation line = new LineAnnotation();
// sets callback for background color options
line.getLabel().setBackgroundColor(new ColorCallback<AnnotationContext>(){

@Override
public IsColor invoke(DatasetContext context){
// logic
return color;
}
});
// stores the annotation in the main options
options.setAnnotations(line);

The following options can be set by a callback:

NameCallbackReturned types
backgroundColorColorCallback<AnnotationContext>String - IsColor - Pattern
colorColorCallback<AnnotationContext>String - IsColor
contentContentCallbackString - List<String> - Img
borderCapStyleCapStyleCallback<AnnotationContext>CapStyle
borderColorColorCallback<AnnotationContext>String - IsColor
borderDashBorderDashCallback<AnnotationContext>List<Integer>
borderDashOffsetBorderDashOffsetCallback<AnnotationContext>double
borderJoinStyleJoinStyleCallback<AnnotationContext>JoinStyle
borderWidthWidthCallback<AnnotationContext>int
borderRadiusBorderRadiusCallback<AnnotationContext>int - - BarBorderRadius
displayDisplayCallback<AnnotationContext>boolean
fontFontCallback<AnnotationContext>FontItem
imageHeightImageSizeCallbackString - int
imageWidthImageSizeCallbackString - int
positionLabelPositionCallbackLabelPosition
rotationRotationCallback<AnnotationContext>double(1)
textAlignTextAlignCallback<AnnotationContext>TextAlign
xAdjustAdjustSizeCallbackdouble
xPaddingPaddingSizeCallbackint
yAdjustAdjustSizeCallbackdouble
yPaddingPaddingSizeCallbackint

(1)To enable autoRotation by the rotation callback, the value to return must be Double.NaN.

// sets callback for auto rotation
line.getLabel().setRotation(new RotationCallback<AnnotationContext>(){

@Override
public Double invoke(DatasetContext context){
return Double.NaN; // autoRotation is set
}
});

Point

Point annotations are used to mark points on the chart area. This can be useful for highlighting values that are of interest.

Every plugin options can have an unlimited number of points annotations.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
// without id (a unique one is created automatically)
PointAnnotation point = new PointAnnotation();
// sets annotation configuration
point.setXScaleID(DefaultScaleId.X);
point.setYScaleID(DefaultScaleId.Y);
point.setXValue("February");
point.setYValue(50);
point.setRadius(10);
point.setBackgroundColor(HtmlColor.YELLOW.alpha(0.3D));
point.setBorderWidth(2);
point.setBorderColor(HtmlColor.YELLOW.darker());
// stores the annotation in the main options
options.setAnnotations(point);

The complete options are described by following table:

NameTypeDefaultScriptableDescription
adjustScaleRangebooleantrueYesIf true, the scale range should be adjusted if this annotation is out of range.
backgroundColorString - IsColorDefaults.get().getGlobal()
.getColorAsString()
YesThe fill color of the point.
See default colors.
borderColorString - IsColorDefaults.get().getGlobal()
.getColorAsString()
YesThe stroke color of the point.
borderDashint[][]YesThe line dash pattern used when stroking lines, using an array of values which specify alternating lengths of lines and gaps which describe the pattern.
borderDashOffsetint0YesOffset for border dashes. See MDN
borderWidthint1YesThe stroke width of the point.
displaybooleantrueYesWhether or not this annotation is visible.
drawTimeDrawTimeDrawTime.
AFTER_DATASETS_DRAW
YesDefines when the annotation is drawn. This allows positioning of the annotation relative to the other elements of the graph.
radiusdouble10YesSize of the point in pixels.
xValueString - double - DatenullYesX coordinate of the point in units along the x axis.
xScaleIDString - ScaleIdDefaultScaleId.X-The ID of the X scale to bind onto.
yValueString - double - DatenullYesY coordinate of the point in units along the y axis.
yScaleIDString - ScaleIdDefaultScaleId.Y-The ID of the Y scale to bind onto.

Point scriptable options

Some options also accept a callback which is called at runtime and that takes the context as single argument, see here the details, which is representing contextual information and chart instance.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
PointAnnotation point = new PointAnnotation();
// sets callback for border width options
point.setBorderWidth(new WidthCallback<AnnotationContext>(){

@Override
public Integer invoke(DatasetContext context){
// logic
return borderWidth;
}
});
// stores the annotation in the main options
options.setAnnotations(point);

The following options can be set by a callback:

NameCallbackReturned types
adjustScaleRangeAdjustScaleRangeCallbackboolean
backgroundColorColorCallback<AnnotationContext>String - IsColor - Pattern
borderColorColorCallback<AnnotationContext>String - IsColor
borderDashBorderDashCallback<AnnotationContext>List<Integer>
borderDashOffsetBorderDashOffsetCallback<AnnotationContext>double
borderWidthWidthCallback<AnnotationContext>int
displayDisplayCallback<AnnotationContext>boolean
drawTimeDrawTimeCallbackDrawTime
radiusRadiusCallback<AnnotationContext>double
xValueValueCallbackString - double - Date
yValueValueCallbackString - double - Date

Events

All annotations provide a set of callbacks which can be enabled to catch events on them.

To catch events is enough to set the events which you want to catch at AnnotationOptions and set a callback instance in the annotation.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
// without id (a unique one is created automatically)
BoxAnnotation box = new BoxAnnotation();
// sets callback
box.setClickCallback(new ClickCallback(){

@Override
public void onClick(IsChart chart, AbstractAnnotation annotation, ChartEventContext event){
// logic
}
});

These are the table of callbacks to implement:

EventCallback typeDescription
enterEnterCallbackCalled when the mouse enters the annotation.
leaveLeaveCallbackCalled when the mouse leaves the annotation.
clickClickCallbackCalled when a single click occurs on the annotation.
dblClickDoubleClickCallbackCalled when a double click occurs on the annotation.

Scriptable context

Some options also accept a callback which is called at runtime and that takes the context as single argument, AnnotationContext representing contextual information and chart instance.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
BoxAnnotation box = new BoxAnnotation();
// sets callback for border width options
box.setBorderWidth(new WidthCallback<AnnotationContext>(){

@Override
public Integer invoke(DatasetContext context){
// logic
return borderWidth;
}
});
// stores the annotation in the main options
options.setAnnotations(box);

The context object contains the following properties:

NameTypeDescription
annotationAbstractAnnotationThe annotation configuration where the options is defined as scriptable.
attributesNativeObjectContainerUser object which you can store your options at runtime.
chartIsChartChart instance.
typeContextTypeThe type of the context. It can be ContextType.CHART or ContextType.ANNOTATION