Abstract base class for managing all the data displayed within a chart. More...

#include <ilviews/charts/data.h>

Inheritance diagram for IlvAbstractChartData:

Public Member Functions
virtual	~IlvAbstractChartData ()
	Destructor. More...

virtual IlBoolean	addDataSet (IlvChartDataSet *dataSet, IlBoolean copy=IlFalse)=0
	Adds a managed data set. More...

void	addListener (IlvChartDataListener *lst)
	Adds a listener. More...

virtual IlvAbstractChartData *	copy () const =0
	Creates and returns a copy of the current object. More...

virtual void	dataAllPointsRemoved (const IlvChartDataSet *ds) const
	Performs the updates needed when a data point is removed. More...

virtual void	dataPointAdded (const IlvChartDataSet *dataSet, IlUInt position) const
	Performs the updates needed when a data point is added. More...

virtual void	dataPointChanged (const IlvChartDataSet *dataSet, IlUInt ptidx, IlBoolean beforeChange) const
	Performs the updates needed when a data point is changed. More...

virtual void	dataPointRemoved (const IlvChartDataSet *dataSet, IlUInt ptidx) const
	Performs the updates needed when a data point is removed. More...

virtual void	dataSetAdded (IlvChartDataSet *dataSet, IlUInt position)
	Performs the updates needed when a data set is added. More...

virtual void	dataSetChanged (IlvChartDataSet oldSet, IlvChartDataSet newSet)
	Performs the updates needed when a data set is changed. More...

virtual void	dataSetRemoved (IlvChartDataSet *dataSet)
	Performs the necessary updates when a data set is removed. More...

virtual void	endBatch (const IlvChartDataSet *dataSet) const
	Specifies the end of a set of modifications on a data set. More...

virtual IlvChartDataSet *	getDataSet (IlUInt index) const =0
	Gets a managed data set by its index. More...

IlvChartDataSet *	getDataSetByName (const char *name) const
	Gets a managed data set by its name. More...

IlUInt	getDataSetIndex (const IlvChartDataSet *dataSet) const
	Returns the index of a managed data set. More...

virtual IlvChartDataSet const	getDataSets (IlUInt &nbDataSets) const
	Returns all the managed data sets. More...

virtual IlUInt	getDataSetsCount () const =0
	Returns the number of managed data sets. More...

IlvChartDataListener const	getListeners (IlUInt &count) const
	Returns all the listeners. More...

virtual IlBoolean	insertDataSet (IlvChartDataSet *dataSet, IlUInt index=IlvLastPositionIndex, IlBoolean copy=IlFalse)=0
	Inserts a managed data set. More...

virtual IlBoolean	isLimited () const
	Indicates whether the number of managed data sets is limited. More...

virtual IlBoolean	isRemovalAllowed () const
	Indicates whether the managed data sets can be removed. More...

virtual IlBoolean	isWritable () const
	Indicates whether the managed data sets can be modified. More...

void	lock ()
	Locks the current `IlvAbstractChartData` object. More...

IlvChartDataSet *	operator[] (IlUInt index)
	Gets a managed data set by its index. More...

const IlvChartDataSet *	operator[] (IlUInt index) const
	Gets a managed data set by its index. More...

virtual IlBoolean	removeDataSet (IlUInt dataSetIndex)=0
	Removes a managed data set. More...

virtual void	removeDataSets ()=0
	Removes all the managed data sets. More...

IlvChartDataListener *	removeListener (IlvChartDataListener *lst)
	Removes a listener. More...

void	removeListeners ()
	Removes all the listeners.

IlBoolean	replaceDataSet (IlvChartDataSet oldDataSet, IlvChartDataSet newDataSet)
	Replaces a managed data set by another one. More...

IlvOutputFile &	save (IlvOutputFile &file) const
	Writes a complete description of the current object in a file. More...

virtual IlBoolean	setDataSet (IlUInt dataSetIndex, IlvChartDataSet *dataSet, IlBoolean copy=IlFalse)=0
	Sets a managed data set. More...

