Skip to content

dimple.legend

Jump to bottom Edit New page
Christabella edited this page Jun 15, 2017 · 7 revisions

A legend object rendering a display of series values against colors.

Constructor
Properties

Constructor

dimple.legend(chart, x, y, width, height, horizontalAlign, series) [code] - Initialise a legend. A legend must have a chart passed into its constructor and it must also reside in this chart's legends property. It is therefore advisable to use chart.addLegend rather than invoking the constructor directly - as it takes care of the double link.

  • x (Required): The x co-ordinate of the upper left corner of the charts render area within the SVG object. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg width. Values may also be mixed in a comma separated list. e.g. "10%,20px" will set the x-coordinate to 10% of the svg width + 20 pixels.

  • y (Required): The y co-ordinate of the upper left corner of the charts render area within the SVG object. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg height. Values may also be mixed in a comma separated list. e.g. "10%,20px" will set the y-coordinate to 10% of the svg height + 20 pixels.

  • width (Required): The width of the legend's plot area within the SVG object. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg width. Elements in the legend will wrap if their width exceeds this bound. Values may also be mixed in a comma separated list. e.g. "10%,20px" will set the legend width to 10% of the svg width + 20 pixels.

  • height (Required): The maximum vertical bounds of the legend within the SVG object. This should be a positive number and can either be an integer or a string suffixed px to set absolute position in pixels, or it can be suffixed % to use a proportion of svg height. Any elements which fall outside this bound will not be rendered. Values may also be mixed in a comma separated list. e.g. "10%,20px" will set the legend height to 10% of the svg height + 20 pixels.

  • horizontalAlign (Optional): Accepted values are "left" and "right", default is "left". The horizontal positioning of the elements within the bounds defined. This does not affect individual legend entries, which will always render with the key on the left and the text on the right. As all elements are sized to the widest, the left edges of each element will always align even if this is set to right.

  • series (Optional): One or more series to include in the legend. By default all chart series will be included, however this allows you to pick particular ones. Accepts either a single dimple.series or an array of dimple.series objects.

  • returns (dimple.legend): The newly added legend.

Properties

dimple.legend.fontSize [code] - This is 10px by default as of version 2. In order to get the dimple version 1 handling (where fonts are resized according to the chart size) set this to "auto". Otherwise any valid CSS font-size string may be passed.

// Let's keep it old skool
myLegend.fontSize = "auto";

dimple.legend.fontFamily [code] - This is sans-serif by default, any CSS font-family is valid here. Changing this will override the font used for axes.

// Use a serif font for this axis
myLegend.fontFamily = "serif";

dimple.legend.height: The maximum vertical bounds of the legend in pixels. Any elements which fall outside this bound will not be rendered.

Example:

// Set the legend to be 100 pixels high
myLegend.height = 100;

dimple.legend.horizontalAlign: Accepted values are "left" and "right". This sets the horizontal positioning of the elements within the bounds defined. This does not affect individual legend entries, which will always render with the key on the left and the text on the right. As all elements are sized to the widest, the left edges of each element will always align even if this is set to right.

Example:

// Align the right edge of the legend to the x + width
myLegend.horizontalAlign = "right";

dimple.legend.series: One or more series to include in the legend. By default all chart series will be included, however this allows you to pick particular ones. If interacting directly with the property an array must be passed.

Example:

// Align the right edge of the legend to the x + width
myLegend.series = [myFirstSeries, mySecondSeries];

dimple.legend.shapes: Once a legend is rendered via the chart's draw method, this will contain the svg shapes allowing further manipulation with standard javascript or d3.

Example:

// Change the legend font
var myLegend = myChart.addLegend(10, 10, 300, 200);
myChart.draw();
// Resize fonts	
myLegend.shapes.selectAll("text").style("font-size", "12px");

dimple.legend.width: The width in pixels of the legend's render area. Elements in the legend will wrap if their width exceeds this bound.

Example:

// Set the legend to be 200 pixels wide
myLegend.width = 200;

dimple.legend.x: The x co-ordinate in pixels for the upper left hand corner of the legend's render area. If horizontalAlign is set to "left" the legend entries will align to this co-ordinate.

Example:

// Set the legend to render 10 pixels from the left edge of the svg
myLegend.x = 10;

dimple.legend.y: The y co-ordinate in pixels for the upper left hand corner of the legend's render area.

Example:

// Set the legend to render 10 pixels from the top edge of the svg
myLegend.y = 10;

dimple.legend.horizontalPadding: The horizontal distance between legend entries. Basically a rightPadding if the horizontalAlign property is set to left and a leftPadding if the horizontalAlign property is set to right.

Example:

// Increase the horizontal distance between legend entries to 30 pixels
myLegend.horizontalPadding = 30;

dimple.legend.verticalPadding: The vertical distance between legend entries. Basically a bottomPadding, but named differently to be consistent with the horizontalPadding property.

Example:

// Increase the vertical distance between legend entries to 10 pixels
myLegend.verticalPadding = 10;
Add a custom footer
Add a custom sidebar
Clone this wiki locally