org.moxieapps.gwt.highcharts.client

Class Legend

java.lang.Object

org.moxieapps.gwt.highcharts.client.Configurable<Legend>

org.moxieapps.gwt.highcharts.client.Legend

public class Legend
extends Configurable<Legend>

A configurable class that can be used to represent custom legend options for the chart, which can then be set on the chart (via the BaseChart.setLegend(Legend) method.) The legend is a box containing a symbol and name for each series item or point item in the chart. Example usage:

   chart.setLegend(
     new Legend()
       .setBorderColor("#CC0000")
       .setLayout(Legend.Layout.HORIZONTAL)
   );
 

Since:

1.0.0

Author:

squinn@moxiegroup.com (Shawn Quinn)

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Legend.Align An enumeration of supported legend horizontal alignment types, which can be passed to methods like setAlign(Legend.Align) method.
static class	Legend.Layout An enumeration of supported legend layout types, which can be passed to methods like setLayout(Layout) method.
static class	Legend.VerticalAlign An enumeration of supported legend vertical alignment types, which can be passed to methods like setVerticalAlign(Legend.VerticalAlign) method.

Constructor Summary

Constructors

Constructor and Description
Legend()

Method Summary

Methods

Modifier and Type	Method and Description
LegendLabelsFormatter	getLabelsFormatter() Returns the custom labels formatter that has been applied to the legend, or null if the built-in generic formatter is being used instead.
Legend	setAlign(Legend.Align align) Convenience method for setting the 'align' option of the legend.
Legend	setBackgroundColor(String backgroundColor) Convenience method for setting the 'backgroundColor' option of the legend.
Legend	setBorderColor(String borderColor) Convenience method for setting the 'borderColor' option of the legend.
Legend	setBorderRadius(Number borderRadius) Convenience method for setting the 'borderRadius' option of the legend.
Legend	setBorderWidth(Number borderWidth) Convenience method for setting the 'borderWidth' option of the legend.
Legend	setEnabled(boolean enabled) Convenience method for setting the 'enabled' option for the legend.
Legend	setFloating(boolean floating) Convenience method for setting the 'floating' option of the legend.
Legend	setItemHiddenStyle(Style itemHiddenStyle) Convenience method for setting the 'itemHiddenStyle' options of the legend.
Legend	setItemHoverStyle(Style itemHoverStyle) Convenience method for setting the 'itemHoverStyle' options of the legend.
Legend	setItemMarginBottom(Number itemMarginBottom) Convenience method for setting the 'itemMarginBottom' options of the legend.
Legend	setItemMarginTop(Number itemMarginTop) Convenience method for setting the 'itemMarginTop' options of the legend.
Legend	setItemStyle(Style itemStyle) Convenience method for setting the 'itemStyle' options of the legend.
Legend	setItemWidth(Number itemWidth) Convenience method for setting the 'itemWidth' option of the legend.
Legend	setLabelsFormatter(LegendLabelsFormatter legendLabelsFormatter) Sets a custom formatter for the labels that can be used to control how the text of the legend labels will be displayed.
Legend	setLayout(Legend.Layout layout) Convenience method for setting the 'layout' option of the legend.
Legend	setMargin(Number margin) Convenience method for setting the 'margin' option of the legend.
Legend	setMaxHeight(Number maxHeight) Convenience method for setting the 'reversed' option of the legend.
Legend	setNavigationActiveColor(Color activeColor) Convenience method for setting the "activeColor" option for the legend navigation.
Legend	setNavigationActiveColor(Number color) Convenience method for setting the "activeColor" option for the legend navigation.
Legend	setNavigationAnimation(Animation animation) Convenience method for setting the "animation" option for the legend navigation.
Legend	setNavigationAnimation(boolean animation) Convenience method for setting the "animation" option for the legend navigation.
Legend	setNavigationArrowSize(Number arrowSize) Convenience method for setting the "arrowSize" option for the legend navigation.
Legend	setNavigationInactiveColor(Color inactiveColor) Convenience method for setting the "inactiveColor" option for the legend navigation.
Legend	setNavigationInactiveColor(Number inactiveColor) Convenience method for setting the "inactiveColor" option for the legend navigation.
Legend	setNavigationStyle(Style style) Convenience method for setting the "style" option for the legend navigation.
Legend	setPadding(Number padding) Convenience method for setting the 'reversed' option of the legend.
Legend	setReversed(boolean reversed) Convenience method for setting the 'reversed' option of the legend.
Legend	setRtl(boolean rtl) Convenience method for setting the 'reversed' option of the legend.
Legend	setShadow(boolean shadow) Convenience method for setting the 'shadow' option of the legend.
Legend	setStyle(Style style) Convenience method for setting the 'style' options of the legend.
Legend	setSymbolHeight(Number symbolHeight) Convenience method for setting the 'symbolHeight' option of the lagend.
Legend	setSymbolPadding(Number symbolPadding) Convenience method for setting the 'symbolPadding' option of the legend.
Legend	setSymbolRadius(Number symbolRadius) Convenience method for setting the 'symbolHeight' option of the lagend.
Legend	setSymbolWidth(Number symbolWidth) Convenience method for setting the 'symbolWidth' option of the legend.
Legend	setTitleStyle(Style style) Convenience method for setting the "style" option for the legend title.
Legend	setTitleText(String text) Convenience method for setting the "text" option for the legend title.
Legend	setUseHTML(boolean useHTML) Convenience method for setting the 'useHTML' option of the legend.
Legend	setVerticalAlign(Legend.VerticalAlign verticalAlign) Convenience method for setting the 'verticalAlign' option of the legend.
Legend	setWidth(Number width) Convenience method for setting the 'width' option of the legend.
Legend	setX(Number x) Convenience method for setting the 'x' position option of the legend.
Legend	setY(Number y) Convenience method for setting the 'y' position option of the legend.

