rwlogo
Rogue Wave Views 5.6

Rogue Wave Views
Charts Package API Reference Guide

Product Documentation:

Rogue Wave Views
Documentation Home

List of all members | Public Member Functions | Static Public Member Functions | Protected Member Functions
IlvAbstractChartData Class Referenceabstract

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

#include <ilviews/charts/data.h>

Inheritance diagram for IlvAbstractChartData:
IlvMemoryChartData IlvXMLChartData

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 IlvAbstractChartDatacopy () const =0
 Virtual copy constructor. 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 IlvChartDataSetgetDataSet (IlUInt index) const =0
 Gets a managed data set by its index. More...
 
IlvChartDataSetgetDataSetByName (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...
 
IlvChartDataSetoperator[] (IlUInt index)
 Gets a managed data set by its index. More...
 
const IlvChartDataSetoperator[] (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...
 
IlvChartDataListenerremoveListener (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...
 
IlvOutputFilesave (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 IlvAbstractChartDataLoad (IlvInputFile &file)
 Reads a chart data object from a file. More...
 

Protected Member Functions

 IlvAbstractChartData ()
 Constructor. More...
 
 IlvAbstractChartData (const IlvAbstractChartData &cData)
 Constructor. More...
 
 IlvAbstractChartData (IlvInputFile &file)
 Constructor. 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.

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
cDataThe 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
Thefile 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
dataSetThe data set to add to the current object.
copyA 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
lstThe 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
dsThe data set of the current object from which a data point is removed.
ptidxThe 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
dataSetThe data set of the current object to which a data point is added.
positionThe 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
dataSetThe data set of the current object in which a data point is changed.
ptidxThe index at which the data point is changed in the data set dataSet.
beforeChangeA 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
dataSetThe data set of the current object from which a data point is removed.
ptidxThe 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
Thedata set that is added to the current object.
positionThe 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
oldSetThe old data set before the change in the current object.
newSetThe 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
dataSetThe 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
dataSetThe data set that is modified.
virtual IlvChartDataSet* IlvAbstractChartData::getDataSet ( IlUInt  index) const
pure virtual

Gets a managed data set by its index.

Parameters
indexThe 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
nameThe 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.
IlUInt IlvAbstractChartData::getDataSetIndex ( const IlvChartDataSet dataSet) const

Returns the index of a managed data set.

Parameters
dataSetThe 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
nbDataSetsThe 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
countThe 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
dataSetThe data set to insert in the current object.
indexThe index at which the data set dataSet must be inserted in the current object.
copyA 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
fileThe 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.

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

Gets a managed data set by its index.

Parameters
indexThe 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.
const IlvChartDataSet* IlvAbstractChartData::operator[] ( IlUInt  index) const

Gets a managed data set by its index.

Parameters
indexThe 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.
virtual IlBoolean IlvAbstractChartData::removeDataSet ( IlUInt  dataSetIndex)
pure virtual

Removes a managed data set.

Parameters
dataSetIndexThe 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
lstThe 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
oldDataSetThe old data set that must be replaced in the current object.
newDataSetThe 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
fileThe 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
dataSetIndexThe index at which the data set dataSet must be set in the current object.
dataSetThe data set to set in the current object.
copyA 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
countThis 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.
dataSetsAn array of the data sets to set in the current object.
copyA 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
dataSetThe 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
fileThe file where the attributes of the current object are written.

Implemented in IlvXMLChartData.


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