IlvXMLChartData Class Reference

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

#include <ilviews/charts/xml.h>

Inheritance diagram for IlvXMLChartData:

Public Member Functions
	IlvXMLChartData (IlvDisplay display, const char fileName)
	Constructor.
virtual IlBoolean	addDataSet (IlvChartDataSet *dataSet, IlBoolean copy=IlFalse)
	Adds a managed data set.
virtual IlvAbstractChartData *	copy () const
	Virtual copy constructor.
virtual IlvChartDataSet *	createDataSet (IlString name, IlvChartDoubleArray xvalues, IlvChartDoubleArray yvalues)
	Creates a data set out of the x- and y-array of values.
virtual IlvChartDataSet *	getDataSet (IlUInt index=0) const
	Returns a data set of the container.
IlvChartDataSet *	getDataSetByName (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.

Rogue Wave ViewsCharts Package API Reference Guide

IlvXMLChartData Class Reference

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Rogue Wave Views
Charts Package API Reference Guide