Methods inherited from class org.moxieapps.gwt.highcharts.client.Configurable

getOptions, setOption

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Legend

public Legend()

Method Detail

setAlign

public Legend setAlign(Legend.Align align)

Convenience method for setting the 'align' option of the legend. Equivalent to:

     legend.setOption("align", Legend.Align.LEFT);
 

The horizontal alignment of the legend box within the chart area. Can be one of "left", "center" and "right". Defaults to Legend.Align.CENTER.

Parameters:

align - The horizontal alignment of the legend box within the chart area.

Returns:

A reference to this Legend instance for convenient method chaining.

setBackgroundColor

public Legend setBackgroundColor(String backgroundColor)

Convenience method for setting the 'backgroundColor' option of the legend. Equivalent to:

     legend.setOption("backgroundColor", "#CCCCCC");
 

The background color of the legend, filling the rounded corner border. Defaults to null.

Parameters:

backgroundColor - The value to set as the 'backgroundColor' option on the legend.

Returns:

A reference to this Legend instance for convenient method chaining.

setBorderColor

public Legend setBorderColor(String borderColor)

Convenience method for setting the 'borderColor' option of the legend. Equivalent to:

     legend.setOption("borderColor", "#CCCCCC");
 

The color of the drawn border around the legend. Defaults to #909090.

Parameters:

borderColor - The color of the drawn border around the legend.

Returns:

A reference to this Legend instance for convenient method chaining.

setBorderRadius

public Legend setBorderRadius(Number borderRadius)

Convenience method for setting the 'borderRadius' option of the legend. Equivalent to:

     legend.setOption("borderRadius", 8);
 

The border corner radius of the legend. Defaults to 5.

Parameters:

borderRadius - The border corner radius of the legend.

Returns:

A reference to this Legend instance for convenient method chaining.

setBorderWidth

public Legend setBorderWidth(Number borderWidth)

Convenience method for setting the 'borderWidth' option of the legend. Equivalent to:

     legend.setOption("borderWidth", 3);
 

The width of the drawn border around the legend. Defaults to 1.

Parameters:

borderWidth - The width of the drawn border around the legend.

Returns:

A reference to this Legend instance for convenient method chaining.

setFloating

public Legend setFloating(boolean floating)

Convenience method for setting the 'floating' option of the legend. Equivalent to:

     legend.setOption("floating", true);
 

When the legend is floating, the plot area ignores it and is allowed to be placed below it. Defaults to false.

