Class: TCompoundPageFolio

Declaration: HighLevelPrint.h

Taxonomy Categories:

Member Functions:

TCompoundPageFolio
~TCompoundPageFolio
CreatePageIterator
GetPageCount
AddFolio
RemoveFolio
DeleteAllFolios
RemoveAllFolios
GetFolioCount
GetFolioAfter
GetFolioBefore
AddFolioBefore
AddFolioAfter
AddFolioLast
AddFolioFirst
GetLastFolio
GetFirstFolio
RemoveLastFolio
RemoveFirstFolio
Member
IsEmpty
operator=
Hash
operator<<=
operator>>=

Interface Category:

API.

Inherits From:

MPageFolio

Inherited By:

None.

Purpose:

This is a page folio class that can contain other instances of page folios, including other compound page folios. Unless other page folios are stored in it, a compound page folio contains no pages of its own. A compound folio is useful when the pages of a document are not the same size (such as letter and envelope pairs), or stem from different sources such as a data base or template.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

A stand-alone class that should not be derived.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TCompoundPageFolio::TCompoundPageFolio

TCompoundPageFolio ()
TCompoundPageFolio (const TCompoundPageFolio &)

Interface Category:

API.

Purpose:

Default constructor. Constructs a valid page folio with no pages.
Copy constructor.

Calling Context:

Called by the stream-in operators only.
Called to copy an object.

Parameters:

Takes no parameters.
const TCompoundPageFolio & -The folio object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::~TCompoundPageFolio

virtual ~ TCompoundPageFolio ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::CreatePageIterator

virtual TPrintPageIterator * CreatePageIterator (TPageRange * aliasRange =NIL) const

Interface Category:

API.

Purpose:

Creates a page iterator that can be used to iterate over pages in the compound page folio. If the returned pointer is cast to a TCompoundPageIterator it can also be used to iterate over the page folios placed inside the compound page folio. The order of pages in a compound page folio is the same as the order in which each individual page folio was placed in the compound page folio. Any number of compound page iterators can be created and used at the same time. The page range, if specified, affects all pages in the compound folio.

Calling Context:

Called directly to create an iterator for a compound page folio. This is the only proper way to obtain a page iterator for a given folio.

Parameters:

TPageRange * aliasRange =NIL -When a page iterator is created, a page range of selected pages can be set with this argument. Thereafter, only pages in this range are involved in the iteration. A NIL page range is the same as a full page range, that is, all pages are selected.

Return Value:

Returns a TCompoundPageIterator able to parse the pages of the compound page folio.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Any number of page iterators can be created for a page folio and all can be operated at the same time (although not in a concurrent context). If at any time the MPageFolio is destroyed without also destroying all of its iterators, the attempt to use any of its iterators could result in catastrophic problems. This consideration applies to all MPageFolio derived classes and their page iterators.

Member Function: TCompoundPageFolio::GetPageCount

virtual unsigned long GetPageCount () const

Interface Category:

API.

Purpose:

Returns the total count of all pages placed in the compound folio.

Calling Context:

Called directly to obtain the number of pages in a folio.

Parameters:

Takes no parameters.

Return Value:

Returns the total number of pages in the folio.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::AddFolio

virtual MPageFolio * AddFolio (MPageFolio * aliasToBeAdded)

Interface Category:

API.

Purpose:

Causes another MPageFolio to be added to the compound folio. If the parameter is NIL, nothing is added. The folio added is returned as the value of the function.

Calling Context:

Called directly to add another page folio to a compound folio.

Parameters:

MPageFolio * aliasToBeAdded -This is a pointer to a valid object derived from an MPageFolio. It is added to the end of the collection of folios already existing in the collection, if any.

Return Value:

Returns the folio that was added to the collection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::RemoveFolio

virtual MPageFolio * RemoveFolio (const MPageFolio &)

Interface Category:

API.

Purpose:

Removes the specified folio from the compound folio if it exists. The found folio is returned as the value of the function or NIL if it is not found.

Calling Context:

Called directly to remove a specific page folio from a compound folio.

Parameters:

const MPageFolio & -Given an MPageFolio object, this function removes it from the collection, if it exists in the collection.

Return Value:

Returns the folio removed or NIL.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::DeleteAllFolios

virtual void DeleteAllFolios ()

Interface Category:

API.

Purpose:

Deletes all the folios currently in the compound folio. Its not wise to call this function if duplicates of the same folio have been placed in the compound folio.

Calling Context:

Called directly to delete all folios without explicitly removing them and deleting them manually. The contents must have been created on the heap.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through. Will probably throw an exception of some sort if not all folios are allocated on the heap.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::RemoveAllFolios

virtual void RemoveAllFolios ()

Interface Category:

API.

Purpose:

Removes all folios from the compound folio without doing anything with them. The caller is responsible for the folios removed.

Calling Context:

Called directly to remove all folios from a compound folio. Can pose a memory management problem if folios are not subsequently deleted. The caller is responsible for the folios removed.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::GetFolioCount

virtual unsigned long GetFolioCount () const

Interface Category:

API.

Purpose:

Returns the total number of folios currently contained in the compound folio.

Calling Context:

Called directly to obtain the number of folios stored in the compound folio.

Parameters:

Takes no parameters.

Return Value:

Returns the number of folios currently in the collection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::GetFolioAfter

virtual MPageFolio * GetFolioAfter (const MPageFolio &) const