virtual IlBoolean	setDataSets (IlUInt &count, IlvChartDataSet const dataSets, IlBoolean copy=IlFalse)=0
	Sets the managed data sets. More...

virtual void	startBatch (const IlvChartDataSet *dataSet) const
	Specifies the beginning of a set of modifications on a data set. More...

void	unLock ()
	Unlocks the current `IlvAbstractChartData` object. More...

virtual void	write (IlvOutputFile &file) const =0
	Writes the attributes of the current object in a file. More...

Static Public Member Functions
static IlvAbstractChartData *	Load (IlvInputFile &file)
	Reads a chart data object from a file. More...

Protected Member Functions
	IlvAbstractChartData ()
	Initializes a new `IlvAbstractChartData` object.

	IlvAbstractChartData (const IlvAbstractChartData &cData)
	Initializes a new `IlvAbstractChartData` object as a copy of another `IlvAbstractChartData`. More...

	IlvAbstractChartData (IlvInputFile &file)
	Initializes a new `IlvAbstractChartData` object from an input file. More...

Detailed Description

Abstract base class for managing all the data displayed within a chart.

Library: ilvcharts
This abstract class manages all the data that are displayed within a chart.

These data are divided into data sets. Each data set can be displayed with a given type of representation (for example, markers or polylines).

A data set is represented by an IlvChartDataSet object and so the IlvAbstractChartData class manages a set of IlvChartDataSet objects.

A lock/unlock system is provided to share an object managing the data among different charts. The lock/unlock system ensures that the object will not be deleted as long as an object needs it. (See the methods IlvAbstractChartData::lock() and IlvAbstractChartData::unLock() methods for more details.)

In order to propagate all modifications that are made to an IlvAbstractChartData object (or one of its derived objects) to all the objects that use it (which is the case for all the chart graphics that use it to manage the data sets they display), listeners are set on the IlvAbstractChartData object.

These listeners are automatically set when a derived object of IlvAbstractChartData is set on a chart graphic as the object used to manage the data it displays.

Note: IlvAbstractChartData is an abstract class. Its constructors are defined as protected because it is not possible to create an instance of this class directly.

See also: IlvMemoryChartData, IlvChartDataSet, IlvChartDataListener.

Constructor & Destructor Documentation

§ ~IlvAbstractChartData()

virtual IlvAbstractChartData::~IlvAbstractChartData ( )

virtual

Destructor.

The destructor removes the listeners that have been added to the current object.

§ IlvAbstractChartData() [1/2]

IlvAbstractChartData::IlvAbstractChartData ( const IlvAbstractChartData & cData )

protected

Initializes a new IlvAbstractChartData object as a copy of another IlvAbstractChartData.

Parameters

cData The object used to initialize the new one.

§ IlvAbstractChartData() [2/2]

IlvAbstractChartData::IlvAbstractChartData ( IlvInputFile & file )

protected

Initializes a new IlvAbstractChartData object from an input file.

Parameters

file	The file that is read to initialize the new chart data object.

Member Function Documentation

§ addDataSet()

virtual IlBoolean IlvAbstractChartData::addDataSet	(	IlvChartDataSet *	dataSet,
		IlBoolean	copy = `IlFalse`
	)

pure virtual

Adds a managed data set.

Parameters

dataSet	The data set to add to the current object.
copy	Indicates whether the data set passed as a parameter must be copied. If copy is `IlTrue`, the data set is copied. Otherwise, a pointer to the data set stored in dataSet is kept. Therefore, its contents should not be deleted.

Returns: IlTrue if the data set has been successfully added or IlFalse otherwise.

Note: When you add a data set, the new data set is locked.

Implemented in IlvMemoryChartData, and IlvXMLChartData.

§ addListener()

void IlvAbstractChartData::addListener ( IlvChartDataListener * lst )

Adds a listener.

Parameters

lst	The new listener that is added to the current object.

§ copy()