Parameters:

floating - 'true' to float the legend above the plot area, or 'false' (the default) to make space for it.

Returns:

A reference to this Legend instance for convenient method chaining.

setEnabled

public Legend setEnabled(boolean enabled)

Convenience method for setting the 'enabled' option for the legend. Equivalent to:

     legend.setOption("enabled", true);
 

Enable or disable the legend. Defaults to true.

Parameters:

enabled - Whether or not to enable or disable the legend.

Returns:

A reference to this Legend instance for convenient method chaining.

setItemHiddenStyle

public Legend setItemHiddenStyle(Style itemHiddenStyle)

Convenience method for setting the 'itemHiddenStyle' options of the legend. Equivalent to:

     legend.setOption("/itemHiddenStyle/fontWeight", "bold");
     legend.setOption("/itemHiddenStyle/fontFamily", "serif");
     etc.
 

CSS styles for each legend item when the corresponding series or point is hidden. Properties are inherited from setStyle(Style) unless overridden here. Defaults to:

• color: '#CCC'

Parameters:

itemHiddenStyle - CSS styles for each legend item when the corresponding series or point is hidden.

Returns:

A reference to this Legend instance for convenient method chaining.

setItemHoverStyle

public Legend setItemHoverStyle(Style itemHoverStyle)

Convenience method for setting the 'itemHoverStyle' options of the legend. Equivalent to:

     legend.setOption("/itemHoverStyle/fontWeight", "bold");
     legend.setOption("/itemHoverStyle/fontFamily", "serif");
     etc.
 

CSS styles for each legend item in hover mode. Properties are inherited from setStyle(Style) unless overridden here. Defaults to:

• color: '#000'

Parameters:

itemHoverStyle - CSS styles for each legend item in hover mode.

Returns:

A reference to this Legend instance for convenient method chaining.

setItemMarginBottom

public Legend setItemMarginBottom(Number itemMarginBottom)

Convenience method for setting the 'itemMarginBottom' options of the legend. Equivalent to:

     legend.setOption("itemMarginBottom", 0);
 

The pixel bottom margin for each legend item. Defaults to 0.

Parameters:

itemMarginBottom - The distance in pixels from the last legend item to the bottom border of the legend.

Returns:

A reference to this Legend instance for convenient method chaining.

setItemMarginTop

public Legend setItemMarginTop(Number itemMarginTop)

Convenience method for setting the 'itemMarginTop' options of the legend. Equivalent to:

     legend.setOption("itemMarginTop", 0);
 

The pixel top margin for each legend item. Defaults to 0.

Parameters:

itemMarginTop - The distance in pixels from the top border of the legend to the first legend item.

Returns:

A reference to this Legend instance for convenient method chaining.

setItemStyle

public Legend setItemStyle(Style itemStyle)

Convenience method for setting the 'itemStyle' options of the legend. Equivalent to:

     legend.setOption("/itemStyle/fontWeight", "bold");
     legend.setOption("/itemStyle/fontFamily", "serif");
     etc.
 

CSS styles for each legend item. Defaults to:

• cursor: 'pointer'
• color: '#3E576F'

Parameters:

itemStyle - CSS styles for each legend item.

Returns:

A reference to this Legend instance for convenient method chaining.

setItemWidth

public Legend setItemWidth(Number itemWidth)

Convenience method for setting the 'itemWidth' option of the legend. Equivalent to:

     legend.setOption("itemWidth", 150);
 

The width for each legend item. This is useful in a horizontal layout with many items when you want the items to align vertically. Defaults to null.

Parameters:

itemWidth - The width for each legend item, or null to automatically calculate.

Returns:

A reference to this Legend instance for convenient method chaining.

setLayout

public Legend setLayout(Legend.Layout layout)

Convenience method for setting the 'layout' option of the legend. Equivalent to:

     legend.setOption("layout", Layout.VERTICAL);
 

The layout of the legend items. Can be one of "horizontal" or "vertical". Defaults to Legend.Layout.HORIZONTAL.

Parameters:

layout - The layout of the legend items.

Returns:

A reference to this Legend instance for convenient method chaining.

setLabelsFormatter

