Class: TGArea

Declaration: AreaGeometry.h

Taxonomy Categories:

Member Functions:

TGArea
~TGArea
GetEmptyArea
GetInfiniteArea
TransformBy
IsEmpty
SetToEmpty
IsRectilinear
IsRectangular
IsSingular
GetBounds
Intersects
Contains
Add
operator+=
Subtract
operator-=
Intersect
operator*=
ExclusiveOr
operator^=
operator=
operator==
operator!=
operator<<=
operator>>=
GetTimeStamp

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

The TGArea class is a device-independent specification of an arbitrarily-shaped area. A TGArea object is defined as an object that performs certain binary CAG (Constructive Area Geometry) operations on other area-defining geometries, such as TGRect, TGEllipse, and TGPolygon. The CAG operations are Add (union), Subtract, Intersection, and Exclusive OR. For instance, a TGArea can be made up of the area of a rectangle minus the area of an ellipse. Thus, the TGArea is a conglomeration of one or more area-enclosing geometries. The TGArea provides constructors for creating an area from a given shape (such as a TGRect, TGPolygon, or TGGlyphRun) and can be transformed by a TGrafMatrix. The class also provides operators and other member functions for the CAG operations.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Do not derive from this class.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TGArea::TGArea

TGArea ()
TGArea (const TGRect & g)
TGArea (const TGEllipse & g)
TGArea (const TGPolygon & g)
TGArea (const TGLoop & g)
TGArea (const TGGlyphRun & g)
TGArea (const TGArea & g)

Interface Category:

API.

Purpose:

Default constructor.
Creates an area geometry from the specified rectangle.
Creates an area geometry from the specified ellipse.
Creates an area geometry from the specified polygon.
Creates an area geometry from the specified loop geometry.
Creates an area geometry from the specified glyph run.
Copy constructor.

Calling Context:

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

Parameters:

Takes no parameters.
const TGRect & g -The rectangle from which the area is to be constructed.
const TGEllipse & g -The ellipse from which the area is to be constructed.
const TGPolygon & g -The polygon from which the area is to be constructed.
const TGLoop & g -The loop geometry from which the area is to be constructed.
const TGGlyphRun & g -The glyph run from which the area is to be constructed.
const TGArea & g -The area geometry to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGArea::~TGArea

virtual ~ TGArea ()

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: TGArea::GetEmptyArea

static const TGArea & GetEmptyArea ()

Interface Category:

API.

Purpose:

Creates a new area geometry that has no area.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the new, empty area geometry.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGArea::GetInfiniteArea

static const TGArea & GetInfiniteArea ()

Interface Category:

API.

Purpose:

Creates a new area geometry that is infinitely large.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the new, infinitely large area geometry.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGArea::TransformBy

void TransformBy (const TGrafMatrix &)

Interface Category:

API.

Purpose:

Transforms the entire area using the specified matrix.

Calling Context:

Call this function directly.

Parameters:

const TGrafMatrix & -The matrix used to transform the area.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGArea::IsEmpty

bool IsEmpty () const

Interface Category:

API.

Purpose:

Tests whether this area contains any geometries.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this area contains no basic geometries.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGArea::SetToEmpty

void SetToEmpty ()

Interface Category:

API.

Purpose:

Removes all basic geometries from this area.

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: TGArea::IsRectilinear

bool IsRectilinear () const

Interface Category:

API.

Purpose:

Tests whether the area is comprised completely of horizontal and vertical edges.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the area is comprised completely of horizontal and vertical edges.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGArea::IsRectangular

bool IsRectangular () const

Interface Category:

API.

Purpose:

Tests whether the area is rectangular in shape.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the area is rectangular in shape.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGArea::IsSingular

bool IsSingular () const

Interface Category:

API.

Purpose:

Tests whether the area is comprised of a single basic geometry.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the area is comprised of a single basic geometry.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGArea::GetBounds

TGRect GetBounds () const

Interface Category:

API.

Purpose:

Returns the rectangle that completely encloses the area.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the bounding rectangle for the area.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGArea::Intersects

bool Intersects (const TGRect &) const

Interface Category:

API.

Purpose:

Tests whether the area geometry intersects the given rectangle.

Calling Context:

Call this function directly.

Parameters:

const TGRect & rect -The rectangle to test for intersection.

Return Value:

Returns true if the area geometry intersects the given rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGArea::Contains

bool Contains (const TGPoint &) const
bool Contains (const TGRect &) const

Interface Category:

API.

Purpose:

Tests whether the area geometry contains the given point.
Tests whether the area geometry contains the given rectangle.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

const TGPoint & -The point to test for within the area geometry.
const TGRect & -The rectangle to test for within the area geometry.

Return Value:

Returns true if either the point or the rectangle lies completely within the area geometry.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGArea::Add

void Add (const TGArea &)

Interface Category:

API.

Purpose:

Adds the shape of the specified TGArea to the current shape. Addition is achieved through union.

Calling Context:

Call this function directly.

Parameters:

const TGArea & -The shape to be added to the current area.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function provides the same functionality as operator +=.

Member Function: TGArea::operator+=

TGArea & operator += (const TGArea &)

Interface Category:

API.

Purpose:

Adds the shape of the TGArea on the right side of the operator += to this one. Addition is achieved through union.

Calling Context:

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

Parameters:

const TGArea & -The shape to be added to the current area.

Return Value:

A const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function provides the same functionality as TGArea::Add. This function is declared inline.

Member Function: TGArea::Subtract

void Subtract (const TGArea &)

Interface Category:

API.

Purpose:

Subtracts the shape of the specified TGArea from the current shape.

Calling Context:

Call this function directly.

Parameters:

const TGArea & -The shape to be subtracted from the current area.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function provides the same functionality as operator -=.

Member Function: TGArea::operator-=

TGArea & operator -=(const TGArea &)

Interface Category:

API.

Purpose:

Subtracts the shape of the specified TGArea from the current shape.

Calling Context:

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

Parameters:

const TGArea & -The shape to be subtracted from the current area.

Return Value:

A const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function provides the same functionality as TGArea::Subtract. This function is declared inline.

Member Function: TGArea::Intersect

void Intersect (const TGArea &)

Interface Category:

API.

Purpose:

Sets the shape to the intersection of the current shape with the specified TGArea's shape.

Calling Context:

Call this function directly.

Parameters:

const TGArea & -The area to be intersected with this one.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function provides the same functionality as operator *=.

Member Function: TGArea::operator*=

TGArea & operator *= (const TGArea &)

Interface Category:

API.

Purpose:

Intersects the current shape with the specified TGArea's shape.

Calling Context:

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

Parameters:

const TGArea & -The area to be intersected with this one.

Return Value:

A const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function provides the same functionality as TGArea::Intersect. This function is declared inline.

Member Function: TGArea::ExclusiveOr

void ExclusiveOr (const TGArea &)

Interface Category:

API.

Purpose:

Sets the shape to the combined area of the current shape and the specified TGArea's shape, minus their intersection.

Calling Context:

Call this function directly.

Parameters:

const TGArea & -The area to be exclusive OR'd with this one.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function provides the same functionality as operator ^=.

Member Function: TGArea::operator^=

TGArea & operator ^= (const TGArea &)

Interface Category:

API.

Purpose:

Sets the shape to the combined area of the current shape and the specified TGArea's shape, minus their intersection.

Calling Context:

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

Parameters:

const TGArea & -The area to be exclusive OR'd with this one.

Return Value:

A const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function provides the same functionality as TGArea::ExclusiveOr. This function is declared inline.

Member Function: TGArea::operator=

TGArea & operator =(const TGArea &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const TGArea & -The area 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: TGArea::operator==

bool operator ==(const TGArea &) const

Interface Category:

API.

Purpose:

Tests whether the two objects are equal.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TGArea & -The area geometry to be compared to this one.

Return Value:

Returns true if the two area geometries are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGArea::operator!=

bool operator != (const TGArea &) const

Interface Category:

API.

Purpose:

Tests whether the two objects are equal.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TGArea & -The area geometry to be compared to this one.

Return Value:

Returns true if the two area geometries are not equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGArea::operator<<=

TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromWhere -The stream from which the object streams itself in.

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: TGArea::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toWhere -The stream to which the object streams itself out.

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: TGArea::GetTimeStamp

TPseudoTimeStamp GetTimeStamp () const

Interface Category:

API.

Purpose:

Returns the object's time stamp. Time stamps are a quick and efficient way to determine whether two TGArea objects are equal. If the time stamps of the two objects are equal, then the objects are equal. However, if the time stamps are not equal, the objects might or might not be equal. A TGArea derived class must maintain the value of its time stamp. If any part of the object's visible value changes, then it updates its time stamp by calling UpdateTimeStamp. A special case: if the object is in the default state (as defined by the derived class), its time stamp is zero.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the object's time stamp.

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.