Class: TPaginatorIterator

Declaration: Paginator.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

A TPaginator is an object that provides pagination metrics for partitioning arbitrary real estate into equal rectangular pieces. A TPaginatorIterator is created by an instance of TPaginator and provides for sequential or random access to any of the rectangular pieces. A TScanOrder and a TPrimitiveRegion parameter to a TPaginatorIterator allow the iterations to be customized as to direction and range. Direction refers to the order in which the rectangular pieces are sequenced and range refers to the subset of pieces that might be included in the iteration. The direction and range can be dynamically altered by clients. This class is used extensively in other classes that do pagination such as TPaginatedPageFolio.

Instantiation:

Always allocated on the heap.

Deriving Classes:

This is a specific class not intended for general deriving. However it can be derived to override specific functionality.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPaginatorIterator::~TPaginatorIterator

virtual ~ TPaginatorIterator ()

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: TPaginatorIterator::CopyRange

virtual TPrimitiveRegion * CopyRange () const

Interface Category:

API.

Purpose:

Modifies the range of items able to be parsed by an iterator by specifying arbitrary subranges of the paginator. The subranges are specified by TPrimitiveRegion and CopyRange makes a copy of the range currently used by the iterator.

Calling Context:

Called directly to get a copy of the current range of this iterator. The range is owned by the client and can be used in other iterators.

Parameters:

Takes no parameters.

Return Value:

A primitive region representing the range of pages in the iterator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::GetScanOrder

virtual TScanOrder * GetScanOrder () const

Interface Category:

API.

Purpose:

Returns the scan order currently being used in the iterator to specify item ordering.

Calling Context:

Called directly to get the scan order for the iterator.

Parameters:

Takes no parameters.

Return Value:

The TScanOrder object used in the iteration.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::AdoptScanOrder

virtual void AdoptScanOrder (TScanOrder *)

Interface Category:

API.

Purpose:

Replaces the current scan order in the iterator with the scan order specified. A NIL scan order reverts to default ordering which is TRasterScanOrder::kRightDown.

Calling Context:

Called directly to replace the scan order.

Parameters:

TScanOrder * -The scan order to be adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::ConvertToPage

virtual TGRect ConvertToPage (const TGPoint &) const

Interface Category:

API.

Purpose:

Takes an arbitrary point and converts it to a rectangle whose top-left corner is at the point and whose size is the size of the page used in the pagination.

Calling Context:

Called directly to convert a point to a page-sized rectangle originating at the point.

Parameters:

const TGPoint & -The point to convert to a page rectangle.

Return Value:

A rectangle representing the size of a page originating at the point.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::SeekOK

virtual bool SeekOK () const

Interface Category:

API.

Purpose:

Returns true after a Seek operation if the point returned represents a valid page in the paginator. If the desired page is not found in the paginator, SeekOK returns false.

Calling Context:

Called directly to determine if a Seek operation succeeded or not.

Parameters:

Takes no parameters.

Return Value:

Returns true if the last Seek operation succeeded.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::SeekFirstPageInRange

virtual TGPoint SeekFirstPageInRange ()

Interface Category:

API.

Purpose:

Finds the first page in the paginator that is within range. If the desired page exists, SeekOK returns true after this call and false otherwise.

Calling Context:

Called directly to find the first page in the iteration.

Parameters:

Takes no parameters.

Return Value:

Returns the top-left corner position for the page found by the Seek.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::SeekLastPageInRange

virtual TGPoint SeekLastPageInRange ()

Interface Category:

API.

Purpose:

Finds the last page in the paginator that is within range. If the desired page exists, SeekOK returns true after this call and false otherwise.

Calling Context:

Called directly to find the last page in the iteration.

Parameters:

Takes no parameters.

Return Value:

Returns the top-left corner position for the page found by the Seek.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::SeekNextPageInRange

virtual TGPoint SeekNextPageInRange ()

Interface Category:

API.

Purpose:

If SeekOK is true before this call, this function returns the next logical page in sequence, as determined by the current scan order and page range in effect at the time of the call. If no page exists, SeekOK reports false.

Calling Context:

Called directly to find the next page in the iteration, given that a previous page has been found.

