com.steema.teechart.legend
Class Legend

java.lang.Object
  extended by com.steema.teechart.TeeBase
      extended by com.steema.teechart.Shape
          extended by com.steema.teechart.TextShape
              extended by com.steema.teechart.TextShapePosition
                  extended by com.steema.teechart.legend.Legend

public class Legend
extends TextShapePosition

Title: Legend class

Description: Accesses all Chart Legend characteristics

Copyright (c) 2005-2013 by Steema Software SL. All Rights Reserved.

Company: Steema Software SL


Field Summary
protected  boolean columnWidthAuto
           
protected  int[] columnWidths
           
protected  int firstValue
           
protected  int iLastValue
           
 LegendStyle iLegendStyle
           
 
Fields inherited from class com.steema.teechart.TextShapePosition
bCustomPosition
 
Fields inherited from class com.steema.teechart.TextShape
defaultText, drawText
 
Fields inherited from class com.steema.teechart.Shape
bBevel, bBorderRound, bBrush, bImageBevel, bTransparent, defaultVisible, pPen, shadow, shapeBounds, visible
 
Fields inherited from class com.steema.teechart.TeeBase
chart, InternalUse
 
Constructor Summary
Legend(IBaseChart c)
           
 
Method Summary
protected  int calcItemHeight()
           
 int clicked(int x, int y)
          Returns the index of the clicked Legend Point.
 int clicked(Point p)
          Returns the index of the clicked Legend Point.
 boolean doMouseDown(Point p)
           
protected  boolean drawTitle()
           
 java.lang.String formattedLegend(int seriesOrValueIndex)
          Returns the text string corresponding to a Legend position.
 java.lang.String formattedValue(Series aSeries, int valueIndex)
          Returns the corresponding Legend text for the Series ValueIndex point.
 LegendAlignment getAlignment()
          Defines the Legend position.
 boolean getCheckBoxes()
          Enables/Disables the display of Legend check boxes.
 int getColorWidth()
           
 int getColumnWidth(int column)
           
 boolean getColumnWidthAuto()
          Automatically calculates best fit of legend columns.
 boolean getCurrentPage()
          Determines whether or not the Legend shows only the current page iItems when the Chart is divided into pages.
 ChartPen getDividingLines()
          Specifies the Pen attributes used to draw lines separating Legend iItems.
 int getFirstValue()
          Defines which is the first Legend item displayed.
 boolean getFontSeriesColor()
          The legend text font color to that of the Series color.
 int getHorizMargin()
          Speficies the number of screen pixels between Legend and Chart rectangles.
 boolean getInverted()
          Draws the Legend iItems in opposite direction when true.
 int getLastValue()
          Returns the index of the first displayed value at legend.
 LegendItems getLegendItems()
           
 LegendStyle getLegendStyle()
          Defines which iItems will be displayed in the Chart Legend.
 java.lang.String[] getLines()
          Accesses the array of Text lines.
 int getMaxNumRows()
          The Maximum number of Legend Rows displayed for a horizontal Legend (Chart Top or Bottom).
 boolean getResizeChart()
          Automatically resizes Chart rectangle to prevent overlap with Legend.
 Series getSeries()
          Determines which series is used as data for the Legend entries.
 LegendSymbol getSymbol()
          Controls the width and position of the color rectangle associated with each Legend's item.
 java.lang.String getText()
          Adds text to the Legend.
 LegendTextStyle getTextStyle()
          Determines how Legend text iItems will be formatted.
 int getTextSymbolGap()
           
 LegendTitle getTitle()
          Sets the Title text and its characteristics at the top of the legend
 int getTopLeftPos()
          Specifies the Legend's top position in percent of total chart height.
 boolean getUseMaxWidth()
           
 boolean getVertical()
          Is read only and returns true only if the legend is left or right aligned.
 int getVertMargin()
          The vertical margin in pixels between Legend and Chart rectangle.
 int getVertSpacing()
          The vertical spacing between Legend iItems (pixels).
 boolean hasCheckBoxes()
          Returns true when the legend displays checkboxes and it is showing series names.
 void paint(IGraphics3D g, Rectangle rect)
          Paints the TextShape object on the Chart Canvas.
