Class: TStandardPageDescription

Declaration: PageDescription.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TPageDescription

Inherited By:

None.

Purpose:

A general purpose page description example that clients can use as a basis for providing their own or as an adjustable page description for almost any conceivable page. It has a full range of getters and setters of its various parameters. There are two ways to construct TStandardPageDescriptions, one default version which constructs a generic 8.5 x 11 inch U.S. letter page with a7.5 x 10 inch centered printable area, and another which takes a physical rectangle size and a personalizing name and insets the printable and margin areas by .5 inches. Once the object is constructed its metrics can be adjusted at will.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Clients are encouraged to derive from TPageDescription rather than this class when providing their own page description classes. Even so, it is still possible to use this class as a base class if necessary. Any of the virtual functions can be overridden.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TStandardPageDescription::TStandardPageDescription

TStandardPageDescription (const TStandardPageDescription &)
TStandardPageDescription (const TPageDescription &)
TStandardPageDescription (const TToken & name, const TGRect & physicalRect)
TStandardPageDescription ()

Interface Category:

API.

Purpose:

Copy constructor.
Copy constructor with polymorphic base class type. Slicing copy but well behaved, for usage as a TStandardPageDescription.
Constructor that takes a TToken and a physical rectangle.
Default constructor.

Calling Context:

Called to copy an object.
Called with a polymorphic object that derives from the base class.
Creates a new named TStandardPageDescription, with the TToken parameter.
Called by the stream-in operators .

Parameters:

const TStandardPageDescription & -A TStandardPageDescription object to copy.
const TPageDescription & -A generic page description to copy. This copy may not preserve all the properties of the original class except as they are reflected by TStandardPageDescription.
const TToken & name -A personalizing name that can be used by clients to identify their own class objects.
const TGRect & physicalRect -This is a rectangle representing the physical size of the page being described. The printable and margin rectangles will be automatically inset by .5 inches.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::~TStandardPageDescription

virtual ~ TStandardPageDescription ()

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: TStandardPageDescription::GetName

virtual TToken GetName () const

Interface Category:

API.

Purpose:

Returns a TToken that is associated with this instance of TStandardPageDescription.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A TToken that is associated with this instance of TStandardPageDescription.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::GetPhysicalRect

virtual TGRect GetPhysicalRect () const

Interface Category:

API.

Purpose:

Returns the physical rectangle of the page.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The physical rectangle of the page.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::GetPrintableRect

virtual TGRect GetPrintableRect () const

Interface Category:

API.

Purpose:

Returns the printable rectangle of the page.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The printable rectangle of the page.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::GetMarginRect

virtual TGRect GetMarginRect () const

Interface Category:

API.

Purpose:

Returns the margin rectangle of the page.

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: TStandardPageDescription::GetActiveRect

virtual TGRect GetActiveRect () const

Interface Category:

API.

Purpose:

Returns the user-selectable active rectangle of the page. The active rectangle is used as the basis for many printing operations such as page tiling, centering, clipping, and so forth. The client or derived class has the option of using the physical page rectangle, the printable page rectangle, the margin rectangle, or some other rectangle with personal meaning.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The user-selectable active rectangle of the page.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::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:

The orientation of the page.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::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:

The duplex choice of the page.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::GetPrintMedia

virtual TPrintMedia * GetPrintMedia () const

Interface Category:

API.

Purpose:

Returns a TPrintMedia* associated with the current page.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A TPrintMedia* associated with the current page.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::MirrorRect

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

Interface Category:

API.

Purpose:

Performs a mirror operation on the passed in TGRect and returns a resultant TGRect. The mirror function is a simple reflection around the center of the page based on the mirror choice specified.

Calling Context:

Call this function directly.

Parameters:

const TGRect & -This specifies the rectangle to be reflected about the center of the page represented by this object.
EMirroredPage mirror =kNoMirror -This specifies how to do the mirror reflection.

Return Value:

The resultant TGRect.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::SetName

virtual void SetName (const TToken &)

Interface Category:

API.

Purpose:

Sets a TToken to be associated with this particular page description. This name is for the client's use and serves simply to help distinguish similar page descriptions from different clients.

Calling Context:

Call this function directly. Called to get the name of this particular page description.

Parameters:

const TToken & -This is the clients own personal tag which is used to name this object.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::SetPhysicalRect

virtual void SetPhysicalRect (const TGRect &)

Interface Category:

API.

Purpose:

Sets the printable rectangle of the page.

Calling Context:

Call this function directly.

Parameters:

const TGRect & -This is the rectangle which will represent the physical size of the page in this page description.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::SetPrintableRect

virtual void SetPrintableRect (const TGRect &)

Interface Category:

API.

Purpose:

Sets the printable rectangle of the page.

Calling Context:

Call this function directly.

Parameters:

