IlvAbstractChartData Class Reference

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

#include <ilviews/charts/data.h>

Inheritance diagram for IlvAbstractChartData:

List of all members.

Public Member Functions
virtual	~IlvAbstractChartData ()
	Destructor.
virtual IlBoolean	addDataSet (IlvChartDataSet *dataSet, IlBoolean copy=IlFalse)=0
	Adds a managed data set.
void	addListener (IlvChartDataListener *lst)
	Adds a listener.
virtual IlvAbstractChartData *	copy () const =0
	Virtual copy constructor.
virtual void	dataAllPointsRemoved (const IlvChartDataSet *ds) const
	Performs the updates needed when a data point is removed.
virtual void	dataPointAdded (const IlvChartDataSet *dataSet, IlUInt position) const
	Performs the updates needed when a data point is added.
virtual void	dataPointChanged (const IlvChartDataSet *dataSet, IlUInt ptidx, IlBoolean beforeChange) const
	Performs the updates needed when a data point is changed.
virtual void	dataPointRemoved (const IlvChartDataSet *dataSet, IlUInt ptidx) const
	Performs the updates needed when a data point is removed.
virtual void	dataSetAdded (IlvChartDataSet *dataSet, IlUInt position)
	Performs the updates needed when a data set is added.
virtual void	dataSetChanged (IlvChartDataSet *oldSet, IlvChartDataSet *newSet)
	Performs the updates needed when a data set is changed.
virtual void	dataSetRemoved (IlvChartDataSet *dataSet)
	Performs the necessary updates when a data set is removed.
virtual void	endBatch (const IlvChartDataSet *dataSet) const
	Specifies the end of a set of modifications on a data set.
virtual IlvChartDataSet *	getDataSet (IlUInt index) const =0
	Gets a managed data set by its index.
IlvChartDataSet *	getDataSetByName (const char *name) const
	Gets a managed data set by its name.
IlUInt	getDataSetIndex (const IlvChartDataSet *dataSet) const
	Returns the index of a managed data set.
virtual IlvChartDataSet *const *	getDataSets (IlUInt &nbDataSets) const
	Returns all the managed data sets.
virtual IlUInt	getDataSetsCount () const =0
	Returns the number of managed data sets.
IlvChartDataListener *const *	getListeners (IlUInt &count) const
	Returns all the listeners.
virtual IlBoolean	insertDataSet (IlvChartDataSet *dataSet, IlUInt index=IlvLastPositionIndex, IlBoolean copy=IlFalse)=0
	Inserts a managed data set.
virtual IlBoolean	isLimited () const
	Indicates whether the number of managed data sets is limited.
virtual IlBoolean	isRemovalAllowed () const
	Indicates whether the managed data sets can be removed.
virtual IlBoolean	isWritable () const
	Indicates whether the managed data sets can be modified.
void	lock ()
	Locks the current IlvAbstractChartData object.
const IlvChartDataSet *	operator[] (IlUInt index) const
	Gets a managed data set by its index.
IlvChartDataSet *	operator[] (IlUInt index)
	Gets a managed data set by its index.
virtual IlBoolean	removeDataSet (IlUInt dataSetIndex)=0
	Removes a managed data set.
virtual void	removeDataSets ()=0
	Removes all the managed data sets.
IlvChartDataListener *	removeListener (IlvChartDataListener *lst)
	Removes a listener.
void	removeListeners ()
	Removes all the listeners.
IlBoolean	replaceDataSet (IlvChartDataSet *oldDataSet, IlvChartDataSet *newDataSet)
	Replaces a managed data set by another one.
IlvOutputFile &	save (IlvOutputFile &file) const
	Writes a complete description of the current object in a file.
virtual IlBoolean	setDataSet (IlUInt dataSetIndex, IlvChartDataSet *dataSet, IlBoolean copy=IlFalse)=0
	Sets a managed data set.
virtual IlBoolean	setDataSets (IlUInt &count, IlvChartDataSet *const *dataSets, IlBoolean copy=IlFalse)=0
	Sets the managed data sets.
