Skip to main content
Version: 5.8

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, labels, polygons 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);
}

Default element options

Every annotation type is a chart element and the common options for a specific type can be configured by elements in the chart and global options:

  • per chart by chart.getOptions().getElements().getElement(ElementFactory) method
  • or globally by Defaults.get().getGlobal().getElements().getElement(ElementFactory) method

The annotation options are providing a ElementFactory instance in order to enable to get and change the options at annotation type level.

// ----------------------------------------------------
// Setting option for all box annotations of the chart
// ----------------------------------------------------
BoxAnnotation boxElement = chart.getOptions().getElements().getElement(BoxAnnotation.FACTORY);
// checks if consistent
if (boxElement != null) {
// set font family for all box labels of the chart
boxElement.getLabel().getFont().setFamily("courier");
}
// ----------------------------------------------------
// Setting option for all box annotations
// ----------------------------------------------------
BoxAnnotation boxElement = Defaults.get().getGlobal().getElements().getElement(BoxAnnotation.FACTORY);
// checks if consistent
if (boxElement != null) {
// set font family for all box labels of all charts
boxElement.getLabel().getFont().setFamily("courier");
}
caution

If the annotation plugin is not activated (see Activation), the annotation element options can not be set because the result will be always an inconsistent options instance.

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
clipbooleantrueIf true, the annotations are clipped to the chart area.
drawTimeDrawTimeDrawTime.AFTER_DATASETS_DRAWDefines when the annotations are drawn. This allows positioning of the annotation relative to the other elements of the graph.
eventsIsEvent[] - Set<IsEvent>Defaults.get().getGlobal()
.getEvents()
The events option defines the browser events that the plugin should listen to. This overrides the options at chart level.
interactionInteractionsee belowTo configure which events trigger plugin interactions.

Interaction

Interaction uses the same format as a chart instance.

caution

InteractionMode.INDEX and InteractionMode.DATASET modes are not supported by the plugin. If set, the plugin will use InteractionMode.NEAREST mode.

InteractionAxis.R is not supported by the plugin. If set, the plugin will use InteractionAxis.XY mode.

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);

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.
backgroundShadowColorString - IsColorHtmlColor.TRANSPARENTYesThe color of shadows. See MDN.
borderCapStyleCapStyleCapStyle.BUTTYesCap style of the border line. See MDN.
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.
borderJoinStyleJoinStyleJoinStyle.MITERYesBorder line joint style. See MDN
borderRadiusint - BarBorderRadius0YesThe radius in pixels of box rectangle.
borderShadowColorString - IsColorHtmlColor.TRANSPARENTYesThe color of border shadows. See MDN.
borderWidthint1YesThe stroke width of the box.
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 annotation, in degrees.
shadowBlurdouble0YesThe amount of blur applied to shadows. See MDN.
shadowOffsetXint0YesThe distance that shadows will be offset horizontally. See MDN.
shadowOffsetYint0YesThe distance that shadows will be offset vertically. See MDN.
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 - ScaleIdnull-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 - ScaleIdnull-The ID of the Y scale to bind onto.
zint0YesAll visible elements will be drawn in ascending order of z option, with the same drawTime option.

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.

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(AnnotationContext 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
backgroundShadowColorColorCallback<AnnotationContext>String - IsColor
borderCapStyleCapStyleCallback<AnnotationContext>CapStyle
borderColorColorCallback<AnnotationContext>String - IsColor
borderDashBorderDashCallback<AnnotationContext>List<Integer>
borderDashOffsetBorderDashOffsetCallback<AnnotationContext>double
borderJoinStyleJoinStyleCallback<AnnotationContext>JoinStyle
borderRadiusBorderRadiusCallback<AnnotationContext>int - - BarBorderRadius
backgroundShadowColorColorCallback<AnnotationContext>String - IsColor
borderWidthWidthCallback<AnnotationContext>int
displaySimpleDisplayCallback<AnnotationContext>boolean
drawTimeDrawTimeCallbackDrawTime
rotationRotationCallback<AnnotationContext>double
shadowBlurShadowBlurCallbackdouble
shadowOffsetXShadowOffsetCallbackint
shadowOffsetYShadowOffsetCallbackint
xMaxValueCallbackString - double - Date
xMinValueCallbackString - double - Date
yMaxValueCallbackString - double - Date
yMinValueCallbackString - double - Date
zZCallbackint

Box label

A box annotation can have a label to draw in the box.

Every box 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)
BoxAnnotation box = new BoxAnnotation();
// sets label configuration
box.getLabel().setDisplay(true);
box.getLabel().setContent("My threshold");
// stores the annotation in the main options
options.setAnnotations(box);

The complete options are described by following table:

