Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
TPrintPageIterator, TPage
Inherited By:
None.
Purpose:
This is an iterator for a TCompoundPageFolio. When a TCompoundPageFolio creates a page iterator, it returns a polymorphic TPageIterator that can be cast to a TCompoundPageIterator. Other than the folio on which it operates, a compound page iterator doesn't do much beyond what a standard TPrintPageIterator does. However, it does have four additional functions that a standard TPageIterator doesn't have, NextFolio, FirstFolio, LastFolio, and PreviousFolio. These functions allow iteration access to the folios inside the compound folio independently of the page iteration.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
This is an explicit derived class of TPageIterator that is specific to the TCompoundPageFolio that constructs it. Clients should not construct this class directly and should not derive from it.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
virtual ~ TCompoundPageIterator ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual MPageFolio * NextFolio ()
Interface Category:
API.
Purpose:
In addition to iterating over pages, a compound page iterator can be used to iterate over the page folios placed in the compound folio. If a previous folio has been found before, this function returns the next page folio or NIL if there are no more. Once the iteration returns NIL, a subsequent call to NextFolio, without first calling FirstFolio or LastFolio, results in an exception.
Calling Context:
Called to find the next folio given that a previous one has been found.
Parameters:
Return Value:
Returns the next folio in the collection provided there was already a previous one. It returns NIL if there isn't a next one.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual MPageFolio * FirstFolio ()
Interface Category:
API.
Purpose:
In addition to iterating over pages, a compound page iterator can be used to iterate over the page folios placed in the compound folio. This function returns the first page folio in the list or NIL if there are none.
Calling Context:
Called directly to find the first folio in a compound folio, if there is one.
Parameters:
Return Value:
Returns the first folio in the collection, if there is one.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual MPageFolio * LastFolio ()
Interface Category:
API.
Purpose:
In addition to iterating over pages, a compound page iterator can be used to iterate over the page folios placed in the compound folio. This function returns the last page folio in the list or NIL if there are none.
Calling Context:
Called directly to find the last folio in a compound folio if there is one.
Parameters:
Return Value:
Returns the last folio in the collection, if there is one.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual MPageFolio * PreviousFolio ()
Interface Category:
API.
Purpose:
In addition to iterating over pages, a compound page iterator can be used to iterate over the page folios placed in the compound folio. If a previous folio has been found before, this function returns the previous page folio in the list or NIL if there are no more. Once the iteration returns NIL, a subsequent call to PreviousFolio, without first calling FirstFolio or LastFolio, results in an exception.
Calling Context:
Called directly to find the previous folio in a compound folio given that one has been found already.
Parameters:
Return Value:
Returns the folio previous to the current one, provided there is already a current one. Returns NIL if there are no folios previous to this one.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual TPage * Current () const
Interface Category:
API.
Purpose:
Reflects the current state or current position of the iterator. Its result points to the TPage object found by the most recent iteration call on the iterator or NIL if no page was found.
Calling Context:
Called directly to obtain the current state of the iterator or the TPage object at which the iterator is currently positioned.
Parameters:
Return Value:
Returns a TPage pointer of the last iteration or NIL.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual TPage * Seek (unsigned long pageNumber)
Interface Category:
API.
Purpose:
Finds the specified page in the iterator and returns a pointer to it. If there aren't any pages in the iterator or the page requested does not exist in the iterator, the function returns NIL. After this call, Current reflects the same result until the iterator is changed or moved to a different page.
Calling Context:
Called directly to position the iterator to a specific page.
Parameters:
- unsigned long pageNumber -This specifies the number of the page the iterator should find.
Return Value:
Returns a pointer to the specified page if it exists in the iterator or NIL if it doesn't exist.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
The value returned by this function is only valid until the iterator is moved to a different page or its state is otherwise changed. Pages cannot be added to or removed from the iterator itself and are never owned by the client. However, it is possible to copy pages.
virtual unsigned long Count () const
Interface Category:
API.
Purpose:
Calculates the total number of pages accessible by the page iterator, which might not be the same as the total number of pages in the folio if a page range is specified when the page iterator is created.
Calling Context:
Called directly to obtain the total number of pages in the iterator.
Parameters:
Return Value:
Returns the total number of pages in the iterator.
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.
Copyright©1995 Taligent,Inc. All rights reserved.