virtual void	startBatch (const IlvChartDataSet *dataSet) const
	Specifies the beginning of a set of modifications on a data set.
void	unLock ()
	Unlocks the current IlvAbstractChartData object.
virtual void	write (IlvOutputFile &file) const =0
	Writes the attributes of the current object in a file.
Static Public Member Functions
static IlvAbstractChartData *	Load (IlvInputFile &file)
	Reads a chart data object from a file.
Protected Member Functions
	IlvAbstractChartData (IlvInputFile &file)
	Constructor.
	IlvAbstractChartData (const IlvAbstractChartData &cData)
	Constructor.
	IlvAbstractChartData ()
	Constructor.

---

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.

Warning:

[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

virtual IlvAbstractChartData::~IlvAbstractChartData

(

)

[virtual]

Destructor.

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

IlvAbstractChartData::IlvAbstractChartData

(

)

[protected]

Constructor.

Initializes a new IlvAbstractChartData object.

IlvAbstractChartData::IlvAbstractChartData

(

const IlvAbstractChartData &

cData

)

[protected]

Constructor.

Initializes a new IlvAbstractChartData object as a copy of cData.

Parameters:

cData

The object used to initialize the current one.

IlvAbstractChartData::IlvAbstractChartData

(

IlvInputFile &

file

)

[protected]

Constructor.

Initializes a new IlvAbstractChartData object from the description read in the input file named file.

Parameters:

The

file used to initialize the current object.

---

Member Function Documentation

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	A Boolean value indicating 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.

Warning:

[note] When you add a data set, the new data set is locked.

Implemented in IlvMemoryChartData, and IlvXMLChartData.

void IlvAbstractChartData::addListener

(

IlvChartDataListener *

lst

)

Adds a listener.

Parameters:

lst

The new listener that is added to the current object.

virtual IlvAbstractChartData* IlvAbstractChartData::copy

(

)

const [pure virtual]

Virtual copy constructor.

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.

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.
	ptidx	The index of the data point that is removed from the data set ds.

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.

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	A Boolean value indicating whether the method is called before the data point is changed or after it has been changed.

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.

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:

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

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.

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.

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.

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.

Warning:

[note] The data set object must not be deleted by the user since it is maintained internally.

Implemented in IlvMemoryChartData, and IlvXMLChartData.

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.

Warning:

[note] The data set object must not be deleted by the user since it is maintained internally.

Reimplemented in IlvXMLChartData.

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.

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.

Warning:

[note] The array is stored in an IlPoolOf(Pointer) and should not be deleted or modified.

Reimplemented in IlvXMLChartData.

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.

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.

Warning:

[note] The returned array should not be freed or reallocated directly since it is maintained internally.

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	A Boolean value indicating 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.

Warning:

[note] When you insert a data set, the new data set is locked.

Implemented in IlvMemoryChartData, and IlvXMLChartData.

virtual IlBoolean IlvAbstractChartData::isLimited

(

)

const [virtual]

Indicates whether the number of managed data sets is limited.

Returns a Boolean 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.

virtual IlBoolean IlvAbstractChartData::isRemovalAllowed

(

)

const [virtual]

Indicates whether the managed data sets can be removed.

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

Returns:

IlTrue by default.

Warning:

[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.

virtual IlBoolean IlvAbstractChartData::isWritable

(

)

const [virtual]

Indicates whether the managed data sets can be modified.

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

Returns:

IlTrue by default.

Warning:

[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.

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.

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.

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.

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.

Warning:

[note] The data set object must not be deleted by the user since it is maintained internally.

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.

Warning:

[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.

virtual void IlvAbstractChartData::removeDataSets

(

)

[pure virtual]

Removes all the managed data sets.

Warning:

[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.

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.

Warning:

[note] The listener is not deleted. The caller is responsible for deleting the listener.

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.

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.

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	A Boolean value indicating 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.

Warning:

[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.

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	A Boolean value indicating 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.

Warning:

[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.

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.

void IlvAbstractChartData::unLock

(

)

Unlocks the current IlvAbstractChartData object.

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

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.