public Legend setLabelsFormatter(LegendLabelsFormatter legendLabelsFormatter)

Sets a custom formatter for the labels that can be used to control how the text of the legend labels will be displayed. See the LegendLabelsFormatter interface, and in particular the LegendLabelsFormatter.format(org.moxieapps.gwt.highcharts.client.labels.LegendLabelsData) method for more details on the capabilities available to custom legend formatters.

Parameters:

legendLabelsFormatter - The custom formatter to use for the labels (if not given a built-in generic formatter is used which simply returns the name of the series or, for pie charts, the name of the point).

Returns:

A reference to this Legend instance for convenient method chaining.

Since:

1.3.0

getLabelsFormatter

public LegendLabelsFormatter getLabelsFormatter()

Returns the custom labels formatter that has been applied to the legend, or null if the built-in generic formatter is being used instead.

Returns:

The custom data labels formatter that has been applied, or null if it has not been set.

Since:

1.3.0

setMargin

public Legend setMargin(Number margin)

Convenience method for setting the 'margin' option of the legend. Equivalent to:

     legend.setOption("margin", 60);
 

If the plot area sized is calculated automatically and the legend is not floating, the legend margin is the space between the legend and the axis labels or plot area. Defaults to 15.

Parameters:

margin - The space between the legend and the axis labels or plot area.

Returns:

A reference to this Legend instance for convenient method chaining.

setMaxHeight

public Legend setMaxHeight(Number maxHeight)

Convenience method for setting the 'reversed' option of the legend. Equivalent to:

     legend.setOption("maxHeight", 60);
 

Maximum pixel height for the legend. When the maximum height is extended, navigation will show.

Parameters:

maxHeight - The Maximum height of the Legend

Returns:

A reference to this Legend instance for convenient method chaining.

setNavigationActiveColor

public Legend setNavigationActiveColor(Color activeColor)

