Class: TPolygon

Declaration: Graphics.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MGraphic

Inherited By:

None.

Purpose:

TPolygon provides a wrapper for the TGPolygon geometry class, to which it adds the facilities inherited from MGraphic: an attribute bundle, matrix transformations, and hit detection. TPolygon has a, not is a, TGPolygon. A TGPolygon is a collection of points connected by straight line segments, with the last point automatically connected to the first, closing the path. Because TGPolygon is derived from TGPolyLine, the path is parameterized.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPolygon::TPolygon

TPolygon (const TPolygon &)
TPolygon (const TGPolygon &, TGrafBundle * adoptBundle =NIL)
TPolygon (const TGRect &, TGrafBundle * adoptBundle =NIL)
TPolygon (unsigned long numPoints, bool EOFill =true, TGrafBundle * adoptBundle =NIL)
TPolygon (const TGPointArray & pts, bool EOFill =true, TGrafBundle * adoptBundle =NIL)
TPolygon ()

Interface Category:

API.

Purpose:

Copy constructor.
Creates a TPolygon from the specified TGPolygon with the specified bundle.
Creates a TPolygon (a rectangle) from the specified TGRect with the specified attribute bundle.
Creates a TPolygon with the specified number of points, fill rule, and attribute bundle.
Creates a TPolygon with the specified points, fill rule, and attribute bundle.
Default constructor.

Calling Context:

Called to copy an object.
Call this function directly.
Call this function directly.
Call this function directly.
Call this function directly.
Called by the stream-in operators.

Parameters:

const TPolygon & -The polygon to be copied.
const TGPolygon & -The polygon geometry to be copied.
TGrafBundle * adoptBundle =NIL -The attribute bundle to be adopted.
const TGRect & -The rectangle geometry to be converted into a polygon.
TGrafBundle * adoptBundle =NIL -The attribute bundle to be adopted.
unsigned long numPoints -The number of points in this polygon.
bool EOFill =true -The flag indicating whether to use the even-odd rule or the nonzero winding number rule when filling the shape. The default is true--even-odd fill rule.
TGrafBundle * adoptBundle =NIL -The attribute bundle to be adopted.
const TGPointArray & pts -The array of points that make up the polygon.
bool EOFill =true -The flag indicating whether to use the even-odd rule or the nonzero winding number rule when filling the shape. The default is true--even-odd fill rule.
TGrafBundle * adoptBundle =NIL -The attribute bundle to be adopted.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::~TPolygon

virtual ~ TPolygon ()

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: TPolygon::Draw

