com.jidesoft.chart
Class Legend

java.lang.Object
  java.awt.Component
      java.awt.Container
          javax.swing.JComponent
              javax.swing.JPanel
                  com.jidesoft.chart.Legend

All Implemented Interfaces:

Drawable, Frontable, ImageObserver, MenuContainer, Serializable, Accessible

public class Legend
extends JPanel
implements Drawable, Frontable

A graphical component to display a legend corresponding to a Chart. Usually a Legend is generated as one entry per ChartModel displayed in the Chart, but sometimes, such as when displaying a pie chart, it is more useful to display a legend item for every point in a model. To use this mode, set the generateFromPoints property to be true. (See the comments on setGenerateFromPoints() for more details on how to name the items in the legend.)

Author:

Simon White (swhite@catalysoft.com)

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javax.swing.JPanel

JPanel.AccessibleJPanel

Nested classes/interfaces inherited from class javax.swing.JComponent

JComponent.AccessibleJComponent

Nested classes/interfaces inherited from class java.awt.Container

Container.AccessibleAWTContainer

Nested classes/interfaces inherited from class java.awt.Component

Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy

Field Summary

static int	CENTER
static int	LEADING
static int	LEFT
static String	PROPERTY_AT_FRONT
static String	PROPERTY_COLUMNS
static String	PROPERTY_GENERATE_FROM_POINTS
static String	PROPERTY_KEY_LABEL_GAP
static String	PROPERTY_LABEL_COLOR
static String	PROPERTY_LEGEND_BACKGROUND
static String	PROPERTY_ORDER_REVERSED
static String	PROPERTY_ROLLOVER_MODEL
static String	PROPERTY_TITLE
static String	PROPERTY_TITLE_COLOR
static String	PROPERTY_TITLE_LABEL
static int	RIGHT
static int	TRAILING

Fields inherited from class javax.swing.JComponent

accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

Legend()
Create a Legend object.

Legend(boolean wrap, int alignment)

Legend(Chart chart)
Create a Legend from the supplied chart and using 1 column for the layout of the entries

Legend(Chart chart, boolean wrap)
Create a Legend as a row of items that optionally wrap around when there is not enough space

Legend(Chart chart, boolean wrap, int alignment)
Create a Legend as a row of items.

Legend(Chart chart, int cols)
Create a Legend from the supplied chart and using the supplied number of columns

Method Summary