protected  java.lang.Object readResolve()
           
 Rectangle resizeChartRect(Rectangle rect)
          Returns the chart rectangle minus the space occupied by the Legend.
 void setAlignment(LegendAlignment value)
          Defines the Legend position.
 void setChart(IBaseChart c)
          Chart associated with this object.
 void setCheckBoxes(boolean value)
          Displays the Legend check boxes when true.
 void setColorWidth(int value)
           
 void setColumnWidth(int column, int value)
           
 void setColumnWidthAuto(boolean value)
          Automatically calculates best fit of legend columns.
 void setCurrentPage(boolean value)
          When true, the Legend shows only the current page iItems when the Chart is divided into pages.
 void setDividingLines(ChartPen value)
          Internal use - serialization
 void setFirstValue(int value)
          Determines which is the first Legend item displayed.
 void setFontSeriesColor(boolean value)
          Sets the legend text font color to that of the Series color.
 void setHorizMargin(int value)
          Speficies the number of screen pixels between Legend and Chart rectangles.
 void setInverted(boolean value)
          Draws the Legend iItems in opposite direction when true.
 void setLegendStyle(LegendStyle value)
          Defines which iItems will be displayed in the Chart Legend.
 void setLines(java.lang.String[] value)
          Accesses the array of Text lines.
 void setMaxNumRows(int value)
          Sets the Maximum number of Legend Rows displayed for a horizontal Legend (Chart Top or Bottom).
 void setResizeChart(boolean value)
          Automatically resizes Chart rectangle to prevent overlap with Legend.
 void setSeries(Series value)
          Determines which series is used as data for the Legend entries.
 void setSymbol(LegendSymbol value)
           
 void setText(java.lang.String value)
          Adds text to the Legend.
 void setTextStyle(LegendTextStyle value)
          Specifies how Legend text iItems will be formatted.
 void setTextSymbolGap(int value)
           
 void setTopLeftPos(int value)
          Specifies the Legend's top position in percent of total chart height.
 void setUseMaxWidth(boolean value)
           
 void setVertMargin(int value)
          Determines the vertical margin in pixels between Legend and Chart rectangle.
 void setVertSpacing(int value)
          Determines the vertical spacing between Legend iItems (pixels).
 
Methods inherited from class com.steema.teechart.TextShapePosition
getCustomPosition, setCustomPosition, shouldSerializeBottom, shouldSerializeLeft, shouldSerializeRight, shouldSerializeTop
 
Methods inherited from class com.steema.teechart.TextShape
assign, drawRectRotated, drawString, drawText, getAutoSize, getFont, getLinesLength, getShadowSize, getShapeStyle, getTextFormat, paint, paint, setAutoSize, setDrawText, setShadowSize, setShapeStyle, setTextFormat
 
Methods inherited from class com.steema.teechart.Shape
assign, getBevel, getBevelInner, getBevelOuter, getBevelWidth, getBorderRound, getBottom, getBrush, getColor, getGradient, getHeight, getImage, getImageBevel, getImageMode, getImageTransparent, getLeft, getPen, getRight, getShadow, getShapeBounds, getTop, getTransparency, getTransparent, getVisible, getWidth, setBevel, setBevelInner, setBevelOuter, setBevelWidth, setBorderRound, setBottom, setBrush, setColor, setDefaultVisible, setHeight, setImage, setImageMode, setImageTransparent, setLeft, setPen, setRight, setShapeBounds, setTop, setTransparency, setTransparent, setVisible, setWidth
 
Methods inherited from class com.steema.teechart.TeeBase
getChart, invalidate, setBooleanProperty, setColorProperty, setDoubleProperty, setIntegerProperty, setStringProperty
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

iLegendStyle

public transient LegendStyle iLegendStyle

columnWidthAuto

protected boolean columnWidthAuto

columnWidths

protected int[] columnWidths

firstValue

protected transient int firstValue

iLastValue

protected transient int iLastValue
Constructor Detail

Legend

public Legend(IBaseChart c)
Method Detail

readResolve

protected java.lang.Object readResolve()
Overrides:
readResolve in class TextShape

getTextStyle