NameTypeDefaultScriptableDescription
colorString - IsColor#fff -         YesThe text color of the label.
contentString - String[] - Img - CanvasnullYesThe content to show in the label. Provide an array to display values on a new line.
displaybooleanfalseYesWhether or not the label is shown.
drawTimeDrawTimeSee description-Defines when the label is drawn.
Defaults to the box annotation draw time if unset.
fontFontSee descriptionYesThe text font of the label. The default value is the global font with the weight set to Weight.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.
paddingPadding6YesNumber of pixels to add above and below the title text.
See padding documentation for more details.
positionAlignPositionSee positionYesAnchor position of label on box.
rotationdouble0YesThe rotation of label, in degrees.
textAlignTextAlignTextAlign.STARTYesHorizontal alignment on the label content when is set as a multiple lines text.
textStrokeColorString - IsColorHtmlColor.TRANSPARENTYesThe stroke color of the text.
textStrokeWidthint0YesThe stroke width of the text.
xAdjustdouble0YesAdjustment along x-axis (left-right) of label relative to computed position. Negative values move the label left, positive right.
yAdjustdouble0YesAdjustment along y-axis (top-bottom) of label relative to computed position. Negative values move the label up, positive down.
zint0YesAll visible elements will be drawn in ascending order of z option, with the same drawTime option.

Box label position

AlignPosition can define the x property for the horizontal alignment in the box. Similarly, the y property defines the vertical alignment in the box.

Possible options for both properties are LabelPosition.START, LabelPosition.CENTER, LabelPosition.END, or a double, a value between 0 and 1, is representing the percentage on the size where the label will be located.

Default is LabelPosition.CENTER.

