Rogue Wave Views
Charts Package API Reference Guide
Product Documentation:

Rogue Wave Views
Documentation Home
List of all members | Public Member Functions
IlvChartLegend Class Reference

Base class for legend objects. More...

#include <ilviews/charts/legend.h>

Inheritance diagram for IlvChartLegend:
IlvShadowRectangle IlvFilledRectangle IlvRectangle IlvSimpleGraphic IlvGraphic IlvValueInterface

Public Member Functions

 IlvChartLegend (IlvDisplay *display, const IlvRect &bbox, IlUShort boxWidth=20, IlUShort boxHeight=10, IlvPalette *itemPalette=0, IlBoolean showFrame=IlTrue, IlUShort labelSpacing=4, IlUShort itemSpacing=4)
 Constructor. More...
 
 ~IlvChartLegend ()
 Destructor. More...
 
IlvChartLegendItemaddLegendItem (const char *label, const IlvAbstractChartDisplayer *dsp, IlAny clientData=0, IlUInt rank=IlvLastPositionIndex)
 Adds a new legend item to the current legend. More...
 
void clearLegendItems (IlBoolean reDraw=IlFalse)
 Deletes all the legend items. More...
 
virtual IlvChartLegendItemcreateLegendItem (const char *label, const IlvAbstractChartDisplayer *dsp, IlAny clientData=0) const
 Creates a new legend item. More...
 
virtual void draw (IlvPort *dst, const IlvTransformer *t=0, const IlvRegion *clip=0) const
 Draws the legend. More...
 
virtual void drawFrame (IlvPort *dst, const IlvTransformer *t=0, const IlvRegion *clip=0) const
 Draws the frame surrounding the legend. More...
 
virtual void drawGhost (IlvPort *dst, const IlvTransformer *t=0, const IlvRegion *clip=0) const
 Draws a ghost of the legend. More...
 
virtual void fitToContents (IlvDirection dir=IlvBadPosition)
 Resizes the legend to show exactly all its contents. More...
 
IlUShort getBoxHeight () const
 Returns the height of the area where the graphic part of the legend items is displayed. More...
 
IlUShort getBoxWidth () const
 Returns the width of the area where the graphic part of the legend items is displayed. More...
 
const IlvChartGraphicgetChartGraphic () const
 Returns the chart with which the current legend is associated. More...
 
IlvPalettegetItemPalette () const
 Returns the palette used to display the legend items. More...
 
IlUShort getItemSpacing () const
 Returns the space between the legend items. More...
 
IlUShort getLabelSpacing () const
 Returns the space between the area where the graphic part is displayed and the label of a legend item. More...
 
IlvChartLegendItemgetLegendItem (IlUInt rank) const
 Returns a legend item at a given index. More...
 
IlvChartLegendItemgetLegendItem (const char *label) const
 Returns a legend item with a given label. More...
 
IlBoolean getLegendItemPosition (IlvChartLegendItem *item, IlUInt &col, IlUInt &row) const
 Returns the column and the row of a legend item. More...
 
IlUInt getNumberOfItems () const
 Returns the number of legend items. More...
 
IlBoolean isAutoFitting () const
 Indicates whether the legend is automatically resized to fit the legend items that it contains. More...
 
IlBoolean isAutoRecomputing () const
 Indicates whether the arrangement of the legend items is automatically recomputed. More...
 
IlBoolean isShowingFrame () const
 Indicates whether the frame surrounding the current legend is shown. More...
 
IlBoolean isTransparent () const
 Indicates the transparency of the current legend. More...
 
virtual void organizeLegendItems (const IlvTransformer *t=0)
 Computes the arrangement of the legend items. More...
 
void removeLegendItems (const IlvAbstractChartDisplayer *dsp)
 Removes the legend items associated with a given displayer. More...
 
void setAutoFit (IlBoolean autoFitToContents)
 Specifies that the legend is automatically resized to fit the legend items that it contains. More...
 
void setAutoRecompute (IlBoolean autoRecompute)
 Specifies that the arrangement of the legend items is automatically recomputed. More...
 
void setBoxHeight (IlUShort h)
 Sets the height of the area where the graphic part of the legend items is displayed. More...
 
void setBoxWidth (IlUShort w)
 Sets the width of the area where the graphic part of the legend items is displayed. More...
 
void setChartGraphic (IlvChartGraphic *chart)
 Sets the chart with which the current legend is associated. More...
 
void setItemPalette (IlvPalette *pal)
 Sets the palette used to display the legend items. More...
 
void setItemSpacing (IlUShort spacing)
 Sets the space between the legend items. More...
 
void setLabelSpacing (IlUShort spacing)
 Sets the space between the area where the graphic part is displayed and the label of a legend item. More...
 
