Class: TGRect

Declaration: BaseGeometry.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

None.

Purpose:

TGRects are axis-aligned rectangles: Each side of the rectangle is parallel to the x- or y-axis. The rectangle is defined by the coordinate points for the top-left corner and the bottom-right corner. The top-left corner consists of the minimum x- and y-coordinates. The bottom-right corner consists of the maximum x- and y-coordinates. TGRects are defined over a half-open interval, so a point is considered to be contained in the rectangle if it falls within left x < right and top <= y < bottom. A TGRect is an area-enclosing geometry that can be filled and/or framed. Unlike the other computational geometry classes, TGRect is supported in the TGrafPort class for rendering a TPolygon or a TEllipse that can be filled and framed. (TGPolygon and TGEllipse accept a TGRect in their constructors to create a TPolygon with a rectangular shape, or a TEllipse with a circular shape.) A TGRect is empty if fRight <= fLeft or fBottom <= fTop. Empty TGRect objects do not fill and they are ignored by TGRect::ExtendTo and the Intersection functions. To find out if a rectangle is empty, call TGRect::IsEmpty(); do not test for equality with kZeroRect, because kZeroRect is a specific rectangle whose coordinates are (0,0,0,0).

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Do not derive any classes from TGRect: All TGRect's data is public, and its destructor is not virtual.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TGRect::TGRect

TGRect ()
TGRect (const TGPoint & p0, const TGPoint & p1)
TGRect (GCoordinate left, GCoordinate top, GCoordinate right, GCoordinate bottom)
TGRect (const TGRect &)

Interface Category:

API.

Purpose:

Default constructor. The member variables are not initialized.
Creates a rectangle with the specified corners.
Creates a rectangle with the specified corners.
Copy constructor.

Calling Context:

Creates a TGRect without initializing the member variables.
Creates a rectangle with the specified corners.
Creates a rectangle with the specified corners.
Called to copy an object.

Parameters:

Takes no parameters.
const TGPoint & p0 -The top-left corner.
const TGPoint & p1 -The bottom-right corner.
GCoordinate left -The x-coordinate of the rectangle's left side.
GCoordinate top -The y-coordinate of the rectangle's top side.
GCoordinate right -The x-coordinate of the rectangle's right side.
GCoordinate bottom -The y-coordinate of the rectangle's bottom side.
const TGRect & -The rectangle to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::~TGRect

~ TGRect ()

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: TGRect::GetTopLeft

TGPoint GetTopLeft () const

Interface Category:

API.

Purpose:

Returns the top-left point of the rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The top-left point of the rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::GetBottomRight

TGPoint GetBottomRight () const

Interface Category:

API.

Purpose:

Returns the bottom-right point of the rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The bottom-right point of the rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::GetTopRight

TGPoint GetTopRight () const

Interface Category:

API.

Purpose:

Returns the top-right point of the rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The top-right point of the rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::GetBottomLeft

TGPoint GetBottomLeft () const

Interface Category:

API.

Purpose:

Returns the bottom-left point of the rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The bottom-left point of the rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::GetTopLine

TGLine GetTopLine () const

Interface Category:

API.

Purpose:

Retrieves the top side of the rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The line segment from the top-left to top-right corner of the rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::GetBottomLine

TGLine GetBottomLine () const

Interface Category:

API.

Purpose:

Retrieves the top side of the rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The line segment from the bottom-left to the bottom-right corner of the rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::GetLeftLine

TGLine GetLeftLine () const

Interface Category:

API.

Purpose:

Retrieves the left side of the rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The line segment from the top-left to the bottom-left corner of the rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::GetRightLine

TGLine GetRightLine () const

Interface Category:

API.

Purpose:

Retrieves the right side of the rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The line segment from the top-right to the bottom-right corner of the rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::Interpolate

TGPoint Interpolate (GParametric u, GParametric v) const

Interface Category:

API.

Purpose:

Creates the point within the rectangle that corresponds to (u,v), where 0 <= u <= 1, 0 <= v <= 1, u =0 is the left edge, and v =0 is the top edge. If u or v exceeds this range, the function returns an extrapolated point outside the rectangle.

Calling Context:

Call this function directly.

Parameters:

GParametric u -The horizontal parameter.
GParametric v -The vertical parameter.

Return Value:

The interpolated or extrapolated point.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::IsEmpty

