Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
TPrintPageIterator, TPage
Inherited By:
None.
Purpose:
This is the instance of TPageIterator created by TPaginatedPageFolio, TTiledPageFolio, and TBookPageFolio. It is created by the CreatePageIterator function of each of the mentioned page folios. If desired, it is appropriate to cast the pointer returned by the CreatePageIterator function, a TPageIterator, to a TPaginatedPageIterator. Otherwise, it can be treated polymorphically as a TPageIterator.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
This is an explicit derived class of TPageIterator that is specific to TPaginatedPageFolio. It cannot be changed or derived in order to change its behavior with respect to Paginated Page Folios. However, it could theoretically be used as a base class for other page iterator uses.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
virtual ~ TPaginatedPageIterator ()
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 TScanOrder * GetScanOrder ()
Interface Category:
API.
Purpose:
Paginated pages have parameters that specify in what order the pages in the grid matrix are scanned (see the descriptions for TPaginator and TScanOrder). This function returns the current scan order for this iterator.
Calling Context:
Called directly to obtain the scan order used in the iteration. Also used internally.
Parameters:
Return Value:
Returns a temporary pointer to the scan order currently being used by the iterator.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual void AdoptScanOrder (TScanOrder *)
Interface Category:
API.
Purpose:
Paginated pages have parameters that specify in what order the pages in the grid matrix are scanned (see the descriptions for TPaginator and TScanOrder). This function replaces the current scan order with the one specified in the call, which changes the order in which pages are parsed in the page folio. This invalidates any currently active page so that Current returns NIL.
Calling Context:
Called directly to set the scan order for a pagination. Several page iterators targeted to a single paginated page folio can all have different scan orders.
Parameters:
- TScanOrder * -The scan order specifies in which order the pages of the pagination are to be scanned. It is adopted by the host object.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual TULongPair GetCurrentPageCoordinate () const
Interface Category:
API.
Purpose:
If Current is non-NIL, this function returns the page coordinate in the grid matrix for the current page. Causes an exception otherwise.
Calling Context:
Called directly to obtain the coordinate of the current page.
Parameters:
Return Value:
If Current returns non-NIL, this function returns the page coordinate for the current page.
Exceptions:
Throws TStandardPrintProcessingException::kIteratorSequenceError if there is not a current page, meaning Current does not return a non-NIL value.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual TGPoint GetCurrentPagePosition () const
Interface Category:
API.
Purpose:
If Current returns non-NIL, this function returns the page position in the extent rectangle for the current page. Causes an exception if Current returns NIL.
Calling Context:
Called directly to get the position of the current page but only when Current is non-NIL.
Parameters:
Return Value:
If Current returns non-NIL, this function returns the top-left corner page position of the current page.
Exceptions:
Throws TStandardPrintProcessingException::kIteratorSequenceError if there is not a current page, meaning Current does not return a non-NIL value.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual TPage * Current () const
Interface Category:
API.
Purpose:
Reflects the current state of the iterator. It returns the result of the last iteration performed on the iterator. If the result is NIL, then the last iteration performed on the iterator did not succeed, meaning the iterator has tried to reach beyond the beginning or end of the iterator, or else no iteration function has yet been called. If the result is non-NIL, the object returned represents the last page found in the iterator.
Calling Context:
Called directly to determine the success or failure of a previous iteration call and to obtain the current state of the iterator.
Parameters:
Return Value:
A pointer to a TPage object is returned, which can be NIL if the iterator is not positioned at a valid page.
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 page in the iterator corresponding to the specified page number moderated by any page range supplied to the iterator. If there are no pages in the iterator or the requested page is not in the iterator, the function returns NIL. Otherwise, a pointer to the requested page is returned as the value of the function. Whatever value is returned from this function is also subsequently returned by all calls to Current until another Seek function is called or the iterator is otherwise moved or has changed state.
Calling Context:
Called directly to position the iterator to a specific page. Also called internally by First, Last, Next, and Previous.
Parameters:
- unsigned long pageNumber -The desired page number at which to position the iterator.
Return Value:
A pointer to the desired page is returned, or NIL if the page does not exist in the iterator.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual unsigned long Count () const
Interface Category:
API.
Purpose:
Returns the total number of pages in the page iterator. This number can differ from the number of pages in the parent folio if a page range was specified in the construction of the iterator.
Calling Context:
Called directly to obtain the total number of pages available for iteration.
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.