void	addChart(Chart chart) Add a chart to the legend; i.e.
void	addExcludedModels(ChartModel... models) Exclude the supplied models from the Legend
void	addExcludedPoints(Chartable... points) Exclude the supplied points from the Legend (when using generateFromPoints)
Legend	addIncludedModel(ChartModel model)
Legend	addLegendItem(LegendItem item)
void	clear() Clear references to all charts from this legend object.
void	clearExcludedModels() Empty out the set of excluded models
void	clearExcludedPoints() Empty out the set of excluded points
protected JLabel	createLegendLabel(Chartable chartable)
protected JLabel	createLegendLabel(ChartModel model)
protected JLabel	createLegendLabel(String labelString)
protected com.jidesoft.chart.LegendPair	createLegendPair(LegendItem legendItem, JLabel label)
protected JLabel	createLegendTitle(String titleString)
protected LegendItem	createModelLegendItem(ChartModel model, Chart chart)
protected LegendItem	createPointLegendItem(Chartable chartable, ChartModel model, Chart chart)
void	draw(Graphics g) By implementing the Drawable interface, it makes it possible for a Legend to be added to be displayed within a chart rather than just next to it.
int	getKeyLabelGap() Returns the pixel gap between each graphical key item and its label in the legend
Color	getLabelColor() Returns the color used for the labels in the legend
Paint	getLegendBackground() Returns the Paint used for the legend background.
String	getTitle() Returns the title of the legend
Color	getTitleColor() Returns the color used for the title in the legend
JLabel	getTitleLabel() Returns the title label as a component
boolean	isAtFront() Should the Legend be drawn in front of the ChartModels when used as a Drawable?
boolean	isGenerateFromPoints() Returns whether the legend is generated based on points.
boolean	isOrderReversed() Returns whether the order of the elements is reversed or the same as the order in which they were added to the chart.
void	paintComponent(Graphics g)
void	removeChart(Chart chart) Remove the models contained by the supplied chart from the legend
void	removeExcludedModels(ChartModel... models) Remove the supplied models from the set of models that have been excluded from the Legend
void	removeExcludedPoints(Chartable... points) Remove the supplied points from the set of points to exclude from the Legend
Legend	removeIncludedModel(ChartModel model)
Legend	removeLegendItem(LegendItem item)
void	setAtFront(boolean atFront) Specify whether the Legend should appear in front of the chart models when added as a Drawable to the chart.
void	setBorder(Border border) This method modifies the default behaviour of JComponent.
void	setColumns(int columns) Set the number of columns to use for the items in the legend.
void	setFont(Font font) Sets the font to use for the Legend items
void	setGenerateFromPoints(boolean generateFromPoints) By default a Legend will be generated as one entry per chart model that is displayed on the chart.
void	setKeyLabelGap(int keyLabelGap) Specify the gap in pixels between each graphical key item and its label in the legend
void	setLabelColor(Color labelColor) Specify the color to use for the labels in the legend
void	setLegendBackground(Paint background) Specifies the Paint to use for the background of the Legend.
void	setOrderReversed(boolean orderReversed) Specify whether the order of iterating through the models should be reversed when generating the legend.
void	setTitle(String title) Set the title to use for this legend.
void	setTitleColor(Color titleColor) Specifies the color to use for the title of the legend
void	setTitleLabel(JLabel titleLabel) Sets the title for this legend
protected void	updateLegend() Recreate the legend object, taking account of the specified number of columns

Methods inherited from class javax.swing.JPanel

getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI

Methods inherited from class javax.swing.JComponent

addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintImmediately, paintImmediately, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update

Methods inherited from class java.awt.Container

add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

LEFT

public static final int LEFT

See Also:

Constant Field Values

CENTER

public static final int CENTER

See Also:

Constant Field Values

LEADING

public static final int LEADING

See Also:

Constant Field Values

RIGHT

public static final int RIGHT

See Also:

Constant Field Values

TRAILING

public static final int TRAILING

See Also:

Constant Field Values

PROPERTY_GENERATE_FROM_POINTS

public static final String PROPERTY_GENERATE_FROM_POINTS

See Also:

Constant Field Values

PROPERTY_TITLE

public static final String PROPERTY_TITLE

See Also:

Constant Field Values

PROPERTY_TITLE_COLOR

public static final String PROPERTY_TITLE_COLOR

See Also:

Constant Field Values

PROPERTY_COLUMNS

public static final String PROPERTY_COLUMNS

See Also:

Constant Field Values

PROPERTY_KEY_LABEL_GAP

public static final String PROPERTY_KEY_LABEL_GAP

See Also:

Constant Field Values

PROPERTY_LABEL_COLOR

public static final String PROPERTY_LABEL_COLOR

See Also:

Constant Field Values

PROPERTY_LEGEND_BACKGROUND

public static final String PROPERTY_LEGEND_BACKGROUND

See Also:

Constant Field Values

PROPERTY_ORDER_REVERSED

public static final String PROPERTY_ORDER_REVERSED

See Also:

Constant Field Values

PROPERTY_AT_FRONT

public static final String PROPERTY_AT_FRONT

See Also:

Constant Field Values

PROPERTY_TITLE_LABEL

public static final String PROPERTY_TITLE_LABEL

See Also:

Constant Field Values

PROPERTY_ROLLOVER_MODEL

public static final String PROPERTY_ROLLOVER_MODEL

See Also:

Constant Field Values

Constructor Detail

Legend

public Legend()

Create a Legend object. You will need to call addChart() to specify the chart(s) to which the legend applies.

Legend

public Legend(boolean wrap,
              int alignment)

Legend

public Legend(Chart chart)

Create a Legend from the supplied chart and using 1 column for the layout of the entries

Parameters:

chart - the chart for which to create a legend

Legend

public Legend(Chart chart,
              boolean wrap)

Create a Legend as a row of items that optionally wrap around when there is not enough space

Parameters:

chart - the chart from which the legend items are to be taken

wrap - whether to allow legend items to wrap around to the next row

Legend

public Legend(Chart chart,
              boolean wrap,
              int alignment)

Create a Legend as a row of items. If wrap is set to true, then the alignment parameter is used in the layout.

Parameters:

chart - the chart from which the legend items are to be taken

wrap - whether to allow legend items to wrap around to the next row

alignment - when wrap is true, the horizontal alignment used for legend items. One of LEFT, CENTER, RIGHT, LEADING or TRAILING.

See Also:

LEFT, RIGHT, CENTER, LEADING, TRAILING

Legend

public Legend(Chart chart,
              int cols)

Create a Legend from the supplied chart and using the supplied number of columns

Parameters:

chart - the chart for which to create a legend

cols - the number of columns to use in the layout of the legend

Method Detail

getKeyLabelGap

public int getKeyLabelGap()

Returns the pixel gap between each graphical key item and its label in the legend

Returns:

the pixel gap between each graphical key item and its label in the legend

setKeyLabelGap

public void setKeyLabelGap(int keyLabelGap)

Specify the gap in pixels between each graphical key item and its label in the legend

Parameters:

keyLabelGap - the gap in pixels

getLegendBackground

public Paint getLegendBackground()

Returns the Paint used for the legend background. If the legendBackground property has never been set, the method returns the Color that is also returned by getBackground()

Returns:

the Paint used for the Legend background.

setLegendBackground

public void setLegendBackground(Paint background)

Specifies the Paint to use for the background of the Legend. For example, you can use this method to set a Gradient fill.

Parameters:

background - the Paint to use for the background of the Legend

getLabelColor

public Color getLabelColor()

Returns the color used for the labels in the legend

Returns:

the color used for the labels in the legend

setLabelColor

public void setLabelColor(Color labelColor)

Specify the color to use for the labels in the legend

Parameters:

labelColor - the color to use for the legend labels

getTitleColor

public Color getTitleColor()

Returns the color used for the title in the legend

Returns:

the color used in the title of the legend

setTitleColor

public void setTitleColor(Color titleColor)

Specifies the color to use for the title of the legend

Parameters:

titleColor - the color to use in the title of the legend

addExcludedModels

public void addExcludedModels(ChartModel... models)

Exclude the supplied models from the Legend

Parameters:

models - the models to exclude from the Legend

removeExcludedModels

public void removeExcludedModels(ChartModel... models)

Remove the supplied models from the set of models that have been excluded from the Legend

Parameters:

models - the models to remove the excluded set

clearExcludedModels

public void clearExcludedModels()

Empty out the set of excluded models

addIncludedModel

public Legend addIncludedModel(ChartModel model)

removeIncludedModel

public Legend removeIncludedModel(ChartModel model)

addLegendItem

public Legend addLegendItem(LegendItem item)

removeLegendItem

public Legend removeLegendItem(LegendItem item)

addExcludedPoints

public void addExcludedPoints(Chartable... points)

Exclude the supplied points from the Legend (when using generateFromPoints)

Parameters:

points - the points to exclude from the Legend

removeExcludedPoints

public void removeExcludedPoints(Chartable... points)

Remove the supplied points from the set of points to exclude from the Legend

Parameters:

points - the points to reinstate as Legend items

clearExcludedPoints

public void clearExcludedPoints()

Empty out the set of excluded points

setBorder

public void setBorder(Border border)

This method modifies the default behaviour of JComponent. If the legend does not have any items to display, then the border becomes null. This prevents an embarrassing dot from appearing next to a chart that doesn't have any data yet. You still call this method to set the border, but it will not appear if the chart does not have any data to display.

Overrides:

setBorder in class JComponent

addChart

public void addChart(Chart chart)

Add a chart to the legend; i.e. allow the legend component to extract the chart models and their styles from the supplied chart object and add them to the legend.

Parameters:

chart - the chart to add to the Legend

removeChart

public void removeChart(Chart chart)

Remove the models contained by the supplied chart from the legend

Parameters:

chart - the chart for which the models should be removed

setColumns

public void setColumns(int columns)

Set the number of columns to use for the items in the legend. If you specify the number of columns as 0, then there will be as many columns as there are items to display.

Parameters:

columns - the number of columns to use for items in the legend

clear

public void clear()

Clear references to all charts from this legend object.

getTitle

public String getTitle()

Returns the title of the legend

Returns:

the title of the legend

setTitle

public void setTitle(String title)

Set the title to use for this legend. Internally, this creates a JLabel. To customize the appearance of the label, you can either retrieve it using getTitleLabel() and then modify it; or create the label yourself and supply it using the setTitleLabel() method.

Parameters:

title - the title to use for the legend

See Also:

getTitleLabel(), setTitleLabel(JLabel)

getTitleLabel

public JLabel getTitleLabel()

Returns the title label as a component

Returns:

the title label

setTitleLabel

public void setTitleLabel(JLabel titleLabel)

Sets the title for this legend

Parameters:

titleLabel - the ready-made JLabel to use for the title

isGenerateFromPoints

public boolean isGenerateFromPoints()

Returns whether the legend is generated based on points.

Returns:

whether the legend is generated based on the points of a chart model.

setGenerateFromPoints

public void setGenerateFromPoints(boolean generateFromPoints)

By default a Legend will be generated as one entry per chart model that is displayed on the chart. Sometimes, however, it makes more sense to generate one entry per point; for example for a pie chart, where each segment represents a single point. If you are generating from points on a categorical data set, then the names of the categories are used as the labels in the legend. Otherwise, if the Chartable instances implement the Named interface (like ChartPoint, for instance), then the name is taken from the name property of the object.

Parameters:

generateFromPoints - whether to generate the legend based on points

isOrderReversed

public boolean isOrderReversed()

Returns whether the order of the elements is reversed or the same as the order in which they were added to the chart.

Returns:

whether the order is reversed

setOrderReversed

public void setOrderReversed(boolean orderReversed)

Specify whether the order of iterating through the models should be reversed when generating the legend. By default, the order is the order in which the models were added to the Chart.

Parameters:

orderReversed - whether to reverse the order

setFont

public void setFont(Font font)

Sets the font to use for the Legend items

Overrides:

setFont in class JComponent

Parameters:

font - the font to use for the Legend items

updateLegend

protected void updateLegend()

Recreate the legend object, taking account of the specified number of columns

createPointLegendItem

protected LegendItem createPointLegendItem(Chartable chartable,
                                           ChartModel model,
                                           Chart chart)

createModelLegendItem

protected LegendItem createModelLegendItem(ChartModel model,
                                           Chart chart)

createLegendPair

protected com.jidesoft.chart.LegendPair createLegendPair(LegendItem legendItem,
                                                         JLabel label)

createLegendLabel

protected JLabel createLegendLabel(Chartable chartable)

createLegendLabel

protected JLabel createLegendLabel(ChartModel model)

createLegendLabel

protected JLabel createLegendLabel(String labelString)

createLegendTitle

protected JLabel createLegendTitle(String titleString)

isAtFront

public boolean isAtFront()

Should the Legend be drawn in front of the ChartModels when used as a Drawable?

Specified by:

isAtFront in interface Frontable

Returns:

whether the Legend should be drawn in front of the ChartModels

setAtFront

public void setAtFront(boolean atFront)

Specify whether the Legend should appear in front of the chart models when added as a Drawable to the chart.

Specified by:

setAtFront in interface Frontable

Parameters:

atFront - whether the object is to be shown in front of ChartModels.

draw

public void draw(Graphics g)

By implementing the Drawable interface, it makes it possible for a Legend to be added to be displayed within a chart rather than just next to it.

Specified by:

draw in interface Drawable

Parameters:

g - the Graphics context onto which the legend should be drawn

paintComponent

public void paintComponent(Graphics g)

Overrides:

paintComponent in class JComponent