Class: TPageCompositor

Declaration: PageCompositor.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

TNUpCompositor TPageImpositor

Purpose:

A high-level printing class used to create a special type of page iterator whose purpose is to compose pages from other page iterators into pages for its own purposes, usually with new format, new adornments, different organization, added form content, or whatever. A compositor creates new pages from old pages. Page compositors are similar to MPageFolios because they create page iterators, but, in fact, that is all they do. Like MPageFolios, the page iterators created by page compositors can be modified with page ranges, but unlike MPageFolios, these iterators have no target folio, instead they use other page iterators as targets. Once an iterator from a page compositor is created, it becomes isolated from the page compositor that created it, making no further references to its creator. Instead, it uses its target page iterator as its reference document. The page compositor itself can be used to create other page iterators or can be discarded without endangering the successful operation of iterators previously created. The created iterator of a page compositor does not necessarily produce the same number of pages as its input target; it can produce more or fewer depending on what its purpose is. Some of the things that page compositors can do are forms printing, labeling, N-up printing, imposition, adornment, and placement of alignment marks, to name just a few. Page compositor iterators can be connected together in chains of arbitrary length to achieve some very sophisticated results. (However it is usually not a good idea to produce iterator chains with branches or circular dependencies, that is, to depend on the same iterator as a target in more than one location in the chain.) Although a base class TPageCompositor can be constructed and used to create a valid page iterator, it really does not do anything except pass its input pages to its output. Derived classes add the interesting functionality and special features.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

All compositors should derive from this base class. Override all virtual functions (CreatePageIterator is really the only one to worry very much about).

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPageCompositor::TPageCompositor

TPageCompositor ()
TPageCompositor (const TPageCompositor &)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Called to create a pass-through compositor. Only for internal use by Resurrect. Developers should treat as protected.
Called to copy an object.

Parameters:

Takes no parameters.
const TPageCompositor & -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageCompositor::~TPageCompositor

virtual ~ TPageCompositor ()

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: TPageCompositor::CreatePageIterator

virtual TPrintPageIterator * CreatePageIterator (TPageIterator * aliasIterator, TPageRange * aliasRange =NIL) const

Interface Category:

API.

Purpose:

Creates the page iterator for a particular derived class of TPageCompositor. Its purpose is to create a page iterator that performs some form of composition over the TPageIterator target passed in as an argument to this function and to generate pages based on the composition of pages. It can also use the TPageRange (if present) to further characterize the resultant composition of pages. It produces a new set of pages that the newly created iterator iterates over. The new iterator is allowed to keep an alias pointer to the target alias iterator and to the alias page range in order to create its pages. The new iterator also has printing semantics, meaning that it can print itself. Be default, the base TPageCompositor class, without a derived class, generates a do-nothing or pass-through TPrintPageIterator. In other words, for every page in the target page iterator, it simply passes that page through unchanged.

Calling Context:

Called directly to create the page iterator for the a particular page compositor.

Parameters:

TPageIterator * aliasIterator -A polymorphic page iterator to use as a target. When a page compositor is created, it must build its pages from other pages, namely those of this page iterator. This iterator is used as the source of pages for the composition. When the compositor iterator is destroyed, the target page iterator is ignored. The iterator used for this argument can be any page iterator, printable or not.
TPageRange * aliasRange =NIL -A page range that is used to modify which pages will be covered by the iterator. It works just like any other page range. It is not adopted but a pointer can be kept by the new iterator.

Return Value:

The created page iterator.

Exceptions:

Throws TStandardPrintPreprocessingException::kTargetMissing if the adopted page iterator is NIL.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageCompositor::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called directly to generate a hash value. Also used when the object is placed in a collection.

Parameters:

Takes no parameters.

Return Value:

The hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageCompositor::operator=

TPageCompositor & operator =(const TPageCompositor &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPageCompositor & -The object from which to assign.

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: TPageCompositor::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called directly to stream in data.

Parameters:

TStream & fromWhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageCompositor::operator>>=

virtual TStream & operator >>=(TStream & toWhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called directly to stream out data.

Parameters:

TStream & toWhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

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.