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
IlvXMLChartData Class Reference

A data set which is read from an XML document. More...

#include <ilviews/charts/xml.h>

Inheritance diagram for IlvXMLChartData:
IlvAbstractChartData

Public Member Functions

 IlvXMLChartData (IlvDisplay *display, const char *fileName)
 Constructor. More...
 
virtual IlBoolean addDataSet (IlvChartDataSet *dataSet, IlBoolean copy=IlFalse)
 Adds a managed data set. More...
 
virtual IlvAbstractChartDatacopy () const
 Virtual copy constructor. More...
 
virtual IlvChartDataSetcreateDataSet (IlString name, IlvChartDoubleArray xvalues, IlvChartDoubleArray yvalues)
 Creates a data set out of the x- and y-array of values. More...
 
virtual IlvChartDataSetgetDataSet (IlUInt index=0) const
 Returns a data set of the container. More...
 
IlvChartDataSetgetDataSetByName (const char *name) const
 Gets a managed data set by its name. More...
 
virtual IlvChartDataSet *const * getDataSets (IlUInt &count) const
 Returns all the managed data sets. More...
 
virtual IlUInt getDataSetsCount () const
 Returns the number of data sets in the container. More...
 
virtual IlBoolean insertDataSet (IlvChartDataSet *dataSet, IlUInt index=IlvLastPositionIndex, IlBoolean copy=IlFalse)
 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 parse ()
 Parses the XML file. More...
 
void registerPropertyReader (IlString propertyName, IlvXMLPropertyReader *reader)
 Register a property reader. More...
 
void registerValueListProcessor (IlString typeName, IlvXMLValueListProcessor *processor)
 Register a value list processor. More...
 
virtual IlBoolean removeDataSet (IlUInt dataSetIndex)
 Removes a managed data set. More...
 
virtual void removeDataSets ()
 Removes all the managed data sets. More...
 
virtual IlBoolean setDataSet (IlUInt dataSetIndex, IlvChartDataSet *dataSet, IlBoolean copy=IlFalse)
 Sets a managed data set. More...
 
virtual IlBoolean setDataSets (IlUInt &count, IlvChartDataSet *const *dataSets, IlBoolean copy=IlFalse)
 Sets the managed data sets. More...
 
virtual void write (IlvOutputFile &file) const
 Writes the attributes of the current object in a file. More...
 
- Public Member Functions inherited from IlvAbstractChartData
virtual ~IlvAbstractChartData ()
 Destructor. More...
 
void addListener (IlvChartDataListener *lst)
 Adds a listener. 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...
 
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...
 
IlvChartDataListener *const * getListeners (IlUInt &count) const
 Returns all the listeners. 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...
 
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 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...
 

Additional Inherited Members

- Static Public Member Functions inherited from IlvAbstractChartData
static IlvAbstractChartDataLoad (IlvInputFile &file)
 Reads a chart data object from a file. More...
 
- Protected Member Functions inherited from IlvAbstractChartData
 IlvAbstractChartData ()
 Constructor. More...
 
 IlvAbstractChartData (const IlvAbstractChartData &cData)
 Constructor. More...
 
 IlvAbstractChartData (IlvInputFile &file)
 Constructor. More...
 

Detailed Description

A data set which is read from an XML document.

Library: ilvcharts

To be properly loaded, the XML document structure should be conform to the following DTD:

<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT chartData (data+)>
<!ATTLIST chartData xmlns:ilvchart CDATA #FIXED "http://www.ilog.com/products/jviews/chart"
                       version CDATA #REQUIRED>
<!ELEMENT data (series+)>
<!ATTLIST data  xSeries IDREF #IMPLIED>
<!ELEMENT series ((value | valuesList)*, property*)>
<!ATTLIST series dateFormat CDATA           #IMPLIED
                    type (double | date)       #REQUIRED
                    id         ID              #REQUIRED>
