rwlogo
Rogue Wave Views 5.5.1

Rogue Wave Views
Charts Package API Reference Guide

Product Documentation:

Rogue Wave Views
Documentation Home

IlvXMLChartData Class Reference

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

#include <ilviews/charts/xml.h>

Inheritance diagram for IlvXMLChartData:
IlvAbstractChartData

List of all members.

Public Member Functions

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

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:
display The 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.
fileName The 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:
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.

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:
name the name of the dataset.
xvalues array of X values
yvalues array of Y values
virtual IlvChartDataSet* IlvXMLChartData::getDataSet ( IlUInt  index = 0  )  const [virtual]

Returns a data set of the container.

Parameters:
index The 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:
name The name of the data set that is returned.
Returns:
A pointer to the data set named name (if it exists), 0 otherwise.

Reimplemented from IlvAbstractChartData.

virtual IlvChartDataSet* const* IlvXMLChartData::getDataSets ( IlUInt count  )  const [virtual]

Returns all the managed data sets.

Parameters:
count 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.

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

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:
propertyName the name of the property.
reader the 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:
typeName the name of the data type.
processor the IlvXMLValueListProcessor which will handle the data type.
virtual IlBoolean IlvXMLChartData::removeDataSet ( IlUInt  dataSetIndex  )  [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.

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

Implements IlvAbstractChartData.

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

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:
file The 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.