Class: TPageMapper

Declaration: Paginator.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

None.

Purpose:

A page mapper maps a sequence of source pages into a destination page. Depending on the number of pages to be mapped and their orientation, it matches the boundaries of the source pages to the boundaries of the destination. It then provides a transformation matrix for each page in the source to its proper location in the destination. Appropriate scaling, orientation, and translation are calculated automatically. The orientation and page frequency for the tiling are supplied by the client and the transformation, and stepping between each page is supplied by the page mapper. In this respect, TPageMapper acts like an iterator, providing a series of transformations for each step in the mapping process. A TPageMapper also takes a scan order to specify in which order the steps are to be sequenced. You begin by calling StepFirst to get the first transformation to place the first page being mapped. Then, until IsLastStepOK is false, call Step for each succeeding page transformation. The input sources pages are tiled over the destination page with the specified orientation and frequency such as might be seen with N-up printing or imposition. The mapping makes sure that the active and physical rectangles of the source pages are within the active and physical rectangles of the destination page respectively.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

This is a specific purpose class not intended for deriving.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPageMapper::TPageMapper

TPageMapper (const TPageMapper &)
TPageMapper (const TULongPair & xyNUpFrequency, const TPageDescription & src)
TPageMapper (const TULongPair & xyNUpFrequency, const TPageDescription & src, const TPageDescription & dst, TPageMapper :: EMapOrientation srcIntoDst =TPageMapper :: k0Degrees, TScanOrder * adoptOrder =NIL, bool overDestination =true)
TPageMapper ()

Interface Category:

API.

Purpose:

Copy constructor.
Constructs a map from page frequency and a source page description. The destination page is assumed to be the same as the source page description.
Constructs a map from a page frequency, a source page description, a destination page description, an orientation, and a scan order. The last arguments can be defaulted.
Default constructor.

Calling Context:

Called to copy an object.
Called to construct a page mapper according to the specified metrics.
Called to construct a page mapper according to a specified set of metrics.
Only for internal use by Resurrect. Developers should treat as protected.

Parameters:

const TPageMapper & -The object to copy.
const TULongPair & xyNUpFrequency -The number of pages in x and y desired in the mapping.
const TPageDescription & src -The source page size to be mapped into the destination. The destination page defaults to the source page in this constructor.
const TULongPair & xyNUpFrequency -The number of pages in x and y desired in the mapping.
const TPageDescription & src -The source page size to be mapped into the destination.
const TPageDescription & dst -The destination page size when it is different than the source page.
TPageMapper :: EMapOrientation srcIntoDst =TPageMapper :: k0Degrees -The orientation to be used in the mapping. The default is no rotation.
TScanOrder * adoptOrder =NIL -The scan order to use in the mapping. Right down is the default.
bool overDestination =true -Currently not used.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageMapper::~TPageMapper

virtual ~ TPageMapper ()

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: TPageMapper::StepFirst

virtual void StepFirst (TGrafMatrix & result)

Interface Category:

API.

Purpose:

Steps to the first position of the mapping sequence as determined by the scan order. It creates a transformation matrix that transforms the source page described by the source page description, into the correct orientation, scale, and translation over the destination page described by the destination page description.

Calling Context:

Called directly to begin a mapping sequence. If there are other steps in mapping, this might be the initial step in a repeating loop. Also called internally by the Printing Framework during printing where a page mapper is used to position input pages on the output page.

Parameters:

TGrafMatrix & result -The resultant mapping transformation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageMapper::Step

virtual void Step (TGrafMatrix & result)

Interface Category:

API.

Purpose:

Performs the next step in the page mapping after at least one initial first step operation. A new matrix is calculated and returned.

Calling Context:

Called directly for all subsequent step operations to perform the mapping for that step. This might be the main stepping operation inside a mapping repeat loop. Also called internally by the Printing Framework during printing where a page mapper is used to position input pages onto output pages.

Parameters:

TGrafMatrix & result -The resultant mapping transformation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageMapper::IsLastStepOK

virtual bool IsLastStepOK () const

Interface Category:

API.

Purpose:

Returns true if the last step operation was correct and completed successfully; false otherwise.

Calling Context:

Called directly to determine whether the last step operation is the final one. If it's the final step, this function returns false. Also called internally by the printing framework during printing where a page mapper is used to position input pages onto output pages.

Parameters:

Takes no parameters.

Return Value:

Returns true if the last step function succeeded.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageMapper::GetNumberOfSteps

virtual unsigned long GetNumberOfSteps () const

Interface Category:

API.

Purpose:

Returns the total number of steps the page mapping takes to completely cover the destination page as specified by the mapping. This value can be used in a loop in lieu of testing TPageMapper::IsLastStepOK.

Calling Context:

Called directly to determine the total number of steps required for this mapping. Also called internally by the Printing Framework during printing where a page mapper is used to position input pages onto output pages.

Parameters:

Takes no parameters.

Return Value:

Returns the total number of steps required to do the mapping.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageMapper::operator=

TPageMapper & operator =(const TPageMapper &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPageMapper & -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: TPageMapper::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Generates a hash value.

Calling Context:

Called directly to generate a hash value.

Parameters:

Takes no parameters.

Return Value:

Returns the hash value for the object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageMapper::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 is streamed 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: TPageMapper::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 is streamed 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.