Skip to main content
Version: 5.1

Datasets items selector plugin

Charba provides an plugin implementation to select an area on the chart which represents a set of datasets items of the chart and inform you by event about the range of datasets items selected.

The goal is to enable selections of a subset of datasets, zooming and drill down/up of the data on chart instance.

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

The implementation is DatasetsItemsSelector and can be set as following:

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

The ID of plugin is charbadatasetsitemsselector (DatasetsItemsSelector.ID).

note

It works on all multiple scales chart type, like line(1), bar(1), scatter or bubble charts.

(1) line and bar charts can be managed ONLY with indexAxis option set to IndexAxis.X.

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 DatasetsItemsSelectorOptions and set it to your chart options as following, setting the color you want:

// creates a plugin options
DatasetsItemsSelectorOptions options = new DatasetsItemsSelectorOptions();
// Set "green" by HtmlColor
options.setColor(HtmlColor.GREEN);

// --------------------------------------
// STORING plugin options
// --------------------------------------
// stores the plugin options by plugin ID
chart.getOptions().getPlugin().setOptions(DatasetsItemsSelector.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
DatasetsItemsSelectorOptions options = new DatasetsItemsSelectorOptions();
// Set "green" by HtmlColor
options.setColor(HtmlColor.GREEN);

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

// gets options reference
DatasetsItemsSelectorOptions options;

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

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

NameTypeDefaultDescription
borderColorString - IsColorrgb(97, 97, 97) -         The border color of the selected area.
borderDashint[][]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.
borderDashOffsetdouble0Offset for line dashes. See MDN
borderWidthint0The border width of the selected area.
colorString - IsColorrgba(255, 204, 128, 0.3) -         The color of selected area on chart.
enabledbooleantrueIf true, the plugin is enabled.
modifierKeyModifierKeynullKeyboard modifier key which must be pressed to enable the selection.
xAxisIDString - ScaleIdDefaultScaleId.XThe ID of the X axis to use to calculate the amount of selectable items.

Selection cleaner

Every options has got a inner element to set selection cleaner options. The selection cleaner element allows to reset the selection directly from the chart.

It adds a label and/or image on top or bottom of the chart which will be visible only when there is a selection on datasets. Clicking on the element, the selection on chart is removed.

// creates a plugin options
DatasetsItemsSelectorOptions options = new DatasetsItemsSelectorOptions();
// sets the options to selection cleaner configuration element
options.getSelectionCleaner().setDisplay(true);
options.getSelectionCleaner().getFont().setSize(18);
options.getSelectionCleaner().setAlign(Align.RIGHT_CHART_AREA);
options.getSelectionCleaner().setPosition(Position.BOTTOM);
options.getSelectionCleaner().setRender(Render.IMAGE_LABEL);
options.getSelectionCleaner().setUseSelectionStyle(true);

The complete options are described by following table:

NameTypeDefaultDescription
displaybooleanfalseIf true the element will be showed to chart.
labelString"Reset selection"The label to show in the element.
fontIsFontSee descriptionFont of selection cleaner label.

The default value is the global font.
See Font.
colorString - IsColorrgb(97, 97, 97) -         The font color of label.
alignAlignAlign.RIGHTAlignment of element.
positionPositionPosition.BOTTOMPosition of the element in the chart. left and right are ignored and use bottom.
imageImgnullThe image to show in the element.
renderRenderRender.LABELDefines if label or image or both will e showed in the element.
marginint2The distance with the canvas borders.
paddingint4The padding around the render element.
spacingint3The distance between image and label in the element.
useSelectionStylebooleanfalseIf true the element will use the style used for selection area.

Actions and events

The plugin can emit events when

  • the selection of area on chart has been finished, an event will fire passing the range of the selected datasets items.
  • the selection area is resetted, an event will fire.

Furthermore it provides a set of methods in order to set and clean selection programmatically.

Selecting dataset items

To set a selection programmatically, the plugin provides 3 methods:

  • setSelection(IsChart chart, String from, String to) which selects on the chart using the axis values passed as argument; being strings, this method should be used on cartesian category axes
  • setSelection(IsChart chart, double from, double to) which selects on the chart using the axis values passed as argument; being numbers, this method should be used on cartesian linear or cartesian logarithmic axes
  • setSelection(IsChart chart, Date from, Date to) which selects on the chart using the axis values passed as argument; being dates, this method should be used on cartesian time or cartesian time series axes

Here is a simple example:

protected void handleSelect() {
// selects the area between "February" and "April" labels
DatasetsItemsSelector.get().setSelection(chart, "February", "April");
}

To catch the event and manage it, you can add a DatasetRangeSelectionEventHandler instance to the chart options, as following:

chart.addHandler(new DatasetRangeSelectionEventHandler(){

/**
* Invoked when the user selects an area on the chart.
*
* @param event chart data set selection event
*/
@Override
public void onSelect(DatasetRangeSelectionEvent event){
// logic
}

}, DatasetRangeSelectionEvent.TYPE);

The event provides 2 methods to get the range of the selected data sets:

  • getFrom() provides the starting value on data sets, by a scale item.
  • getTo() provides the ending value on data sets, by a scale item.

Cleaning selection

To reset a selection programmatically, without using selection cleaner element, the plugin provides 2 methods:

  • cleanSelection(IsChart chart) which resets the selected area on passed chart instance firing event on reset if a clean selection handler has been configured.
  • cleanSelection(IsChart chart, boolean fireEvent) which resets the selected area on passed chart instance, setting if the event must be fired

Here is a simple example:

protected void reset() {
// removes the area, previously selected
DatasetsItemsSelector.get().cleanSelection(chart);
}

To catch the event and manage it, you can add a DatasetRangeCleanSelectionEventHandler instance to the chart options, as following:

chart.addHandler(new DatasetRangeCleanSelectionEventHandler(){

/**
* Invoked when the user cleans an area on the chart.
*
* @param event chart data set clean selection event
*/
@Override
public void onClean(DatasetRangeCleanSelectionEvent event){
// logic
}

}, DatasetRangeCleanSelectionEvent.TYPE);

To update a current selection is NOT mandatory to reset it but it's enough to re-select new area on the chart.

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 the plugin options
DatasetsItemsSelectorOptions options = DatasetsItemsSelectorOptionsBuilder.create()
.setBorderWidth(5)
.setBorderDash(6, 2, 3)
.setDisplay(true)
.setFontSize(18)
.setAlign(Align.RIGHT_CHART_AREA)
.setUseSelectionStyle(true)
.build();
// sets plugin options
chart.getOptions().getPlugins().setOptions(DatasetsItemsSelector.ID, options);