Interface Category:

API.

Purpose:

Looks for the folio after the one specified and returns it. Returns NIL if it cannot find the folio specified or if there isn't one after it.

Calling Context:

Called directly to obtain the folio after the one specified.

Parameters:

const MPageFolio & -This is a folio to look for in the collection. If it is found, the folio immediately after this one is returned, if there is one; otherwise, NIL is returned.

Return Value:

Returns the folio after the one supplied or NIL if none is found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::GetFolioBefore

virtual MPageFolio * GetFolioBefore (const MPageFolio &) const

Interface Category:

API.

Purpose:

Returns the folio immediately preceding the specified folio if it can be found. Returns NIL if it cannot be found or a preceding folio does not exist.

Calling Context:

Called directly to obtain a folio before the one specified.

Parameters:

const MPageFolio & -GetFolioBefore looks for this MPageFolio object and returns the one immediately before it, if it exists. If there isn't one before it, or the folio does not exist in the collection, NIL is returned.

Return Value:

Returns the folio before the one supplied or NIL if it is not found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::AddFolioBefore

virtual void AddFolioBefore (const MPageFolio & existing, MPageFolio * aliasToBeAdded)

Interface Category:

API.

Purpose:

Adds the specified folio immediately before the existing folio, if it is found, or it adds it to the beginning of the list otherwise.

Calling Context:

Called directly to add a folio in a specific place in a compound folio.

Parameters:

const MPageFolio & existing -A new folio is added to the collection just before this folio, if it is found; otherwise, the folio is added at the beginning of the collection.
MPageFolio * aliasToBeAdded -This is the folio to be added to the compound folio collection.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::AddFolioAfter

virtual void AddFolioAfter (const MPageFolio & existing, MPageFolio * aliasToBeAdded)

Interface Category:

API.

Purpose:

Adds the folio to be added immediately after the existing folio if it is found, or it adds it to the end of the list otherwise.

Calling Context:

Called directly to add a folio in a specific place in a compound folio.

Parameters:

const MPageFolio & existing -The folio to be added to the collection is added after this existing folio, if it is found; otherwise the new folio is added to the end of the collection.
MPageFolio * aliasToBeAdded -This is the folio to be added to the compound folio collection.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::AddFolioLast

virtual void AddFolioLast (MPageFolio *)

Interface Category:

API.

Purpose:

Adds the specified folio to the end of the list.

Calling Context:

Called directly to add a folio to the end of the list.

Parameters:

MPageFolio * -This folio is added to the end of the collection.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::AddFolioFirst

virtual void AddFolioFirst (MPageFolio *)

Interface Category:

API.

Purpose:

Adds the specified folio to the beginning of the list.

Calling Context:

Called directly to add a folio at the front.

Parameters:

MPageFolio * -This folio is added at the beginning of the collection.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::GetLastFolio

virtual MPageFolio * GetLastFolio () const

Interface Category:

API.

Purpose:

Finds the folio at the end of the list and returns it. Returns NIL if there are none.

Calling Context:

Called directly to get the last folio without removing it.

Parameters:

Takes no parameters.

Return Value:

Returns the last folio in the collection or NIL if there are none.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::GetFirstFolio

virtual MPageFolio * GetFirstFolio () const

Interface Category:

API.

Purpose:

Finds the folio at the beginning of the list and returns it. Returns NIL if there are none.

Calling Context:

Called directly to get the first folio without removing it.

Parameters:

Takes no parameters.

Return Value:

Returns the first folio in the collection or NIL if there are none.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::RemoveLastFolio

virtual MPageFolio * RemoveLastFolio ()

Interface Category:

API.

Purpose:

Removes the last folio from the list and returns it. Returns NIL if there are none.

Calling Context:

Called directly to get and remove the last folio.

Parameters:

Takes no parameters.

Return Value:

Returns the last folio or NIL if there are none.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::RemoveFirstFolio

virtual MPageFolio * RemoveFirstFolio ()

Interface Category:

API.

Purpose:

Removes the first folio from the beginning of the list and returns it. Returns NIL if there are none.

Calling Context:

Called directly to get and remove the first folio.

Parameters:

Takes no parameters.

Return Value:

Returns the first folio in the collection or NIL if there are none.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::Member

virtual MPageFolio * Member (const MPageFolio &) const

Interface Category:

API.

Purpose:

Finds the folio if it is a member of this list and returns it. Returns NIL if it is not a member.

Calling Context:

Called directly to see if a folio is a member of this collection.

Parameters:

const MPageFolio & -This folio is tested to see if it already exists in the collection.

Return Value:

Returns the folio found or NIL if it wasn't found.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::IsEmpty

virtual bool IsEmpty () const

Interface Category:

API.

Purpose:

Determines if a folio has any folios in it.

Calling Context:

Called directly to see if a folio has any folios in it.

Parameters:

Takes no parameters.

Return Value:

Returns true if there are no folios in this collection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::operator=

TCompoundPageFolio & operator =(const TCompoundPageFolio &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TCompoundPageFolio & -The object from which to assign.

Return Value:

A reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called directly and by the collection framework when this object is placed in a collection.

Parameters:

Takes no parameters.

Return Value:

A hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called directly to stream in data.

Parameters:

TStream & fromWhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TCompoundPageFolio::operator>>=

virtual TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called directly to stream out data.

Parameters:

TStream & toWhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.