netcharts.pro.common
Class NFLegend

java.lang.Object
  netcharts.pro.common.NFBaseClass
      netcharts.pro.common.NFLegend

All Implemented Interfaces:

java.lang.Cloneable

public class NFLegend
extends NFBaseClass

The NFLegend property describes a chart's legend. The legend object has many options for configuring text, background, layout, and location properties. A typical use of this object is as follows:

        ...
        Font font = new Font("Comic Sans MS", Font.PLAIN, 10);
        NFLegend legend = new NFLegend(new NFLabel("Legend", black, font),
                new NFRegion(Color.gray, NFRegion.RAISED, 2));

        legend.setLocation(NFLegend.BOTTOM);
        legend.setOrientation(NFLegend.HORIZONTAL);

        chart.setLegend(legend);

        ...
  

This would create a horizontal legend at the bottom of the chart that would use the dataset names or (slice labels) as the legend items.

Developers may opt to explicitly specify the legend item symbols and colors by passing in NFLegendItem objects via the setLegendItems or addLegendItem method calls. An example of this usage is shown here:

        ...
        Font font = new Font("Comic Sans MS", Font.PLAIN, 10);
        NFLegend legend = new NFLegend(new NFLabel("Legend", black, font),
                new NFRegion(Color.gray, NFRegion.RAISED, 2));
        legend.addLegendItem(new NFLegendItem("item 1", NFLegendItemSymbol.CROSS, Color.yellow));
        legend.addLegendItem(new NFLegendItem("item 2", NFLegendItemSymbol.DIAMOND, Color.blue));
        legend.addLegendItem(new NFLegendItem("item 3", NFLegendItemSymbol.SQUARE, Color.red));
        legend.addLegendItem(new NFLegendItem("", NFLegendItemSymbol.NONE, Color.white)); // space
        legend.addLegendItem(new NFLegendItem("item 4", NFLegendItemSymbol.CIRCLE, Color.green));


        chart.setLegend(legend);

        ...
  

This would create a vertically oriented legend at the right side of the chart (default) The legend would have a gap between the first three items and the last.

Field Summary

static int	BOTTOM Bottom legend location
static int	BOTTOMLEFT Bottom left legend location
static int	BOTTOMRIGHT Bottom right legend location
static int	CENTER Center legend location.
static int	HORIZONTAL Horizontal legend orientation.
static int	LEFT Left legend location
static java.util.Hashtable	legendItemOrderMap legendItemOrderMap hashtable
static java.util.Hashtable	legendOrientationMap legendOrientationMap hashtable
static java.util.Hashtable	legendPositionMap legendPositionMap hashtable
static java.util.Hashtable	legendSymbolPositionMap legendSymbolPositionMap hashtable
static int	RIGHT Right legend location
static int	SETDISPLAYORDER Inverse data set legend item order
static int	SETNAMEORDER Data set legend item order
static int	TOP Top legend location
static int	TOPLEFT Top left legend location.
static int	TOPRIGHT Top right legend location
static int	VERTICAL Vertical legend orientation.

Constructor Summary

NFLegend()
Constructs a default legend object

NFLegend(java.util.Hashtable state)
Constructs a legend using CDL parameters

NFLegend(NFLabel label, NFRegion region)
Constructs a legend object using the given NFLabel text object and background NFRegion object.

Method Summary

