Class: TPageIterator

Declaration: PageIterator.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TPrintPageIterator

Purpose:

This is an abstract base class that defines the iteration property among TPages or collections of TPages. Although TPageIterators resemble typical iterators in many ways, there are important distinctions. A TPageIterator iterates over collections of TPage objects. The pages it returns are MDrawable objects that can be displayed or drawn using an appropriate TGrafPort. TPage objects returned from a TPageIterator are valid only as long as the iterator is positioned at a given page. TPage objects cannot be added to or removed from an iterator or retained by clients unless they are copied. A TPage object returned by any iterator operation is valid only until the iterator is changed or moved to a new page. Once the iterator is moved, previous TPage objects become obsolete and should no longer be used. The page objects returned by a print page iterator are MDrawables that can be drawn to any valid TGrafPort just like any other MDrawable. The content that is drawn is the content of the page represented by the last iterator operation. Pages are accessed by calling the iteration functions, which search for the requested page and return non-NIL results if the find operation was successful. The success of an iteration can be determined by checking the return value of the function or by calling Current. Current always returns the success state of the previous iteration, which can be NIL if the last iteration was not successful. If an iteration is successful, a valid TPage pointer is returned as the value of the function. When a value of NIL is returned, the result of a subsequent call to Next or Previous causes an exception to occur because the result for any of these functions is indeterminate without a previous successful iteration. Clients cannot retain page pointers across iterations nor assume any implementation behind them. Page numbers are chronological page numbers from the beginning of the collection and are zero based, zero being the first page in the collection. Any arbitrary collection of pages constitutes a viable target for iteration. Page numbers and order within the collection are reflected or imposed by the iterator and do not necessarily correspond to ordering within the collection itself. This means page iterators can define their own ordering independent of the original collection. The ordinal page number gives the page number relative to other pages in the iteration such as the previous or next page. This allows page iterators to reflect embedded page range selections in the collection. It also means page numbers do not necessarily reflect the page number assigned to a page by the Document framework or the application.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

All page iterators should derive from this class. Any collection of pages, those in a document, in a folio, in a compositor, or other abstract collection, should use this as a base class.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Other Considerations:

The TPage objects returned from a TPageIterator are considered valid only as long as the iterator is positioned at that page. Once the iterator is moved or repositioned at a different page, the previous page becomes invalid. Clients should not retain pointers to pages from previous iterations unless the page object itself is copied.

Member Function: TPageIterator::~TPageIterator

virtual ~ TPageIterator ()

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.

Member Function: TPageIterator::Count

virtual unsigned long Count () const

Interface Category:

API.

Purpose:

Returns the total number of pages in the iterator.

Calling Context:

Called to obtain the number of pages available in an iterator.

Parameters:

Return Value:

Returns the number of pages in the page iterator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageIterator::First

virtual TPage * First ()

Interface Category:

API.

Purpose:

Returns the first page (ordinal page number 0) in the page iterator. First is implemented internally in terms of Seek so derived classes should not implement Seek in terms of First, Last, Next, or Previous. Clients are free to override all iteration functions.

Calling Context:

Called to obtain the first page in a page iterator.

Parameters:

Return Value:

Returns a pointer to the first TPage object in the page iterator or NIL if there are no pages in the iterator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

First is implemented internally in terms of Seek, which derived classes must override. Clients should not implement Seek in terms of First, Next, Last, or Previous, unless they too are overridden.

Member Function: TPageIterator::Last

virtual TPage * Last ()

Interface Category:

API.

Purpose:

Finds the last page in a page iterator and returns it or NIL if there are no pages in the iterator.

Calling Context:

Called to obtain the last page in a page iterator.

Parameters:

Return Value:

A pointer to the last page in the iterator is returned or NIL if there is no last page.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is implemented internally in terms of Seek, which derived classes must override. Clients should not implement Seek in terms of First, Next, Last, or Previous, unless they too are overridden.

Member Function: TPageIterator::Next

virtual TPage * Next ()

Interface Category:

API.

Purpose:

Given a current page, this function returns a pointer to the next page in the page iterator or NIL if the current page is the last page. If there is a current page, Current returns a non-NIL pointer to that page, meaning that the page iterator is positioned at that page. If there is no current page, this function causes an exception.

Calling Context:

Called to get the next page in the page iterator. It positions the page iterator at the next available page.

Parameters:

Return Value:

Returns a pointer to the next page found in the iterator or NIL if there are no more pages.

Exceptions:

Throws TStandardPrintPreprocessingException::kIteratorSequenceError if Current returns NIL, meaning that the iterator is not positioned at a valid page. Another successful iterator function must immediately precede this function call.

Concurrency:

Not multithread safe.

Other Considerations:

This function is implemented internally in terms of Seek, which derived classes must override. Clients should not implement Seek in terms of First, Next, Last, or Previous, unless they too are overridden.

Member Function: TPageIterator::Previous

virtual TPage * Previous ()

Interface Category:

API.

Purpose:

Given a current page, this function returns a pointer to the previous page in the page iterator or NIL if the current page is the first page. If there is a current page, Current returns a non-NIL pointer to that page, meaning that the page iterator is positioned at that page. If there is no current page, this function causes an exception.

Calling Context:

Called to get the previous page in the page iterator. The iterator is positioned to point at the page returned.

Parameters:

Return Value:

Returns a pointer to the previous page found in the iterator or NIL if there are no more pages previous to the current one.

Exceptions:

Throws TStandardPrintPreprocessingException::kIteratorSequenceError if Current returns NIL, meaning that the iterator is not positioned at a valid page. Another successful iterator function must immediately precede this function call.

Concurrency:

Not multithread safe.

Other Considerations:

This function is implemented internally in terms of Seek, which derived classes must override. Clients should not implement Seek in terms of First, Next, Last, or Previous, unless they too are overridden.

Member Function: TPageIterator::Seek

virtual TPage * Seek (unsigned long pageNumber)

Interface Category:

API.

Purpose:

Finds a page in the page iterator corresponding to the specified page number and positions the iterator to that page.

Calling Context:

Called to move the iterator to a specific page.

Parameters:

Return Value:

Returns a pointer to the page specified or NIL if that page does not exist in the iterator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function must always be overridden by derived classes but it should not be implemented in terms of First, Last, Next or Previous unless they too are overridden.

Member Function: TPageIterator::Current

virtual TPage * Current () const

Interface Category:

API.

Purpose:

Reflects the current state of the iterator. It supplies a pointer to the page that was last iterated or NIL if the last iteration failed.

Calling Context:

Called to obtain the result of the last iteration call or to determine if the last iteration call was successful.

Parameters:

Return Value:

Returns the value of the last iteration function call, which is non-NIL if the last call was successful, or NIL if it was unsuccessful. If the result is non-NIL, it points to the TPage object found in the last iteration.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageIterator::TPageIterator

TPageIterator ()

Interface Category:

API.

Purpose:

Default constructor.

Calling Context:

Called by the stream-in operators and by derived classes.

Parameters:

Return Value:

None.

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.