ilog.views.chart
Class IlvLegend

ilog.views.chart.IlvLegend

public class IlvLegend

This class allows you to define a legend that can be added to a chart.

An IlvLegend object is associated with a unique chart (you cannot share a legend among several charts). Each time a change occurs on the chart, the legend is automatically notified and updates itself accordingly. Usually, items are automatically added to the legend that invokes the IlvChartRenderer.createLegendItems method of each renderer of the chart. In this case, items are by default instances of IlvRendererLegendItem.
You may also wish to add items that are not associated with any renderer (for example for information purpose or when an annotation has been added to the chart). In this case, you should create IlvIconLegendItem objects and add them explicitly to the legend.
Since legend items inherit from JComponent, they are added to the legend using the Container.add() method and can be retrieved using the standard AWT Container methods (get(), getAll()).

The IlvLegend class inherits from JComponent, it can thus be added to any Container, in particular to an IlvChart instance (Note that this is the only component that can be added directly to the chart. See IlvChart for more information.) When added to a chart, a legend can either be placed around the chart area or within it, depending on its constraints (see IlvChartLayout.) It can also have a dockable behavior (click on its border and drag it around) if its movable property is set to true.

By default, an IlvLegend uses a custom layout manager (instance of IlvLegendLayout) to dynamically lay out the items depending on the current legend position. You can change this default layout by using the layout manager of your choice invoking the setLayout() method.
A legend may also generate an event to all the registered listeners each time an item is clicked. This behavior is associated with the interactive property.

Note: So that the auto-transparency capability of the IlvLegend class works properly with the Swing RepaintManager, the IlvLegend class does not use the opaque property to know whether it should fill its background or not. Instead, a new property paintingBackground (see setPaintingBackground) with the same purpose has been added in JViews 5.0. The default value is true, which means that the legend paints its background by default. Note that this behavior is different from the IlvChart behavior that is not filled by default.

Here is a picture showing the different parameters and components of a legend :

CSS example:

chartLegend {
class : "ilog.views.chart.IlvLegend";
antiAliasing : "false";
antiAliasingText : "false";
background : "green";
border : "@#emptyBorder";
floatingLayoutDirection : "2";
followChartResize : "false";
font : "sansserif-BOLD-8";
foreground : "green";
interactive : "false";
location : "0,0";
movable : "false";
opaque : "false";
paintingBackground : "false";
symbolSize : "0,0";
symbolTextSpacing : "2";
title : "<value>";
toolTipText : "<value>";
}

Property Summary

boolean	antiAliasing Sets the antiAliasing property.
boolean	antiAliasingText Sets the antiAliasingText property.
java.awt.Color	background Sets the background color of this component.
Border	border Sets the border of this component.
java.lang.String	class Creates a new IlvLegend object.
int	floatingLayoutDirection Sets the flow direction of the floating layout.
boolean	followChartResize Sets whether the legend location is updated on a chart resize event.
java.awt.Font	font Sets the font for this component.
java.awt.Color	foreground Sets the foreground color of this component.
boolean	interactive Sets the interactive mode property.
java.awt.Point	location Moves the legend to a new location.
boolean	movable Sets the legend movable property.
boolean	opaque If true the component paints every pixel within its bounds.
boolean	paintingBackground Sets the paintingBackground property.
Dimension	symbolSize Sets the size of the items symbols.
int	symbolTextSpacing Sets the space (in pixels) between the symbol and the text of a legend item.
java.lang.String	title Sets the legend title.
java.lang.String	toolTipText Registers the text to display in a tool tip.

Property Detail

class

public java.lang.String class

Creates a new IlvLegend object. By default, a legend is movable and uses a TitledBorder.

CSS example: class : "ilog.views.chart.IlvLegend";

antiAliasing

public boolean antiAliasing

Sets the antiAliasing property. When this property is set to true, all drawings in the legend component and subcomponents are antialiased. This property does not affect text. To toggle the anti-aliasing of text, use the setAntiAliasingText method. The default value of this property is false.

CSS example: antiAliasing : "false";

antiAliasingText

public boolean antiAliasingText

Sets the antiAliasingText property. When this property is set to true, all text drawings in the legend component and subcomponents are antialiased. This property only affects text. To toggle the anti-aliasing of other drawings, use the setAntiAliasing method. The default value of this property is false.

CSS example: antiAliasingText : "false";

background

public java.awt.Color background

Sets the background color of this component.

CSS example: background : "green";

A color can either be a string representing a color or else an octal or hexadecimal string that starts with the character "#" or else a comma separated "RGB" value where the integer values are in the range 0..255.

border

public Border border

Sets the border of this component. The Border object is responsible for defining the insets for the component (overriding any insets set directly on the component) and for optionally rendering any border decorations within the bounds of those insets. Borders should be used (rather than insets) for creating both decorative and non-decorative (such as margins and padding) regions for a swing component. Compound borders can be used to nest multiple borders within a single component. This is a bound property.

CSS example: border : "@#emptyBorder";

See implementing class EmptyBorder for an example of implementing a border.

floatingLayoutDirection

public int floatingLayoutDirection

Sets the flow direction of the floating layout. This method is meaningful only if the layout manager is an IlvLegendLayout instance.

CSS example: floatingLayoutDirection : "2";

followChartResize

public boolean followChartResize

Sets whether the legend location is updated on a chart resize event. When set to true, the legend position is updated when its chart is resized so that its position relative to the chart does not change. When set to false, the legend position does not change. The default value is false.

CSS example: followChartResize : "false";

font

public java.awt.Font font

Sets the font for this component.

CSS example: font : "sansserif-BOLD-8";

foreground

public java.awt.Color foreground

Sets the foreground color of this component.

CSS example: foreground : "green";

A color can either be a string representing a color or else an octal or hexadecimal string that starts with the character "#" or else a comma separated "RGB" value where the integer values are in the range 0..255.

interactive

public boolean interactive

Sets the interactive mode property. If mode is true, an event is fired each time the user clicks on an item.

CSS example: interactive : "false";

location

public java.awt.Point location

Moves the legend to a new location. If the legend is added to a chart, the specified location is only used if the position of the legend is IlvChartLayout.ABSOLUTE.

CSS example: location : "0,0";

movable

public boolean movable

Sets the legend movable property. If movable is true, the legend can be moved by dragging it anywhere within the chart bounds. If false, the legend is set unmovable.

CSS example: movable : "false";

opaque

public boolean opaque

If true the component paints every pixel within its bounds. Otherwise, the component may not paint some or all of its pixels, allowing the underlying pixels to show through. The default value of this property is false for JComponent. However, the default value for this property on most standard JComponent subclasses (such as JButton and JTree) is look-and-feel dependent.

CSS example: opaque : "false";

paintingBackground

public boolean paintingBackground

Sets the paintingBackground property. If paint is true, the legend fills its background before drawing its items.

CSS example: paintingBackground : "false";

symbolSize

public Dimension symbolSize

Sets the size of the items symbols.

CSS example: symbolSize : "0,0";

symbolTextSpacing

public int symbolTextSpacing

Sets the space (in pixels) between the symbol and the text of a legend item.

CSS example: symbolTextSpacing : "2";

title

public java.lang.String title

Sets the legend title.

CSS example: title : "<value>";

toolTipText

public java.lang.String toolTipText

Registers the text to display in a tool tip. The text displays when the cursor lingers over the component.

CSS example: toolTipText : "<value>";