bool IsEmpty () const

Interface Category:

API.

Purpose:

Informs the caller whether the rectangle is empty. An empty rectangle is one that encloses no space, such as kZeroRect. Other examples are a rectangle whose left side is defined to be to the right of its right side, or one whose top is set to be below its bottom. (Such rectangles can be made non-empty by invoking TGRect::OrderPoints.)

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the calling rectangle encloses no space (fTop <= fBottom ||fLeft <= fRight).

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::GetSize

TGPoint GetSize () const

Interface Category:

API.

Purpose:

Retrieves the height and width of the rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A point whose fX member variable equals the rectangle's width and whose fY equals the rectangle's height.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::GetCenter

TGPoint GetCenter () const

Interface Category:

API.

Purpose:

Retrieves the midpoint of the rectangle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The point at the horizontal and vertical center of the rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::GetHeight

GCoordinate GetHeight () const

Interface Category:

API.

Purpose:

Retrieves the rectangle's height.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The rectangle's height. The value is negative if the bottom side has been set to be above the top side.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::GetWidth

GCoordinate GetWidth () const

Interface Category:

API.

Purpose:

Retrieves the rectangle's width.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The rectangle's width. The value is negative if the left side has been set to the right of the right side.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::EqualSize

bool EqualSize (const TGRect & g) const

Interface Category:

API.

Purpose:

Determines whether two rectangles have the same height and width.

Calling Context:

Call this function directly.

Parameters:

const TGRect & g -The rectangle to compare with this rectangle.

Return Value:

Returns true if the rectangles have matching heights and widths.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::Pin

void Pin (TGPoint & Point) const

Interface Category:

API.

Purpose:

Moves a point to within the rectangle. If the point is outside the rectangle, its values are modified to lie on the nearest border of the rectangle. If only one of the point's coordinates is outside the range of the rectangle's corresponding coordinate, the point is moved perpendicularly to the nearest border. If both its coordinates are outside the rectangle's range, it is moved to the nearest corner. If two sides of the rectangle are not in the normal order (for example, if fLeft >fRight), the point is always considered to be outside the rectangle, and it is moved to midway between these two sides.

Calling Context:

Call this function directly.

Parameters:

TGPoint & Point -The point to be moved.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::MapRect

void MapRect (TGRect & r, const TGRect & dr) const

Interface Category:

API.

Purpose:

Takes the size and position of a rectangle r relative to this rectangle (in other words, *this) and maps it to the same proportional size and position relative to the destination rectangle dr. In other words, if r and *this have a certain visual relationship, then after the mapping, r and dr have a similar relationship. If *this has a height or width of zero, rectangle r is given an infinite height or width.

Calling Context:

Call this function directly.

Parameters:

TGRect & r -The rectangle to be scaled and moved.
const TGRect & dr -The destination rectangle, to which rectangle r bears the relationship it previously bore to *this.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::SetToPoint

void SetToPoint (const TGPoint &)

Interface Category:

API.

Purpose:

Makes the rectangle infinitesimal and places it at the specified point.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & -The new location of the zero-sized rectangle.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::SetTopLeft

void SetTopLeft (const TGPoint & point)

Interface Category:

API.

Purpose:

Sets the top-left corner of the rectangle to the specified point.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & point -The new location of the top-left corner.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::SetBottomRight

void SetBottomRight (const TGPoint & point)

Interface Category:

API.

Purpose:

Sets the bottom-right corner of the rectangle to the specified point.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & point -The new location of the bottom-right corner.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::SetTopRight

void SetTopRight (const TGPoint & pt)

Interface Category:

API.

Purpose:

Sets the top-right corner of the rectangle to the specified point.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & point -The new location of the top-right corner.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::SetBottomLeft

void SetBottomLeft (const TGPoint & pt)

Interface Category:

API.

Purpose:

Sets the bottom-left corner of the rectangle to the specified point.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & point -The new location of the bottom-left corner.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::SetCenter

void SetCenter (const TGPoint & center)

Interface Category:

API.

Purpose:

Moves the rectangle so that it is centered on the specified point.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & center -The new midpoint of the rectangle.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::SetSize

void SetSize (const TGPoint & size)

Interface Category:

API.

Purpose:

Sets the rectangle's height and width, without changing its center point.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & size -The point whose x-coordinate specifies the new width, and whose y-coordinate specifies the new height.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::Set