public LegendTextStyle getTextStyle()
Determines how Legend text iItems will be formatted.
Plain shows the point Label only.
LeftValue shows the point Value and the point Label.
RightValue shows the point Label and the point Value.
LeftPercent shows the percent the point represents and the point Label.
RightPercent shows the point Label and the percent the points represent.
XValue shows the point's X value. It applies only to Series with X (horizontal) values.

Values are pre-formatted using the Series ValueFormat property.
Percents are pre-formatted using the Series PercentFormat property.

Default value: LeftValue

Returns:
LegendTextStyle

getLastValue

public int getLastValue()
Returns the index of the first displayed value at legend. The index can be a series value index or a series index depending on legend style.

Returns:
int

setTextStyle

public void setTextStyle(LegendTextStyle value)
Specifies how Legend text iItems will be formatted.
Default value: LeftValue

Parameters:
value - LegendTextStyle

getTextSymbolGap

public int getTextSymbolGap()

setTextSymbolGap

public void setTextSymbolGap(int value)

getSeries

public Series getSeries()
Determines which series is used as data for the Legend entries.
By default, the Legend chooses the first Active Series with ShowInLegend:=true. It only applies to Legend style "Values".

Returns:
Series

setSeries

public void setSeries(Series value)
Determines which series is used as data for the Legend entries.

Parameters:
value - Series

getCheckBoxes

public boolean getCheckBoxes()
Enables/Disables the display of Legend check boxes.
Default value: false

Returns:
boolean

setChart

public void setChart(IBaseChart c)
Description copied from class: Shape
Chart associated with this object.

Overrides:
setChart in class TextShape
Parameters:
c - IBaseChart

setCheckBoxes

public void setCheckBoxes(boolean value)
Displays the Legend check boxes when true.
Default value: false

Parameters:
value - boolean

getCurrentPage

public boolean getCurrentPage()
Determines whether or not the Legend shows only the current page iItems when the Chart is divided into pages.
Default value: true

Returns:
boolean

setCurrentPage

public void setCurrentPage(boolean value)
When true, the Legend shows only the current page iItems when the Chart is divided into pages.
Default value: true

Parameters:
value - boolean

getFontSeriesColor

public boolean getFontSeriesColor()
The legend text font color to that of the Series color.
Default value: false

Returns:
boolean

setFontSeriesColor

public void setFontSeriesColor(boolean value)
Sets the legend text font color to that of the Series color.
Default value: false

Parameters:
value - boolean

getDividingLines

public ChartPen getDividingLines()
Specifies the Pen attributes used to draw lines separating Legend iItems.
Lines are drawn horizontally for Left or Right aligned Legend and vertically for Top or Bottom Legend alignments.

Returns:
ChartPen

setDividingLines

public void setDividingLines(ChartPen value)
Internal use - serialization


getSymbol

public LegendSymbol getSymbol()
Controls the width and position of the color rectangle associated with each Legend's item.

Returns:
LegendSymbol

setSymbol

public void setSymbol(LegendSymbol value)

getInverted

public boolean getInverted()
Draws the Legend iItems in opposite direction when true.
Legend strings are displayed starting at top for Left and Right Aligment and starting at left for Top and Bottom Legend orientations. You can use Legend.FirstValue to determine the ValueIndex for the first Legend text item.
Default value: false

Returns:
boolean

setInverted

public void setInverted(boolean value)
Draws the Legend iItems in opposite direction when true.
Default value: false

Parameters:
value - boolean

getAlignment

public LegendAlignment getAlignment()
Defines the Legend position.
Legend can be currently placed at Top, Left, Right and Bottom side of Chart.
Left and Right Legend alignments define a vertical Legend with currently one single column of iItems.
Top and Bottom Legend alignments define an horizontal Legend with currently one single row of iItems.
The Legend itself automatically reduces the number of displayed legend iItems based on the available charting space.
The Legend.ResizeChart property controls if Legend dimensions should be used to reduce Chart points space.
The Legend.GetLegendRect event provides a mechanism to supply the desired Rectangle Legend dimensions and placement.
The Legend.GetLegendPos event can be used to specify fixed Legend iItems X Y coordinates.
The Legend.HorizMargin and VertMargin properties control distance between Legend and Left and Right margins.
The Legend.TopLeftPos property can be used in Left Legend alignments to control vertical distance between Legend and Top Chart Margin.