Box 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
BoxAnnotation box = new BoxAnnotation();
// sets callback for color options
box.getLabel().setColor(new ColorCallback<AnnotationContext>(){

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

The following options can be set by a callback:

NameCallbackReturned types
colorColorCallback<AnnotationContext>String - IsColor
contentContentCallbackString - List<String> - Img - Canvas
displaySimpleDisplayCallback<AnnotationContext>boolean
fontFontCallback<AnnotationContext>FontItem
imageHeightImageSizeCallbackString - int
imageWidthImageSizeCallbackString - int
paddingPaddingCallback<AnnotationContext>PaddingItem
rotationRotationCallback<AnnotationContext>double
positionLabelAlignPositionCallbackAlignPosition
textAlignTextAlignCallback<AnnotationContext>TextAlign
textStrokeColorColorCallback<AnnotationContext>String - IsColor
textStrokeWidthWidthCallback<AnnotationContext>int
xAdjustAdjustSizeCallbackdouble
yAdjustAdjustSizeCallbackdouble
zZCallbackint

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.
backgroundShadowColorString - IsColorHtmlColor.TRANSPARENTYesThe color of shadows. See MDN.
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.
borderShadowColorString - IsColorHtmlColor.TRANSPARENTYesThe color of border shadows. 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 annotation, in degrees.
shadowBlurdouble0YesThe amount of blur applied to shadows. See MDN.
shadowOffsetXint0YesThe distance that shadows will be offset horizontally. See MDN.
shadowOffsetYint0YesThe distance that shadows will be offset vertically. See MDN.
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 - ScaleIdnull-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 - ScaleIdnull-The ID of the Y scale to bind onto.
zint0YesAll visible elements will be drawn in ascending order of z option, with the same drawTime option.

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(AnnotationContext 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
backgroundShadowColorColorCallback<AnnotationContext>String - IsColor
borderColorColorCallback<AnnotationContext>String - IsColor
borderDashBorderDashCallback<AnnotationContext>List<Integer>
borderDashOffsetBorderDashOffsetCallback<AnnotationContext>double
borderShadowColorColorCallback<AnnotationContext>String - IsColor
borderWidthWidthCallback<AnnotationContext>int
displaySimpleDisplayCallback<AnnotationContext>boolean
drawTimeDrawTimeCallbackDrawTime
rotationRotationCallback<AnnotationContext>double
shadowBlurShadowBlurCallbackdouble
shadowOffsetXShadowOffsetCallbackint
shadowOffsetYShadowOffsetCallbackint
xMaxValueCallbackString - double - Date
xMinValueCallbackString - double - Date
yMaxValueCallbackString - double - Date
yMinValueCallbackString - double - Date
zZCallbackint

Ellipse label

An ellipse annotation can have a label to draw in the ellipse.

Every ellipse 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)
EllipseAnnotation ellipse = new EllipseAnnotation();
// sets label configuration
ellipse.getLabel().setDisplay(true);
ellipse.getLabel().setContent("My label");
// stores the annotation in the main options
options.setAnnotations(ellipse);

The complete options are described by following table:

NameTypeDefaultScriptableDescription
colorString - IsColor#fff -         YesThe text color of the label.
contentString - String[] - Img - CanvasnullYesThe content to show in the label. Provide an array to display values on a new line.
displaybooleanfalseYesWhether or not the label is shown.
drawTimeDrawTimeSee description-Defines when the label is drawn.
Defaults to the box annotation draw time if unset.
fontFontSee descriptionYesThe text font of the label. The default value is the global font with the weight set to Weight.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.
paddingPadding6YesNumber of pixels to add above and below the title text.
See padding documentation for more details.
positionAlignPositionSee positionYesAnchor position of label on box.
rotationdouble0YesThe rotation of label, in degrees.
textAlignTextAlignTextAlign.STARTYesHorizontal alignment on the label content when is set as a multiple lines text.
textStrokeColorString - IsColorHtmlColor.TRANSPARENTYesThe stroke color of the text.
textStrokeWidthint0YesThe stroke width of the text.
xAdjustdouble0YesAdjustment along x-axis (left-right) of label relative to computed position. Negative values move the label left, positive right.
yAdjustdouble0YesAdjustment along y-axis (top-bottom) of label relative to computed position. Negative values move the label up, positive down.
zint0YesAll visible elements will be drawn in ascending order of z option, with the same drawTime option.

Ellipse 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
EllipseAnnotation ellipse = new EllipseAnnotation();
// sets callback for color options
ellipse.getLabel().setColor(new ColorCallback<AnnotationContext>(){

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

The following options can be set by a callback:

NameCallbackReturned types
colorColorCallback<AnnotationContext>String - IsColor
contentContentCallbackString - List<String> - Img - Canvas
displaySimpleDisplayCallback<AnnotationContext>boolean
fontFontCallback<AnnotationContext>FontItem
imageHeightImageSizeCallbackString - int
imageWidthImageSizeCallbackString - int
paddingPaddingCallback<AnnotationContext>PaddingItem
rotationRotationCallback<AnnotationContext>double
positionLabelAlignPositionCallbackAlignPosition
textAlignTextAlignCallback<AnnotationContext>TextAlign
textStrokeColorColorCallback<AnnotationContext>String - IsColor
textStrokeWidthWidthCallback<AnnotationContext>int
xAdjustAdjustSizeCallbackdouble
yAdjustAdjustSizeCallbackdouble
zZCallbackint

Label

Label annotations are used to add contents on the chart area. This can be useful for describing values that are of interest.

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

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
// without id (a unique one is created automatically)
LabelAnnotation label = new LabelAnnotation();
label.setDrawTime(DrawTime.AFTER_DRAW);
label.setXScaleID(DefaultScaleId.X);
label.setYScaleID(DefaultScaleId.Y);
label.setXValue("February");
label.setYValue(50);
label.setContent("My label");
// stores the annotation in the main options
options.setAnnotations(label);

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 - IsColorHtmlColor.TRANSPARENTYesThe fill color of the label box.
See default colors.
backgroundShadowColorString - IsColorHtmlColor.TRANSPARENTYesThe color of shadows. See MDN.
borderCapStyleCapStyleCapStyle.BUTTYesCap style of the border label box. See MDN.
borderColorString - IsColorDefaults.get().getGlobal()
.getColorAsString()
YesThe stroke color of the label box.
See default colors.
borderDashint[][]YesThe length and spacing of dashes. See MDN.
borderDashOffsetdouble0YesThe offset for line dashes. See MDN.
borderJoinStyleJoinStyleJoinStyle.MITERYesBorder line joint style. See MDN
borderRadiusint - BarBorderRadius0YesThe radius in pixels of label box.
borderShadowColorString - IsColorHtmlColor.TRANSPARENTYesThe color of border shadows. See MDN.
borderWidthint0YesThe stroke width of the label box.
colorString - IsColorHtmlColor.BLACK -         YesThe text color of the label.
contentString - String[] - Img - CanvasnullYesThe content to show in the label. Provide an array to display values on a new 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.
fontFontSee descriptionYesThe text font of the label. The default value is the global font.
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.
paddingPadding6YesNumber of pixels to add above and below the title text.
See padding documentation for more details.
positionAlignPositionSee positionYesAnchor position of label.
rotationdouble0YesThe rotation of annotation, in degrees.
shadowBlurdouble0YesThe amount of blur applied to shadows. See MDN.
shadowOffsetXint0YesThe distance that shadows will be offset horizontally. See MDN.
shadowOffsetYint0YesThe distance that shadows will be offset vertically. See MDN.
textAlignTextAlignTextAlign.CENTERYesHorizontal alignment on the label content when is set as a multiple lines text.
textStrokeColorString - IsColorHtmlColor.TRANSPARENTYesThe stroke color of the text.
textStrokeWidthint0YesThe stroke width of the text.
xAdjustdouble0YesAdjustment along x-axis (left-right) of point relative to computed position. Negative values move the point left, positive right.
xMaxString - double - DatenullYesX coordinate of end two of the box, whose center is used as the center of the point, in units along the x axis.
xMinString - double - DatenullYesX coordinate of end one of the box, whose center is used as the center of the point, in units along the x axis.
xScaleIDString - ScaleIdnull-The ID of the X scale to bind onto.
xValueString - double - DatenullYesX coordinate of the center of point in units along the x axis.
yAdjustdouble0YesAdjustment along y-axis (top-bottom) of point relative to computed position. Negative values move the point up, positive down.
yMaxString - double - DatenullYesY coordinate of end one of the box, whose center is used as the center of the point, in units along the y axis.
yMinString - double - DatenullYesY coordinate of end one of the box, whose center is used as the center of the point, in units along the y axis.
yScaleIDString - ScaleIdnull-The ID of the Y scale to bind onto.
yValueString - double - DatenullYesY coordinate of the center of point in units along the y axis.
zint0YesAll visible elements will be drawn in ascending order of z option, with the same drawTime option.

If one of the axes does not match an axis in the chart, the point annotation will take the center of the chart as point. The 2 coordinates, xValue, yValue are optional. If not specified, the point annotation will take the center of the chart as point.

The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the box is expanded out to the edges in the respective direction and the box size is used to calculated the center of the point.

Label position

AlignPosition can define the x property for the horizontal alignment of the label with respect to the selected point. Similarly, the y property defines the vertical alignment.

Possible options for both properties are LabelPosition.START, LabelPosition.CENTER, LabelPosition.END, or a double, a value between 0 and 1, is representing the percentage on the size where the label will be located.

Default is LabelPosition.CENTER.

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
LabelAnnotation label = new LabelAnnotation();
// sets callback for border width options
label.setBorderWidth(new WidthCallback<AnnotationContext>(){

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

The following options can be set by a callback:

NameCallbackReturned types
adjustScaleRangeAdjustScaleRangeCallbackboolean
backgroundColorColorCallback<AnnotationContext>String - IsColor - Pattern
backgroundShadowColorColorCallback<AnnotationContext>String - IsColor
borderCapStyleCapStyleCallback<AnnotationContext>CapStyle
borderColorColorCallback<AnnotationContext>String - IsColor
borderDashBorderDashCallback<AnnotationContext>List<Integer>
borderDashOffsetBorderDashOffsetCallback<AnnotationContext>double
borderJoinStyleJoinStyleCallback<AnnotationContext>JoinStyle
borderRadiusBorderRadiusCallback<AnnotationContext>int - - BarBorderRadius
borderShadowColorColorCallback<AnnotationContext>String - IsColor
borderWidthWidthCallback<AnnotationContext>int
colorColorCallback<AnnotationContext>String - IsColor
contentContentCallbackString - List<String> - Img - Canvas
displaySimpleDisplayCallback<AnnotationContext>boolean
drawTimeDrawTimeCallbackDrawTime
fontFontCallback<AnnotationContext>FontItem
imageHeightImageSizeCallbackString - int
imageWidthImageSizeCallbackString - int
paddingPaddingCallback<AnnotationContext>PaddingItem
positionLabelAlignPositionCallbackAlignPosition
rotationRotationCallback<AnnotationContext>double
textAlignTextAlignCallback<AnnotationContext>TextAlign
shadowBlurShadowBlurCallbackdouble
shadowOffsetXShadowOffsetCallbackint
shadowOffsetYShadowOffsetCallbackint
textStrokeColorColorCallback<AnnotationContext>String - IsColor
textStrokeWidthWidthCallback<AnnotationContext>int
xAdjustAdjustSizeCallbackdouble
xMaxValueCallbackString - double - Date
xMinValueCallbackString - double - Date
xValueValueCallbackString - double - Date
yAdjustAdjustSizeCallbackdouble
yMaxValueCallbackString - double - Date
yMinValueCallbackString - double - Date
yValueValueCallbackString - double - Date
zZCallbackint

Callout

The callout connects the label by a line to the selected point.

Every label annotation can have ONLY 1 callout.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
// without id (a unique one is created automatically)
LabelAnnotation label = new LabelAnnotation();
// sets callout configuration
line.getCallout().setDisplay(true);
// stores the annotation in the main options
options.setAnnotations(line);

The complete options are described by following table:

NameTypeDefaultScriptableDescription
borderCapStyleCapStyleCapStyle.BUTTYesCap style of the callout line. See MDN.
borderColorString - IsColorHtmlColor.BLACK -         YesThe color of the callout line.
borderDashint[][]YesLength and spacing of dashes. See MDN.
borderDashOffsetdouble0YesOffset for line dashes. See MDN.
borderJoinStyleJoinStyleJoinStyle.MITERYesCallout line joint style. See MDN.
borderWidthint1YesThe width of the callout line in pixels.
displaybooleanfalseYesWhether or not the callout is shown.
marginint5YesAmount of pixels between the label and the callout separator.
positionCalloutPositionCalloutPosition.AUTOYesThe position of callout, with respect to the label.
sideint5YesWidth of the starter line of callout pointer.
startdouble - int0.5DYesThe percentage of the separator dimension to use as starting point for callout pointer. Could be set in pixel by an integer, or in percentage of the separator dimension by a double, a value between 0 and 1.

Callout 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
LabelAnnotation label = new LabelAnnotation();
// sets callback for border color options
label.getCallout().setBorderColor(new ColorCallback<AnnotationContext>(){

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

The following options can be set by a callback:

NameCallbackReturned types
borderCapStyleCapStyleCallback<AnnotationContext>CapStyle
borderColorColorCallback<AnnotationContext>String - IsColor
borderDashBorderDashCallback<AnnotationContext>List<Integer>
borderDashOffsetBorderDashOffsetCallback<AnnotationContext>double
borderJoinStyleJoinStyleCallback<AnnotationContext>JoinStyle
borderWidthWidthCallback<AnnotationContext>int
displaySimpleDisplayCallback<AnnotationContext>boolean
marginMarginCallbackint
positionCalloutPositionCallbackCalloutPosition
sideSideCallbackint
start[StartCallback](https://pepstock-org.github.io/Charba/5.8/org/pepstock/charba/client/annotation/callbacks/StartCallback](https.html)double - int

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);

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
borderShadowColorString - IsColorHtmlColor.TRANSPARENTYesThe color of border shadows. See MDN.
borderWidthint2YesThe 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 - ScaleIdnull-ID of the scale in single scale mode. If unset, xScaleID and yScaleID are used.
shadowBlurdouble0YesThe amount of blur applied to shadows. See MDN.
shadowOffsetXint0YesThe distance that shadows will be offset horizontally. See MDN.
shadowOffsetYint0YesThe distance that shadows will be offset vertically. See MDN.
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 - ScaleIdnull-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 - ScaleIdnull-The ID of the Y scale to bind onto.
zint0YesAll visible elements will be drawn in ascending order of z option, with the same drawTime option.

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).

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(AnnotationContext 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
borderShadowColorColorCallback<AnnotationContext>String - IsColor
borderWidthWidthCallback<AnnotationContext>int
displaySimpleDisplayCallback<AnnotationContext>boolean
drawTimeDrawTimeCallbackDrawTime
endValueValueCallbackString - double - Date
shadowBlurShadowBlurCallbackdouble
shadowOffsetXShadowOffsetCallbackint
shadowOffsetYShadowOffsetCallbackint
valueValueCallbackString - double - Date
xMaxValueCallbackString - double - Date
xMinValueCallbackString - double - Date
yMaxValueCallbackString - double - Date
yMinValueCallbackString - double - Date
zZCallbackint

Line 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.
backgroundShadowColorString - IsColorHtmlColor.TRANSPARENTYesThe color of shadows. See MDN.
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.
borderRadiusint - BarBorderRadius6YesThe radius of label box in pixels.
borderShadowColorString - IsColorHtmlColor.TRANSPARENTYesThe color of border shadows. See MDN.
borderWidthint0YesThe width of the line in pixels.
colorString - IsColor#fff -         YesThe text color of the label.
contentString - String[] - Img - CanvasnullYesThe content to show in the label. Provide an array to display values on a new line.
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.
paddingPadding6YesNumber of pixels to add above and below the title text.
See padding documentation for more details.
positionLabelPosition - doubleLabelPosition.CENTERYesAnchor position of label on line. If set by a double, a value between 0 and 1, is representing the percentage on the size where the label will be located.
rotationdouble0YesThe rotation of label, in degrees.
shadowBlurdouble0YesThe amount of blur applied to shadows. See MDN.
shadowOffsetXint0YesThe distance that shadows will be offset horizontally. See MDN.
shadowOffsetYint0YesThe distance that shadows will be offset vertically. See MDN.
textAlignTextAlignTextAlign.CENTERYesHorizontal alignment on the label content when is set as a multiple lines text.
textStrokeColorString - IsColorHtmlColor.TRANSPARENTYesThe stroke color of the text.
textStrokeWidthint0YesThe stroke width of the text.
xAdjustdouble0YesAdjustment along x-axis (left-right) of label relative to computed position. Negative values move the label left, positive right.
yAdjustdouble0YesAdjustment along y-axis (top-bottom) of label relative to computed position. Negative values move the label up, positive down.
zint0YesAll visible elements will be drawn in ascending order of z option, with the same drawTime option.

Line 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(AnnotationContext 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
backgroundShadowColorColorCallback<AnnotationContext>String - IsColor
borderCapStyleCapStyleCallback<AnnotationContext>CapStyle
borderColorColorCallback<AnnotationContext>String - IsColor
borderDashBorderDashCallback<AnnotationContext>List<Integer>
borderDashOffsetBorderDashOffsetCallback<AnnotationContext>double
borderJoinStyleJoinStyleCallback<AnnotationContext>JoinStyle
borderRadiusBorderRadiusCallback<AnnotationContext>int - - BarBorderRadius
borderShadowColorColorCallback<AnnotationContext>String - IsColor
borderWidthWidthCallback<AnnotationContext>int
colorColorCallback<AnnotationContext>String - IsColor
contentContentCallbackString - List<String> - Img - Canvas
displaySimpleDisplayCallback<AnnotationContext>boolean
fontFontCallback<AnnotationContext>FontItem
imageHeightImageSizeCallbackString - int
imageWidthImageSizeCallbackString - int
paddingPaddingCallback<AnnotationContext>PaddingItem
positionLabelPositionCallbackdouble - LabelPosition
rotationRotationCallback<AnnotationContext>double(1)
shadowBlurShadowBlurCallbackdouble
shadowOffsetXShadowOffsetCallbackint
shadowOffsetYShadowOffsetCallbackint
textAlignTextAlignCallback<AnnotationContext>TextAlign
textStrokeColorColorCallback<AnnotationContext>String - IsColor
textStrokeWidthWidthCallback<AnnotationContext>int
xAdjustAdjustSizeCallbackdouble
yAdjustAdjustSizeCallbackdouble
zZCallbackint

(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(AnnotationContext context){
return Double.NaN; // autoRotation is set
}
});

Callout

The callout connects the label by a line to the line annotation.

Every line annotation can have ONLY 1 line label and callout.

// 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);
line.getLabel().setYAdjust(-100);
// sets callout configuration
line.getLabel().getCallout().setDisplay(true);
// stores the annotation in the main options
options.setAnnotations(line);

The complete options are described by following table:

NameTypeDefaultScriptableDescription
borderCapStyleCapStyleCapStyle.BUTTYesCap style of the callout line. See MDN.
borderColorString - IsColorHtmlColor.BLACK -         YesThe color of the callout line.
borderDashint[][]YesLength and spacing of dashes. See MDN.
borderDashOffsetdouble0YesOffset for line dashes. See MDN.
borderJoinStyleJoinStyleJoinStyle.MITERYesCallout line joint style. See MDN.
borderWidthint1YesThe width of the callout line in pixels.
displaybooleanfalseYesWhether or not the callout is shown.
marginint5YesAmount of pixels between the label and the callout separator.
positionCalloutPositionCalloutPosition.AUTOYesThe position of callout, with respect to the label.
sideint5YesWidth of the starter line of callout pointer.
startdouble - int0.5DYesThe percentage of the separator dimension to use as starting point for callout pointer. Could be set in pixel by an integer, or in percentage of the separator dimension by a double, a value between 0 and 1.

Line label Callout 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 label configuration
line.getLabel().setDisplay(true);
line.getLabel().setContent("My threshold");
line.getLabel().setBackgroundColor(HtmlColor.RED);
line.getLabel().setYAdjust(-100);
line.getLabel().getCallout().setDisplay(true);
// sets callback for border color options
line.getLabel().getCallout().setBorderColor(new ColorCallback<AnnotationContext>(){

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

The following options can be set by a callback:

NameCallbackReturned types
borderCapStyleCapStyleCallback<AnnotationContext>CapStyle
borderColorColorCallback<AnnotationContext>String - IsColor
borderDashBorderDashCallback<AnnotationContext>List<Integer>
borderDashOffsetBorderDashOffsetCallback<AnnotationContext>double
borderJoinStyleJoinStyleCallback<AnnotationContext>JoinStyle
borderWidthWidthCallback<AnnotationContext>int
displaySimpleDisplayCallback<AnnotationContext>boolean
marginMarginCallbackint
positionCalloutPositionCallbackCalloutPosition
sideSideCallbackint
start[StartCallback](https://pepstock-org.github.io/Charba/5.8/org/pepstock/charba/client/annotation/callbacks/StartCallback](https.html)double - int

Arrow heads

Enabling it, you can add arrow heads at start and/or end of a line. It uses the borderWidth of the line options to configure the line width of the arrow head.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// creates an annotation
// without id (a unique one is created automatically)
LineAnnotation line = new LineAnnotation();
// sets arrowheads configuration
line.getArrowHeads().setDisplay(true);
line.getArrowHeads().setLength(20);
line.getArrowHeads().setWidth(12);
// stores the annotation in the main options
options.setAnnotations(line);

The following options can be specified per (line.getArrowHeads().getStart() and/or line.getArrowHeads().getEnd()) arrow head, or at the top level (line.getArrowHeads()) which apply to all arrow heads.

The complete options are described by following table:

NameTypeDefaultScriptableDescription
backgroundColorString - IsColorlineAnnotation.borderColorYesBackground color of the arrow head.
backgroundShadowColorString - IsColorHtmlColor.TRANSPARENTYesThe color of shadows. See MDN.
borderColorString - IsColorlineAnnotation.borderColorYesThe border arrow head color.
borderDashint[]lineAnnotation.borderDashYesLength and spacing of dashes. See MDN.
borderDashOffsetdoublelineAnnotation.borderDashOffsetYesOffset for line dashes. See MDN.
borderShadowColorString - IsColorlineAnnotation.borderShadowColorYesThe color of border shadows. See MDN.
borderWidthintlineAnnotation.borderWidthYesThe width of the line in pixels.
displaybooleanfalseYesWhether or not the arrow head is shown.
endArrowHeads--To configure the arrow head at the end of the line.
fillbooleanfalseYesWhether or not the arrow head is filled.
lengthint12YesThe length of the arrow head in pixels.
shadowBlurdoublelineAnnotation.shadowBlurYesThe amount of blur applied to shadows. See MDN.
shadowOffsetXintlineAnnotation.shadowOffsetXYesThe distance that shadows will be offset horizontally. See MDN.
shadowOffsetYintlineAnnotation.shadowOffsetYYesThe distance that shadows will be offset vertically. See MDN.
startArrowHeads--To configure the arrow head at the start of the line.
widthint6YesThe width of the arrow head in pixels.

ArrowHeads 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.getArrowHeads().setBackgroundColor(new ColorCallback<AnnotationContext>(){

@Override
public IsColor invoke(AnnotationContext 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
backgroundShadowColorColorCallback<AnnotationContext>String - IsColor
borderColorColorCallback<AnnotationContext>String - IsColor
borderDashBorderDashCallback<AnnotationContext>List<Integer>
borderDashOffsetBorderDashOffsetCallback<AnnotationContext>double
borderShadowColorColorCallback<AnnotationContext>String - IsColor
borderWidthWidthCallback<AnnotationContext>int
displaySimpleDisplayCallback<AnnotationContext>boolean
fillFillCallbackboolean
lengthLengthCallbackint
shadowBlurShadowBlurCallbackdouble
shadowOffsetXShadowOffsetCallbackint
shadowOffsetYShadowOffsetCallbackint
widthWidthCallback<AnnotationContext>int

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.
backgroundShadowColorString - IsColorHtmlColor.TRANSPARENTYesThe color of shadows. See MDN.
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
borderShadowColorString - IsColorHtmlColor.TRANSPARENTYesThe color of border shadows. 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.
pointStylePointStyle - Img - CanvasPointStyle.CIRCLEYesStyle of the point.
radiusdouble10YesSize of the point in pixels.
rotationdouble0YesThe rotation of the point, in degrees.
shadowBlurdouble0YesThe amount of blur applied to shadows. See MDN.
shadowOffsetXint0YesThe distance that shadows will be offset horizontally. See MDN.
shadowOffsetYint0YesThe distance that shadows will be offset vertically. See MDN.
xAdjustdouble0YesAdjustment along x-axis (left-right) of point relative to computed position. Negative values move the point left, positive right.
xMaxString - double - DatenullYesX coordinate of end two of the box, whose center is used as the center of the point, in units along the x axis.
xMinString - double - DatenullYesX coordinate of end one of the box, whose center is used as the center of the point, in units along the x axis.
xScaleIDString - ScaleIdnull-The ID of the X scale to bind onto.
xValueString - double - DatenullYesX coordinate of the center of point in units along the x axis.
yAdjustdouble0YesAdjustment along y-axis (top-bottom) of point relative to computed position. Negative values move the point up, positive down.
yMaxString - double - DatenullYesY coordinate of end one of the box, whose center is used as the center of the point, in units along the y axis.
yMinString - double - DatenullYesY coordinate of end one of the box, whose center is used as the center of the point, in units along the y axis.
yScaleIDString - ScaleIdnull-The ID of the Y scale to bind onto.
yValueString - double - DatenullYesY coordinate of the center of point in units along the y axis.
zint0YesAll visible elements will be drawn in ascending order of z option, with the same drawTime option.

If one of the axes does not match an axis in the chart, the point annotation will take the center of the chart as point. The 2 coordinates, xValue, yValue are optional. If not specified, the point annotation will take the center of the chart as point.

The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the box is expanded out to the edges in the respective direction and the box size is used to calculated the center of the point. To enable to use the box positioning, the radius must be set to 0.

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(AnnotationContext 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
backgroundShadowColorColorCallback<AnnotationContext>String - IsColor
borderColorColorCallback<AnnotationContext>String - IsColor
borderDashBorderDashCallback<AnnotationContext>List<Integer>
borderDashOffsetBorderDashOffsetCallback<AnnotationContext>double
borderShadowColorColorCallback<AnnotationContext>String - IsColor
borderWidthWidthCallback<AnnotationContext>int
displaySimpleDisplayCallback<AnnotationContext>boolean
drawTimeDrawTimeCallbackDrawTime
pointStylePointStyleCallback<AnnotationContext>PointStyle - Img - Canvas
radiusRadiusCallback<AnnotationContext>double
rotationRotationCallback<AnnotationContext>double
shadowBlurShadowBlurCallbackdouble
shadowOffsetXShadowOffsetCallbackint
shadowOffsetYShadowOffsetCallbackint
xAdjustAdjustSizeCallbackdouble
xMaxValueCallbackString - double - Date
xMinValueCallbackString - double - Date
xValueValueCallbackString - double - Date
yAdjustAdjustSizeCallbackdouble
yMaxValueCallbackString - double - Date
yMinValueCallbackString - double - Date
yValueValueCallbackString - double - Date
zZCallbackint

Polygon

Polygon annotations are used to mark whatever polygon (for instance triangle, square or pentagon) on the chart area. This can be useful for highlighting values that are of interest.

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

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

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 polygon.
See default colors.
backgroundShadowColorString - IsColorHtmlColor.TRANSPARENTYesThe color of shadows. See MDN.
borderCapStyleCapStyleCapStyle.BUTTYesCap style of the border line. See MDN.
borderColorString - IsColorDefaults.get().getGlobal()
.getColorAsString()
YesThe stroke color of the polygon.
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
borderJoinStyleJoinStyleJoinStyle.MITERYesBorder line joint style. See MDN
borderShadowColorString - IsColorHtmlColor.TRANSPARENTYesThe color of border shadows. See MDN.
borderWidthint1YesThe stroke width of the polygon.
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 polygon in pixels.
rotationdouble0YesThe rotation of the polygon, in degrees.
shadowBlurdouble0YesThe amount of blur applied to shadows. See MDN.
shadowOffsetXint0YesThe distance that shadows will be offset horizontally. See MDN.
shadowOffsetYint0YesThe distance that shadows will be offset vertically. See MDN.
sidesint3YesAmount of sides of polygon.
xAdjustdouble0YesAdjustment along x-axis (left-right) of polygon relative to computed position. Negative values move the polygon left, positive right.
xMaxString - double - DatenullYesX coordinate of end two of the box, whose center is used as the center of the polygon, in units along the x axis.
xMinString - double - DatenullYesX coordinate of end one of the box, whose center is used as the center of the polygon, in units along the x axis.
xScaleIDString - ScaleIdnull-The ID of the X scale to bind onto.
xValueString - double - DatenullYesX coordinate of the center of polygon in units along the x axis.
yAdjustdouble0YesAdjustment along y-axis (top-bottom) of polygon relative to computed position. Negative values move the polygon up, positive down.
yMaxString - double - DatenullYesY coordinate of end one of the box, whose center is used as the center of the polygon, in units along the y axis.
yMinString - double - DatenullYesY coordinate of end one of the box, whose center is used as the center of the polygon, in units along the y axis.
yScaleIDString - ScaleIdnull-The ID of the Y scale to bind onto.
yValueString - double - DatenullYesY coordinate of the center of polygon in units along the y axis.
zint0YesAll visible elements will be drawn in ascending order of z option, with the same drawTime option.

If one of the axes does not match an axis in the chart, the point annotation will take the center of the chart as point. The 2 coordinates, xValue, yValue are optional. If not specified, the point annotation will take the center of the chart as point.

The 4 coordinates, xMin, xMax, yMin, yMax are optional. If not specified, the box is expanded out to the edges in the respective direction and the box size is used to calculated the center of the point. To enable to use the box positioning, the radius must be set to 0.

Polygon 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
PolygonAnnotation polygon = new PolygonAnnotation();
// sets callback for border width options
polygon.setBorderWidth(new WidthCallback<AnnotationContext>(){

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

The following options can be set by a callback:

NameCallbackReturned types
adjustScaleRangeAdjustScaleRangeCallbackboolean
backgroundColorColorCallback<AnnotationContext>String - IsColor - Pattern
backgroundShadowColorColorCallback<AnnotationContext>String - IsColor
borderCapStyleCapStyleCallback<AnnotationContext>CapStyle
borderColorColorCallback<AnnotationContext>String - IsColor
borderDashBorderDashCallback<AnnotationContext>List<Integer>
borderDashOffsetBorderDashOffsetCallback<AnnotationContext>double
borderJoinStyleJoinStyleCallback<AnnotationContext>JoinStyle
borderShadowColorColorCallback<AnnotationContext>String - IsColor
borderWidthWidthCallback<AnnotationContext>int
displaySimpleDisplayCallback<AnnotationContext>boolean
drawTimeDrawTimeCallbackDrawTime
radiusRadiusCallback<AnnotationContext>double
rotationRotationCallback<AnnotationContext>double
shadowBlurShadowBlurCallbackdouble
shadowOffsetXShadowOffsetCallbackint
shadowOffsetYShadowOffsetCallbackint
sidesSidesCallbackint
xAdjustAdjustSizeCallbackdouble
xMaxValueCallbackString - double - Date
xMinValueCallbackString - double - Date
xValueValueCallbackString - double - Date
yAdjustAdjustSizeCallbackdouble
yMaxValueCallbackString - double - Date
yMinValueCallbackString - double - Date
yValueValueCallbackString - double - Date
zZCallbackint

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 for specific annotation
box.setClickCallback(new ClickCallback(){

@Override
public boolean onClick(IsChart chart, AbstractAnnotation annotation, ChartEventContext event){
// logic
return false; // no redrawing
}
});

You can also catch events with listeners defined for all defined annotations with a single instance, defining it to AnnotationOptions.

// creates a plugin options
AnnotationOptions options = new AnnotationOptions();
// sets callback for all annotations
options.setClickCallback(new ClickCallback(){

@Override
public boolean onClick(IsChart chart, AbstractAnnotation annotation, ChartEventContext event){
// logic
return false; // no redrawing
}
});

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 click occurs on the annotation.
info

If the event callback returns true, the chart will re-render automatically after processing the event completely. This is important when there are the annotations that require re-draws (for instance, after a change of a rendering options).

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(AnnotationContext 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.
elementAnnotationElementThe element instance related to the annotation.
sharedMap<String, Object>A map that can be used to share objects among all contexts for all annotation.
typeContextTypeThe type of the context. It can be ContextType.CHART or ContextType.ANNOTATION