By default, the chart is rendered with the legend activated, positioned on the right side of the chart and with a transparent (i.e. invisible) legend box:
The legend shows the value symbols used in the chart and the names of the data series.
To deactivate the legend, use
new ac.ACBarChartBuilder() // ... .setShowLegend(false) // ...
If the legend is deactivated, the chart will use the space no longer used for the legend.
Use the following commands to add text to the legend, either as a header (above the data series) or below the data series:
// ... .addLegendText("This appears above the legend.", ac.LegendTextPosition.TOP) // ...
and / or
.addLegendText("This appears below the legend.", ac.LegendTextPosition.BOTTOM)
(The text of the legend series is currently always identical with the name of the data series.)
You can use the usual HTML tags that are supported in ArcadiaCharts (see below), for example <br> for line breaks. The following example shows what the legend might look like:
As you can see in the screenshot, the fonts for legend header, text and footer can be edited separately. The respective font styles can be defined in the theme file. The style names are:
For example, to change the font of the legend header in the above example, the following font definition was used:
<variable type="style" name="LegendHeader"> <fontFamily>Bebas</fontFamily> <color>$WHITE</color> </variable>
For more information please refer to the Fonts section of the Reference Manual.
The padding in the legend can be modified with the PADDING_LEGEND_HEADER and PADDING_LEGEND_FOOTER theme variables (see Using themes for more details).
As elsewhere in arcadiaCharts, you can use the following tags to tag your custom legend text:
<strong>
<em>
<b>
<i>
<h1>, <h2>, <h3>,
<small>
<pre>
<br>
By default, the legend appears to the right of the chart. You can use
// ... .setLegendPosition(ac.LegendPosition.LEFT) .setLegendPosition(ac.LegendPosition.RIGHT) // ...
to make the legend appear to the left or the right of the chart. The example below shows a chart with the legend at the left side.
Within the space assigned to the legend, the text may be aligned with the top or the bottom of the legend box. So, using this code:
// ... .setStringVariable("LEGEND_VERTICAL_ALIGNMENT", "BOTTOM") // ...
would result in the following legend alignment:
(“BOTTOM” or “TOP” may be used, with “TOP” being the default.
A variety of attributes concerning the layout of the legend can be modified in the theme file (for more information on how to work with the theme file, please read the Reference Manual page on Using the theme and in particular the legend chartoptions: <legend>. Use the following chart options / attributes to change the appearance of the legend:
Attribute name | Description | Usage example |
---|---|---|
LEGEND_WIDTH | Change the legend width in pixels. If you do not use this option, the legend will have the width and height required to display all text. | <chartoptions> <legend> <width>250</width> </legend> </chartoptions> |
LEGEND_HEIGHT | Change the legend height in pixels. | <chartoptions> <legend> <height>250</width> </legend> </chartoptions> |
LEGEND_PADDING | Changes the padding (distance) between the legend's frame and the text of the legend (on all sides). Default: 10 px | <chartoptions> <legend> <padding>10</padding> </legend> </chartoptions> |
LEGEND_PADDING_TOP, LEGEND_PADDING_BOTTOM, LEGEND_PADDING_RIGHT, LEGEND_PADDING_LEFT | Changes the padding (distance) between the respective side of the legend's frame and the text of the legend. | <chartoptions> <legend> <paddingLeft>10</paddingLeft> </legend> </chartoptions> |
LEGEND_AXIS_PADDING | Changes the padding (distance) between the legend and the axis. Default: 5% of the chart width. | <variables> <variable name="LEGEND_AXIS_PADDING" type="size" value="20" /> </variables> |
As always, you can also use setSizeVariable(“LEGEND_HEIGHT”,”150”)
to change any of the above settings directly from the chart code, rather than in the theme.
The legend can be displayed with a legend box in the background. In the theme file, use the chart option
<legend> <background> <!-- your settings here --> </background> </legend>
to change these settings.
Some of the options that can be configured with the legend/background chart option:
<color>
)<style>
, <glossyEffect>
)<borderRoundness>
, <borderWidth>
, <borderColor>
, <borderStyle>
For a full list of available options and how to use them, please consult the documentation page in the <legend> chart option.
Here are some sample legend backgrounds and the respective chart options to illustrate the usage of the <legend><background> chart option:
You can change the symbols for the data series in the legend by using the <legendsymbol> option in the theme file (see Using themes on how to edit the theme file). (Click here for the full documentation of the <legendsymbol> option.) For example,
<?xml version="1.0" encoding="UTF-8"?> <theme> <!-- ... --> <chartoptions> <!-- ... --> <legendSymbol> <type>circle</type> <style>plain</style> <size>11</size> <shadow>true</shadow> <donutSize>6</donutSize> <donutColor>$RED</donutColor> </legendSymbol> <!-- ... --> </chartoptions> <!-- ... --> </theme>
would change the value symbol as follows:
Available options for <type> are circle
, square
, triangle
, diamond
, or line
.
Available options for <style> are plain
, beveled
, or 3d
.
For full details on the available options, please refer to the chart options: ValueSymbol documentation.
Background images can be displayed behind the legend. For more information, please read the legend section in the page on "Using Images in your Chart".