IlvChartLegend Class Reference

Base class for legend objects. More...

#include <ilviews/charts/legend.h>

Inheritance diagram for IlvChartLegend:

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.
IlvChartLegendItem *	addLegendItem (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 IlvChartLegendItem *	createLegendItem (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 IlvChartGraphic *	getChartGraphic () const
	Returns the chart with which the current legend is associated.
IlvPalette *	getItemPalette () 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.
IlvChartLegendItem *	getLegendItem (const char *label) const
	Returns a legend item with a given label.
IlvChartLegendItem *	getLegendItem (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.

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:

The graphic part illustrates the graphical representation of data with which the legend item is associated. For example, for data displayed by markers, the graphic part will show a marker with the same color and shape.
The text part displays a description or a label for the represented data.

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.

Rogue Wave ViewsCharts Package API Reference Guide

IlvChartLegend Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Rogue Wave Views
Charts Package API Reference Guide