void	addActiveLabel(NFActiveLabel activeLabel) Add an active label item to the list of active labels.
void	addLegendItem(NFLegendItem legendItem) Add a legend item to the list of legend items.
void	addLegendLabel(java.lang.String label) Add a legend label to the list of legend labels.
java.lang.Object	clone() Clone this legend.
NFVector	getActiveLabels() Returns the list of active labels for this legend.
NFAxisMap	getAxisMap() Returns the axis map for this legend
java.lang.String	getCDLItemBorder() Generate CDL parameters representing outlines for all the legend item symbols.
java.lang.String	getCDLLegendLayout() Generate CDL parameters representing the legend layout
java.lang.String	getCDLMaxSize() Generate CDL parameters representing the legend max size
java.lang.String	getCDLSymbolPosition() Generate CDL parameters representing the legend item symbol position relative to the label.
java.util.Vector	getCDLVector() NFLegend is a compound object representing multiple CDL parameters.
int	getColumns() Get the number of columns to be used when laying out legend items.
java.awt.Color	getFillColor() Gets the legend fill (background) color.
java.awt.Font	getFont() Gets the legend text font or null if not set.
NFLine	getItemBorder() Returns the line representing the border outlines of the legend item symbols.
int	getItemOrder() Get the order legend items should render.
int	getJustify() Get legend justify.
NFLabel	getLabel() Gets the NFLabel object (text characteristics) object for this legend.
boolean	getLegendEnabled() Returns the state of the legend
NFVector	getLegendItems() Get vector of NFLegendItems.
NFVector	getLegendLabels() Get vector of legend labels.
int	getLocation() Get the legend's location
java.awt.Dimension	getMaxSize() Get legend max size.
int	getOrientation() Get the legend's orientation
NFPoint	getPosition() Get legend position
NFRegion	getRegion() Gets the NFRegion object (background characteristics) object for this legend.
int	getSymbolPosition() Get the legend item symbol's position relative to the label.
java.lang.String	getText() Gets the title text for the legend.
int	getTextAngle() Gets the text angle for the legend items.
java.awt.Color	getTextColor() Gets the color of the legend text
void	setActiveLabels(NFVector activeLabels) Sets a vector of NFActiveLabels for this legend object.
void	setAxisMap(NFAxisMap axisMap) Set the axis map for this legend.
void	setCDLItemBorder(java.lang.Object cdl) Configures the legend item symbol outlines from a CDL parameter representation.
void	setCDLLegendLayout(java.lang.String s) Configures the legend layout attributes from a CDL parameter representation.
void	setCDLMaxSize(java.lang.String cdl) Configures the legend max size attributes from a CDL parameter representation.
void	setCDLSymbolPosition(java.lang.String cdl) Configures the legend symbol position attribute from a CDL parameter representation.
void	setColumns(int columns) Set the number of columns to be used when laying out legend items.
void	setFillColor(java.awt.Color fillColor) Sets the legend fill (background) color.
void	setFont(java.awt.Font font) Sets the font for the legend text.
void	setItemBorder(NFLine legendItemBorder) Explicitly define the border outline of all legend item symbols.
void	setItemOrder(int itemOrder) Set the order in which the legend items appear.
void	setJustify(int justify) Set legend justification.
void	setLabel(NFLabel label) Explicitly sets the NFLabel (text characteristics) object for this legend.
void	setLegendEnabled(boolean enabled) Enables or disables the legend
void	setLegendItems(NFVector legendItems) Explicitly set legend items.
void	setLegendLabels(NFVector labels) Explicitly set legend labels.
void	setLocation(int location) Set the legend's location using a constant.
void	setMaxSize(java.awt.Dimension maxSize) Set legend max size - performs mandatory clip if legend items become too large.
void	setOrientation(int orientation) Set the legend's orientation using a constant.
void	setPosition(NFPoint position) Set legend position.
void	setRegion(NFRegion region) Explicitly sets the NFRegion (background characteristics) object for this legend.
void	setSymbolPosition(int symbolPosition) Set the position all legend item symbols should appear relative to the legend item labels.
void	setText(java.lang.String text) Sets the title for the legend.
void	setTextAngle(int textAngle) Sets text angle for the legend items.
void	setTextColor(java.awt.Color color) Sets the color of the legend text.

Methods inherited from class netcharts.pro.common.NFBaseClass

getModified, getUserObject, setModified, setUserObject

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VERTICAL

public static final int VERTICAL

Vertical legend orientation. Causes the legend layout to be vertically oriented.

HORIZONTAL

public static final int HORIZONTAL

Horizontal legend orientation. Causes the legend layout to be horizontally oriented.

TOPLEFT

public static final int TOPLEFT

Top left legend location.

TOP

public static final int TOP

Top legend location

TOPRIGHT

public static final int TOPRIGHT

Top right legend location

LEFT

public static final int LEFT

Left legend location

CENTER

public static final int CENTER

Center legend location. When location is CENTER, The legend may be placed anywhere within the data area defined by axis parameters.

RIGHT

public static final int RIGHT

Right legend location

BOTTOMLEFT

public static final int BOTTOMLEFT

Bottom left legend location

BOTTOM

public static final int BOTTOM

Bottom legend location

BOTTOMRIGHT

public static final int BOTTOMRIGHT

Bottom right legend location

SETNAMEORDER

public static final int SETNAMEORDER

Data set legend item order

SETDISPLAYORDER

public static final int SETDISPLAYORDER

Inverse data set legend item order