virtual IlvAbstractChartData* IlvAbstractChartData::copy ( ) const

pure virtual

Creates and returns a copy of the current object.

This method must be overloaded in subclasses. It is automatically declared by the DeclareChartDataTypeInfo macro. The IlvPredefinedChartDataIOMembers macro lets you define a default implementation, which returns an instance initialized with the copy constructor.

Returns: A copy of the current object.

Implemented in IlvXMLChartData.

§ dataAllPointsRemoved()

virtual void IlvAbstractChartData::dataAllPointsRemoved ( const IlvChartDataSet * ds ) const

virtual

Performs the updates needed when a data point is removed.

The modification is propagated to the listeners by calling the IlvChartDataListener::dataPointRemoved() method for each listener defined for the current object.

Parameters

ds	The data set of the current object from which a data point is removed.

§ dataPointAdded()

virtual void IlvAbstractChartData::dataPointAdded	(	const IlvChartDataSet *	dataSet,
		IlUInt	position
	)		const

virtual

Performs the updates needed when a data point is added.

The modification is propagated to the listeners by calling the IlvChartDataListener::dataPointAdded() method for each listener defined for the current object.

Parameters

dataSet	The data set of the current object to which a data point is added.
position	The index at which the data point is added in the data set dataSet.

§ dataPointChanged()

virtual void IlvAbstractChartData::dataPointChanged	(	const IlvChartDataSet *	dataSet,
		IlUInt	ptidx,
		IlBoolean	beforeChange
	)		const

virtual

Performs the updates needed when a data point is changed.

The modification is propagated to the listeners by calling the IlvChartDataListener::dataPointChanged() method for each listener defined for the current object.

Parameters

dataSet	The data set of the current object in which a data point is changed.
ptidx	The index at which the data point is changed in the data set dataSet.
beforeChange	indicates whether the method is called before the data point is changed or after it has been changed.

§ dataPointRemoved()

virtual void IlvAbstractChartData::dataPointRemoved	(	const IlvChartDataSet *	dataSet,
		IlUInt	ptidx
	)		const

virtual

Performs the updates needed when a data point is removed.

The modification is propagated to the listeners by calling the IlvChartDataListener::dataPointRemoved() method for each listener defined for the current object.

Parameters

dataSet	The data set of the current object from which a data point is removed.
ptidx	The index of the data point that is removed from the data set dataSet.

§ dataSetAdded()

virtual void IlvAbstractChartData::dataSetAdded	(	IlvChartDataSet *	dataSet,
		IlUInt	position
	)

virtual

Performs the updates needed when a data set is added.

The modification is propagated to the listeners by calling the IlvChartDataListener::dataSetAdded() method for each listener defined for the current object.

Parameters

dataSet	The data set that is added to the current object.
position	The index at which the data set is added to the current object.

§ dataSetChanged()

virtual void IlvAbstractChartData::dataSetChanged	(	IlvChartDataSet *	oldSet,
		IlvChartDataSet *	newSet
	)

virtual

Performs the updates needed when a data set is changed.

The modification is propagated to the listeners by calling the IlvChartDataListener::dataSetChanged() method for each listener defined for the current object.

Parameters

oldSet	The old data set before the change in the current object.
newSet	The new data set that replaces the old data set oldSet in the current object.

§ dataSetRemoved()

virtual void IlvAbstractChartData::dataSetRemoved ( IlvChartDataSet * dataSet )

virtual

Performs the necessary updates when a data set is removed.

The modification is propagated to the listeners by calling the IlvChartDataListener::dataSetRemoved() method for each listener defined for the current object.

Parameters

dataSet The data set that is removed from the current object.

§ endBatch()

virtual void IlvAbstractChartData::endBatch ( const IlvChartDataSet * dataSet ) const

virtual

Specifies the end of a set of modifications on a data set.

The purpose of this method is to notify all the subscribed listeners that a set of modifications has occurred on the data set dataSet.

Parameters

dataSet The data set that is modified.

