Class: MGraphic

Declaration: Graphics.h

Taxonomy Categories:

Member Functions:


Interface Category:

API.

Inherits From:

MDrawable

Inherited By:

TGraphicHierarchy TPicture TTextGraphic MCanvasGraphic TArea TCurve TEllipse TImage TLine TLoop TPolygon TPolyline TRecursiveLineLayoutGraphic TDecoration TSliderRuler TTimeGraphic TView

Purpose:

MGraphic is an abstract base class derived from MDrawable. MDrawable provides the protocol for drawing a 2-D or 3-D graphic, and MGraphic provides the protocols for constructing and deleting a 2-D graphic, obtaining attribute information, transforming the graphic, finding the bounds of the graphic, and detecting whether the graphic has been selected by the user (hit detection). The properties that determine how a 2-D graphic is drawn--such as fill color, frame color, and pen width--are called attributes. Attributes are encapsulated in the MGraphic's bundle, an object of the TGrafBundle class. Bundles are created and passed to a graphic to define the attributes for that graphic. If a graphic does not have a bundle, the default graphic state of the drawing port defines the graphic's attributes.

Instantiation:

Abstract class; do not allocate.

Deriving Classes:

Must override Draw(), GetGeometricBounds() and TransformBy() appropriately. Draw() -renders the MGraphic(), GetGeometricBounds() returns the geometric bounds of the primitives being rendered, TransformBy() transforms the geometry.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: MGraphic::~MGraphic

virtual ~ MGraphic ()

Interface Category:

API.

Purpose:

Destructor. Deletes the graphic's bundle.

Calling Context:

Called to destroy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MGraphic::Draw

