Skip to main content
Version: 6.3

Crosshair plugin

Charba provides a plugin implementation to set the crosshair on the chart when a chart.

Crosshairs are thin vertical and horizontal lines centered on a data point in a chart. When you, as a chart creator, enable crosshairs in your charts, your users will then be able to target a single element.

This plugin, as singleton, can be set both at global and at chart level.

The implementation is Crosshair and can be set as following:

// ---------------------------------
// Registers as global plugin
// ---------------------------------
Defaults.get().getPlugins().register(Crosshair.get());
// ---------------------------------
// Registers as single chart plugin
// ---------------------------------
chart.getPlugins().add(Crosshair.get());

The ID of plugin is charbacrosshair (Crosshair.ID).

Options

It could be that you set this plugin as global one for all your charts but you want to change it for only one instance.

In this case you should instantiate a CrosshairOptions and set it to your chart options as following, setting the color you want:

// creates a plugin options
CrosshairOptions options = new CrosshairOptions();
// set mode
options.setMode(InteractionAxis.XY);

// --------------------------------------
// STORING plugin options
// --------------------------------------
// stores the plugin options by plugin ID
chart.getOptions().getPlugin().setOptions(Crosshair.ID, options);
// stores the plugin options without plugin ID
chart.getOptions().getPlugin().setOptions(options);
// stores the plugin options directly by the options
options.store(chart);

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

// creates a plugin options
CrosshairOptions options = new CrosshairOptions();
// set mode
options.setMode(InteractionAxis.XY);

// --------------------------------------
// STORING plugin options
// --------------------------------------
// stores the plugin options by plugin ID
Defaults.get().getGlobal().getPlugin().setOptions(Crosshair.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, CrosshairOptionsFactory as static reference inside the plugin which can be used to retrieve the options from chart, as following:

// gets options reference
CrosshairOptions options;

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

The following are the attributes that you can set to plugin options:

NameTypeDefaultDescription
enabledbooleantrueIf true, the plugin is enabled.
groupStringnullDefines the group which the plugin instance belongs to. It can link the crosshair instances on multiple charts as group and the position is synchronized on all charts.
lineColorString - IsColorHtmlColor.GRAY -         The color of the line of the cross hairs.
lineDashint[][2, 2]The line dash pattern used when stroking lines, using an array of values which specify alternating lengths of lines and gaps which describe the pattern.
lineDashOffsetdouble0Offset for line dashes. See MDN
lineWidthint1The width of the line of the cross hairs.
modeInteractionAxisInteractionAxis.XYSets the display on horizontal and/or vertical hairs.
modifierKeyModifierKeynullKeyboard modifier key which must be pressed to enable the cross hair.
xScaleIDString - ScaleIdDefaultScaleId.XThe ID of the X axis to use to position the vertical cross hair.
yScaleIDString - ScaleIdDefaultScaleId.YThe ID of the Y axis to use to position the horizontal cross hair.

Labelling

The plugin enables the labels on the scales in order to show the values of the cross hair. You can configure separately the labels on X and Y.

// creates a plugin options
CrosshairOptions options = new CrosshairOptions();
// set X label options
options.getXLabel().setBackgroundColor(HtmlColor.RED);
// set Y label options
options.getYLabel().setBackgroundColor(HtmlColor.YELLOW);

The following are the attributes that you can set to plugin label options:

NameTypeDefaultDescription
displaybooleantrueIf true, the label is shown.
backgroundColorString - IsColorrgb(110, 112, 121) -         The background color of the label.
borderColorString - IsColorHtmlColor.TRANSPARENTThe border color of the label.
borderRadiusint6The border radius of the label.
borderWidthint0The border width of the label.
colorString - IsColorHtmlColor.WHITE -         The color of the text of the label.
fontIsFontSee descriptionFont of the text of the label.

The default value is the global font.
See Font.
paddingint6The space around the text of the label.

To set the same value to both labels, without writing twice the same code, CrosshairOptions is providing a objet which enables that:

// creates a plugin options
CrosshairOptions options = new CrosshairOptions();
// set background color to X and Y labels
options.getLabels().setBackgroundColor(HtmlColor.RED);

Formatter

The plugin provides a callback to change the format the value of label text in order to show whatever is needed.

The formatter can be instantiated implementing CrosshairFormatterCallback interface which is providing 3 parameters:

  1. chart instance
  2. the scale instance, where the label is related to.
  3. the value, retrieved from the scale at the position of the cross hair.
// creates a plugin options
CrosshairOptions options = new CrosshairOptions();
// set Y label formatter
options.getYLabel().setFormatter(new CrosshairFormatterCallback() {

/**
* Returns the text to apply to the crosshair label.
*
* @param chart chart instance
* @param scale scale instance
* @param value current value to draw in the label
* @return the text to apply to the crosshair label
*/
@Override
public String format(IsChart chart, ScaleItem scale, ScaleValueItem value) {
if (format.getValue()) {
return Utilities.applyPrecision(value.getValue(), 0);
}
return value.getLabel();
}
});

Options builder

Charba provides a builder to create options using the set methods in sequence and get the options object at the end of configuration.

// creates a plugin options
CrosshairOptions options = CrosshairOptionsBuilder.create()
.setMode(InteractionAxis.XY)
.setXLabelBackgroundColor(HtmlColor.RED)
.build();
// sets options
chart.getOptions().getPlugins().setOptions(Crosshair.ID, options);

Creating a build by CrosshairOptionsBuilder.create() it will use the global options as default, instead by CrosshairOptionsBuilder.create(chart) it will use the global chart options as default.