§ getDataSet()

virtual IlvChartDataSet* IlvAbstractChartData::getDataSet ( IlUInt index ) const

pure virtual

Gets a managed data set by its index.

Parameters

index The index of the returned data set in the current object.

Returns: A pointer to the data set at the index index if it exists and 0 otherwise.

Note: The data set object must not be deleted by the user since it is maintained internally.

Implemented in IlvMemoryChartData, and IlvXMLChartData.

§ getDataSetByName()

IlvChartDataSet* IlvAbstractChartData::getDataSetByName ( const char * name ) const

Gets a managed data set by its name.

Parameters

name	The name of the returned data set in the current object.

Returns: A pointer to the data set with the name name if it exists and 0 otherwise.

Note: The data set object must not be deleted by the user since it is maintained internally.

§ getDataSetIndex()

IlUInt IlvAbstractChartData::getDataSetIndex ( const IlvChartDataSet * dataSet ) const

Returns the index of a managed data set.

Parameters

dataSet The data set for which we want to get the index.

Returns: The index of the data set dataSet in the set of managed data sets if dataSet belongs to this set. Otherwise, it returns IlvBadIndex.

§ getDataSets()

virtual IlvChartDataSet* const* IlvAbstractChartData::getDataSets ( IlUInt & nbDataSets ) const

virtual

Returns all the managed data sets.

Parameters

nbDataSets The number of data sets managed by the current object.

Returns: An array of pointers to all the data sets managed by the current object.

Note: The array is stored in an IlPoolOf(Pointer) and should not be deleted or modified.

Reimplemented in IlvXMLChartData.

§ getDataSetsCount()

virtual IlUInt IlvAbstractChartData::getDataSetsCount ( ) const

pure virtual

Returns the number of managed data sets.

Returns: The number of data sets managed by this object.

Implemented in IlvMemoryChartData, and IlvXMLChartData.

§ getListeners()

IlvChartDataListener* const* IlvAbstractChartData::getListeners ( IlUInt & count ) const

Returns all the listeners.

Parameters

count The number of listeners defined for the current object.

Returns: An array of all the listeners defined for the current object.

Note: The returned array should not be freed or reallocated directly since it is maintained internally.

§ insertDataSet()

virtual IlBoolean IlvAbstractChartData::insertDataSet	(	IlvChartDataSet *	dataSet,
		IlUInt	index = `IlvLastPositionIndex`,
		IlBoolean	copy = `IlFalse`
	)

pure virtual

Inserts a managed data set.

Parameters

dataSet	The data set to insert in the current object.
index	The index at which the data set dataSet must be inserted in the current object.
copy	Indicates whether the data set passed as a parameter must be copied. If copy is `IlTrue`, the data set is copied. Otherwise, a pointer to the data set stored in dataSet is kept. Therefore, its contents should not be deleted.

Returns: IlTrue if the data set has been successfully inserted or IlFalse otherwise.

Note: When you insert a data set, the new data set is locked.

Implemented in IlvMemoryChartData, and IlvXMLChartData.

§ isLimited()

virtual IlBoolean IlvAbstractChartData::isLimited ( ) const

virtual

Indicates whether the number of managed data sets is limited.

Returns a value that indicates whether the number of data sets that can be managed by the object is limited.

Returns: IlFalse by default.

Reimplemented in IlvMemoryChartData, and IlvXMLChartData.

§ isRemovalAllowed()

virtual IlBoolean IlvAbstractChartData::isRemovalAllowed ( ) const

virtual

Indicates whether the managed data sets can be removed.

Returns a value that indicates whether the data can be removed.

Returns: IlTrue by default.

Note: This method can be useful, for example, when you want to write your own subclass to have access to data in a database and the data cannot be removed from the database.

Reimplemented in IlvXMLChartData.

§ isWritable()

virtual IlBoolean IlvAbstractChartData::isWritable ( ) const

virtual

Indicates whether the managed data sets can be modified.

Returns a value that indicates whether the existing data can be modified or whether new data sets can be created.