void setTransparent (IlBoolean transparent)
 Specifies the transparency of the current legend. More...
 
void showFrame (IlBoolean showFrame)
 Specifies that the frame surrounding the current legend is shown. More...
 
virtual IlBoolean zoomable () const
 Indicates whether the legend is zoomable. More...
 

Detailed Description

Base class for legend objects.

Library: ilvcharts

This class allows you to define a legend that can be added to a given chart. It inherits from the IlvShadowRectangle class. Thus, the chart legend is a graphic object and can be positioned independently of the chart. By default, the legend is drawn surrounded by a filled rectangle with a shadow. It can be drawn without background and shadow if the Boolean indicating that the legend is transparent is set to IlTrue (see the IlvChartLegend::setTransparent method).

The following figure shows an example of a legend for a given chart. This legend is composed of six legend items and is surrounded by a filled rectangle with a shadow.

The legend items that make up the legend are represented by instances of the IlvChartLegendItem class. Each legend item is composed of a graphic part and a text part:

When a legend object is created, it does not contain any legend items. The legend items corresponding to the displayers defined in a chart will be computed automatically and added to the legend when the legend is set on the chart.

See also
IlvShadowRectangle, IlvChartLegendItem, IlvChartGraphic, IlvAbstractChartDisplayer.

Constructor & Destructor Documentation

IlvChartLegend::IlvChartLegend ( IlvDisplay display,
const IlvRect bbox,
IlUShort  boxWidth = 20,
IlUShort  boxHeight = 10,
IlvPalette itemPalette = 0,
IlBoolean  showFrame = IlTrue,
IlUShort  labelSpacing = 4,
IlUShort  itemSpacing = 4 
)

Constructor.

Initializes a new IlvChartLegend object. By default, the chart with which the current legend is associated is set to 0, the shadow thickness of the frame to 2, and the shadow position to IlvBottomRight.
By default, the legend is not transparent (that is, the legend is drawn with a background and a shadow), the arrangement of the legend items is automatically recomputed and the legend is resized automatically to fit the legend items it contains.

Parameters
displayThe display that is used.
bboxThe dimensions of the legend without taking into account the shadow.
boxWidthThe width of the area where the graphic part of the legend item is displayed.
boxHeightThe height of the area where the graphic part of the legend item is displayed.
itemPaletteThe palette used to display the legend items. If itemPalette is 0, the default palette of the display display is set as the palette used to display the legend items.
showFrameThe Boolean indicating whether the frame surrounding the legend is shown.
labelSpacingThe space between the area where the graphic part is displayed and the label of a legend item.
itemSpacingThe space between the legend items.
IlvChartLegend::~IlvChartLegend ( )

Destructor.

This destructor unlocks the item palette if it is defined, clears the current legend from the chart with which it is associated, and sets the stored pointer to the chart to 0.

Member Function Documentation

IlvChartLegendItem* IlvChartLegend::addLegendItem ( const char *  label,
const IlvAbstractChartDisplayer dsp,
IlAny  clientData = 0,
IlUInt  rank = IlvLastPositionIndex 
)

Adds a new legend item to the current legend.

The new legend item is associated with the graphical representation of the data displayed by the displayer dsp.

Parameters
labelThe label of the new legend item.
dspThe displayer with which the legend item is associated.
clientDataThe client data for the new legend item. This client data is used to store additional information when necessary.
rankThe index at which the new legend item is added to the current legend. If rank is equal to IlvLastPositionIndex, the legend item is added at the end.
Note
Inside the addLegendItem() method, the legend item is created with the parameters passed to this method by calling the IlvChartLegend::createLegendItem() method before being added to the current legend.
void IlvChartLegend::clearLegendItems ( IlBoolean  reDraw = IlFalse)

Deletes all the legend items.

If the Boolean reDraw is set to IlTrue, the legend is redrawn.

Parameters
reDrawIndicates whether the legend must be redrawn after the legend items have been deleted.
virtual IlvChartLegendItem* IlvChartLegend::createLegendItem ( const char *  label,
const IlvAbstractChartDisplayer dsp,
IlAny  clientData = 0 
) const
virtual

Creates a new legend item.

Parameters
labelThe label of the created legend item.
dspThe displayer with which the created legend item is associated.
clientDataThe client data for the created legend item. This client data is used to store additional information when necessary.
Note
This method is called inside the IlvChartLegend::addLegendItem() method in order to create the corresponding legend item in the current legend. This method is for internal use only and should not be called directly by the user.
virtual void IlvChartLegend::draw ( IlvPort dst,
const IlvTransformer t = 0,
const IlvRegion clip = 0 
) const
virtual

Draws the legend.

