Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
TPageIterator, MPrintable
Inherited By:
TCompoundPageIterator
TPaginatedPageIterator
Purpose:
An abstract base class that further refines the abstract base class, TPageIterator, for printing-specific purposes. It defines an iteration process on a collection of pages in a document, such as an MPageFolio. The pages it returns are MDrawable objects that can be displayed or printed using an appropriate TGrafPort. For example, a page iterator is created by an MPageFolio in order for it to be able to print its pages. Like its parent, TPageIterator, certain member functions of TPrintPageIterator are pure virtual and must be overridden.
There are a number of concrete page iterator objects already available in the system and a number of concrete MPageFolios that create Print Page Iterators for you. TPaginatedPageFolio, TTiledPageFolio, TBookPageFolio, and TCompoundPageFolio are some examples of concrete MPageFolios. Each one can create specific instances of TPageIterator such as TPaginatedPageIterator and TCompoundPageIterator.
As a client, you have the choice of using a print page iterator to print the entire collection of pages it contains by calling either of its MPrintable Print functions. You can also manually sequence through all pages of the iterator and do whatever you want with them: print them, display them, or eat them. 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. 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.
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 could 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.
One of the concepts that printing page iterators introduce, besides printability, is page ranges. If a page iterator is created with an embedded page range, only those pages in the range are considered part of the collection. However, the page number returned from each page as it is referenced, is the ordinal page number relative to the iteration rather than to all pages in the entire collection.
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 source for iteration. This means an iteration can be affected by a page range not designating the whole document. In these cases, the page number is still the ordinal page in the iteration. 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 Frameworks or the application.
Instantiation:
Allocate on the heap or the stack.
Deriving Classes:
Derive this class to create page iterators with inherent printing capability. MPageFolio objects should create a TPrintPageIterator object derived from this class. TPageCompositor objects should also create a TPrintPageIterator object derived from this class.
Concurrency:
Not multithread safe.
Resource Use:
No special requirements.
Other Considerations:
None.
virtual ~ TPrintPageIterator ()
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 void Print (const TPrintJobDescription & job)
Interface Category:
API.
Purpose:
Because TPageIterator is an MPrintable, this function performs the task of printing all pages in the iterator as a single job. Derived classes need not override this function.
Calling Context:
Called directly to automatically print all pages accessible from this page iterator.
Parameters:
- const TPrintJobDescription & job -This is the print job that describes how the client wants the job to be printed. There are two standard components that make up this object: a print device portion and a client application portion. Clients have the option of setting various parameters for printing before passing the job description to the print routine. Among the things that can be affected are the number of copies, the beginning and ending banner pages, the disposition of the job, and other application or device-specific parameters.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
Member Function: TPrintPageIterator::PrintAndCreateJobHandle
virtual TPrintJobHandle * PrintAndCreateJobHandle (const TPrintJobDescription & job)
Interface Category:
API.
Purpose:
Prints all pages reachable by the page iterator and returns a print job handle to the print job just submitted. Derived classes don't need to override this function.
Calling Context:
Called directly to automatically print all pages accessible from this page iterator and to obtain a handle to the job just submitted. The job handle returned can then be used to track the status of the job.
Parameters:
- const TPrintJobDescription & job -This is the print job that describes how the client wants the job to be printed. There are two standard components that make up this object: a print device portion and a client application portion. Clients have the option of setting various parameters for printing before passing the job description to the print routine. Among the things that can be affected are the number of copies, the beginning and ending banner pages, the disposition of the job, and other application or device-specific parameters.
Return Value:
Returns a client-owned print job handle that can be used to track the status of the just-submitted print job.
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 reachable by the iterator. Derived classes must override this function.
Calling Context:
Called directly to return the total number of pages reachable by the iterator.
Parameters:
Return Value:
Returns the total number of pages in the folio that created this iterator.
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:
Seeks to an absolute page number or to a specific iteration of the iterator.
Calling Context:
Called directly at any time to find or iterate to a specific page of the iterator.
Parameters:
- unsigned long pageNumber -The page number to find. Think of this as the index number of the iteration.
Return Value:
Returns a pointer to a TPage object that represents the page found or NIL if the specified page does not exist in the iterator.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual TPage * Current () const
Interface Category:
API.
Purpose:
Returns the current state of the iterator representing the last iteration function performed on the iterator. The value of the last iteration is returned as the value of Current whether it was successful or not. A non-NIL value means the last iteration was successful and points to a TPage object for that iteration. A NIL value means the last iteration was unsuccessful, that is, the iterator either reached the end or beginning of the iterator collection or no iteration has yet been performed.
Calling Context:
Called directly to determine the success or failure of the last iteration and to return the value of the last iteration performed.
Parameters:
Return Value:
A pointer to a TPage object for the last iteration or NIL if the last iteration was unsuccessful.
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.