Returns: IlTrue by default.

Note: This method can be useful, for example, when you want to write your own subclass to have access to data in a database and the database cannot be modified.

Reimplemented in IlvXMLChartData.

§ Load()

static IlvAbstractChartData* IlvAbstractChartData::Load ( IlvInputFile & file )

static

Reads a chart data object from a file.

Creates a chart data instance from the description stored in the file file. The object description must have been written with the IlvAbstractChartData::save() method.

Parameters

file	The file where the object description is stored.

Returns: A pointer to the created object.

§ lock()

void IlvAbstractChartData::lock ( )

Locks the current IlvAbstractChartData object.

Ensures that the IlvAbstractChartData will not be destroyed before it is unlocked.
This method increments a reference count initially set to 0. When you keep a pointer to an IlvAbstractChartData object (because you store it in the field of an object or it is in a variable), you should lock it for the duration of its use so that it is not destroyed by some other object or component. When you do not need the IlvAbstractChartData any more, you should release it with a call to unLock(); if the lock you just removed was the last one, Rogue Wave Views will free the IlvAbstractChartData.

§ operator[]() [1/2]

IlvChartDataSet* IlvAbstractChartData::operator[] ( IlUInt index )

Gets a managed data set by its index.

Parameters

index The index of the returned data set in the current object.

Returns: A pointer to the data set at the index index if it exists and 0 otherwise.

Note: The data set object must not be deleted by the user since it is maintained internally.

§ operator[]() [2/2]

const IlvChartDataSet* IlvAbstractChartData::operator[] ( IlUInt index ) const

Gets a managed data set by its index.

Parameters

index The index of the returned data set in the current object.

Returns: A pointer to the data set at the index index if it exists and 0 otherwise.

§ removeDataSet()

virtual IlBoolean IlvAbstractChartData::removeDataSet ( IlUInt dataSetIndex )

pure virtual

Removes a managed data set.

Parameters

dataSetIndex The index at which the data set must be removed from the current object.

Returns: IlTrue if the data set has been removed or IlFalse otherwise.

Note: When you remove a data set, the data set is not deleted but unlocked (that is, the IlvChartDataSet::unLock() method is called). It will be deleted only when no objects reference it.

Implemented in IlvMemoryChartData, and IlvXMLChartData.

§ removeDataSets()

virtual void IlvAbstractChartData::removeDataSets ( )

pure virtual

Removes all the managed data sets.

Note: When you remove a data set, the data set is not deleted but unlocked (that is, the IlvChartDataSet::unLock() method is called). It will be deleted only when no objects reference it.

Implemented in IlvMemoryChartData, and IlvXMLChartData.

§ removeListener()

IlvChartDataListener* IlvAbstractChartData::removeListener ( IlvChartDataListener * lst )

Removes a listener.

Parameters

lst	The listener that is removed from the current object.

Returns: A pointer to the removed listener when the listener passed as parameter is one of the listeners of the current object and 0 otherwise.

Note: The listener is not deleted. The caller is responsible for deleting the listener.

§ replaceDataSet()

IlBoolean IlvAbstractChartData::replaceDataSet	(	IlvChartDataSet *	oldDataSet,
		IlvChartDataSet *	newDataSet
	)

Replaces a managed data set by another one.

Parameters

oldDataSet	The old data set that must be replaced in the current object.
newDataSet	The new data set that replaces the old data set oldDataSet in the current object.

Returns: IlTrue if the data set replacement has been successfully performed and IlFalse otherwise.

§ save()

IlvOutputFile& IlvAbstractChartData::save ( IlvOutputFile & file ) const

Writes a complete description of the current object in a file.

Writes the complete object description in a file. This description contains all the information necessary to read back this object with the IlvAbstractChartData::Load() member function. This method first writes information regarding the type of the object and calls the IlvAbstractChartData::write() method.

Parameters

file	The file where the complete object description is written.

§ setDataSet()