virtual void Draw (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws the TPolygon to the specific TGrafPort. Attributes in the polygon's bundle override those already provided in the port (if any).

Calling Context:

Call this function directly.

Parameters:

TGrafPort & port -The port to which drawing should go. The port in turn invokes rendering on a particular TGrafDevice.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::TransformBy

virtual void TransformBy (const TGrafMatrix &)

Interface Category:

API.

Purpose:

Transforms the TPolygon's shape and position by applying the specified transformation matrix.

Calling Context:

Called by the Graphics system. You can also call this function directly.

Parameters:

const TGrafMatrix & -The transformation matrix by which the polygon's points are multiplied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::ScaleBy

virtual void ScaleBy (const TGPoint &, const TGPoint & =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Changes the TPolygon's size according to the specified horizontal and vertical scalars (the coordinates of the first parameter). Because there are two independent scalars, the polygon's shape can change. The second parameter defines the center of scale. Every point is mapped to a new position by applying the scalars to the point's horizontal and vertical displacements from the center of scale. Thus, the scaled polygon does not stay centered at the same point unless the second argument is the old center of the polygon.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & -A vector whose x-coordinate is the horizontal scalar, and whose y-coordinate is the vertical scalar.
const TGPoint & =TGPoint :: kOrigin -The point from which to measure the horizontal and vertical displacement of each point to be scaled. To create the resulting geometry, the displacements are multiplied by the horizontal and vertical scalars, respectively. The default center of scale is the origin (0,0).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::TranslateBy

virtual void TranslateBy (const TGPoint &)

Interface Category:

API.

Purpose:

Moves the TPolygon's position by the specified vector.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & -The vector whose x- and y-coordinates are to be added to those of each point in the geometry.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::RotateBy

virtual void RotateBy (GDegrees, const TGPoint & =TGPoint :: kOrigin)

Interface Category:

API.

Purpose:

Rotates the TPolygon by the given number of degrees, using the specified center of rotation. This does not change the size or shape of the polygon, only its orientation.

Calling Context:

Call this function directly.

Parameters:

GDegrees -The number of degrees to rotate the graphic.
const TGPoint & =TGPoint :: kOrigin -The point around which the polygon is rotated.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::GetGeometricBounds

virtual TGRect GetGeometricBounds () const

Interface Category:

API.

Purpose:

Gets the bounding rectangle of the TPolygon's geometry, without considering any area added by its attribute bundle. (For example, the pen is a bundled attribute that can increase the area of the polygon by adding a border that extends beyond the bounds of the geometry.)

Calling Context:

Called during hit detection. You can also call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the bounding rectangle, which is the smallest axis-aligned rectangle that encloses the geometry.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::GetLooseFitBounds

virtual TGRect GetLooseFitBounds (const TGrafPort* =NIL) const

Interface Category:

API.

Purpose:

Gets the entire TPolygon's bounding rectangle, taking into account the bundle information. (For example, the pen is a bundled attribute that can increase the area of the graphic by adding a border that extends beyond the bounds of the geometry.)

Calling Context:

Called during hit detection. You can also call this function directly.

Parameters:

const TGrafPort * =NIL -The graphics port used for accessing hierarchical bundles.

Return Value:

Returns the bounding rectangle, which is the smallest axis-aligned rectangle that encloses the entire graphic, including any area added by the pen.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::GetNumberOfPoints

unsigned long GetNumberOfPoints () const

Interface Category:

API.

Purpose:

Gets the number of control points in this TPolygon.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the number of control points.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::GetPoint

TGPoint GetPoint (unsigned long index) const

Interface Category:

API.

Purpose:

Gets the control point at the specified index.

Calling Context:

Call this function directly.

Parameters:

unsigned long index -The index into the array of control points. Zero returns the first point.

Return Value:

Returns the control point at the indexed location.

Exceptions:

Throws no exceptions, passes all exceptions through. However, a parameter assertion in TGPolyline fails if the index is out of range.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::GetPoints

void GetPoints (TGPointArray & pts) const

Interface Category:

API.

Purpose:

Returns, in the specified parameter, the complete array of control points.

Calling Context:

Call this function directly.

Parameters:

TGPointArray & pts -The polygon's control points, returned by reference.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::IsRectilinear

bool IsRectilinear () const

Interface Category:

API.

Purpose:

Determines whether all the line segments of the TPolygon are horizontal or vertical.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if all the line segments of the polygon are horizontal or vertical.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::GetEOFill

bool GetEOFill () const

Interface Category:

API.

Purpose:

Returns a Boolean indicating which one of two possible algorithms is used to fill the curve.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if an even-odd rule is used for determining what area is filled, and false if a nonzero winding rule is used.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::IsConvex

bool IsConvex () const

Interface Category:

API.

Purpose:

Determines if this TPolygon is convex.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this polygon is convex.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::SetEOFill

void SetEOFill (bool EOFill)

Interface Category:

API.

Purpose:

Determines which one of two possible algorithms is used to fill the polygon.

Calling Context:

Call this function directly.

Parameters:

bool EOFill -true if an even-odd rule should be used for determining what area is filled, and false if a nonzero winding rule should be used.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::SetPoints

void SetPoints (const TGPointArray & newPoints)

Interface Category:

API.

Purpose:

Resets the TPolygon's control points. The number of points can be changed.

Calling Context:

Call this function directly.

Parameters:

const TGPointArray & newPoints -The new control points.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::SetPoint

void SetPoint (unsigned long index, const TGPoint & p)

Interface Category:

API.

Purpose:

Resets the control point at the specified index to the TGPoint.

Calling Context:

Call this function directly.

Parameters:

unsigned long index -The index (whose value must be less than the number of control points).
const TGPoint & p -The new control point.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::AddBefore

void AddBefore (unsigned long index, const TGPoint & tobeadded)

Interface Category:

API.

Purpose:

Inserts the specified TGPoint before the control point at the specified index. The size of this TPolygon increases by one.

Calling Context:

Call this function directly.

Parameters:

unsigned long index -The index (whose value must be less than the number of control points).
const TGPoint & tobeadded -The new control point.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::Append

void Append (const TGPoint & p)

Interface Category:

API.

Purpose:

Appends the specified point to the end of the TPolygon.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & p -The new control point.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::RemovePoint

void RemovePoint (unsigned long index)

Interface Category:

API.

Purpose:

Removes the control point at the specified index.

Calling Context:

Call this function directly.

Parameters:

unsigned long index -The index (whose value must be less than the number of control points).

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::ReverseDirection

void ReverseDirection ()

Interface Category:

API.

Purpose:

Reverses the direction of the TPolygon (that is, the order of the control points).

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: TPolygon::DragPosition

void DragPosition (GCoordinate parametric, const TGPoint & toPoint)

Interface Category:

API.

Purpose:

Changes the TPolygon so that it passes through the specified TGPoint at the specified parametric value. The two control points nearest to the parametric are moved so that the line segment passes through the specified point.

Calling Context:

Call this function directly.

Parameters:

GCoordinate parametric -The parametric value.
const TGPoint & toPoint -The new point that this polyline passes through.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::NearestParametric

GParametric NearestParametric (const TGPoint & p) const

Interface Category:

API.

Purpose:

Returns the parametric value of the TPolygon at the point on the polygon nearest to the specified TGPoint. Polygons are parameterized starting at 0 and incremented by 1 at each control point. For example, a three-point polygon has a parametric range between 0 and 2 (inclusively).

Calling Context:

Call this function directly.

Parameters:

const TGPoint & p -The point for which the parametric value is computed.

Return Value:

Returns the parametric value of the polyline corresponding to a point on the polyline nearest to the specified point.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::operator=

TPolygon & operator =(const TPolygon & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPolygon & source -The polygon to be copied.

Return Value:

Returns a 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: TPolygon::operator==

bool operator ==(const TPolygon & source) const

Interface Category:

API.

Purpose:

Tests two TPolygons for equality.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TPolygon & source -The polygon to be compared to this polygon.

Return Value:

Returns true if all the control points are equal to the corresponding points of the source polygon, and if the bundles are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::operator!=

bool operator != (const TPolygon &) const

Interface Category:

API.

Purpose:

Tests two TPolygons for inequality.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TPolygon & -The polygon to be compared to this polygon.

Return Value:

Returns true if any of the control points of the source polygon are not equal to this polygon's corresponding points, and if the bundles are unequal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolygon::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 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: TPolygon::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 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: TPolygon::Validate

void Validate ()

Interface Category:

API.

Purpose:

Makes sure that the graphic's bounds are up-to-date.

Calling Context:

Called by the Graphics system before returning bounds to the user. You should not need to call it directly.

Parameters:

Takes no parameters.

Return Value:

None.

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.