User LegendBox

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.


// Show the user legend box
chart1.setUserLegendBox(true);
// Hide the user legend box
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:


// Dock the user legend box on the right
chart1.getUserLegendBoxObj().setDocked(Docked.RIGHT);
// Make the user legend box visible
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:


// define the first user legend key
UserLegendBoxItem item1 =
chart1.getUserLegendBoxObj().getItem(0);
item1.setLabel("Warning");
item1.setColor(java.awt.Color.red);
item1.setMarkerShape(MarkerShape.RECT);
item1.setBorderEffect(BorderEffect.NONE);
// define the second user legend key
UserLegendBoxItem item2 =
chart1.getUserLegendBoxObj().getItem(1);
item2.setLabel("Caution");
item2.setColor(java.awt.Color.yellow);
item2.setMarkerShape(MarkerShape.RECT);
item2.setBorderEffect(BorderEffect.NONE);
// define the third user legend key
UserLegendBoxItem item3 =
chart1.getUserLegendBoxObj().getItem(2);
item3.setLabel("Normal");
item3.setColor(java.awt.Color.green);
item3.setMarkerShape(MarkerShape.RECT);
item3.setBorderEffect(BorderEffect.NONE);
// Show the user legend box in the chart
chart1.setUserLegendBox(true);