IlvOutputFile Class Reference

Input/Output class. More...

#include <ilviews/graphics/io.h>

List of all members.

Public Member Functions
	IlvOutputFile (ostream &stream)
	Constructor.
ostream &	getStream () const
	Gets the output stream.
IlvOutputFile &	operator<< (const IlvGraphic *obj)
	Writes out the palette index and object description.
virtual void	saveMoreInfo (IlUInt count, IlvGraphic *const *objs)
	Save user information in the data file.
virtual IlvGraphic *const *	saveObjects (IlUInt count, IlvGraphic *const *objs, IlUInt &totalCount)
	Save objects by writing to the output stream.
void	setStream (ostream &stream)
	Sets the output stream.
virtual void	writeObject (const IlvGraphic *obj)
	Writes an object description.
void	writeObjectBlock (const IlvGraphic *obj)
	Writes an object description block.
IlvOutputFile &	writeReference (const IlvGraphic *)
	Writes an object reference.

---

Detailed Description

Input/Output class.

Library: views

The IlvOutputFile class writes the complete description of a series of objects in an output stream.
Rogue Wave Views uses an ASCII file format for objects. This format is basically composed of a small header indicating the version of Rogue Wave Views that has created the file, a description of the IlvPalette objects that are shared by the saved objects, and then the objects themselves. Objects are embedded in blocks enabling you to easily subtype the class to add your own application information within these blocks. An object description block begins with an open "curly brace" ({) and ends with a closed "curly brace" (}).

See also:

IlvInputFile, ostream::operator<<.

---

Constructor & Destructor Documentation

IlvOutputFile::IlvOutputFile

(

ostream &

stream

)

Constructor.

Initializes a new IlvOutputFile object which is ready to accept text data that defines the object descriptions.

Parameters:

stream

The output stream.

---

Member Function Documentation

ostream& IlvOutputFile::getStream

(

)

const

Gets the output stream.

Returns:

The ostream object that is used for writing.

IlvOutputFile& IlvOutputFile::operator<<

(

const IlvGraphic *

obj

)

Writes out the palette index and object description.

The member operator<< writes out the palette index of this object (or 0 if the object does not own any), then writes the object description itself by means of a call to the member function write of object.
A complete object is normally embedded within two block markers. However, in the case of objects that reference or group other objects, this member function is used to save the sub-objects. This is the case of the IlvGraphicSet object. This special kind of graphic object is used to group other objects.

Parameters:

object

The object to be written.

virtual void IlvOutputFile::saveMoreInfo	(	IlUInt	count,
		IlvGraphic *const *	objs
	)			[virtual]

Save user information in the data file.

This member function is called by saveObjects after all objects have been written out, so that you can add more information at the end of the data file. This function is called with the array objects of the count objects that have been written out. The default implementation does nothing.

Parameters:

	count	The number of objects in objects.
	objects	The array of objects.

virtual IlvGraphic* const* IlvOutputFile::saveObjects	(	IlUInt	count,
		IlvGraphic *const *	objs,
		IlUInt &	totalCount
	)			[virtual]

Save objects by writing to the output stream.

Writes in the output stream the full description of the count objects that can be found in the objects array. This is a virtual member function.
As some objects may reference other objects, there might be more written object descriptions than expected. The actual number of saved objects is returned in the totalCount parameter, and the array of these objects is also returned. You should never delete this array yourself, as it is internally maintained.
In addition this member function should not be called directly by the user application; instead, it is called internally by the Rogue Wave Views input/output mechanism. It may also be overloaded.

Parameters:

	count	The number of objects in objects.
	objects	The array of objects.

Returns:

The count of saved objects in totalCount.

void IlvOutputFile::setStream

(

ostream &

stream

)

Sets the output stream.

Changes the stream to which you write information.

Parameters:

stream

The output stream.

virtual void IlvOutputFile::writeObject

(

const IlvGraphic *

obj

)

[virtual]

Writes an object description.

Writes an object description by means of a call to the member function writeObjectBlock. You overload this virtual member function when you need to add your specific object information.
When you overload this member function, you can add your specific information before and/or after the object block. This information must be read correctly by the IlvInputFile::readObject member function.

Parameters:

obj

The object description to be written.

void IlvOutputFile::writeObjectBlock

(

const IlvGraphic *

obj

)

Writes an object description block.

This member function writes a complete object description block by means of a call to the operator<< of the IlvOutputFile class. The begin and end descriptors of the block are placed before and after this call, respectively.

Parameters:

obj

The object description block to be written.

IlvOutputFile& IlvOutputFile::writeReference

(

const IlvGraphic *

)

Writes an object reference.

Writes the necessary information in the output stream to indicate an already saved object that is referenced by another object. Use this member function when you save instances of the IlvGraphicHandle class, an object which references another object. This process ensures that the referenced object is correctly saved apart from the standard saving procedure. When it is time to save a referencing object such as an IlvGraphicHandle instance, then the referenced object is saved by means of a call to writeReference.
The following source code presents the member function write of the IlvGraphicHandle class (see IlvGraphic::write):

 void
 IlvGraphicHandle::write(IlvOutputFile& file) const
 {
     // Save the `ownership' of the referencing object
     file.getStream() << (int)isOwner();
     // Now, do we save the reference, or the object itself?
     if (isOwner())
         file << IlvSpc() << getObject();
     else
         file.writeReference(getObject());

In this example, the saving of the referenced object is not the same if the object is owned by the IlvGraphicHandle object or if it is not. If it is, then the saving operation is performed just as if it was an IlvGraphicSet element. That is, when this file is read, a new object is allocated, and IlvGraphicHandle is told to use the object as a reference that the IlvGraphicHandle owns.
If the object is independent, that is, not owned by the referencing structure, then it has been saved elsewhere in the file and is already allocated. In this case, just link together the two objects. This is exactly the role of the member function writeReference.
The writeReference function finally returns the IlvOutputFile object that is concerned by this function call.

Parameters:

object

The object whose reference is to be written.