rwlogo
Rogue Wave Views 5.5.1

Rogue Wave Views
Charts Package API Reference Guide

Product Documentation:

Rogue Wave Views
Documentation Home

IlvChartLegend Class Reference

Base class for legend objects. More...

#include <ilviews/charts/legend.h>

Inheritance diagram for IlvChartLegend:
IlvShadowRectangle IlvFilledRectangle IlvRectangle IlvSimpleGraphic IlvGraphic

List of all members.

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

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.

img_legend.gif

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:
display The display that is used.
bbox The dimensions of the legend without taking into account the shadow.
boxWidth The width of the area where the graphic part of the legend item is displayed.
boxHeight The height of the area where the graphic part of the legend item is displayed.
itemPalette The 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.
showFrame The Boolean indicating whether the frame surrounding the legend is shown.
labelSpacing The space between the area where the graphic part is displayed and the label of a legend item.
itemSpacing The 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:
label The label of the new legend item.
dsp The displayer with which the legend item is associated.
clientData The client data for the new legend item. This client data is used to store additional information when necessary.
rank The 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.
Warning:
[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:
reDraw Indicates 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:
label The label of the created legend item.
dsp The displayer with which the created legend item is associated.
clientData The client data for the created legend item. This client data is used to store additional information when necessary.
Warning:
[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:
dst The port where the legend is drawn.
t The transformer for the drawing.
clip The 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:
dst The port where the frame surrounding the legend is drawn.
t The transformer used for the drawing.
clip The 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:
dst The port where the legend is drawn.
t The transformer used for the drawing.
clip The 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:
dir The 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 ( const char *  label  )  const

Returns a legend item with a given label.

Parameters:
label The 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.
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:
rank The index of the legend item.
Returns:
A pointer to the legend item at the index rank 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:
item The legend item for which we want to get the position.
col The index of the column in which the legend item item is located.
row The 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:
t The 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:
dsp The 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.

Warning:
[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:
autoFitToContents The new value of the Boolean 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:
autoRecompute The 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:
h The 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:
w The 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:
chart The new chart with which the current legend is associated.
Warning:
[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:
pal The new palette that will be used to display the legend items.
void IlvChartLegend::setItemSpacing ( IlUShort  spacing  ) 

Sets the space between the legend items.

Parameters:
spacing The 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:
spacing The 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:
transparent The 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:
showFrame The 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 2012, 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.