const TGRect & -This is the rectangle which defines the printable area of the page.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::SetMarginRect

virtual void SetMarginRect (const TGRect &)

Interface Category:

API.

Purpose:

Sets the margin rectangle of the page.

Calling Context:

Call this function directly.

Parameters:

const TGRect & -This is the rectangle which specifies the client margins of a page.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::SetActiveRectChoice

virtual void SetActiveRectChoice (TPageDescription :: EPageActiveRect choice)

Interface Category:

API.

Purpose:

Sets the active rectangle choice for the page. This merely tells the printing system which rectangle to use as the basis for various paging functions such as tiling, or N-Up positioning.

Calling Context:

Call this function directly.

Parameters:

TPageDescription :: EPageActiveRect choice -This specifies which one of the possible rectangles in the page description will be used as the active rectangle. The active rectangle may be the physical rectangle, the printable rectangle, or the margin rectangle. (kPhysicalRect, kPrintableRect, or kMarginRect, respectively.)

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::RotatePage90

virtual void RotatePage90 (bool =true)

Interface Category:

API.

Purpose:

Rotates the page 90 degrees and takes an orientation parameter.

Calling Context:

Call this function directly.

Parameters:

bool = true -If this parameter is true (which is the default) the page is rotated 90 degrees clockwise, else if false, counter clockwise.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::SetWide

virtual void SetWide ()

Interface Category:

API.

Purpose:

Sets the page to landscape mode and uses TStandardPageDescription::RotatePage90.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::SetNarrow

virtual void SetNarrow ()

Interface Category:

API.

Purpose:

Sets the page to be in portrait mode and uses TStandardPageDescription::RotatePage90.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::AdoptMedia

virtual void AdoptMedia (TPrintMedia *)

Interface Category:

API.

Purpose:

Adopts a TPrintMedia pointer and its associated storage. The media type tells the preferred type of media to be used for this page, for example, paper or film.

Calling Context:

Call this function directly.

Parameters:

TPrintMedia * -Specifies the type of media this page description represents.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::operator=

