Package smile.plot.vega

Class Legend

java.lang.Object
smile.plot.vega.Legend
public class Legend extends Object
Similar to axes, legends visualize scales. However, whereas axes aid interpretation of scales with positional ranges, legends aid interpretation of scales with ranges such as colors, shapes and sizes.

By default, Vega-Lite automatically creates legends with default properties for color, opacity, size, and shape channels when they encode data fields. User can set the legend property of a mark property channel's field definition to an object to customize legend properties or set legend to null to remove the legend.

Besides legend property of a field definition, the configuration object (config) also provides legend config for setting default legend properties for all legends.

  • Method Details

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • toPrettyString

      public String toPrettyString()
      Returns the specification in pretty print.
      Returns:
      the specification in pretty print.

    • title

      public Legend title(String title)
      Sets a descriptive title.
      Parameters:
      title - a descriptive title.
      Returns:
      this object.

    • aria

      public Legend aria(boolean flag)
      Sets if ARIA attributes should be included (SVG output only).
      Parameters:
      flag - A flag indicating if ARIA attributes should be included (SVG output only). If false, the "aria-hidden" attribute will be set on the output SVG group, removing the legend from the ARIA accessibility tree.
      Returns:
      this object.

    • cornerRadius

      public Legend cornerRadius(double radius)
      Sets the corner radius for the full legend.
      Parameters:
      radius - the corner radius for the full legend.
      Returns:
      this object.

    • description

      public Legend description(String description)
      Sets the text description of this legend for ARIA accessibility (SVG output only). If the aria property is true, for SVG output the "aria-label" attribute will be set to this description. If the description is unspecified it will be automatically generated.
      Parameters:
      description - the text description of this legend for ARIA accessibility.
      Returns:
      this object.

    • direction

      public Legend direction(String direction)
      Sets the direction of the legend, one of "vertical" or "horizontal".
      Parameters:
      direction - "vertical" or "horizontal".
      Returns:
      this object.

    • fillColor

      public Legend fillColor(String color)
      Sets the background fill color for the full legend.
      Parameters:
      color - the background fill color.
      Returns:
      this object.

    • x

      public Legend x(double x)
      Sets the custom x-position for legend with orient "none".
      Parameters:
      x - the custom x-position for legend with orient "none".
      Returns:
      this object.

    • y

      public Legend y(double y)
      Sets the custom y-position for legend with orient "none".
      Parameters:
      y - the custom y-position for legend with orient "none".
      Returns:
      this object.

    • offset

      public Legend offset(double offset)
      Sets the offset, in pixels, by which to displace the legend from the edge of the enclosing group or data rectangle.
      Parameters:
      offset - the offset in pixels.
      Returns:
      this object.

    • orient

      public Legend orient(String orient)
      Sets the orientation of the legend.
      Parameters:
      orient - "top", "bottom", "left" or "right".
      Returns:
      this object.

    • padding

      public Legend padding(double padding)
      Sets the padding between the border and content of the legend group.
      Parameters:
      padding - the padding between the border and content of the legend group.
      Returns:
      this object.

    • strokeColor

      public Legend strokeColor(String color)
      Sets the border stroke color for the full legend.
      Parameters:
      color - the border stroke color.
      Returns:
      this object.

    • type

      public Legend type(String type)
      Sets the type of the legend. Use "symbol" to create a discrete legend and "gradient" for a continuous color gradient.
      Parameters:
      type - "symbol" or "gradient".
      Returns:
      this object.

    • tickCount

      public Legend tickCount(int count)
      Sets the desired number of tick values for quantitative legends.
      Parameters:
      count - the desired number of tick values.
      Returns:
      this object.

    • tickCount

      public Legend tickCount(String expr)
      Sets the desired number of tick values for quantitative legends.
      Parameters:
      expr - the expression of desired number of tick values.
      Returns:
      this object.

    • values

      public Legend values(String... values)
      Sets the explicitly set the visible legend values.
      Parameters:
      values - the visible legend values.
      Returns:
      this object.

    • zindex

      public Legend zindex(int zindex)
      Sets a non-negative integer indicating the z-index of the legend. If zindex is 0, axes should be drawn behind all chart elements. To put them in front, set zindex to 1 or more.
      Parameters:
      zindex - a non-negative integer indicating the z-index of the legend.
      Returns:
      this object.

    • gradientLength

      public Legend gradientLength(double length)
      Sets the length in pixels of the primary axis of a color gradient. This value corresponds to the height of a vertical gradient or the width of a horizontal gradient.
      Parameters:
      length - the length in pixels.
      Returns:
      this object.

    • gradientOpacity

      public Legend gradientOpacity(double opacity)
      Sets the opacity of the color gradient.
      Parameters:
      opacity - a value between [0, 1].
      Returns:
      this object.

    • gradientStrokeColor

      public Legend gradientStrokeColor(String color)
      Sets the color of the gradient stroke.
      Parameters:
      color - the color of the gradient stroke.
      Returns:
      this object.

    • gradientStrokeWidth

      public Legend gradientStrokeWidth(double width)
      Sets the width of the gradient stroke.
      Parameters:
      width - the width in pixels.
      Returns:
      this object.

    • gradientThickness

      public Legend gradientThickness(double thickness)
      Sets the thickness in pixels of the color gradient. This value corresponds to the width of a vertical gradient or the height of a horizontal gradient.
      Parameters:
      thickness - the thickness in pixels.
      Returns:
      this object.

    • format

      public Legend format(String format)
      Sets the text format. When used with the default "number" and "time" format type, the text formatting pattern for labels of guides (axes, legends, headers) and text marks.

      If the format type is "number" (e.g., for quantitative fields), this is D3's number format pattern. If the format type is "time" (e.g., for temporal fields), this is D3's time format pattern.

      Parameters:
      format - the text formatting pattern.
      Returns:
      this object.

    • formatType

      public Legend formatType(String formatType)
      Sets the format type for labels.
      Parameters:
      formatType - "number", "time", or a registered custom format type.
      Returns:
      this object.

    • labelAlign

      public Legend labelAlign(String alignment)
      Sets the alignment of the legend label.
      Parameters:
      alignment - "left", "center", or "right".
      Returns:
      this object.

    • labelBaseline

      public Legend labelBaseline(String baseline)
      Sets the position of the baseline of legend label.
      Parameters:
      baseline - "top", "middle", "bottom", or "alphabetic".
      Returns:
      this object.

    • labelColor

      public Legend labelColor(String color)
      Sets the color of the legend label.
      Parameters:
      color - the color of the legend label.
      Returns:
      this object.

    • labelExpr

      public Legend labelExpr(String expr)
      Sets the Vega expression for customizing labels. The label text and value can be assessed via the label and value properties of the legend's backing datum object.
      Parameters:
      expr - the Vega expression.
      Returns:
      this object.

    • labelFont

      public Legend labelFont(String font)
      Sets the font of the legend label.
      Parameters:
      font - the font of the legend label.
      Returns:
      this object.

    • labelFontSize

      public Legend labelFontSize(double size)
      Sets the font size of the label in pixels.
      Parameters:
      size - the font size in pixels.
      Returns:
      this object.

    • labelFontStyle

      public Legend labelFontStyle(String style)
      Sets the font style of the title.
      Parameters:
      style - the font style of the title.
      Returns:
      this object.

    • labelFontWeight

      public Legend labelFontWeight(String weight)
      Sets the font weight of legend labels.
      Parameters:
      weight - the font weight of legend labels.
      Returns:
      this object.

    • labelFontWeight

      public Legend labelFontWeight(int weight)
      Sets the font weight of legend labels.
      Parameters:
      weight - the font weight of legend labels.
      Returns:
      this object.

    • labelLimit

      public Legend labelLimit(int limit)
      Sets the maximum allowed pixel width of legend labels.
      Parameters:
      limit - the maximum allowed pixel width of legend labels.
      Returns:
      this object.

    • labelOffset

      public Legend labelOffset(int offset)
      Sets the position offset in pixels to apply to labels.
      Parameters:
      offset - the position offset in pixels to apply to labels.
      Returns:
      this object.

    • labelOverlap

      public Legend labelOverlap(boolean flag)
      Sets the strategy to use for resolving overlap of legend labels. If false (the default), no overlap reduction is attempted. If set to true, a strategy of removing every other label is used (this works well for standard linear axes).
      Parameters:
      flag - a value between [0, 1].
      Returns:
      this object.

    • labelOverlap

      public Legend labelOverlap(String strategy)
      Sets the strategy to use for resolving overlap of legend labels. If set to "parity", a strategy of removing every other label is used (this works well for standard linear axes). If set to "greedy", a linear scan of the labels is performed, removing any labels that overlaps with the last visible label (this often works better for log-scaled axes).
      Parameters:
      strategy - "parity" or "greedy".
      Returns:
      this object.

    • clipHeight

      public Legend clipHeight(double height)
      Sets the height in pixels to clip symbol legend entries and limit their size.
      Parameters:
      height - the height in pixels.
      Returns:
      this object.

    • columnPadding

      public Legend columnPadding(double padding)
      Sets the horizontal padding in pixels between symbol legend entries.
      Parameters:
      padding - the horizontal padding in pixels.
      Returns:
      this object.

    • rowPadding

      public Legend rowPadding(double padding)
      Sets the vertical padding in pixels between symbol legend entries.
      Parameters:
      padding - the vertical padding in pixels.
      Returns:
      this object.

    • columns

      public Legend columns(int columns)
      Sets the number of columns in which to arrange symbol legend entries. A value of 0 or lower indicates a single row with one column per entry.
      Parameters:
      columns - the number of columns.
      Returns:
      this object.

    • gridAlign

      public Legend gridAlign(String alignment)
      Sets the alignment to apply to symbol legends rows and columns.
      Parameters:
      alignment - "all", "each", or "none".
      Returns:
      this object.

    • symbolLimit

      public Legend symbolLimit(int limit)
      Sets the maximum number of allowed entries for a symbol legend. Additional entries will be dropped.
      Parameters:
      limit - the maximum number of allowed entries.
      Returns:
      this object.