Draws the legend in the port named dst using the transformer t and the clipping region clip. If the drawing mode of the legend palette is different from IlvModeSet, the ghost of the legend is drawn. Otherwise, the legend is drawn normally. The frame surrounding the legend is drawn by calling the IlvChartLegend::drawFrame method if the Boolean indicating that the surrounding frame is shown is set to IlTrue. The legend items are then drawn. If no legend items are defined, the name of the class is displayed instead.

Parameters
dstThe port where the legend is drawn.
tThe transformer for the drawing.
clipThe clipping region used for the drawing.

Reimplemented from IlvShadowRectangle.

virtual void IlvChartLegend::drawFrame ( IlvPort dst,
const IlvTransformer t = 0,
const IlvRegion clip = 0 
) const
virtual

Draws the frame surrounding the legend.

Draws the frame surrounding the legend in the port named dst using the transformer t and the clipping region clip. If the Boolean indicating that the legend is transparent is set to IlTrue (see the IlvChartLegend::setTransparent method), only a simple rectangle is drawn. Otherwise, a filled rectangle with a shadow is drawn. (See the figure in the Detailed Description paragraph.)

Parameters
dstThe port where the frame surrounding the legend is drawn.
tThe transformer used for the drawing.
clipThe clipping region used for the drawing.
virtual void IlvChartLegend::drawGhost ( IlvPort dst,
const IlvTransformer t = 0,
const IlvRegion clip = 0 
) const
virtual

Draws a ghost of the legend.

Draws a ghost of the legend in the port named dst using the transformer t and the clipping region clip. This method first calls the IlvChartLegend::drawFrame method if the Boolean indicating that the surrounding frame is shown is set to IlTrue (see the IlvChartLegend::isShowingFrame method). It then draws lines separating the legend items with an inverted palette. The legend items themselves are not drawn.

Parameters
dstThe port where the legend is drawn.
tThe transformer used for the drawing.
clipThe clipping region used for the drawing.
virtual void IlvChartLegend::fitToContents ( IlvDirection  dir = IlvBadPosition)
virtual

Resizes the legend to show exactly all its contents.

Resizes the legend in the direction dir so that all of its contents are exactly shown.

Parameters
dirThe direction in which the legend is resized.
IlUShort IlvChartLegend::getBoxHeight ( ) const

Returns the height of the area where the graphic part of the legend items is displayed.

Returns
The height of the area where the graphic part of the legend items is displayed.
IlUShort IlvChartLegend::getBoxWidth ( ) const

Returns the width of the area where the graphic part of the legend items is displayed.

Returns
The width of the area where the graphic part of the legend items is displayed.
const IlvChartGraphic* IlvChartLegend::getChartGraphic ( ) const

Returns the chart with which the current legend is associated.

Returns
A pointer to the chart with which the current legend is associated.
IlvPalette* IlvChartLegend::getItemPalette ( ) const

Returns the palette used to display the legend items.

Returns
A pointer to the palette used to display the legend items.
IlUShort IlvChartLegend::getItemSpacing ( ) const

Returns the space between the legend items.

Returns
The space between the legend items.
IlUShort IlvChartLegend::getLabelSpacing ( ) const

Returns the space between the area where the graphic part is displayed and the label of a legend item.

Returns
The space between the area where the graphic part is displayed and the label of a legend item.
IlvChartLegendItem* IlvChartLegend::getLegendItem ( IlUInt  rank) const

Returns a legend item at a given index.

Returns a pointer to the legend item at the index rank in the current legend.

Parameters
rankThe index of the legend item.
Returns
A pointer to the legend item at the index rank if it exists, and 0 otherwise.
IlvChartLegendItem* IlvChartLegend::getLegendItem ( const char *  label) const

Returns a legend item with a given label.

Parameters
labelThe label of the legend item to be returned.
Returns
A pointer to the legend item with the label label if it exists, and 0 otherwise.
IlBoolean IlvChartLegend::getLegendItemPosition ( IlvChartLegendItem item,
IlUInt col,
IlUInt row 
) const

Returns the column and the row of a legend item.

The legend items are arranged in columns and rows in a legend. (See the figure in the Detailed Description paragraph.) This method returns in col and row, the indexes of the column and the row where the legend item item is located.

Parameters
itemThe legend item for which we want to get the position.
colThe index of the column in which the legend item item is located.
rowThe index of the row in which the legend item item is located.
IlUInt IlvChartLegend::getNumberOfItems ( ) const

Returns the number of legend items.

Returns
The number of legend items for the current legend.
IlBoolean IlvChartLegend::isAutoFitting ( ) const

Indicates whether the legend is automatically resized to fit the legend items that it contains.