Convenience method for setting the "activeColor" option for the legend navigation. Equivalent to:

     legend.setOption("/navigation/activeColor", #3E576F);
 

The color for the active up or down arrow in the legend page navigation. Defaults to #3E576F

Parameters:

activeColor -

Returns:

A reference to this Legend instance for convenient method chaining.

setNavigationActiveColor

public Legend setNavigationActiveColor(Number color)

Convenience method for setting the "activeColor" option for the legend navigation. Equivalent to:

     legend.setOption("/navigation/activeColor", );
 

The color for the active up or down arrow in the legend page navigation. Defaults to #3E576F

Parameters:

color -

Returns:

A reference to this Legend instance for convenient method chaining.

setNavigationAnimation

public Legend setNavigationAnimation(boolean animation)

Convenience method for setting the "animation" option for the legend navigation. Equivalent to:

     legend.setOption(("/navigation/animation", true);
 

How to animate the pages when navigating up or down. A value of true applies the default navigation given in the chart. animation option. Additional options can be given as an object containing values for easing and duration. Defaults to true.

Parameters:

animation -

Returns:

A reference to this Legend instance for convenient method chaining.

setNavigationAnimation

public Legend setNavigationAnimation(Animation animation)

Convenience method for setting the "animation" option for the legend navigation. Equivalent to:

     legend.setOption("/navigation/animation", );
 

How to animate the pages when navigating up or down. A value of true applies the default navigation given in the chart. animation option. Additional options can be given as an object containing values for easing and duration. Defaults to true.

Parameters:

animation -

Returns:

A reference to this Legend instance for convenient method chaining.

setNavigationArrowSize

public Legend setNavigationArrowSize(Number arrowSize)

Convenience method for setting the "arrowSize" option for the legend navigation. Equivalent to:

     legend.setOption("/navigation/arrowSize", 12);
 

The pixel size of the up and down arrows in the legend paging navigation. . Defaults to 12.

Parameters:

arrowSize -

Returns:

A reference to this Legend instance for convenient method chaining.

setNavigationInactiveColor

public Legend setNavigationInactiveColor(Color inactiveColor)

Convenience method for setting the "inactiveColor" option for the legend navigation. Equivalent to:

     legend.setOption("/navigation/inactiveColor", #CCC);
 

The color of the inactive up or down arrow in the legend page navigation. . Defaults to #CCC.

Parameters:

inactiveColor -

Returns:

A reference to this Legend instance for convenient method chaining.

setNavigationInactiveColor

public Legend setNavigationInactiveColor(Number inactiveColor)

Convenience method for setting the "inactiveColor" option for the legend navigation. Equivalent to:

     legend.setOption("/navigation/inactiveColor", );
 

The color of the inactive up or down arrow in the legend page navigation. . Defaults to #CCC.

Parameters:

inactiveColor -

Returns:

A reference to this Legend instance for convenient method chaining.

setNavigationStyle

public Legend setNavigationStyle(Style style)

Convenience method for setting the "style" option for the legend navigation. Equivalent to:

     legend.setOption("/navigation/style", null);
 

Text styles for the legend page navigation.

Parameters:

style -

Returns:

A reference to this Legend instance for convenient method chaining.

setPadding

public Legend setPadding(Number padding)

Convenience method for setting the 'reversed' option of the legend. Equivalent to:

     legend.setOption("padding", 8);
 

The inner padding of the legend box. Defaults to 8.

Parameters:

padding - the distance in pixels of legend items to the legend border.

Returns:

A reference to this Legend instance for convenient method chaining.

setReversed

public Legend setReversed(boolean reversed)

Convenience method for setting the 'reversed' option of the legend. Equivalent to:

     legend.setOption("reversed", true);
 

Whether to reverse the order of the legend items compared to the order of the series or points as defined in the configuration object. Defaults to false.

Parameters:

reversed - 'true' to reverse the order of the legend items.

Returns:

A reference to this Legend instance for convenient method chaining.

setRtl

public Legend setRtl(boolean rtl)

Convenience method for setting the 'reversed' option of the legend. Equivalent to:

     legend.setOption("rtl", true);
 

Whether to show the symbol on the right side of the text rather than the left side. This is common in Arabic and Hebraic. Defaults to false

Parameters:

rtl - 'true' to show the symbol to the right of the text of the legend item.

Returns:

A reference to this Legend instance for convenient method chaining.

setShadow

public Legend setShadow(boolean shadow)

Convenience method for setting the 'shadow' option of the legend. Equivalent to:

     legend.setOption("shadow", true);
 

Whether to apply a drop shadow to the legend. A setBackgroundColor(String) also needs to be applied for this to take effect. Defaults to false.

Parameters:

shadow - 'true' to apply a drop shadow to the legend.

Returns:

A reference to this Legend instance for convenient method chaining.

setStyle

public Legend setStyle(Style style)

Convenience method for setting the 'style' options of the legend. Equivalent to:

     legend.setOption("/style/fontWeight", "bold");
     legend.setOption("/style/fontFamily", "serif");
     etc.
 

CSS styles for the legend area. In the 1.x versions the position of the legend area was determined by CSS. In 2.x, the position is determined by properties like setAlign(org.moxieapps.gwt.highcharts.client.Legend.Align), setVerticalAlign(org.moxieapps.gwt.highcharts.client.Legend.VerticalAlign), setX(Number) and setY(Number), but the styles are still parsed for backwards compatibility.

Parameters:

style - CSS styles for the legend area.

Returns:

A reference to this Legend instance for convenient method chaining.

setSymbolHeight

public Legend setSymbolHeight(Number symbolHeight)

Convenience method for setting the 'symbolHeight' option of the lagend. Equivalent to:

     legend.setOption("symbolHeight", 25);
 

The pixel height of the symbol for series types that use a rectangle in the legend. Defaults to 12.

Parameters:

symbolHeight - The pixel height of the symbol.

Returns:

A reference to this Legend instance for convenient method chaining.

Since:

1.7.0

setSymbolPadding

public Legend setSymbolPadding(Number symbolPadding)

Convenience method for setting the 'symbolPadding' option of the legend. Equivalent to:

     legend.setOption("symbolPadding", 4);
 

The pixel padding between the legend item symbol and the legend item text. Defaults to 5.

Parameters:

symbolPadding - The pixel padding between the legend item symbol and the legend item text.

Returns:

A reference to this Legend instance for convenient method chaining.

setSymbolRadius

public Legend setSymbolRadius(Number symbolRadius)

Convenience method for setting the 'symbolHeight' option of the lagend. Equivalent to:

     legend.setOption("symbolRadius", 5);
 

The border radius of the symbol for series types that use a rectangle in the legend. Defaults to 2.

Parameters:

symbolRadius - The border radius of the symbol.

Returns:

A reference to this Legend instance for convenient method chaining.

Since:

1.7.0

setSymbolWidth

public Legend setSymbolWidth(Number symbolWidth)

Convenience method for setting the 'symbolWidth' option of the legend. Equivalent to:

     legend.setOption("symbolWidth", 40);
 

The pixel width of the legend item symbol. Defaults to 30.

Parameters:

symbolWidth - The pixel width of the legend item symbol.

Returns:

A reference to this Legend instance for convenient method chaining.

setTitleStyle

public Legend setTitleStyle(Style style)

Convenience method for setting the "style" option for the legend title. Equivalent to:

     legend.setOption("/title/style", "fontWeight: 'bold'");
 

Generic CSS styles for the legend title. Defaults to:

 style: {
     fontWeight: 'bold'
 }
 

Parameters:

style -

Returns:

A reference to this Legend instance for convenient method chaining.

setTitleText

public Legend setTitleText(String text)

Convenience method for setting the "text" option for the legend title. Equivalent to:

     legend.setOption("/title/text", null);
 

A text or HTML string for the title. Defaults to null.

Parameters:

text -

Returns:

A reference to this Legend instance for convenient method chaining.

setUseHTML

public Legend setUseHTML(boolean useHTML)

Convenience method for setting the 'useHTML' option of the legend. Equivalent to:

     legend.setOption("useHTML", false);
 

Whether to use HTML to render the legend item texts. Using HTML allows for advanced formatting, images and reliable bi-directional text rendering. Note that exported images won't respect the HTML, and that HTML won't respect Z-index settings. When using HTML, legend.navigation is disabled.

Parameters:

useHTML - 'true' to use HTML to render Legend texts.

Returns:

A reference to this Legend instance for convenient method chaining.

setVerticalAlign

public Legend setVerticalAlign(Legend.VerticalAlign verticalAlign)

Convenience method for setting the 'verticalAlign' option of the legend. Equivalent to:

     legend.setOption("verticalAlign", Legend.VerticalAlign.BOTTOM);
 

The vertical alignment of the legend box. Can be one of "top", "middle" or "bottom". Vertical position can be further determined by the y option. Defaults to Legend.VerticalAlign.BOTTOM.

Parameters:

verticalAlign - The vertical alignment of the legend.

Returns:

A reference to this Legend instance for convenient method chaining.

setWidth

public Legend setWidth(Number width)

Convenience method for setting the 'width' option of the legend. Equivalent to:

     legend.setOption("width", 150);
 

The width of the legend box, not including and padding set on the style. Defaults to null.

Parameters:

width - The width of the legend box (not including padding).

Returns:

A reference to this Legend instance for convenient method chaining.

setX

public Legend setX(Number x)

Convenience method for setting the 'x' position option of the legend. Equivalent to:

     legend.setOption("x", 70);
 

The x offset of the legend relative to it's horizontal alignment align within BaseChart.setSpacingLeft(Number) and BaseChart.setSpacingRight(Number). Negative x moves it to the left, positive x moves it to the right. The default value of 15 together with Legend.Align.CENTER puts it in the center of the plot area. Defaults to 15.

Parameters:

x - The x offset of the legend, relative to the chart's spacing.

Returns:

A reference to this Legend instance for convenient method chaining.

setY

public Legend setY(Number y)

Convenience method for setting the 'y' position option of the legend. Equivalent to:

     legend.setOption("y", -20);
 

The vertical offset of the legend relative to it's vertical alignment (@link VerticalAlign} within BaseChart.setSpacingTop(Number) and BaseChart.setSpacingBottom(Number). Negative y moves it up, positive y moves it down. Defaults to 0.

Parameters:

y - The y position of the legend, relative to the chart's spacing.

Returns:

A reference to this Legend instance for convenient method chaining.