TStandardPageDescription & operator =(const TStandardPageDescription &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TStandardPageDescription & -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: TStandardPageDescription::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 for the target object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::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: TStandardPageDescription::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: TStandardPageDescription::SetPageCenterByDisplacement

virtual void SetPageCenterByDisplacement (const TGRect & destination, const TGPoint & displacement)

Interface Category:

API.

Purpose:

This function allows the page centering operation to be set by example. The client supplies a sample printer output page rectangle and a desired center offset vector for where this page is to be positioned on that output page. TStandardPageDescription remembers that displacement and will use this specified displacement when a page is printed using this page description. If the final output page is not the same as the example used when the displacement is set, the placement value used at output time will be proportional to the displacement used in the example. That is if the example displacement is half way from the center to the bottom edge, then the output displacement for a different page size will still be half way from center to bottom edge.

Calling Context:

Called to specify how to center a page for output.

Parameters:

const TGRect & destination -An example printer output page physical rectangle.
const TGPoint & displacement -The displacement to use for the example rectangle.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function determines what the result of GetCenterDisplacement will return.

Member Function: TStandardPageDescription::SetPageCenter

virtual void SetPageCenter (const TPageCenter &)

Interface Category:

API.

Purpose:

This function provides an alternative way of specifying how to center a page on an output printer. It takes a TPageCenter object which specifies how a page should be centered with respect to any output page. There are a number of predefined TPageCenter constants that can be used to specify page centering. These are: TPageDescription::kNoCentering. This aligns page origins (not page centers) and usually gives the same results as kFlushLeftTop (below). TPageDescription::kCentered. Page centers are exactly aligned. TPageDescription::kFlushLeftTop. Left top edges are made flush. TPageDescription::kFlushTop. Top center edges are made flush. TPageDescription::kFlushRightTop. Right top corners are made flush. TPageDescription::kFlushRight. Right center edges are made flush. TPageDescription::kFlushRightBottom. Right bottom corners are made flush. TPageDescription::kFlushBottom. Bottom center edges are made flush. TPageDescription::kFlushLeftBottom. Left bottom corners are made flush. TPageDescription::kFlushLeft. Left center edges are made flush. Clients can provide their own TPageCenter values by choosing an appropriate output page rectangle different from this page, specifying a displacement for this page over that page, and then calling SetPageCenterByDisplacement followed by GetPageCenter to retrieve the desired value. This TPageCenter value can be used on any output page to obtain a proportional displacement. Page center values can be calculated manually since they are simple four value structures containing relative distances from source page edge to destination page edge. The first field of this structure is the distance from the left edge of the output page to the left edge of the input page. The second field is the distance from the top edge of the output page to the top edge of the source page. The third field is the distance from right edge to right edge. And the fourth field is the distance from bottom edge to bottom edge. Since these values are relative distances, all entries may be normalized to some convenient range without affecting the results. Values are also allowed to be negative or zero. If both top and bottom or both left and right entries are zero, no centering is performed in that dimension.

Calling Context:

Called directly to set the page centering context.

Parameters:

const TPageCenter & -A page centering value. This type is structurally similar to a TGRect.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::GetPageCenter

virtual TPageCenter GetPageCenter () const

Interface Category:

API.

Purpose:

Returns a TPageCenter value that can be used in other TPageCenter contexts where the client wishes to specify page centering. There are a number of predefined TPageCenter constants that can be used to specify page centering. These are: TPageDescription::kNoCentering. This aligns page origins (not page centers) and usually gives the same results as kFlushLeftTop (below). TPageDescription::kCentered. Page centers are exactly aligned. TPageDescription::kFlushLeftTop. Left top edges are made flush. TPageDescription::kFlushTop. Top center edges are made flush. TPageDescription::kFlushRightTop. Right top corners are made flush. TPageDescription::kFlushRight. Right center edges are made flush. TPageDescription::kFlushRightBottom. Right bottom corners are made flush. TPageDescription::kFlushBottom. Bottom center edges are made flush. TPageDescription::kFlushLeftBottom. Left bottom corners are made flush. TPageDescription::kFlushLeft. Left center edges are made flush. Clients can provide their own TPageCenter values by choosing an appropriate output page rectangle different from this page, specifying a displacement for this page over that page, and then calling SetPageCenterByDisplacement followed by GetPageCenter to retrieve the desired value. This TPageCenter value can be used on any output page to obtain a proportional displacement. Page center values can be calculated manually since they are simple four value structures containing relative distances from source page edge to destination page edge. The first field of this structure is the distance from the left edge of the output page to the left edge of the input page. The second field is the distance from the top edge of the output page to the top edge of the source page. The third field is the distance from right edge to right edge. And the fourth field is the distance from bottom edge to bottom edge. Since these values are relative distances, all entries may be normalized to some convenient range without affecting the results. Values are also allowed to be negative or zero. If both top and bottom or both left and right entries are zero, no centering is performed in that dimension.

Calling Context:

Called to obtain the page centering specification for this page description.

Parameters:

Takes no parameters.

Return Value:

Returns a TPageCenter value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::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. It defaults to 1.0.

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:

TPageDescription defines a number of TPageCenter constant values which can be used by clients or derived classes to implement various kinds of centering.

Member Function: TStandardPageDescription::Validate

void Validate ()

Interface Category:

API.

Purpose:

An internal function that makes the object self-consistent.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::SetPageMismatchChoice

virtual TPageDescription :: EPageMismatchOption SetPageMismatchChoice (TPageDescription :: EPageMismatchOption choice)

Interface Category:

API.

Purpose:

Sets the clients preference for the appropriate action to be taken during printing if a page mismatch occurs between this page description and the page destination on the printer. The options are to tile, clip, scale or not print.

Calling Context:

Called directly to set the page mismatch choice.

Parameters:

TPageDescription :: EPageMismatchOption choice -This parameter is set by the client to be one of kPrintTiled, kPrintClipped, kPrintScaled, kNonUniformScale, or kNoPrint.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::SetDuplexChoice

virtual TPageDescription :: EDuplexOption SetDuplexChoice (TPageDescription :: EDuplexOption aDuplex)

Interface Category:

API.

Purpose:

When duplex capability is available on the targeted printer, this parameter advises the printing system that the page defined by this page description should be printed in the duplex mode specified by the input parameter.

Calling Context:

Called directly to specify the duplex mode of printing.

Parameters:

TPageDescription :: EDuplexOption aDuplex -This is a parameter which can be at least one of the following values: kDuplexNoDuplex (no duplex printing or not specified), kDuplexOneSided (one sided simplex printing), kDuplexTwoSided (full duplex printing).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::GetPageMismatchChoice

virtual TPageDescription :: EPageMismatchOption GetPageMismatchChoice () const

Interface Category:

API.

Purpose:

Returns the page mismatch choice for the page.

Calling Context:

Called directly to get the current choice for the action to take when a page mismatch occurs.

Parameters:

Takes no parameters.

Return Value:

Returns the current page mismatch choice as an enum, EPageMismatchOption.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardPageDescription::GetActiveRectChoice

virtual TPageDescription :: EPageActiveRect GetActiveRectChoice () const

Interface Category:

API.

Purpose:

Returns the active rectangle choice, which the client can set to be the physical, printable or margin rectangles. Default is the printable rectangle. The active rectangle is defined to be the area of the page which is used by the printing system when calculating scaling, page mapping, and page matching.

Calling Context:

Called directly to obtain the current active rectangle choice.

Parameters:

Takes no parameters.

Return Value:

Returns the active rectangle choice.

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.