Class: TPen

Declaration: GrafPens.h

Taxonomy Categories:

Member Functions:

~TPen
GetPenData
GetPenType
GetPenBalance
GetPenWidth
operator>>=
operator<<=
TPen
operator=
AdjustBounds

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

THairlinePen TSolidPen

Purpose:

Pens are objects that define how lines are drawn--more specifically, the lines that frame a graphic. (These can be curved or straight lines, depending on the geometry whose edges form the frame of the graphic.) Pens are one of the kinds of attributes stored in TGrafBundles. TPen is an abstract class interface for pens. Derived classes, such as THairlinePen and TSolidPen, provide the details of the pen behavior. The lines drawn by a pen can be arbitrarily wide (depending on the behavior of the TPen derived class). The pen balance describes where a line is drawn relative to the edge of the geometry. The pen can be centered, so that the edge of the geometry lies right in the middle of the drawn line. Alternatively, the pen can draw the frame inside or outside the edge of an area-enclosing geometry. Chose one of these alternatives by selecting one value from the enum EPenBalance. The line drawn by the pen can be transformed along with the graphic whose frame it draws. For example, doubling the size of a polygon might also double the thickness of the line around it. Alternatively, the pen can be made independent, so that the style of its frame isn't affected by transformations to the graphic.

Instantiation:

Abstract class; do not allocate.

Deriving Classes:

Principal derived classes are THairlinePen and TSolidPen, with other classes descending from TSolidPen.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPen::~TPen

virtual ~ TPen ()

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:

This is a pure virtual function and must be overridden by classes deriving from TPen.

Member Function: TPen::GetPenData

virtual EPenType GetPenData (EPenBalance & penBalance, GCoordinate & penWidth) const

Interface Category:

API.

Purpose:

Provides the caller with the most commonly needed information about this pen.

Calling Context:

Called when you need the balance, width, and type information about a pen quickly.

Parameters:

EPenBalance & penBalance -The type of pen balance (internal, external, or centered).
GCoordinate & penWidth -The width of the pen in world coordinates .

Return Value:

Returns an EPenType (hairline, solid, dashed or unknown).

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPen::GetPenType

virtual EPenType GetPenType () const

Interface Category:

API.

Purpose:

Returns the type of pen defined by the TPen, as specified by an EPenType (hairline, solid, dashed, or unknown).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns an EPenType value (kHairlinePen, kSolidPen, kDashedPen, or kUnknownPen).

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPen::GetPenBalance

virtual EPenBalance GetPenBalance () const

Interface Category:

API.

Purpose:

Returns the type of pen balance defined by the TPen, as specified by an EPenBalance (internal, external, or center).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns an EPenBalance value (kCenterFrame, kInsetFrame or kOutsetFrame).

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPen::GetPenWidth

virtual GCoordinate GetPenWidth () const

Interface Category:

API.

Purpose:

Returns the width of the pen (in world coordinates).

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The width of the pen in world coordinates.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPen::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream that 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.

Member Function: TPen::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The stream that 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: TPen::TPen

TPen ()
TPen (const TPen &)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

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

Parameters:

Takes no parameters.
const TPen & -The TPen to copy from.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TPen.

Member Function: TPen::operator=

TPen & operator =(const TPen & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function by using the operator in an assignment statement.

Parameters:

const TPen & source -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:

This function is a pure virtual function and must be overridden by classes deriving from TPen.

Member Function: TPen::AdjustBounds

virtual TGRect AdjustBounds (const TGRect & bounds) const

Interface Category:

API.

Purpose:

Adjusts the size of the specified bounding rectangle to account for the width of the pen being used. For the TPen abstract class, the bounds parameter remains unchanged.

Calling Context:

Call this function directly.

Parameters:

const TGRect & bounds -The rectangle to be adjusted.

Return Value:

Returns the modified version of the bounding rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

TPen's derived classes must override this function to adjust the bounds according to the pen width.

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