legendOrientationMap

public static java.util.Hashtable legendOrientationMap

legendOrientationMap hashtable

legendPositionMap

public static java.util.Hashtable legendPositionMap

legendPositionMap hashtable

legendItemOrderMap

public static java.util.Hashtable legendItemOrderMap

legendItemOrderMap hashtable

legendSymbolPositionMap

public static java.util.Hashtable legendSymbolPositionMap

legendSymbolPositionMap hashtable

Constructor Detail

NFLegend

public NFLegend()

Constructs a default legend object

NFLegend

public NFLegend(NFLabel label,
                NFRegion region)

Constructs a legend object using the given NFLabel text object and background NFRegion object.

Parameters:

label - The label object containing the text style and legend title.

region - The region object describing the legend background.

NFLegend

public NFLegend(java.util.Hashtable state)

Constructs a legend using CDL parameters

Parameters:

state - Hashtable containing CDL parameters.

Method Detail

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Clone this legend. Performs a deep copy of this object.

Overrides:

clone in class NFBaseClass

Returns:

copy of this object

Throws:

java.lang.CloneNotSupportedException

setOrientation

public void setOrientation(int orientation)

Set the legend's orientation using a constant. Either VERTICAL or HORIZONTAL. By default, the legend will be vertically oriented. If the value passed is not a valid orientation, an IllegalArgumentException will be thrown.

Parameters:

orientation - The orientation type.

getOrientation

public int getOrientation()

Get the legend's orientation

Returns:

A constant representing the orientation. Either VERTICAL (default) or HORIZONTAL

setLocation

public void setLocation(int location)

Set the legend's location using a constant. One of TOPLEFT, TOP, TOPRIGHT, LEFT, CENTER, RIGHT, BOTTOMLEFT, BOTTOM, BOTTOMRIGHT The default, the legend will be placed on the right side. If the value passed is not a valid legend location, an IllegalArgumentException will be thrown. Note that "CENTER" is only valid in charts contain rectangular axes (e.g., Barchart, Bubblechart, Combochart, Stockchart, Linechart, XYchart).

Parameters:

location - A constant representing the location.

getLocation

public int getLocation()

Get the legend's location

Returns:

A constant representing the legend location. One of TOPLEFT, TOP, TOPRIGHT, LEFT, CENTER, RIGHT (default), BOTTOMLEFT, BOTTOM, BOTTOMRIGHT

setPosition

public void setPosition(NFPoint position)

Set legend position. Only used if location = CENTER and the chart has rectangular axes. Values are relative to the axis map. In other words, the x/y value expressed in the NFPoint object is interpreted as a pixel value, a percentage value, or left/right/top/bottom axis value depending on how the axis map has been defined.

Parameters:

position - A NFPoint object representing the legend position.

getPosition

public NFPoint getPosition()

Get legend position

Returns:

The NFPoint object representing the legend position or null if not set.

setMaxSize

public void setMaxSize(java.awt.Dimension maxSize)

Set legend max size - performs mandatory clip if legend items become too large. This is sometimes preferable in situations where the legend items are dynamically generated. Usually, the chart will attempt to accomodate even the largest legend item. Setting a max size overrides this behavior.

Parameters:

maxSize - Dimension representing the maximum size of the NFLegend.

getMaxSize

public java.awt.Dimension getMaxSize()

Get legend max size.

Returns:

maxSize or null if not set.

setJustify

public void setJustify(int justify)

Set legend justification. Only used if location = CENTER and the chart contains rectangular axes. Controls where the legend is placed relative to the legend position. One of TOPLEFT, TOP, TOPRIGHT, LEFT, CENTER (default), RIGHT, BOTTOMLEFT, BOTTOM, BOTTOMRIGHT If the value passed is not a valid legend justify value, an IllegalArgumentException will be thrown.

Parameters:

justify - A constant representing the legend justification.

getJustify

public int getJustify()

Get legend justify.

Returns:

A constant representing the legend justification. One of TOPLEFT, TOP, TOPRIGHT, LEFT, CENTER, RIGHT, BOTTOMLEFT, BOTTOM, BOTTOMRIGHT

setColumns

public void setColumns(int columns)

Set the number of columns to be used when laying out legend items. The default value, -1, automatically creates columns as needed.

Parameters:

columns - The number of columns to use.

getColumns

public int getColumns()

Get the number of columns to be used when laying out legend items.

Returns:

The number of columns to use or -1 (default).

setItemOrder

public void setItemOrder(int itemOrder)

Set the order in which the legend items appear. If SETNAMEORDER, legend items will render in data set order. For example, if a the legend is displayed vertically on the righthand side of a chart and the itemOrder is SETNAMEORDER then legend item sets will appear from the top down. If SETDISPLAYORDER, legend items will render as inverse data set order. If the value passed is not a valid legend itemOrder value, an IllegalArgumentException will be thrown.

Parameters:

itemOrder - The order legend items should render. One of SETNAMEORDER, SETDISPLAYORDER

getItemOrder

public int getItemOrder()

Get the order legend items should render.

Returns:

A constant representing the legend item order. One of SETNAMEORDER, SETDISPLAYORDER

setSymbolPosition

public void setSymbolPosition(int symbolPosition)

Set the position all legend item symbols should appear relative to the legend item labels. The default behaviour is for the legend item symbol to appear left of the label. If the value passed is not a valid legend item symbol position value, an IllegalArgumentException will be thrown.

Parameters:

symbolPosition - The position legend items should appear relative to the legend item label. One of LEFT, RIGHT

getSymbolPosition

public int getSymbolPosition()

Get the legend item symbol's position relative to the label.

Returns:

A constant representing the legend item symbol's position. One of LEFT, RIGHT

addLegendItem

public void addLegendItem(NFLegendItem legendItem)

Add a legend item to the list of legend items. This method should only be called if the default legend behavior is insufficient.

Parameters:

legendItem - The new NFLegendItem to add to the list of legend items.

setLegendItems

public void setLegendItems(NFVector legendItems)

Explicitly set legend items. This method should only be used if the default legend behavior is insufficient. If the supplied vector has elements which are not NFLegendItem objects, an IllegalArgumentException will be thrown.

Parameters:

legendItems - A vector of NFLegendItems.

getLegendItems

public NFVector getLegendItems()

Get vector of NFLegendItems. This vector will only be populated if the legend items have been explicitly set.

Returns:

a vector of NFLegendItem(s).

addLegendLabel

public void addLegendLabel(java.lang.String label)

Add a legend label to the list of legend labels. This method should only be called if the default legend behavior is insufficient.

Parameters:

label - The new String to add to the list of legend labels.

setLegendLabels

public void setLegendLabels(NFVector labels)

Explicitly set legend labels. This method should only be used if the default legend behavior is insufficient. If the supplied vector has elements which are not String objects, an IllegalArgumentException will be thrown.

Parameters:

labels - A vector of Strings.

getLegendLabels

public NFVector getLegendLabels()

Get vector of legend labels. This vector will only be populated if the legend labels have been explicitly set.

Returns:

a vector of String(s).

setText

public void setText(java.lang.String text)

Sets the title for the legend. If set to "OFF" the legend will not be shown.

Parameters:

text - The legend title.

getText

public java.lang.String getText()

Gets the title text for the legend.

Returns:

text The legend title or null if not set.

setFont

public void setFont(java.awt.Font font)

Sets the font for the legend text.

Parameters:

font - Legend font.

getFont

public java.awt.Font getFont()

Gets the legend text font or null if not set.

Returns:

the legend font.

setTextAngle

public void setTextAngle(int textAngle)

Sets text angle for the legend items.

Parameters:

angle - The angle to rotate the legend items.

getTextAngle

public int getTextAngle()

Gets the text angle for the legend items.

Returns:

the angle to rotate legend items. Defaults to 0 if not set.

setTextColor

public void setTextColor(java.awt.Color color)

Sets the color of the legend text.

Parameters:

color - Color of the legend text.

getTextColor

public java.awt.Color getTextColor()

Gets the color of the legend text

Returns:

the color of the legend text or null if not set.

setFillColor

public void setFillColor(java.awt.Color fillColor)

Sets the legend fill (background) color.

Parameters:

fillColor - The legend background color.

getFillColor

public java.awt.Color getFillColor()

Gets the legend fill (background) color.

Returns:

the legend background color or null if not set.

setLabel

public void setLabel(NFLabel label)

Explicitly sets the NFLabel (text characteristics) object for this legend.

Parameters:

label -

getLabel

public NFLabel getLabel()

Gets the NFLabel object (text characteristics) object for this legend.

Returns:

label or null if not set

setRegion

public void setRegion(NFRegion region)

Explicitly sets the NFRegion (background characteristics) object for this legend.