Returns
IlTrue if the legend is automatically resized to fit the legend items that it contains and IlFalse otherwise.
See also
setAutoFit.
IlBoolean IlvChartLegend::isAutoRecomputing ( ) const

Indicates whether the arrangement of the legend items is automatically recomputed.

Returns
IlTrue if the arrangement of the legend items is automatically recomputed and IlFalse otherwise.
See also
setAutoRecompute.
IlBoolean IlvChartLegend::isShowingFrame ( ) const

Indicates whether the frame surrounding the current legend is shown.

Returns
IlTrue if the frame surrounding the current legend is shown and IlFalse otherwise.
See also
showFrame.
IlBoolean IlvChartLegend::isTransparent ( ) const

Indicates the transparency of the current legend.

Returns
IlTrue if the current legend is transparent and IlFalse otherwise.
See also
setTransparent.
virtual void IlvChartLegend::organizeLegendItems ( const IlvTransformer t = 0)
virtual

Computes the arrangement of the legend items.

Using the current size of the legend, this method divides the available space into columns and rows. It then arranges the legend items accordingly.

Parameters
tThe transformer that is applied to the legend.
void IlvChartLegend::removeLegendItems ( const IlvAbstractChartDisplayer dsp)

Removes the legend items associated with a given displayer.

Removes the legend items associated with the graphical representation of the data displayed by the displayer dsp.

Parameters
dspThe displayer with which the legend items are associated.
void IlvChartLegend::setAutoFit ( IlBoolean  autoFitToContents)

Specifies that the legend is automatically resized to fit the legend items that it contains.

Note
If you do not want the size of the legend to be systematically recomputed from the legend items, you have to set this flag to IlFalse.
Parameters
autoFitToContentsThe new value of the flag indicating whether the legend is automatically resized to fit the legend items that it contains.
void IlvChartLegend::setAutoRecompute ( IlBoolean  autoRecompute)

Specifies that the arrangement of the legend items is automatically recomputed.

When a legend is in automatic arrangement mode, the legend items corresponding to the displayers defined in a chart are automatically computed and added to the legend when the legend is set on the chart.

The automatic arrangement of the legend items is also performed when the legend is resized, when the inner spacing of the legend is modified, and so on. New legend items are also added automatically and arranged when new displayers are added to the chart.

Parameters
autoRecomputeThe new value of the Boolean indicating whether the arrangement of the legend items is automatically recomputed.
void IlvChartLegend::setBoxHeight ( IlUShort  h)

Sets the height of the area where the graphic part of the legend items is displayed.

Parameters
hThe new height of the area where the graphic part of the legend items is defined.
void IlvChartLegend::setBoxWidth ( IlUShort  w)

Sets the width of the area where the graphic part of the legend items is displayed.

Parameters
wThe new width of the area where the graphic part of the legend items is displayed.
void IlvChartLegend::setChartGraphic ( IlvChartGraphic chart)

Sets the chart with which the current legend is associated.

Parameters
chartThe new chart with which the current legend is associated.
Note
This method is for internal use only and should not be used directly by the user. The chart with which the current legend is associated is automatically set when the legend is set on this chart. Therefore, the chart with which the current legend is associated does not need to be set by hand.
void IlvChartLegend::setItemPalette ( IlvPalette pal)

Sets the palette used to display the legend items.

The old palette, if it exists, is unlocked. The new palette is locked. (See the methods IlvResource::lock and IlvResource::unLock for more details.)

Parameters
palThe new palette that will be used to display the legend items.
void IlvChartLegend::setItemSpacing ( IlUShort  spacing)

Sets the space between the legend items.

Parameters
spacingThe new space between the legend items.
void IlvChartLegend::setLabelSpacing ( IlUShort  spacing)

Sets the space between the area where the graphic part is displayed and the label of a legend item.

Parameters
spacingThe new space between the area where the graphic part is displayed and the label of a legend item.
void IlvChartLegend::setTransparent ( IlBoolean  transparent)

Specifies the transparency of the current legend.

Parameters
transparentThe new value of the Boolean indicating whether the current legend is transparent. If transparent is IlTrue, the legend is set as transparent and appears without a background and a shadow.
void IlvChartLegend::showFrame ( IlBoolean  showFrame)

Specifies that the frame surrounding the current legend is shown.

Parameters
showFrameThe new value of the Boolean indicating whether the frame surrounding the legend is shown. If showFrame is IlTrue, the frame is shown.
virtual IlBoolean IlvChartLegend::zoomable ( ) const
virtual

Indicates whether the legend is zoomable.

Returns a Boolean indicating whether the legend is zoomable.

Returns
IlFalse by default.

Reimplemented from IlvGraphic.


© Copyright 2016, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.