Parameters:

Takes no parameters.

Return Value:

Returns the top-left corner position for the page found by the Seek.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::SeekPreviousPageInRange

virtual TGPoint SeekPreviousPageInRange ()

Interface Category:

API.

Purpose:

If SeekOK is true before this call, this function returns the previous logical page in sequence, as determined by the current scan order and page range in effect at the time of the call. If no page exists, SeekOK reports false.

Calling Context:

Called directly to find the previous page in the iteration, given that a current page already has been found.

Parameters:

Takes no parameters.

Return Value:

Returns the top-left corner position for the page found by the Seek.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::SeekToNthPageInRange

virtual TGPoint SeekToNthPageInRange (unsigned long offset)

Interface Category:

API.

Purpose:

Counting only pages that are within range, this function counts pages in range until N is reached (offset in this case). If N is still in range, it becomes the current page and SeekOK reports true. If there aren't that many pages in range, SeekOK reports false.

Calling Context:

Called directly to find the Nth page in range when the actual page number is not known.

Parameters:

unsigned long offset -The Nth page to see if its in range.

Return Value:

Returns the top-left corner position for the page found by the Seek.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::SeekFirstPage

virtual TGPoint SeekFirstPage ()

Interface Category:

API.

Purpose:

Finds the first possible page in the paginator.

Calling Context:

Called directly to find the absolute first page in the iteration.

Parameters:

Takes no parameters.

Return Value:

Returns the top-left corner position for the page found by the Seek.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::SeekLastPage

virtual TGPoint SeekLastPage ()

Interface Category:

API.

Purpose:

Finds the last possible page in the paginator.

Calling Context:

Called directly to find the absolute last page in the iteration.

Parameters:

Takes no parameters.

Return Value:

Returns the top-left corner position for the page found by the Seek.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::SeekNextPage

virtual TGPoint SeekNextPage ()

Interface Category:

API.

Purpose:

If SeekOK reports true, this function finds the next page in sequence determined by the scan order. The page range is ignored. If there are no more pages, SeekOK reports false.

Calling Context:

Called directly to find the absolute next page in the iteration, given that a current page already has been found and the range is not needed.

Parameters:

Takes no parameters.

Return Value:

Returns the top-left corner position for the page found by the Seek.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::SeekPreviousPage

virtual TGPoint SeekPreviousPage ()

Interface Category:

API.

Purpose:

If SeekOK reports true, this function finds the previous page in sequence determined by the scan order. The page range is ignored. If there are no more pages, SeekOK reports false.

Calling Context:

Called directly to find the absolute previous page in an iteration, given that a current page already has been found and the range is not needed.

Parameters:

Takes no parameters.

Return Value:

Returns the top-left corner position for the page found by the Seek.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::SeekToPageNumber

virtual TGPoint SeekToPageNumber (unsigned long aPageNumber)

Interface Category:

API.

Purpose:

Finds the page specified by the page number if it exists.

Calling Context:

Called directly to find an absolute page number.

Parameters:

unsigned long aPageNumber -The absolute page number to find.

Return Value:

Returns the top-left corner position for the page found by the Seek.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::GetCurrentPageLocation

virtual TGPoint GetCurrentPageLocation () const

Interface Category:

API.

Purpose:

If SeekOK is true, the location of the top-left corner of the current page is returned. If SeekOK is false, an exception occurs.

Calling Context:

Called directly to get the location in the pagination for the current page.

Parameters:

Takes no parameters.

Return Value:

Returns the current page position.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::GetCurrentPageCoordinate

virtual TULongPair GetCurrentPageCoordinate () const

Interface Category:

API.

Purpose:

If SeekOK is true, the grid coordinate of the current page is returned.

Calling Context:

Called directly to get the coordinate in the grid of the current page.

Parameters:

Takes no parameters.

Return Value:

Returns the current page grid coordinate.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::GetCurrentPageNumber

virtual unsigned long GetCurrentPageNumber () const

Interface Category:

API.

Purpose:

If SeekOK is true, the page number for the current page is returned.

Calling Context:

Called directly to get the page number of the current page.

Parameters:

Takes no parameters.

