Class: TEllipse

Declaration: Graphics.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MGraphic

Inherited By:

None.

Purpose:

TEllipse provides a wrapper for the TGEllipse geometry class, to which it adds the facilities inherited from MGraphic: an attribute bundle, matrix transformations, and hit detection. TEllipse has a, not is a, TGEllipse. A TGEllipse is a vertically or horizontally oriented ellipse. Unlike the other MGraphic derived classes that encapsulate a corresponding geometry class, TEllipse has a TGrafMatrix that is used to concatenate all transformations. Every time you invoke a member function that alters the ellipse--ScaleBy, TranslateBy, RotateBy, or TransformBy--the alteration is concatenated to the TGrafMatrix instead of altering the data of the geometry itself (the TGEllipse). (This feature arises from the observation that ellipses are not closed for arbitrary transforms.) TEllipse::GetSize and TEllipse::GetCenter return the data associated with the original, untransformed geometry. To determine the actual size and center, use the TEllipse's transformation matrix to transform the returned data. You obtain this matrix by calling GetMatrix.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TEllipse::TEllipse

TEllipse (const TEllipse &)
TEllipse (const TGEllipse &, TGrafBundle * adoptBundle =NIL)
TEllipse (const TGRect & r)
TEllipse (const TGPoint & center, GCoordinate radius)
TEllipse (const TGPoint & center, GCoordinate Xradius, GCoordinate Yradius)
TEllipse ()

Interface Category:

API.

Purpose:

Copy constructor.
Creates a TEllipse with the specified TGrafBundle.
Creates a TEllipse that fits within the specified rectangle. If the rectangle is a square, the ellipse is a circle.
Creates an TEllipse with a uniform radius (thus, the ellipse is a circle) whose center is at the specified location.
Creates an TEllipse with the specified horizontal and vertical radii, and whose center is at the specified location.
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. You can also call this function directly.

Parameters:

const TEllipse & -The ellipse to be copied.
const TGEllipse & -The ellipse to be copied.
TGrafBundle * adoptBundle =NIL -The bundle to be adopted.
const TGRect & r -The rectangle that the ellipse is to be constructed within.
const TGPoint & center -The coordinates where the circle is to be placed.
GCoordinate radius -The radius of the circle.
const TGPoint & center -The coordinates where the ellipse is to be placed.
GCoordinate Xradius -The width of the ellipse.
GCoordinate Yradius -The height of the ellipse.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEllipse::~TEllipse

virtual ~ TEllipse ()

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: TEllipse::GetSize

virtual TGPoint GetSize () const

Interface Category:

API.

Purpose:

Gets this TEllipse's height and width. If the height and width are the same, the ellipse is a circle.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a TGPoint whose x-coordinate contains the ellipse's width and whose y-coordinate contains the ellipse's height.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEllipse::GetCenter

virtual TGPoint GetCenter () const

Interface Category:

API.

Purpose:

Gets the center point of this TEllipse.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a TGPoint whose coordinates are the center of this ellipse.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEllipse::GetMatrix

virtual const TGrafMatrix * GetMatrix () const

Interface Category:

API.

Purpose:

Returns this TEllipse's TGrafMatrix.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the object's graphic transformation matrix.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEllipse::Draw

virtual void Draw (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws the TEllipse to the specific TGrafPort. Attributes in the ellipse'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: TEllipse::GetLooseFitBounds

virtual TGRect GetLooseFitBounds (const TGrafPort* =NIL) const

Interface Category:

API.

Purpose:

Gets the entire TEllipse'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: TEllipse::GetGeometricBounds

virtual TGRect GetGeometricBounds () const

Interface Category:

API.

Purpose:

Gets the bounding rectangle of this TEllipse'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:

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 this ellipse's geometry.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEllipse::TransformBy

virtual void TransformBy (const TGrafMatrix &)

Interface Category:

API.

Purpose:

Transforms the TEllipse'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 graphic's points are multiplied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEllipse::ScaleBy

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

Interface Category:

API.

Purpose:

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

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: TEllipse::TranslateBy

virtual void TranslateBy (const TGPoint &)

Interface Category:

API.

Purpose:

Moves the TEllipse'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: TEllipse::RotateBy

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

Interface Category:

API.

Purpose:

Rotates the TEllipse by the given number of degrees, using the specified center of rotation. This does not change the size or shape of the ellipse, 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 ellipse is rotated.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEllipse::operator=

TEllipse & operator =(const TEllipse & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TEllipse & source -The object 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: TEllipse::operator==

bool operator ==(const TEllipse & source) const

Interface Category:

API.

Purpose:

Tests two TEllipses for equality, by determining whether their respective geometries and bundles are equal.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TEllipse & source -The ellipse to be compared with this one.

Return Value:

Returns true if this ellipse and the parameter have equal geometries and bundles.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TEllipse::operator!=

bool operator != (const TEllipse & source) const

Interface Category:

API.

Purpose:

Tests two TEllipses for inequality, by determining whether their geometries and bundles are different.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TEllipse & source -The ellipse to be compared with this one.

Return Value:

Returns true if the geometries or bundles of this ellipse and the parameter are not equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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

void Validate ()

Interface Category:

API.

Purpose:

Makes sure that the TEllipse'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.