![](../../Home/Icons/Home.gif)
![](../icons/UpCNM.gif)
![](../icons/CNMContext.gif)
![](../../Home/Icons/Search.gif)
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.
- 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:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
virtual ~ TPageDescription ()
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: 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:
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:
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.
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:
Return Value:
The margin rectangle of the page.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
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:
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:
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:
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:
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:
Return Value:
Returns an enum EPageMismatchOption.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
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:
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.
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.
TPageDescription & operator =(const TPageDescription &)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Called when an object is assigned to another compatible object.
Parameters:
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.
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.
virtual long Hash () const
Interface Category:
API.
Purpose:
Returns a unique hash value for the target object.
Calling Context:
Call this function directly.
Parameters:
Return Value:
A unique hash value.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Not multithread safe.
Other Considerations:
None.
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.
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.
Copyright©1995 Taligent,Inc. All rights reserved.