virtual void Draw (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws the graphic to the specific TGrafPort.

Calling Context:

Call concrete derived classes' Draw functions directly.

Parameters:

Return Value:

None.

Exceptions:

Determined by derived classes.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function.

Member Function: MGraphic::GetGeometricBounds

virtual TGRect GetGeometricBounds () const

Interface Category:

API.

Purpose:

Gets the bounding rectangle of the 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. Note that this applies only to concrete derived classes because this function is pure virtual.

Parameters:

Return Value:

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

Exceptions:

Determined by derived classes.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function.

Member Function: MGraphic::GetLooseFitBounds

virtual TGRect GetLooseFitBounds (const TGrafPort* =NIL) const

Interface Category:

API.

Purpose:

Gets the entire graphic's bounding rectangle, taking into account the bundle information.

Calling Context:

Called during hit detection. You can also call this function directly. Note that this applies only to concrete derived classes because this function is pure virtual.

Parameters:

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:

Determined by derived classes.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function.

Member Function: MGraphic::TransformBy

virtual void TransformBy (const TGrafMatrix &)

Interface Category:

API.

Purpose:

Transforms the graphic's shape and position by applying the specified transformation matrix. TransformBy is a pure virtual function that is implemented for every basic 2-D graphics class.

Calling Context:

Called by the Graphics system. You can also call this function directly. Note that this applies only to concrete derived classes because this function is pure virtual.

Parameters:

Return Value:

None.

Exceptions:

Determined by derived classes.

Concurrency:

Not multithread safe.

Other Considerations:

This is a pure virtual function.

Member Function: MGraphic::ScaleBy

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

Interface Category:

API.

Purpose:

Changes the graphic's size according to the specified horizontal and vertical scalars. Because there are two independent scalars, the graphic's shape can change. Every point is scaled by multiplying its horizontal and vertical displacements from the specified center of scale. Thus, the scaled graphic does not stay centered at the same point unless the centerOfScale argument is the old center of the graphic. For example, take an axis-aligned square whose width is 1.0 and whose lower left corner is at the point (1.0,0.0). Scale it by a vector (2.0,1.0). Regardless of what center of scale you use or what the original center of the geometry was, the result of the scaling is a rectangle two units wide and one unit high. If the default center of scale (the origin) is used, the rectangle's lower left corner is at (2.0,0.0). On the other hand, if the center of scale is the same as the original center of the square--the point (1.5,1.5)--then the rectangle stays centered at this point, meaning its lower left corner is at (0.5,0.0).

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The base class implements scaling by creating a temporary transformation matrix and calling MGraphic::TransformBy. Derived classes can implement more efficient schemes.

Member Function: MGraphic::RotateBy

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

Interface Category:

API.

Purpose:

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

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The base class implements scaling by creating a temporary transformation matrix and calling MGraphic::TransformBy. Derived classes can implement more efficient schemes.

Member Function: MGraphic::TranslateBy

virtual void TranslateBy (const TGPoint &)

Interface Category:

API.

Purpose:

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The base class implements scaling by creating a temporary transformation matrix and calling MGraphic::TransformBy. Derived classes can implement more efficient schemes.

Member Function: MGraphic::AdoptBundle

virtual void AdoptBundle (TGrafBundle * adoptedBundle)

Interface Category:

API.

Purpose:

Adopts the specified bundle to determine the graphic's attributes.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MGraphic::OrphanBundle

virtual TGrafBundle * OrphanBundle ()

Interface Category:

API.

Purpose:

Relinquishes knowledge of, and responsibility for, the MGraphic's bundle, returning it to the caller.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns the orphaned bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MGraphic::GetBundle

virtual const TGrafBundle * GetBundle () const

Interface Category:

API.

Purpose:

Gets the bundle, keeping it available to the MGraphic.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns a constant pointer to the bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MGraphic::GetAttributeState

virtual const TAttributeState * GetAttributeState () const

Interface Category:

API.

Purpose:

Gets the attribute bundle, keeping it available to the MGraphic.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns a constant pointer to the attribute bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MGraphic::OrphanAttributeState

virtual TAttributeState * OrphanAttributeState ()

Interface Category:

API.

Purpose:

Relinquishes knowledge of, and responsibility for, the MGraphic's attribute bundle, returning it to the caller.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns the orphaned bundle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MGraphic::AdoptAttributeState

virtual void AdoptAttributeState ( TAttributeState * adoptedAttributeState)

Interface Category:

API.

Purpose:

Adopts the specified attribute bundle to determine the graphic's attributes.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MGraphic::operator==

bool operator ==(const MGraphic & source) const

Interface Category:

API.

Purpose:

Tests two MGraphics for equality. The base class only tests whether the two bundles have equal contents.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

Return Value:

Returns true if this MGraphic and the argument have equal bundles.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes can override this function to add other tests. In particular, classes that encapsulate geometries check that the two geometries are equal.

Member Function: MGraphic::operator!=

bool operator != (const MGraphic & source) const

Interface Category:

API.

Purpose:

Tests two MGraphics for inequality. The base class only tests whether the two bundles have different contents.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

Return Value:

Returns true if the bundles of this MGraphic and the argument are not equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Derived classes can override this function to add other tests. In particular, classes that encapsulate geometries check that the two geometries are not equal.

Member Function: MGraphic::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

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

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

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: MGraphic::MGraphic

  1. MGraphic ()
  2. MGraphic (TGrafBundle * adoptedBundle)
  3. MGraphic (const MGraphic &)

Interface Category:

API.

Purpose:

  1. Default constructor.
  2. Creates a new MGraphic that adopts the given bundle.
  3. Copy constructor.

Calling Context:

  1. Called by the stream-in operators.
  2. Called by derived classes.
  3. Called to copy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

The constructors are all protected because this class is abstract.

Member Function: MGraphic::operator=

MGraphic & operator =(const MGraphic & source)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

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:

This is a protected function because the class is abstract.

Member Function: MGraphic::UpdateTimeStamp

virtual void UpdateTimeStamp ()

Interface Category:

API.

Purpose:

Updates the object's time stamp. Time stamps are a quick and efficient way to determine whether two 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. Time stamps optimize the process of comparing two graphic hierarchies.

Calling Context:

Called by the Graphics system (typically, by derived classes) when the object changes in any way. When implementing your own derived class, call this function directly whenever you change the object's data.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MGraphic::ResetTimeStamp

virtual void ResetTimeStamp ()

Interface Category:

API.

Purpose:

Sets the time stamp to zero.

Calling Context:

Called by the Graphics system.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MGraphic::SetTimeStamp

virtual void SetTimeStamp (const TPseudoTimeStamp &)

Interface Category:

API.

Purpose:

Sets the time stamp to the specified value.

Calling Context:

Called by the Graphics system.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MGraphic::GetTimeStamp

virtual TPseudoTimeStamp GetTimeStamp () const

Interface Category:

API.

Purpose:

Gets the object's time stamp. Time stamps are a quick and efficient way to determine whether two 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. Time stamps optimize the process of comparing two graphic hierarchies.

Calling Context:

Called by the Graphics system. You generally do not need to call it directly.

Parameters:

Return Value:

Returns the graphic's time stamp.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: MGraphic::operatorTGraphicGroup*

virtual operator TGraphicGroup * ()

Interface Category:

API.

Purpose:

Allows users to RTTI a particular MGraphic and determine if it is a TGraphicGroup or not.

Calling Context:

Call it as a casting operator for a pointer.

Parameters:

Return Value:

NIL or pointer to a TGraphicGroup.

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.
Copyright©1995 Taligent,Inc. All rights reserved.