These techniques allow almost complete Legend control.
Default value: Right

Returns:
LegendAlignment

setAlignment

public void setAlignment(LegendAlignment value)
Defines the Legend position.
Default value: Right

Parameters:
value - LegendAlignments
See Also:
LegLegendAlignment

getColumnWidth

public int getColumnWidth(int column)

setColumnWidth

public void setColumnWidth(int column,
                           int value)

getColumnWidthAuto

public boolean getColumnWidthAuto()
Automatically calculates best fit of legend columns.
When set to true, columnWidths control the legend width
Default value: true

Returns:
boolean

setColumnWidthAuto

public void setColumnWidthAuto(boolean value)
Automatically calculates best fit of legend columns.
When set to true, columnWidths control the legend width
Default value: true

Parameters:
value - boolean

getFirstValue

public int getFirstValue()
Defines which is the first Legend item displayed.
Legend can display all active Series names or all points of a single Series. FirstValue should be set accordingly, taking care not to overflow the number of active Series or the number of Series points. You can use FirstValue to show a specific subset of Series or points in Legend. It should be greater or equal to zero, and lower than the number of active Series or Series points. See Legend.LegendStyle for a description of the different Legend styles.
Default value: 0

Returns:
int

setFirstValue

public void setFirstValue(int value)
Determines which is the first Legend item displayed.
Default value: 0

Parameters:
value - int
See Also:
getFirstValue()

getTopLeftPos

public int getTopLeftPos()
Specifies the Legend's top position in percent of total chart height.
It's used when Legend.Alignment is Left or Right only. For Top or Bottom Legend alignments, you can use the Chart's MarginTop and MarginBottom.
Default value: 10

Returns:
int

setTopLeftPos

public void setTopLeftPos(int value)
Specifies the Legend's top position in percent of total chart height.
Default value: 10

Parameters:
value - int

getMaxNumRows

public int getMaxNumRows()
The Maximum number of Legend Rows displayed for a horizontal Legend (Chart Top or Bottom).
Default value: 10

Returns:
int

setMaxNumRows

public void setMaxNumRows(int value)
Sets the Maximum number of Legend Rows displayed for a horizontal Legend (Chart Top or Bottom).
Default value: 10

Parameters:
value - int

getLines

public java.lang.String[] getLines()
Description copied from class: TextShape
Accesses the array of Text lines.
Use lines to add multiline text to TeeChart's text objects (TeeChart Header, TeeChart Axis Titles etc.).
Default value: null

Overrides:
getLines in class TextShape
Returns:
String[]

setLines

public void setLines(java.lang.String[] value)
Description copied from class: TextShape
Accesses the array of Text lines.
Default value: null

Overrides:
setLines in class TextShape
Parameters:
value - String[]

getText

public java.lang.String getText()
Adds text to the Legend.

Overrides:
getText in class TextShape
Returns:
String

setText

public void setText(java.lang.String value)
Adds text to the Legend.

Overrides:
setText in class TextShape
Parameters:
value - String

getVertSpacing

public int getVertSpacing()
The vertical spacing between Legend iItems (pixels).
Default value: 0

Returns:
int

setVertSpacing

public void setVertSpacing(int value)
Determines the vertical spacing between Legend iItems (pixels).
Default value: 0

Parameters:
value - int

getHorizMargin

public int getHorizMargin()
Speficies the number of screen pixels between Legend and Chart rectangles.
By default it is 0, meaning Legend will calculate a predefined margin based on total Legend width. It is only used when Legend position is Left or Right aligned otherwise use VertMargin.
Default value: 0

Returns:
int

setHorizMargin

public void setHorizMargin(int value)
Speficies the number of screen pixels between Legend and Chart rectangles.
Default value: 0

Parameters:
value - int

getVertMargin

public int getVertMargin()
The vertical margin in pixels between Legend and Chart rectangle.
Legend.ResizeChart must be true and Legend.Alignment must be Top or Bottom. When 0, the corresponding Chart margin method is used to determine the amount of pixels for margins (Chart.MarginTop for Top Legend.alignment and Chart.MarginBottom for Bottom Legend.Alignment).
Default value: 0