Return Value:

Returns the page number of the current page.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::GetPageCount

virtual unsigned long GetPageCount () const

Interface Category:

API.

Purpose:

Calculates the total number of pages represented by the pagination.

Calling Context:

Called directly to get the total number of pages.

Parameters:

Takes no parameters.

Return Value:

Returns the total number of pages.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::GetPageCountInRange

virtual unsigned long GetPageCountInRange () const

Interface Category:

API.

Purpose:

Returns the total number of pages in the pagination that are within range.

Calling Context:

Called directly to get the total number of pages in range.

Parameters:

Takes no parameters.

Return Value:

Returns the total number of pages in range.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::GetPageFromCoordinate

virtual bool GetPageFromCoordinate (TGPoint & position, unsigned long & pageNumber, const TULongPair inputCoordinate) const

Interface Category:

API.

Purpose:

Given a coordinate within the pagination grid, the page number and top-left corner page position are calculated and returned. If there is no such page represented by that coordinate, the function returns false.

Calling Context:

Called directly to convert a page coordinate to a page position.

Parameters:

TGPoint & position -The argument in which the page position is returned.
unsigned long & pageNumber -The argument in which the page number is returned.
const TULongPair inputCoordinate -The input coordinate of the desired page.

Return Value:

Returns true if the page exists in the paginator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::GetPageFromPoint

virtual bool GetPageFromPoint (TGPoint & position, unsigned long & pageNumber, TULongPair & coordinate, const TGPoint inputPoint) const

Interface Category:

API.

Purpose:

Given an arbitrary point, calculates the page number, the top-left corner position, and the grid coordinate for the page closest to the arbitrary point. If the point happens to fall within the boundaries of a page, the function returns a value of true, otherwise false. It acts like a hit function for the paginator.

Calling Context:

Called directly to convert an arbitrary point to the closest page.

Parameters:

TGPoint & position -The argument in which the page position is calculated and returned.
unsigned long & pageNumber -The argument in which the page number of the resultant page is returned.
TULongPair & coordinate -The argument in which the resultant page coordinate is returned.
const TGPoint inputPoint -The arbitrary input point for which the closest page is desired.

Return Value:

Returns true if the point is within the bounds of a page in the pagination.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::GetPageFromNumber

virtual bool GetPageFromNumber (TGPoint & position, TULongPair & coordinate, unsigned long pageNumber) const

Interface Category:

API.

Purpose:

Given a page number, calculates the top-left corner position and the grid coordinate for the page. The function returns true if the page number is valid, false otherwise.

Calling Context:

Called directly to convert a page number to a physical page.

Parameters:

TGPoint & position -The argument in which the desired page position is returned.
TULongPair & coordinate -The argument in which the desired page coordinate is returned.
unsigned long pageNumber -The page number of the desired page.

Return Value:

Returns true if the page number represents a real page in the pagination.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::GetPaginator

virtual TPaginator * GetPaginator () const

Interface Category:

API.

Purpose:

Returns the paginator that the iterator is targeting.

Calling Context:

Called directly to get the paginator used in the pagination.

Parameters:

Takes no parameters.

Return Value:

Returns the paginator for which the iterator is tracking.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPaginatorIterator::operator=

TPaginatorIterator & operator =(const TPaginatorIterator &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPaginatorIterator & -The object to be copied.

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: TPaginatorIterator::calcLocation

void calcLocation ()

Interface Category:

API.

Purpose:

Revalidates the internal state of the iterator when the target paginator it refers to is changed unsuspectingly.

Calling Context:

Never called directly by clients.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function cannot be overridden or otherwise influenced.

Member Function: TPaginatorIterator::ValidatePaginator

TPaginator * ValidatePaginator () const

Interface Category:

API.

Purpose:

This function is used to lazy evaluate the state of a paginator iterator.

Calling Context:

Never called directly by clients.

Parameters:

Takes no parameters.

Return Value:

Returns a valid TPaginator target.

Exceptions:

Throws TStandardPrintPreprocessingException::kTargetMissing if the iterator has no target TPaginator.

Concurrency:

Not multithread safe.

Other Considerations:

This function cannot be overridden.

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