Parameters:

region -

getRegion

public NFRegion getRegion()

Gets the NFRegion object (background characteristics) object for this legend.

Returns:

region or null if not set

addActiveLabel

public void addActiveLabel(NFActiveLabel activeLabel)

Add an active label item to the list of active labels. This allows the developer to enable rollover/drilldown operations on legend items. Each NFActiveLabel added corresponds 1 to 1 with the legend items.

Parameters:

activeLabel - The new NFActiveLabel to add to the list of active labels..

setActiveLabels

public void setActiveLabels(NFVector activeLabels)

Sets a vector of NFActiveLabels for this legend object. This allows the developer to enable rollover/drilldown operations on legend items. Each NFActiveLabel in the vector corresponds 1 to 1 with the legend items. If the supplied vector has elements which are not NFActiveLabel objects, an IllegalArgumentException will be thrown.

Parameters:

activeLabels - Vector of NFActiveLabels

getActiveLabels

public NFVector getActiveLabels()

Returns the list of active labels for this legend.

Returns:

a vector of NFActiveLabel objects.

setAxisMap

public void setAxisMap(NFAxisMap axisMap)

Set the axis map for this legend. The axis map applies only for charts with rectangular axes and when legend location = CENTER. The legend axis map identifies how the legend position maps onto the chart. For example, if the legend position is X=50 and Y=50, and the axismap is (PIXEL,PIXEL), it indicates that the legend position is 50 pixels from the left and top of the rectangular axis area.

Parameters:

axisMap - Axis map to use

getAxisMap

public NFAxisMap getAxisMap()

Returns the axis map for this legend

Returns:

the axis map

setLegendEnabled

public void setLegendEnabled(boolean enabled)

Enables or disables the legend

Parameters:

enabled - If true, legend will be shown.

getLegendEnabled

public boolean getLegendEnabled()

Returns the state of the legend

Returns:

enabled If true, dwell popups will be available.

getItemBorder

public NFLine getItemBorder()

Returns the line representing the border outlines of the legend item symbols.

Returns:

itemBorder Symbol border line, null if not already set

setItemBorder

public void setItemBorder(NFLine legendItemBorder)

Explicitly define the border outline of all legend item symbols.

Parameters:

legendItemBorder - Line representing the legend symbol border outlines

getCDLLegendLayout

public java.lang.String getCDLLegendLayout()

Generate CDL parameters representing the legend layout

Returns:

CDL in the form: (Orientation, Location, X, Y, Justify, Columns)

setCDLLegendLayout

public void setCDLLegendLayout(java.lang.String s)

Configures the legend layout attributes from a CDL parameter representation.

Parameters:

cdl - CDL in the form: (Orientation, Location, X, Y, Justify, Columns)

getCDLMaxSize

public java.lang.String getCDLMaxSize()

Generate CDL parameters representing the legend max size

Returns:

CDL in the form: (maxWidth, maxHeight)

setCDLMaxSize

public void setCDLMaxSize(java.lang.String cdl)

Configures the legend max size attributes from a CDL parameter representation. If the String is null, then no LegendMaxSize will be used.

Parameters:

cdl - CDL in the form: (maxWidth, maxHeight)

getCDLSymbolPosition

public java.lang.String getCDLSymbolPosition()

Generate CDL parameters representing the legend item symbol position relative to the label.

Returns:

CDL in the form: sybomPosition

setCDLSymbolPosition

public void setCDLSymbolPosition(java.lang.String cdl)

Configures the legend symbol position attribute from a CDL parameter representation. If the String is null, then the legend item symbols will appear to the left of labels by default.

Parameters:

cdl - CDL in the form: symbolPosition

getCDLItemBorder

public java.lang.String getCDLItemBorder()

Generate CDL parameters representing outlines for all the legend item symbols.

Returns:

CDL in the form: (lineType, lineWidth, lineColor)

setCDLItemBorder

public void setCDLItemBorder(java.lang.Object cdl)

Configures the legend item symbol outlines from a CDL parameter representation. If the String is null, then the outlines will have solid, black, one pixel borders by default.

Parameters:

cdl - CDL in the form: (lineType, lineWidth, lineColor)

getCDLVector

public java.util.Vector getCDLVector()

NFLegend is a compound object representing multiple CDL parameters. This method returns a vector containing CDL representations for all attributes described in this NFLegend

Returns:

Vector of NFKeyValue objects