Returns:
int

setVertMargin

public void setVertMargin(int value)
Determines the vertical margin in pixels between Legend and Chart rectangle.
Default value: 0

Parameters:
value - int

getResizeChart

public boolean getResizeChart()
Automatically resizes Chart rectangle to prevent overlap with Legend.
When set to true, Legend.HorizMargin and Legend.VertMargin control the amount of pixels by which the Chart rectangle will be reduced.
Default value: true

Returns:
boolean

setResizeChart

public void setResizeChart(boolean value)
Automatically resizes Chart rectangle to prevent overlap with Legend.
When set to true, Legend.HorizMargin and Legend.VertMargin control the amount of pixels by which the Chart rectangle will be reduced.
Default value: true

Parameters:
value - boolean

getLegendStyle

public LegendStyle getLegendStyle()
Defines which iItems will be displayed in the Chart Legend.
Series style shows the Series.Title of all active Series in a Chart. Whenever a Series Title is empty, Series Name is used.
Values style shows a text representation of all points of the first active Series in a Chart.
LastValues style shows the last point value and the Series.Title of all active Series in a Chart. It is useful for real-time charting, where new points are being added at the end of each Series.
Auto style (the default) means LegendStyle will be Series when there's more than one Active Series, and Values when there's only one Series in a Chart.
Legend.TextStyle determines how the Series point values are formatted.
Default value: auto

Returns:
LegendStyle

setLegendStyle

public void setLegendStyle(LegendStyle value)
Defines which iItems will be displayed in the Chart Legend.
Default value: Auto

Parameters:
value - LegendStyles
See Also:
getLegendStyle()

getTitle

public LegendTitle getTitle()
Sets the Title text and its characteristics at the top of the legend


doMouseDown

public boolean doMouseDown(Point p)

clicked

public int clicked(Point p)
Returns the index of the clicked Legend Point.

Parameters:
p - Point
Returns:
int

clicked

public int clicked(int x,
                   int y)
Returns the index of the clicked Legend Point.

Parameters:
x - int
y - int
Returns:
int

calcItemHeight

protected int calcItemHeight()

drawTitle

protected boolean drawTitle()

hasCheckBoxes

public boolean hasCheckBoxes()
Returns true when the legend displays checkboxes and it is showing series names.

Returns:
boolean

getVertical

public boolean getVertical()
Is read only and returns true only if the legend is left or right aligned.

Returns:
boolean

getColorWidth

public int getColorWidth()

setColorWidth

public void setColorWidth(int value)

getUseMaxWidth

public boolean getUseMaxWidth()

setUseMaxWidth

public void setUseMaxWidth(boolean value)

resizeChartRect

public Rectangle resizeChartRect(Rectangle rect)
Returns the chart rectangle minus the space occupied by the Legend.

Parameters:
rect - Rectangle
Returns:
Rectangle

paint

public void paint(IGraphics3D g,
                  Rectangle rect)
Description copied from class: TextShape
Paints the TextShape object on the Chart Canvas.

Overrides:
paint in class TextShape
Parameters:
g - IGraphics3D
rect - Rectangle

formattedLegend

public java.lang.String formattedLegend(int seriesOrValueIndex)
Returns the text string corresponding to a Legend position.
The Legend position depends on Legend.LegendStyle. If LegendStyle is lsSeries, then the text string will be the SeriesOrValueIndexth Active Series Title.
If LegendStyle is lsValues, then the text string will be the formatted SeriesOrValueIndexth value of the first Active Series in the Chart.
If LegendStyle is lsAuto and only one Active Series exists in the Chart, then the LegendStyle is considered to be lsValues.
If there is more than one Active Series then LegendStyle will be lsSeries.
Values are formatted accordingly to LegendTextStyle.

Parameters:
seriesOrValueIndex - int
Returns:
String

formattedValue

public java.lang.String formattedValue(Series aSeries,
                                       int valueIndex)
Returns the corresponding Legend text for the Series ValueIndex point.
Legend.LegendTextStyle is used to properly format the point values and labels.

Parameters:
aSeries - Series
valueIndex - int
Returns:
String

getLegendItems

public LegendItems getLegendItems()