void Set (const TGPoint & a, const TGPoint & b)

Interface Category:

API.

Purpose:

Moves the rectangle's top-left and bottom-right corners to the specified points.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & a -The new top-left corner.
const TGPoint & b -The new bottom-right corner.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::ExtendTo

void ExtendTo (const TGRect & g)
void ExtendTo (const TGPoint & pt)

Interface Category:

API.

Purpose:

Expands the rectangle until it just encompasses the specified rectangle. If the specified rectangle is empty or already lies within this rectangle, nothing changes. The rectangle is only stretched in the required direction(s), so it does not necessarily retain its original shape or center.
Expands the rectangle until it just encompasses the specified point. If the specified point already lies within this rectangle, nothing changes. The rectangle is only stretched in the required direction(s), so it does not necessarily retain its original shape or center.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

const TGRect & g -The rectangle to enclose within this one.
const TGPoint & pt -The point to enclose within this one.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::IntersectWith

void IntersectWith (const TGRect & g)

Interface Category:

API.

Purpose:

Finds the intersection of this rectangle with the specified rectangle, g. It modifies *this by replacing its coordinates with those of the rectangular intersection. The result can be an empty rectangle, which can be determined by calling TGRect::IsEmpty. If the two rectangles do not overlap, the resulting rectangle is empty.

Calling Context:

Call this function directly.

Parameters:

const TGRect & g -The rectangle that intersects with this rectangle.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::Offset

void Offset (const TGPoint & dg)

Interface Category:

API.

Purpose:

Moves the rectangle by the specified vector dg.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & dg -The offset.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::Inset

void Inset (const TGPoint & inset)

Interface Category:

API.

Purpose:

Moves opposite sides of the rectangle inwards towards its center or outwards from its center. Each side of the rectangle moves inwards by the x or y values of the parameter (x for the left and right sides and y for the top and bottom). Negative values move the corresponding sides outwards. The center of the rectangle stays the same.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & inset -The point whose x- and y-coordinates determine the amount that each side moves.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::OrderPoints

void OrderPoints ()

Interface Category:

API.

Purpose:

Rearranges the rectangle's coordinates if necessary, so that the top-left corner is not below or to the right of the bottom-right corner. If the left and right sides are out of order, the two sides are swapped. The same is true for the top and bottom sides. This operation ensures a non-empty rectangle unless the left side is the same as the right side or the top is the same as the bottom.

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: TGRect::Intersects

bool Intersects (const TGRect & g) const

Interface Category:

API.

Purpose:

Specifies whether the rectangle intersects the specified rectangle.

Calling Context:

Call this function directly.

Parameters:

const TGRect & g -The rectangle to test.

Return Value:

Returns true if neither rectangle is empty and they intersect. Rectangles are considered to intersect if their borders cross or touch, or if one encloses the other.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::Contains

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

Interface Category:

API.

Purpose:

Specifies whether the rectangle encloses the specified point. A point that lies on the top or left side is considered to be contained in the rectangle, but a point on the right or bottom side isn't.
Specifies whether the rectangle encloses the specified rectangle. Any or all sides of the enclosed rectangle can lie on the corresponding sides of the outer rectangle.

Calling Context:

Call this function directly.
Call this function directly.

Parameters:

const TGPoint & p -The point to test.
const TGRect & g -The rectangle that is tested to see whether it is contained by *this.

Return Value:

Returns true if the specified geometry is contained in this rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::operator>>=

TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream 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: TGRect::operator<<=

TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -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: TGRect::operator=

TGRect & operator =(const TGRect & Src)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TGRect & Src -The rectangle 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: TGRect::operator==

bool operator ==(const TGRect & Src) const

Interface Category:

API.

Purpose:

Tests whether the rectangle's coordinates equal those of the argument.

Calling Context:

Called to test equivalence of two objects.

Parameters:

const TGRect & Src -The object whose coordinates are compared to this object's coordinates.

Return Value:

Returns true if the rectangles are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGRect::operator!=

bool operator != (const TGRect & Src) const

Interface Category:

API.

Purpose:

Tests whether the rectangle's coordinates differ from those of the argument.

Calling Context:

Called to test equivalence of two objects.

Parameters:

const TGRect & Src -The object whose coordinates are compared to this object's coordinates.

Return Value:

Returns true if the rectangles have different coordinates.

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.