Class: TPageDescription

Declaration: PageDescription.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TPrinterAttribute

Inherited By:

TStandardPageDescription

Purpose:

This class incorporates most of the physical metrics of a page. It contains the page rectangles of the printable media. It consists of three rectangles corresponding to the physical dimensions of a page, the printable area, and the current margins. The physical rectangle is always referenced from the origin which is located at the upper left hand corner of the page. This convention is completely general and saves much confusion since page content placement and overall positioning are regulated by other classes. The origin as reference point cannot be changed or altered for purposes of moving page contents. Placement of the page itself on a printers output page is controlled by options within this class and by centering, also in this class. The printable area and margin rectangles are always positioned relative to the physical page rectangle. This class combines the Bounds, the Media, and other print options into a single class that should be retained by documents. Included are the page metrics, the media, duplex capability, mismatch options, page orientation choice, page centering, and a list of media sources and destinations on the printer.

Instantiation:

Abstract base class; do not instantiate.

Deriving Classes:

We expect lots of derived classes from TPageDescription that characterize various types of pages used in printers. All derived classes must implement all pure virtual functions but may additionally override other virtual functions. Derived classes come in several categories. Some could be const descriptions while others could be adjustable. Some could represent specific printers while others could be shared across many different printers. One general purpose derived class provided by the printing system is TStandardPageDescription. GetName must be overridden to provide a human readable name for your derived class. GetPhysicalRect and GetPrintableRect must be overridden to return the physical and printable sizes of the page being described. If GetMarginRect, GetActiveRect, GetActiveRectChoice are not overridden their behavior defaults to the printable rectangle. GetCenterDisplacement, if not overridden, returns a center point centered within the destination rectangle supplied. Other virtual functions may be overridden if needed for specific variational behavior changes.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPageDescription::TPageDescription

TPageDescription (const TPageDescription &)
TPageDescription ()

Interface Category:

API.

Purpose:

Copy constructor.
Default constructor.

Calling Context:

Called to copy an object.
Called by the stream-in operators.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageDescription::~TPageDescription

virtual ~ TPageDescription ()

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: TPageDescription::GetPhysicalRect

virtual TGRect GetPhysicalRect () const

Interface Category:

API.

Purpose:

The top-left point of the physical rectangle is used to locally reference a page to global coordinates. All other coordinates in TPageDescription are referenced to the top-left corner of the physical rectangle, that is, they are local coordinates. For example, GetPhysicalRect.GetSize returns the local size of a page but not its position. The printable rectangle of a page is referenced to the top-left corner of the physical rectangle. Thus, GetPrintableRect.GetTopLeft + GetPhysicalRect.GetTopLeft is the global offset of the printable rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a rectangle representing the physical size of the page.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageDescription::GetPrintableRect

virtual TGRect GetPrintableRect () const

Interface Category:

API.

Purpose:

The margin rectangle is purely a client parameter. It is not otherwise used by printing. Because a margin rectangle belongs to the client, it can be modified to reflect mirror images of a page. This allows binding margins, for example, to be mirrored on alternating pages of a document. It defaults to the printable rectangle. Like the printable rectangle, its coordinates are local to the physical rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a rectangle representing the printable area within a page boundary.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageDescription::GetMarginRect

virtual TGRect GetMarginRect () const

Interface Category:

API.

Purpose:

Returns the margin rectangle of the page. Defaults to the printable rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The margin rectangle of the page.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageDescription::GetActiveRect

virtual TGRect GetActiveRect () const

Interface Category:

API.

Purpose:

Returns the active rectangle of the page, which is totally user defined. Defaults to the printable rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The active rectangle of the page.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageDescription::GetActiveRectChoice

virtual EPageActiveRect GetActiveRectChoice () const

Interface Category:

API.

Purpose:

Returns the active rectangle choice, which is totally user defined. Defaults to the printable rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The active rectangle choice.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageDescription::GetOrientation

virtual EWhichWayIsUp GetOrientation () const

Interface Category:

API.

Purpose:

Returns the orientation of the page.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns an enum EWhichWayIsUp.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageDescription::GetDuplexChoice

virtual EDuplexOption GetDuplexChoice () const

Interface Category:

API.

Purpose:

Returns the duplex choice of the page.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns an enum EDuplexOption.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageDescription::GetPageMismatchChoice

virtual EPageMismatchOption GetPageMismatchChoice () const

Interface Category:

API.

Purpose:

Returns the page mismatch choice of the page.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns an enum EPageMismatchOption.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageDescription::GetPrintMedia

virtual TPrintMedia * GetPrintMedia () const

Interface Category:

API.

Purpose:

Returns the TPrintMedia for the page. Defaults to NIL if the TPrintMedia is unspecified.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the TPrintMedia for the page. Defaults to NIL if the TPrintMedia is unspecified.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageDescription::MirrorRect

virtual TGRect MirrorRect (const TGRect &, EMirroredPage mirror =kNoMirror)

Interface Category:

API.

Purpose:

Returns a TGRect with the result of applying a mirror operation on the passed in TGRect with a EMirrorPage option. The mirror operation is a simple reflection about the center of the page based on the mirror option. Mirror options are: no mirror, mirror left to right only, mirror top to bottom only, or mirror both directions.

Calling Context:

Call this function directly.

Parameters:

const TGRect & -The TGRect passed in.
EMirroredPage mirror =kNoMirror -Specifies how the client wants the page rectangles to be mirrored. Defaults to no mirror option.

Return Value:

A TGRect.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageDescription::operator=

TPageDescription & operator =(const TPageDescription &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPageDescription & -The object to be copied.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageDescription::IsEqual

virtual bool IsEqual (const MCollectible *) const

Interface Category:

API.

Purpose:

Checks to see if the parameter TPageDescription is equal to the target TPageDescription.

Calling Context:

Call this function directly.

Parameters:

const MCollectible * -The object to be compared with the page description.

Return Value:

Returns true if the parameter object is equal to the target object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageDescription::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Returns a unique hash value for the target object.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A unique hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPageDescription::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called 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: TPageDescription::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called 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.

Member Function: TPageDescription::GetCenterDisplacement

virtual TGPoint GetCenterDisplacement (const TGRect & destination, GCoordinate scale =1.0) const

Interface Category:

API.

Purpose:

When a page with a page description is being rendered onto a printer, its placement on the printer page is adjusted by a call to this function. It takes a printer output page size, compares it to its own size, compensates for any scale factor, and returns an appropriate displacement from the center. A return value of TGPoint(0.0,0.0) means the page is exactly centered on the printer output page.

Calling Context:

Called by the printing subsystem to place a document page onto a printer page. Although Printer Handlers are the principle clients of this function, it is not harmful for anyone to call it.

Parameters:

const TGRect & destination -A rectangle representing the physical dimensions of the output page for a printer on which a page is being printed.
GCoordinate scale =1.0 -This represents the current scaling factor from source page to output.

Return Value:

Returns a distance vector from the center of the output page where the source page center should be placed. This vector is in unscaled units.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This class also defines a number of TPageCenter constant values which can be used by derived classes to implement various kinds of centering.

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