<!ELEMENT value (#PCDATA)>
<!ELEMENT valuesList (#PCDATA)>
<!ATTLIST valuesList delimiter CDATA #IMPLIED>
<!ENTITY % propertyExt "">
<!ELEMENT property (#PCDATA propertyExt;)*>
<!ATTLIST property name  CDATA #REQUIRED
                   value CDATA #IMPLIED>
<!ELEMENT seriesRef EMPTY>
<!ATTLIST seriesRef ref IDREF #REQUIRED>
 

Assuming that a chart contains 3 data sets: 2 (DS_A and DS_B) that do not use x-values series, 1 (DS_C) using a specific series for its abscissa; the resulting XML file is:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chartData SYSTEM 'file:///c://myapp/chartxml.dtd'>
<chartData version="0.3">
  <data>
    <series id="DS_A" type="double">
      <valuesList>0.0,8.0,6.0,13.0,22.0,21.0,19.0,28.0,27.0,23.0</valuesList>
    </series>
    <series id="DS_B" type="double">
      <valuesList>0.0,9.0,11.0,14.0,11.0,16.0,19.0,21.0,12.0,12.0</valuesList>
    </series>
  </data>
  <data xseries="X_DS_C">
    <series id="X_DS_C" type="double">
      <valuesList>0.0,2.0,4.0,6.0,8.0,10.0,12.0,14.0,16.0,18.0</valuesList>
    </series>
    <series id="DS_C" type="double">
      <valuesList>0.0,0.0,6.0,3.0,0.0,2.0,9.0,18.0,9.0,5.0</valuesList>
    </series>
  </data>
</chartData>

This class can be derived from and extended by the user.

Constructor & Destructor Documentation

IlvXMLChartData::IlvXMLChartData ( IlvDisplay display,
const char *  fileName 
)

Constructor.

Creates a new IlvXMLChartData.

Parameters
displayThe IlvDisplay whose path is used to search the file. If this parameter is null, the IlvXMLChartData instance opens the file without searching the path list of the display.
fileNameThe name of the file from which the XML data is read.

Member Function Documentation

virtual IlBoolean IlvXMLChartData::addDataSet ( IlvChartDataSet dataSet,
IlBoolean  copy = IlFalse 
)
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.

Implements IlvAbstractChartData.

virtual IlvAbstractChartData* IlvXMLChartData::copy ( ) const
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.

Implements IlvAbstractChartData.

virtual IlvChartDataSet* IlvXMLChartData::createDataSet ( IlString  name,
IlvChartDoubleArray  xvalues,
IlvChartDoubleArray  yvalues 
)
virtual

Creates a data set out of the x- and y-array of values.

This method is called when all series are built, to create the actual IlvChartDataSet out of the values.

It might be useful to override this method in case of special requirements on data set creation (need to build a specific type of data set).

Parameters
namethe name of the dataset.
xvaluesarray of X values
yvaluesarray of Y values
virtual IlvChartDataSet* IlvXMLChartData::getDataSet ( IlUInt  index = 0) const
virtual

Returns a data set of the container.

Parameters
indexThe index of the data set that is returned.
Returns
A pointer to the data set at the index index (if it exists), 0 otherwise.

Implements IlvAbstractChartData.

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

Gets a managed data set by its name.

Parameters
nameThe name of the data set that is returned.
Returns
A pointer to the data set named name (if it exists), 0 otherwise.
virtual IlvChartDataSet* const* IlvXMLChartData::getDataSets ( IlUInt count) const
virtual

Returns all the managed data sets.

Parameters
countThe number of data sets managed by the current object.
Returns
An array of pointers to all the data sets managed by the current object.

Reimplemented from IlvAbstractChartData.

virtual IlUInt IlvXMLChartData::getDataSetsCount ( ) const
virtual

Returns the number of data sets in the container.

Returns
The number of data sets that are in the container.

Implements IlvAbstractChartData.

virtual IlBoolean IlvXMLChartData::insertDataSet ( IlvChartDataSet dataSet,
IlUInt  index = IlvLastPositionIndex,
IlBoolean  copy = IlFalse 
)
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.

Implements IlvAbstractChartData.

virtual IlBoolean IlvXMLChartData::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 from IlvAbstractChartData.

virtual IlBoolean IlvXMLChartData::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 from IlvAbstractChartData.

virtual IlBoolean IlvXMLChartData::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 from IlvAbstractChartData.

void IlvXMLChartData::parse ( )

Parses the XML file.

Parse the XML file whose name was given when creating the object.

void IlvXMLChartData::registerPropertyReader ( IlString  propertyName,
IlvXMLPropertyReader reader 
)

Register a property reader.

Register a new property reader for the specified propertyName. The reader will then be used when encountering a property of the corresponding name.

Parameters
propertyNamethe name of the property.
readerthe IlvXMLPropertyReader which will handle the property
void IlvXMLChartData::registerValueListProcessor ( IlString  typeName,
IlvXMLValueListProcessor processor 
)

Register a value list processor.

Register a new value list processor for the specified type of values (typically, "double" or "date"). The processor will then be used when encountering a value list of the corresponding type.

Parameters
typeNamethe name of the data type.
processorthe IlvXMLValueListProcessor which will handle the data type.
virtual IlBoolean IlvXMLChartData::removeDataSet ( IlUInt  dataSetIndex)
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.

Implements IlvAbstractChartData.

virtual void IlvXMLChartData::removeDataSets ( )
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.

Implements IlvAbstractChartData.

virtual IlBoolean IlvXMLChartData::setDataSet ( IlUInt  dataSetIndex,
IlvChartDataSet dataSet,
IlBoolean  copy = IlFalse 
)
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.

Implements IlvAbstractChartData.

virtual IlBoolean IlvXMLChartData::setDataSets ( IlUInt count,
IlvChartDataSet *const *  dataSets,
IlBoolean  copy = IlFalse 
)
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.

Implements IlvAbstractChartData.

virtual void IlvXMLChartData::write ( IlvOutputFile file) const
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.

Implements IlvAbstractChartData.


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