Class: TPolyline

Declaration: Graphics.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MGraphic

Inherited By:

None.

Purpose:

TPolyline provides a wrapper for the TGPolyline geometry class, to which it adds the facilities inherited from MGraphic: an attribute bundle, matrix transformations, and hit detection. TPolyline has a, not is a, TGPolyline. A polyline is a collection of points that are connected with straight line segments. Polylines are parameterized, much like linear curves.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TPolyline::TPolyline

TPolyline (const TPolyline &)
TPolyline (const TGPolyline &, TGrafBundle * adoptBundle =NIL)
TPolyline (unsigned long numPoints)
TPolyline (const TGPointArray & points)
TPolyline ()

Interface Category:

API.

Purpose:

Copy constructor.
Creates a TPolyline.
Creates a TPolyline with the specified number of control points. All the points are initialized to TGPoint::kOrigin.

TPolyline

TGPointArray

Default constructor.

Calling Context:

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

Parameters:

const TPolyline & -The polyline to be copied.
const TGPolyline & -The polyline to be copied.
TGrafBundle * adoptBundle =NIL -The bundle to be adopted.
unsigned long numPoints -The number of control points.
const TGPointArray & points -The array of control points.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline::~TPolyline

virtual ~ TPolyline ()

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

virtual void Draw (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws the TPolyline to the specified TGrafPort.

Calling Context:

Call this function directly.

Parameters:

TGrafPort & port -The grafport to draw to.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline::TransformBy

virtual void TransformBy (const TGrafMatrix &)

Interface Category:

API.

Purpose:

Transforms the TPolyline'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 that the polyline's points are multiplied by.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline::ScaleBy

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

Interface Category:

API.

Purpose:

Changes the TPolyline's size according to the specified horizontal and vertical scalars (the coordinates of the first parameter). Because there are two independent scalars, the polyline'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 graphic does not stay centered at the same point unless the second argument is the old center of the graphic.

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.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline::TranslateBy

virtual void TranslateBy (const TGPoint &)

Interface Category:

API.

Purpose:

Moves the TPolyline'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: TPolyline::GetGeometricBounds

virtual TGRect GetGeometricBounds () const

Interface Category:

API.

Purpose:

Gets the bounding rectangle of the TPolyline's geometry, without considering any area added by the bundle. (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:

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: TPolyline::GetLooseFitBounds

virtual TGRect GetLooseFitBounds (const TGrafPort* =NIL) const

Interface Category:

API.

Purpose:

Gets the entire TPolyline'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: TPolyline::GetNumberOfPoints

unsigned long GetNumberOfPoints () const

Interface Category:

API.

Purpose:

Gets the number of points in this TPolyline.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the number of points.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline::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 (whose value must be less than the number of control points).

Return Value:

Returns the point at the index.

Exceptions:

Throws no exceptions, but TGPolyline::GetPoint calls a parameter assertion that fails if the index is out of range.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline::GetPoints

void GetPoints (TGPointArray & pts) const

Interface Category:

API.

Purpose:

Copies the TPolyline's control points into the parameter.

Calling Context:

Call this function directly.

Parameters:

TGPointArray & pts -The point array that the polyline's control points are copied into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline::IsRectilinear

bool IsRectilinear () const

Interface Category:

API.

Purpose:

Determines whether all the line segments of the TPolyline 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 polyline are horizontal or vertical.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline::SetPoints

void SetPoints (const TGPointArray & newPoints)

Interface Category:

API.

Purpose:

Resets the TPolyline'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: TPolyline::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, but TGPolyline::GetPoint calls a parameter assertion that fails if the index is out of range.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline::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 TPolyline 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, but TGPolyline::AddBefore calls a parameter assertion that fails if the index is out of range.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline::Append

void Append (const TGPoint & p)

Interface Category:

API.

Purpose:

Appends the specified point to the end of the TPolyline.

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: TPolyline::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, but TGPolyline::RemovePoint calls a parameter assertion that fails if the index is out of range.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline::ReverseDirection

void ReverseDirection ()

Interface Category:

API.

Purpose:

Reverses the direction of the TPolyline (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: TPolyline::DragPosition

void DragPosition (GCoordinate parametric, const TGPoint & toPoint)

Interface Category:

API.

Purpose:

Changes the TPolyline 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: TPolyline::NearestParametric

GParametric NearestParametric (const TGPoint & p) const

Interface Category:

API.

Purpose:

Gets the parametric value of the TPolyline at the point on the polyline nearest to the specified TGPoint. Polylines are parameterized starting at 0 and incremented by 1 at each control point. For example, a three-point polyline 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: TPolyline::operator=

TPolyline & operator =(const TPolyline & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TPolyline & source -The polyline 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: TPolyline::operator==

bool operator ==(const TPolyline & source) const

Interface Category:

API.

Purpose:

Tests two TPolylines for equality.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TPolyline & source -The polyline to be compared to this polyline.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TPolyline::operator!=

bool operator != (const TPolyline & source) const

Interface Category:

API.

Purpose:

Tests two TPolylines for inequality.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TPolyline & source -The polyline to be compared to this polyline.

Return Value:

Returns true if any of the control points of the source polyline are not equal to this polyline'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: TPolyline::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: TPolyline::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: TPolyline::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.