In most cases, the legend box and series legend box provide
the necessary information that users need to successfully
understand a chart. At other times, there is a void where the
legend box and series legend box cannot provide this to the
end user. The user legend box allows you as the developer
to create legends to provide essential information about a
chart that normally cannot be relayed using the series legend
box or the value legend box.
A user legend box is very useful in many situations, one
of which is when the number of colors in a chart is not related
to the number of series in a chart. For example, when a Contour
gallery type chart is used, colors in the chart represent
intensity of a particular condition. By enabling the user
legend box, you can define legend keys to help an end user
decipher exactly what the chart is representing.
Another situation where the user legend can be very useful
is when per point attributes are assigned to a chart. For
example, all red points may represent values over 50, where
all blue points represent values under 50. A user legend box
could be used to make the user understand this relation more
clearly. User legends are also a great way to define or explain
abbreviations or symbols that are included in financial charting
applications.
Enabling the User LegendBox
The user legend box is enabled in the same way as both the
series legend box and legend box objects. The UserLegendBox
property is a Boolean property, which allows you to show or
hide the user legend box with one line of code.
chart1.setUserLegendBox(true);
chart1.setUserLegendBox(false);
|
Defining the User LegendBox
The beauty of the user legend box is the myriad of information
that may be used to define the legend keys for the chart.
The user legend will allow you to display any information
you wish, however, there is a trade off. In order to populate
the user legend box, every key the
legend will display needs to be defined. To do this, Chart FX offers the UserLegendBoxObj
and Item objects.
The user legend box object and supported properties provide
the mechanism to customize position and style and to define the contents of the user legend. The UserLegendBoxObj
object inherits all the properties from the SerLegBoxObj object
and offers many more.
To dock the user legend box on the right side of the chart,
you could use the following code:
chart1.getUserLegendBoxObj().setDocked(Docked.RIGHT);
chart1.setUserLegendBox(true);
|
The previous code will make the user legend box visible and
docked to the right of the chart. However, there are still
no keys in the legend that describe the chart content.

The Item object is a collection which allows you to create and assign attributes to each key that will exist in the user
legend box. The Item object has several properties that allow
you to relate the configured key to the chart, such as color
or marker shape.
In the sample chart shown, each bar represents the volume of calls into a tech support call center. Each bar has been
assigned a color based on the number of incoming calls for that day. The user legend box has been created to describe what each color represents: Red = Warning, Yellow = Caution, or Green = Normal. The label, color, marker shape, border
effect and border color for each key in the user legend needs to be configured in order to display the desired information.
Below is the code used to create the user legend box of the displayed chart:
UserLegendBoxItem item1 = chart1.getUserLegendBoxObj().getItem(0); item1.setLabel("Warning"); item1.setColor(java.awt.Color.red); item1.setMarkerShape(MarkerShape.RECT); item1.setBorderEffect(BorderEffect.NONE);
UserLegendBoxItem item2 = chart1.getUserLegendBoxObj().getItem(1); item2.setLabel("Caution"); item2.setColor(java.awt.Color.yellow); item2.setMarkerShape(MarkerShape.RECT); item2.setBorderEffect(BorderEffect.NONE);
UserLegendBoxItem item3 = chart1.getUserLegendBoxObj().getItem(2); item3.setLabel("Normal"); item3.setColor(java.awt.Color.green); item3.setMarkerShape(MarkerShape.RECT); item3.setBorderEffect(BorderEffect.NONE);
chart1.setUserLegendBox(true);
|
|