com.sas.graphics.components
Class LegendModel

com.sas.graphics.components.LegendModel

public class LegendModel

A LegendModel contains the set of display properties applied to a graph's legend. Changing LegendModel property values will trigger the associated graph to refresh its display.

Usage

For graphs capable of displaying a legend, you gain access to the LegendModel via the graph's GraphModel. Typically, a graph is capable of displaying only a single legend in which case the legend model is usually accessible via graph.getGraphModel().getLegendModel();. However, some graphs are capable of displaying multiple legends, in which case it becomes necessary to locate the relevant LegendModel by examining the LegendModel properties found within that graph's associated GraphModel. (ex. The ScatterPlot can display a legend for color values and a separate legend for shape values. The legend responsible for identifying the color values is scatterplot.getGraphModel().getColorLegendModel();.

Behavior

Note: The display of a legend is at the discretion of each graph, that is a legend will only be displayed when one is necessary. For some graph types, such as the GanttChart, this is always whereas for most other graph types it is only when certain criteria have been established. For instance a BarChart will attempt to display a legend only when any of the following have been satisfied: (1) multiple response variables have been specified or (2) a subgroup variable has been specified or (3) a styleBy variable has been specified. The LegendModel's visible property is only applicable when the graph is a state such that it will attempt to display a legend.

By default, legends use an automatic layout strategy enabling the the graph to determine how to best fit all the values and associated legend graphics within the provided space. Properties are available to allow the legend's display to be customised. However, when pressed for space, fitting strategies are engaged which will shrink fonts sizes, truncate legend values, etc. in an attempt to fit the legend display within the available space while continuing to allow the graph to be displayed. When the fitting strategies are engaged, that is when there is insufficient display space to accommodate the graph's preferred size, some user setting may be ignored or modified in an attempt to fit the legend. Sometimes there just isn't sufficient display space to accommodate both the graph and the legend, in which case, the legend is dropped from the display altogether. Typically this only happens when there is a rather small amount of available display space or when there is a large amount of values in the legend.

Best practices

Legends are there to reduce the visual complexity within a graph by centralising the labelling necessary to identify portions of the information contained in the graph. People typically have a difficult time comprehending a graph if there are too many entries in the legend. When utilising a discrete legend, it is best to not allow the number of legend values to exceed 8 entries.

Since:

SAS 9.1

See Also:

BarChartModel, PieChartModel, ScatterPlotModel

Constructor Summary

LegendModel()
Default constructor.

Method Summary

void	addEntryToLegendValuesIndexMap(java.lang.String keyStr, java.lang.String valueStr) This method can be used to add a key - value pair in the legendValuesIndexMap.
void	apply(LegendModel theOtherObject) Utility method to convey properties contained in "theOtherObject" to this object.
boolean	equals(java.lang.Object obj) Determines whether another object is equal to this LegendModel.
int	getActualCOLOR_BYLegendSize()
FillStyle	getBackgroundFillStyle() Returns the FillStyle used by the legend's background.
double	getBaseline() Returns the baseline value which represents a data value color inflection point (only applicable to continuous color legends).
java.lang.String[]	getCategories() Returns the array of Strings that will be used for the legend value text.
boolean	getFirstTimeColorVectorCOLOR_BY()
boolean	getFirstTimeStringVectorCOLOR_BY()
LineStyle	getFrameLineStyle() Gets the visual properties applicable to the frame's line.
boolean	getIsFirstTime() Getter method for the boolean member isFirstTime.
int	getLabelPlacement() Returns the placement of the legend's label.
java.util.LinkedHashMap	getLegendValuesIndexMap() The getter method for the member HashMap legendValuesIndexMap;
double	getMaximum() Sets the the maximum value to represent on the legend (valid only for the continuous color legends).
boolean	getMilestoneMarkerFlag() This is the getter method for the boolean member isMilestoneMarkerPresent which indicates whether the "Milestone" marker is present or not.
int	getMilestoneMarkerIndex() This is the getter method for the integer member milestoneMarkerIndex which indicates the row index of the "Milestone" marker.
double	getMinimum() Sets the the minimum value represented on the legend (only applicable to the continuous color legends).
int	getPlacement() Returns the placement of the legend in relation to the chart.
ShadowStyle	getShadowStyle() Returns the shadow style of the legend border.
boolean	getTargetMarkerFlag() This is the getter method for the boolean member isTargetMarkerPresent which indicates whether the "Target" marker is present or not.
int	getTargetMarkerIndex() This is the getter method for the integer member targetMarkerIndex which indicates the row index of the "Target" marker.
java.lang.String	getValueFromLegendValuesIndexMap(java.lang.String keyStr) This method can be used to return a String index value for a key stored in the legendValuesIndexMap.
int	hashCode() Computes the hash code for this LegendModel.
boolean	isDrillIconVisible() Return if a drill-down icon should appear next to the subgroup label (if present).
boolean	isSymmetricEnabled() Returns whether or not the legend range is symmetric about the baseline value (only applicable to continuous color legends and when the baseline value is a real number (i.e. not a Double.NaN)).
void	setActualCOLOR_BYLegendSize(int i) setter method for setting the member actualCOLOR_BYLegendSize.
void	setBackgroundFillStyle(FillStyle newFillStyle) Set the legend's background fill properties.
void	setBaseline(double baselineValue) Sets the baseline value which represents a data value color inflection point (only applicable to continuous color legends).
void	setCategories(java.lang.String[] newValues) Set the category string values for the legend entries.
void	setDrillIconVisible(boolean newVis) Set if a drill-down icon should appear next to the subgroup label (if present).
void	setFirstTimeColorVectorCOLOR_BY(int i) setter method for setting the member isFirstTimeColorVectorCOLOR_BY
void	setFirstTimeStringVectorCOLOR_BY(int i) setter method for setting the member isFirstTimeStringVectorCOLOR_BY.
void	setFrameLineStyle(LineStyle newFrameLineStyle) Sets the visual properties applicable to the frame's line.
void	setIsFirstTime(int i) Setter method for the boolean member isFirstTime.
void	setLabelPlacement(int newPlacement) Sets the placement of the legend's label within the legend frame.
void	setLegendValues(java.lang.String[] newValues) This method is same as the above setCategories method except that this method does not call the firePropertyChange() method at the end.
void	setLegendValuesIndexMap(java.util.LinkedHashMap hm) This method should be used only to read back the persisted legend index values.
void	setMaximum(double maxValue) Sets the the maximum value to represent on the legend (only applicable to the continuous color legends).
void	setMilestoneMarkerFlag(boolean b) This is the setter method for the boolean member isMilestoneMarkerPresent which indicates whether the "Milestone" marker is present or not.
void	setMilestoneMarkerIndex(int i) This is the setter method for the integer member milestoneMarkerIndex which indicates the row index of the "Milestone" marker.
void	setMinimum(double minValue) Sets the the minimum value to represent on the legend (only applicable to the continuous color legends).
void	setPlacement(int newPlacement) Sets the placement of the legend in relation to the chart.
void	setShadowStyle(ShadowStyle newShadow) Set the shadow attributes for the legend's shadow.
void	setSymmetricEnabled(boolean symmetry) Sets whether or not the legend range is symmetric about the baseline value (only applicable to continuous color legends).
void	setTargetMarkerFlag(boolean b) This is the setter method for the boolean member isTargetMarkerPresent which indicates whether the "Target" marker is present or not.
void	setTargetMarkerIndex(int i) This is the setter method for the integer member targetMarkerIndex which indicates the row index of the "Target" marker.

Methods inherited from class com.sas.graphics.components.ContentsModel

apply, getLabel, getLabelTextStyle, getValueTextStyle, isVisible, setLabel, setLabelTextStyle, setValueTextStyle, setVisible

Methods inherited from class com.sas.graphics.components.ModelBase

addPropertyChangeListener, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, removePropertyChangeListener, setContainedModel

Constructor Detail

LegendModel

public LegendModel()

Default constructor.

Method Detail

apply

public void apply(LegendModel theOtherObject)

Utility method to convey properties contained in "theOtherObject" to this object.

Note: Contained "models" (i.e. properties that are subclasses of ModelBase) will in turn be called on to convey their properties to the like contained models in the other object. In that respect this can be considered a "tree" type copy.

Also Note: This is a deep copy. Thus after the copy, mutable properties will not be shared by the two instances.

Parameters:

theOtherObject - properties applied to this instance

setLabelPlacement

public void setLabelPlacement(int newPlacement)
                       throws java.lang.IllegalArgumentException

Sets the placement of the legend's label within the legend frame.

This method is not applicable in conjunction with a continuous legend such as a legend showing a continuous color ramp which has no frame.

Valid values are:

• GraphConstants.PLACEMENT_AUTOMATIC: (default)
• GraphConstants.PLACEMENT_LEFT: Rotates the label by 90 degrees and put it on left side in seperate column.
• GraphConstants.PLACEMENT_RIGHT: Rotates the label by 90 degrees and put it on right side in seperate column.
• GraphConstants.PLACEMENT_INSIDE: Sets the label at the top-center of legend and just under the border.
• GraphConstants.PLACEMENT_OUTSIDE: Sets the label at the top-center of legend and just over the border.
• GraphConstants.PLACEMENT_ACROSS: Sets the label at the top-left of legend crossing the border frame.
• GraphConstants.PLACEMENT_INSIDE_LEFT: Sets the label at the top-left of legend and just under the border.
• GraphConstants.PLACEMENT_OUTSIDE_LEFT: Sets the label at the top-left of legend and just over the border.
• GraphConstants.PLACEMENT_ACROSS_LEFT: Same as GraphConstants.PLACEMENT_ACROSS.
• GraphConstants.PLACEMENT_INSIDE_RIGHT: Sets the label at the top-right of legend and just under the border.
• GraphConstants.PLACEMENT_OUTSIDE_RIGHT: Sets the label at the top-right of legend and just over the border.
• GraphConstants.PLACEMENT_ACROSS_RIGHT: Sets the label at the top-right of legend crossing the border frame.
• GraphConstants.PLACEMENT_INSIDE_CENTER: Sets the label at the top-center of legend and just under the border.
• GraphConstants.PLACEMENT_OUTSIDE_CENTER: Sets the label at the top-center of legend and just over the border.
• GraphConstants.PLACEMENT_ACROSS_CENTER: Sets the label at the top-center of legend crossing the border frame.

Parameters:

newPlacement - legend label placement specification

Throws:

java.lang.IllegalArgumentException - if an invalid value is passed in.

See Also:

getLabelPlacement()

getLabelPlacement

public int getLabelPlacement()

Returns the placement of the legend's label.

Returns:

int The legend label's placement

See Also:

setLabelPlacement(int)

setShadowStyle

public void setShadowStyle(ShadowStyle newShadow)
                    throws java.lang.IllegalArgumentException

Set the shadow attributes for the legend's shadow.

Note: The shadow style is ignored if the border is not visible.

Parameters:

newShadow - the border's shadow attributes

Throws:

java.lang.IllegalArgumentException - if newShadow is null.

See Also:

getShadowStyle(), ShadowStyle.apply(com.sas.graphics.components.ShadowStyle)

getShadowStyle

public ShadowStyle getShadowStyle()

Returns the shadow style of the legend border. The shadow style is ignored if the border is not visible.

Returns:

ShadowStyle The legend's shadow visible attributes

See Also:

setShadowStyle(com.sas.graphics.components.ShadowStyle)

setCategories

public void setCategories(java.lang.String[] newValues)
                   throws java.lang.IllegalArgumentException

Set the category string values for the legend entries.

Parameters:

newValues - an array of text strings for the legend to display.

Throws:

java.lang.IllegalArgumentException - if array is empty, any array element is null or has duplicate string values.

See Also:

getCategories()

setLegendValues

public void setLegendValues(java.lang.String[] newValues)
                     throws java.lang.IllegalArgumentException

This method is same as the above setCategories method except that this method does not call the firePropertyChange() method at the end. The intention here is to just set the String array member "values".

Parameters:

newValues -

Throws:

java.lang.IllegalArgumentException

getCategories

public java.lang.String[] getCategories()

Returns the array of Strings that will be used for the legend value text.

Returns:

String[] The legend's value strings

See Also:

setCategories(java.lang.String[])

setMilestoneMarkerFlag

public void setMilestoneMarkerFlag(boolean b)

This is the setter method for the boolean member isMilestoneMarkerPresent which indicates whether the "Milestone" marker is present or not.

Parameters:

b -

setTargetMarkerFlag

public void setTargetMarkerFlag(boolean b)

This is the setter method for the boolean member isTargetMarkerPresent which indicates whether the "Target" marker is present or not.

Parameters:

b -

getMilestoneMarkerFlag

public boolean getMilestoneMarkerFlag()

This is the getter method for the boolean member isMilestoneMarkerPresent which indicates whether the "Milestone" marker is present or not.

Returns:

boolean

getTargetMarkerFlag

public boolean getTargetMarkerFlag()

This is the getter method for the boolean member isTargetMarkerPresent which indicates whether the "Target" marker is present or not.

Returns:

boolean

setMilestoneMarkerIndex

public void setMilestoneMarkerIndex(int i)

This is the setter method for the integer member milestoneMarkerIndex which indicates the row index of the "Milestone" marker.

Parameters:

i -

setTargetMarkerIndex

public void setTargetMarkerIndex(int i)

This is the setter method for the integer member targetMarkerIndex which indicates the row index of the "Target" marker.

Parameters:

i -

getMilestoneMarkerIndex

public int getMilestoneMarkerIndex()

This is the getter method for the integer member milestoneMarkerIndex which indicates the row index of the "Milestone" marker.

getTargetMarkerIndex

public int getTargetMarkerIndex()

This is the getter method for the integer member targetMarkerIndex which indicates the row index of the "Target" marker.

Returns:

int

getLegendValuesIndexMap

public java.util.LinkedHashMap getLegendValuesIndexMap()

The getter method for the member HashMap legendValuesIndexMap;

Returns:

LinkedHashMap

setLegendValuesIndexMap

public void setLegendValuesIndexMap(java.util.LinkedHashMap hm)

This method should be used only to read back the persisted legend index values.

Parameters:

hm - LinkedHashMap to be used

addEntryToLegendValuesIndexMap

public void addEntryToLegendValuesIndexMap(java.lang.String keyStr,
                                           java.lang.String valueStr)

This method can be used to add a key - value pair in the legendValuesIndexMap.

Parameters:

keyStr -

valueStr - Value string found in the legend

getValueFromLegendValuesIndexMap

public java.lang.String getValueFromLegendValuesIndexMap(java.lang.String keyStr)

This method can be used to return a String index value for a key stored in the legendValuesIndexMap.

Parameters:

keyStr -

Returns:

String the value stored in the legendValuesIndexMap for the key keyStr (if present) null otherwise.

setIsFirstTime

public void setIsFirstTime(int i)

Setter method for the boolean member isFirstTime.

Parameters:

i -

getIsFirstTime

public boolean getIsFirstTime()

Getter method for the boolean member isFirstTime.

Returns:

boolean

getActualCOLOR_BYLegendSize

public int getActualCOLOR_BYLegendSize()

Returns:

int the actualCOLOR_BYLegendSize

setActualCOLOR_BYLegendSize

public void setActualCOLOR_BYLegendSize(int i)

setter method for setting the member actualCOLOR_BYLegendSize.

Parameters:

i -

getFirstTimeStringVectorCOLOR_BY

public boolean getFirstTimeStringVectorCOLOR_BY()

Returns:

boolean value of isFirstTimeStringVectorCOLOR_BY

setFirstTimeStringVectorCOLOR_BY

public void setFirstTimeStringVectorCOLOR_BY(int i)

setter method for setting the member isFirstTimeStringVectorCOLOR_BY.

Parameters:

i -

getFirstTimeColorVectorCOLOR_BY

public boolean getFirstTimeColorVectorCOLOR_BY()

Returns:

value of isFirstTimeColorVectorCOLOR_BY

setFirstTimeColorVectorCOLOR_BY

public void setFirstTimeColorVectorCOLOR_BY(int i)

setter method for setting the member isFirstTimeColorVectorCOLOR_BY

Parameters:

i -

setBackgroundFillStyle

public void setBackgroundFillStyle(FillStyle newFillStyle)
                            throws java.lang.IllegalArgumentException

Set the legend's background fill properties. Note: At this time, legend's do not support image or gradient background fills. When the legend's background is visible it will reflect the FillStyle's solidFillColor.

This method is not applicable in conjunction with a continuous legend such as a legend showing a continuous color ramp which has no frame or background.

Parameters:

newFillStyle - the legend background attributes

Throws:

java.lang.IllegalArgumentException - if newFillStyle is null.

See Also:

getBackgroundFillStyle(), FillStyle.apply(com.sas.graphics.components.FillStyle)

getBackgroundFillStyle

public FillStyle getBackgroundFillStyle()

Returns the FillStyle used by the legend's background. Note: The legend background does not support image or gradient fills.

Returns:

FillStyle The legend's background display properties.

See Also:

setBackgroundFillStyle(com.sas.graphics.components.FillStyle)

setPlacement

public void setPlacement(int newPlacement)

Sets the placement of the legend in relation to the chart.

Valid values are:

• SwingConstants.NORTH
• SwingConstants.SOUTH
• SwingConstants.EAST
• SwingConstants.WEST
• GraphConstants.PLACEMENT_AUTOMATIC (default)

A value of GraphConstants.PLACEMENT_AUTOMATIC (the default value) allows the chart to place the legend where it thinks is aesthetically the best place based upon the type of chart it is and it current state.

Parameters:

newPlacement - legend placement specification

Throws:

java.lang.IllegalArgumentException - if an invalid value is passed in.

See Also:

getPlacement()

getPlacement

public int getPlacement()

Returns the placement of the legend in relation to the chart.

Returns:

int The legend's placement

See Also:

setPlacement(int)

setFrameLineStyle

public void setFrameLineStyle(LineStyle newFrameLineStyle)
                       throws java.lang.IllegalArgumentException

Sets the visual properties applicable to the frame's line.

This method is not applicable in conjunction with a continuous legend such as a legend showing a continuous color ramp which has no frame.

Parameters:

newFrameLineStyle - the display attributes of the frame's line.

Throws:

java.lang.IllegalArgumentException - if newFrameLineStyle is null.

See Also:

getFrameLineStyle()

getFrameLineStyle

public LineStyle getFrameLineStyle()

Gets the visual properties applicable to the frame's line.

Returns:

LineStyle frame color for the legend

See Also:

setFrameLineStyle(com.sas.graphics.components.LineStyle)

setDrillIconVisible

public void setDrillIconVisible(boolean newVis)

Set if a drill-down icon should appear next to the subgroup label (if present). The default value is false.

Parameters:

newVis - Should the drill-down icon be displayed?

See Also:

isDrillIconVisible()

isDrillIconVisible

public boolean isDrillIconVisible()

Return if a drill-down icon should appear next to the subgroup label (if present).

Returns:

boolean Should the drill-down icon be displayed?

See Also:

setDrillIconVisible(boolean)

setMinimum

public void setMinimum(double minValue)

Sets the the minimum value to represent on the legend (only applicable to the continuous color legends). A value of Double.NaN (the default) indicates no user override and that the minimum value applied to the legend should be computed from the data specified to the graph. Note: specifying a minimum value fixes the legend's minimum value at that value reguardless of the data specified on the graph. Any data values less than the minimum value are represented using the legend's minimum color value.

Throws:

java.lang.IllegalArgumentException - if minValue is Double.NEGATIVE_INFINITY or Double.POSITIVE_INFINITY.

See Also:

getMinimum(), setMaximum(double)

getMinimum

public double getMinimum()

Sets the the minimum value represented on the legend (only applicable to the continuous color legends).

Returns:

double user defined minimum value

See Also:

setMinimum(double), getMaximum()

setMaximum

public void setMaximum(double maxValue)

Sets the the maximum value to represent on the legend (only applicable to the continuous color legends). A value of Double.NaN (the default) indicates no user override and that the maximum value applied to the legend should be computed from the data specified to the graph. Note: specifying a maximum value fixes the legend's maximum value at that value reguardless of the data specified on the graph. Any data values greater than the minimum value are represented using the legend's maximum color value.

Throws:

java.lang.IllegalArgumentException - if maxValue is Double.NEGATIVE_INFINITY or Double.POSITIVE_INFINITY.

See Also:

getMaximum(), setMinimum(double)

getMaximum

public double getMaximum()

Sets the the maximum value to represent on the legend (valid only for the continuous color legends).

Returns:

double user defined maximun value for the legend.

See Also:

setMaximum(double), getMinimum()

setBaseline

public void setBaseline(double baselineValue)

Sets the baseline value which represents a data value color inflection point (only applicable to continuous color legends).
The default value is 0.0 which was deemed most useful since it is a typical indicator of gains vs losses.
Double.Nan indicates no fixed baseline.
Note: the symmetricEnabled property is only applicable if a baseline value is specified (i.e. not Double.NaN).
Note: a warning message is when rendering if:

• if minimum is specified and baseline is less than minimum
• if maximum is specified and baseline is greater than maximum
• if maximum is specified less than minimum

Note: The baseline value may affect the graph's resulting min/max range.

Throws:

java.lang.IllegalArgumentException - if baselineValue is Double.NEGATIVE_INFINITY or Double.POSITIVE_INFINITY.

See Also:

getBaseline(), setSymmetricEnabled(boolean)

getBaseline

public double getBaseline()

Returns the baseline value which represents a data value color inflection point (only applicable to continuous color legends).

Returns:

double user defined baseline value for the legend.

See Also:

setMaximum(double), getMinimum()

setSymmetricEnabled

public void setSymmetricEnabled(boolean symmetry)

Sets whether or not the legend range is symmetric about the baseline value (only applicable to continuous color legends).

The default value is false. Note: symetricEnabled is only applicable if baseline is specified (i.e. not Double.NaN). Note: symetricEnabled is not applicable if either minimum or maximum are specified.

Parameters:

symmetry - true means to make the resulting min/max range symmetric about the baseline

See Also:

isSymmetricEnabled()

isSymmetricEnabled

public boolean isSymmetricEnabled()

Returns whether or not the legend range is symmetric about the baseline value (only applicable to continuous color legends and when the baseline value is a real number (i.e. not a Double.NaN)).

Returns:

boolean Is the continuous color legend symmetric about the baseline?

See Also:

setSymmetricEnabled(boolean)

equals

public boolean equals(java.lang.Object obj)

Determines whether another object is equal to this LegendModel.

The result is true if and only if the argument is not null and is a LegendModel object that has the same property values as this object.

Overrides:

equals in class ContentsModel

Parameters:

obj - the object to test for equality with this LegendModel

Returns:

true if the objects are the same; false otherwise.

hashCode

public int hashCode()

Computes the hash code for this LegendModel.

Overrides:

hashCode in class ContentsModel

Returns:

int a hash code value for this object.