Legend

With a chart, a legend is an area of a chart describing each of the data sets of the chart.

The chart legend displays data about the data sets that area appearing on the chart.

To get, change and apply own properties, you can invoke the set and get methods, as following:

// sets and gets position option to the legend of the chart
chart.getOptions().getLegend().setPosition(Position.BOTTOM);

Position position = chart.getOptions().getLegend().getPosition();

The default values are set in global defaults options, see default global legend options.

The following legend options are available.

Name	Type	Description
align	ElementAlign	Alignment of the legend.
display	boolean	If true, the legend is shown.
events	Event[]	The events option defines the browser events that the legend should listen to.
fullSize	boolean	Marks that this box should take the full width/height of the canvas (moving other boxes).
maxHeight	int	Maximum height of the legend, in pixels.
maxWidth	int	Maximum width of the legend, in pixels.
position	Position	Position of the legend.
reverse	boolean	Legend will show data sets in reverse order.
rtl	boolean	Set true for rendering the legends from right to left.
textDirection	TextDirection	This will force the text direction on the canvas for rendering the legend, regardless of the CSS specified on the canvas.

Events

A chart legend can emits events during its life cycle, when the user clicks, hovers or leaves the legend.

Clicking

The click event is thrown when a click event is registered on a label item. To catch the event and manage it, you can add a LegendClickEventHandler instance to the chart options, as following:

chart.addHandler(new LegendClickEventHandler(){

   /**
    * Invoked when the user clicks on the chart legend.
    * 
    * @param event legend click event
    */
   @Override 
   public void onClick(LegendClickEvent event){
      // logic
   }
      
}, LegendClickEvent.TYPE);

The event provides the legend item object with all information about the clicked item.

When a LegendClickEventHandler instance, the default behavior of the chart (enable and disable datasets) is not performed. To invoke it, you can use invokeLegendOnClick method of Defaults object.

Hovering

The hover event is thrown when a mousemove event is registered on top of a label item. To catch the event and manage it, you can add a LegendHoverEventHandler instance to the chart options, as following:

chart.addHandler(new LegendHoverEventHandler(){

   /**
    * Invoked when the user hovers on the chart legend.
    * 
    * @param event legend hover event
    */
   @Override 
   public void onHover(LegendHoverEvent event){
      // logic
   }
         
}, LegendHoverEvent.TYPE);

The event provides the legend item object with all information about the hovered item.

When a LegendHoverEventHandler instance, the default behavior of the chart is not performed. To invoke it, you can use invokeLegendOnHover method of Defaults object.

Leaving

The leave event is thrown when a mouseout event is registered on top of a label item. To catch the event and manage it, you can add a LegendLeaveEventHandler instance to the chart options, as following:

chart.addHandler(new LegendleaveEventHandler(){

   /**
    * Invoked when the user leaves on the chart legend.
    * 
    * @param event legend leave event
    */
   @Override 
   public void onLeave(LegendLeaveEvent event){
      // logic
   }
         
}, LegendLeaveEvent.TYPE);

The event provides the legend item object with all information about the left item.

When a LegendLeaveEventHandler instance, the default behavior of the chart is not performed. To invoke it, you can use invokeLegendOnLeave method of Defaults object.

Legend labels

The chart legend title can configure the title visible on legend element.

To get, change and apply own properties, you can invoke the set and get methods, as following:

// sets and gets the padding and usePointStyle options for
// the labels of legend
chart.getOptions().getLegend().getLegendLabels().setPadding(5);
chart.getOptions().getLegend().getLegendLabels().setUsePointStyle(true);

boolean usePointStyle = chart.getOptions().getLegend().getLegendLabels().isUsePointStyle();
int padding = chart.getOptions().getLegend().getLegendLabels().getPadding();

The default values are set in global defaults options, see default global legend labels options.

The following are the attributes that you can set:

Name	Type	Description
boxWidth	int	Width of colored box.
boxHeight	int	Height of the colored box.
color	String - String[] - IsColor - IsColor[]	The color of the legend text label. See default colors.
font	IsFont	Font family of legend text label. See Font.
padding	int	Padding between rows of colored boxes.
pointStyle	PointStyle - Img - Canvas	This style of point is used for the legend. Only used if usePointStyle is true.
textAlign	TextAlign	Horizontal alignment of the label text.
usePointStyle	boolean	Label style will match corresponding point style (size is based on fontSize, boxWidth is not used in this case).

Callbacks

A chart legend labels can be configured at runtime, providing some interfaces for a specific purpose.

filter callback

Allows filtering of legend items.

To apply a filter callback, you can set a LegendFilterCallback instance to the chart options, as following:

chart.getOptions().getLegend().getLabels().setFilterCallback(new LegendFilterCallback(){

   /**
    * Allows filtering of legend items.
    * 
    * @param chart chart instance
    * @param item item to be filtered
    * @return false to remove the item
    *         from the container, otherwise true.
    */
   @Override 
   public boolean onFilter(IsChart chart, LegendItem item){
      // logic
      return true;
   }
         
});

The callback uses LegendItem to enable filtering.

itemSort callback

Allows sorting of legend items.

To apply a item sort callback, you can set a LegendItemSortCallback instance to the chart options, as following:

chart.getOptions().getLegend().getLabels().setItemSortCallback(new LegendItemSortCallback(){

   /**
    * Allows sorting of legend items.
    * 
     * @param chart chart instance
     * @param item1 the first object to be compared.
     * @param item2 the second object to be compared.
     * @return a negative integer, zero, or a positive integer as the first argument is less than, equal to, or greater than the second.
     */
   @Override 
   public int onItemSort(IsChart chart, LegendItem item1, LegendItem item2){
      // logic
      return 0;
   }
         
});

The callback uses LegendItem to enable filtering.

generateLabels callback

Generates legend label items for each thing in the legend. Default implementation returns the text and styling for the color box.

To apply a custom callback, you can set a legend labels callback instance to the chart options, as following:

chart.getOptions().getLegend().getLegendLabels().setLabelsCallback(new LegendLabelsCallback(){

   /**
    * Generates legend items for each thing in the legend. Default implementation returns the text + styling for the color box.
    * 
    * @param chart chart instance
    * @param defaultLabels list of labels created by CHART.JS using the out of the box generate labels callback.
    * @return a list of legend items. if null, uses the default implementation
    */
   @Override 
   List<LegendLabelItem> generateLegendLabels(IsChart chart, List<LegendLabelItem> defaultLabels){
      // logic
      return legendItemListInstance;
   }
         
});

The callback gets the list of legend items, as argument, that Chart.JS have been calculated as default.

This helps the implementation of the callback because you can change ONLY what you need to update.

The callback returns a list of label items, which the properties to be applied.

Legend title

The chart legend labels can configure the labels visible on legend element.

To change and apply own properties, you can invoke the set methods, as following:

// sets text to the title of legend
chart.getOptions().getLegend().getTitle().setText("This is my legend title");
// sets padding to the title of legend and enables it
chart.getOptions().getLegend().getTitle().getPadding().set(5);
chart.getOptions().getLegend().getTitle().setDisplay(true);

Padding padding = chart.getOptions().getLegend().getTitle().getPadding();
boolean display = chart.getOptions().getLegend().getTitle().isDisplay();

The default values are set in global defaults options, see default global legend title options.

The following are the attributes that you can set:

Name	Type
display	boolean	If true, the legend title is shown.
padding	Padding	Number of pixels to add above and below the title text. See padding documentation for more details.
color	String - String[] - IsColor - IsColor[]	The color of the legend text title. See default colors.
font	IsFont	Font family of legend text title. See Font.

AtLeastOneDatasetHandler event handler

Charba provides a common implementation for legend click event handler to enable the control about how many data sets are hidden, in order to have at least 1 data set visible and avoid to have an empty chart.

To apply the event handler, you can set to the chart, as following:

// adds handler
chart.addHandler(new AtLeastOneDatasetHandler(), LegendClickEvent.TYPE);