virtual IlBoolean IlvAbstractChartData::setDataSet	(	IlUInt	dataSetIndex,
		IlvChartDataSet *	dataSet,
		IlBoolean	copy = `IlFalse`
	)

pure virtual

Sets a managed data set.

If a data set already exists at the index dataSetIndex, the data set is replaced by the new one. Otherwise, the new one is added at the end.

Parameters

dataSetIndex	The index at which the data set dataSet must be set in the current object.
dataSet	The data set to set in the current object.
copy	Indicates whether the data set passed as a parameter must be copied. If copy is `IlTrue`, the data set is copied. Otherwise, a pointer to the data set stored in dataSet is kept. Therefore, its contents should not be deleted.

Returns: IlTrue if the data set has been successfully set or IlFalse otherwise.

Note: When you set a data set, the new data set is locked and the old one, if it exists, is unlocked.

Implemented in IlvMemoryChartData, and IlvXMLChartData.

§ setDataSets()

virtual IlBoolean IlvAbstractChartData::setDataSets	(	IlUInt &	count,
		IlvChartDataSet const	dataSets,
		IlBoolean	copy = `IlFalse`
	)

pure virtual

Sets the managed data sets.

Parameters

count	This parameter first contains the number of data sets in the array dataSets. It is eventually modified to contain the number of data sets that have actually been set, if not all the data sets have been set in the current object.
dataSets	An array of the data sets to set in the current object.
copy	Indicates whether the data sets passed as parameters must be copied. If copy is `IlTrue`, the data sets are copied. Otherwise, the data sets that are stored in the array dataSets are kept. Therefore, the contents of the array should not be deleted.

Returns: IlTrue if data sets have been set. If not all the data sets could be set, the parameter count is modified to indicate the number of data sets that have been successfully set.

Note: When you set a data set, the new data set is locked and the old one, if any, is unlocked.

Implemented in IlvMemoryChartData, and IlvXMLChartData.

§ startBatch()

virtual void IlvAbstractChartData::startBatch ( const IlvChartDataSet * dataSet ) const

virtual

Specifies the beginning of a set of modifications on a data set.

The purpose of this method is to notify all the subscribed listeners that a set of modifications is under way on the data set dataSet.

Parameters

dataSet The data set that is modified.

§ unLock()

void IlvAbstractChartData::unLock ( )

Unlocks the current IlvAbstractChartData object.

Decrements the reference count of this object and deletes it when the count becomes 0.

§ write()

virtual void IlvAbstractChartData::write ( IlvOutputFile & file ) const

pure virtual

Writes the attributes of the current object in a file.

Called by the IlvAbstractChartData::save() method. This method can be overloaded in subclasses that define new attributes. The information written by the write() method is read by the IO constructor, which takes an IlvInputFile as its only argument. Both this method and the IO constructor can be automatically declared by using the DeclareChartDataTypeInfo macro within the class declaration.

Parameters

file	The file where the attributes of the current object are written.

Implemented in IlvXMLChartData.

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

§ ~IlvAbstractChartData()

§ IlvAbstractChartData() [1/2]

§ IlvAbstractChartData() [2/2]

Member Function Documentation

§ addDataSet()

§ addListener()

§ copy()

§ dataAllPointsRemoved()

§ dataPointAdded()

§ dataPointChanged()

§ dataPointRemoved()

§ dataSetAdded()

§ dataSetChanged()

§ dataSetRemoved()

§ endBatch()

§ getDataSet()

§ getDataSetByName()

§ getDataSetIndex()

§ getDataSets()

§ getDataSetsCount()

§ getListeners()

§ insertDataSet()

§ isLimited()

§ isRemovalAllowed()

§ isWritable()

§ Load()

§ lock()

§ operator[]() [1/2]

§ operator[]() [2/2]

§ removeDataSet()

§ removeDataSets()

§ removeListener()

§ replaceDataSet()

§ save()

§ setDataSet()

§ setDataSets()

§ startBatch()

§ unLock()

§ write()