Class: TTextGraphic

Declaration: TextGraphic.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MGraphic

Inherited By:

None.

Purpose:

Provides a graphic representation of non-editable text. The text contained in a TTextGraphic class cannot be edited, but can undergo various graphic transformations and be used polymorphically with other MGraphic derived classes. TTextGraphic is a wrapper class containing a TTextDisplay. Information about the text itself, its styling and line breaking, are all stored in the TTextDisplay. TTextGraphic merely provides for graphic manipulation of the result. TTextDisplay is not itself an MGraphic because of the overhead involved. Clients who do not explicitly require the additional graphic manipulations provided by an MGraphic derived classes should not use TTextGraphic, but use TTextDisplay directly.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

It should not be necessary to derive this class. Clients who derive TTextDisplay will want to provide their own TTextGraphic-analogs inheriting from MGraphic, but it is not necessary to derive TTextGraphic itself. Some clients might want to derive TTextGraphic to override its handling of an MGraphic grafbundle. TTextGraphic's behavior is to ignore the grafbundle.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TTextGraphic::TTextGraphic

TTextGraphic (const TTextGraphic & text)
TTextGraphic (const TTextDisplay & text)
TTextGraphic (const TText & text)
TTextGraphic (const TText & text, const TGPoint & origin)
TTextGraphic (const TText & text, const TGPoint & origin, const TMultiLineOrientation & orient, bool useFontSubstitution =true)
TTextGraphic ()

Interface Category:

API.

Purpose:

Copy constructor.
Constructs a TTextGraphic from a TTextDisplay.
Constructs a TTextGraphic from a TText object by wrapping it within a TTextDisplay.
Constructs a TTextGraphic from a TText object by wrapping it within a TTextDisplay.
Constructs a TTextGraphic from a TText object by wrapping it within a TTextDisplay.
Default constructor.

Calling Context:

Called to copy an object.
Called to construct a TTextGraphic from a TTextDisplay.
Called to construct a TTextGraphic from a TText object by wrapping it within a TTextDisplay.
Called to construct a TTextGraphic from a TText object by wrapping it within a TTextDisplay.
Called to construct a TTextGraphic from a TText object by wrapping it within a TTextDisplay.
Called by the stream-in operators.

Parameters:

const TTextGraphic & text -The object to copy.
const TTextDisplay & text -The TTextDisplay object to wrap within a TTextGraphic.
const TText & text -The text to wrap within a TTextDisplay object to wrap within a TTextGraphic.
const TText & text -The text to wrap within a TTextDisplay object to wrap within a TTextGraphic.
const TGPoint & origin -The text origin used by the TTextDisplay object.
const TText & text -The text to wrap within a TTextDisplay object to wrap within a TTextGraphic.
const TGPoint & origin -The text origin used by the TTextDisplay object.
const TMultiLineOrientation & orient -The line orientation object used by the TTextDisplay object.
bool useFontSubstitution =true -Determines whether font substitution will be used by the TTextDisplay object to force all text to be displayed in an appropriate font.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::~TTextGraphic

virtual ~ TTextGraphic ()

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:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::operator=

TTextGraphic & operator =(const TTextGraphic &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TTextGraphic & -The object to copy.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::operator==

bool operator ==(const TTextGraphic &) const

Interface Category:

API.

Purpose:

Equality operator.

Calling Context:

Determines if two TTextGraphic objects are equal.

Parameters:

const TTextGraphic & -The object against which this object is to be compared.

Return Value:

Returns true if the two objects are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & toWhere -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:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::operator<<=

virtual TStream & operator <<= (TStream & fromWhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

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

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws an exception if the object being streamed in is of an invalid version of TTextGraphic.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::SetText

virtual void SetText (const TText & text)

Interface Category:

API.

Purpose:

Sets the text to be displayed. This text is wrapped within a TTextDisplay owned by the TTextGraphic object.

Calling Context:

Call to specify the text to be displayed.

Parameters:

const TText & text -The text to display.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::GetText

virtual void GetText (TText & text) const

Interface Category:

API.

Purpose:

Provides access to the text drawn by the TTextGraphic object.

Calling Context:

Called to obtain access to the text drawn by the TTextGraphic object.

Parameters:

TText & text -Filled in with the text drawn by the TTextGraphic object.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::SetOrigin

virtual void SetOrigin (const TGPoint & where)

Interface Category:

API.

Purpose:

Sets the text origin at which to display the text.

Calling Context:

Call to set the text origin at which to display the text.

Parameters:

const TGPoint & where -The origin at which to display the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::GetOrigin

virtual void GetOrigin (TGPoint & origin) const

Interface Category:

API.

Purpose:

Returns the origin at which to display the text.

Calling Context:

Called when displaying the text.

Parameters:

TGPoint & origin -The origin at which to display the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::SetLineOrientation

virtual void SetLineOrientation (const TMultiLineOrientation &)

Interface Category:

API.

Purpose:

Sets the TMultiLineOrientation object used to lay out the text.

Calling Context:

Called to change the orientation of the text after the TTextGraphic object has been created.

Parameters:

const TMultiLineOrientation & -The TMultiLineOrientation object to use in laying out the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::GetLineOrientation

virtual void GetLineOrientation (TMultiLineOrientation &) const

Interface Category:

API.

Purpose:

Returns the TMultiLineOrientation instance used to lay out the text line.

Calling Context:

Called by a client who wants to query a TTextDisplay regarding its positioning (vertical or horizontal), justification (left, right, center), and so on.

Parameters:

TMultiLineOrientation & -Filled in with the TMultiLineOrientation instance used to lay out the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::SetFontSubstitutionProcessing

virtual void SetFontSubstitutionProcessing (const bool &)

Interface Category:

API.

Purpose:

Specifies whether font substitution processing should occur before the text is displayed.

Calling Context:

Called to change the current setting. By default, font substitution processing occurs.

Parameters:

const bool & -Whether or not font substitution processing should occur.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::GetFontSubstitutionProcessing

virtual bool GetFontSubstitutionProcessing () const

Interface Category:

API.

Purpose:

Queries whether font substitution processing should occur before the text is displayed.

Calling Context:

Called when displaying the text.

Parameters:

Takes no parameters.

Return Value:

Returns true if font substitution processing should occur.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::GetTextDisplay

virtual const TTextDisplay * GetTextDisplay () const

Interface Category:

API.

Purpose:

Provides direct access to the TTextDisplay object stored by a TTextGraphic object.

Calling Context:

Called to obtain more information about the TTextDisplay object stored by a TTextGraphic object than is provided through the API of TTextGraphic.

Parameters:

Takes no parameters.

Return Value:

A pointer to the TTextDisplay object stored by a TTextGraphic object. Storage is owned by the TTextGraphic.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::Draw

virtual void Draw (TGrafPort & port) const

Interface Category:

API.

Purpose:

Draws the text.

Calling Context:

Call to display the text.

Parameters:

TGrafPort & port -The grafport within which to draw the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::GetGeometricBounds

virtual TGRect GetGeometricBounds () const

Interface Category:

API.

Purpose:

Returns the smallest rectangle surrounding the text.

Calling Context:

Called to obtain the smallest rectangle surrounding the text.

Parameters:

Takes no parameters.

Return Value:

The smallest rectangle surrounding the text.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::GetLooseFitBounds

virtual TGRect GetLooseFitBounds (const TGrafPort * =NIL) const

Interface Category:

API.

Purpose:

Returns the smallest rectangle surrounding the text.

Calling Context:

Called to obtain the smallest rectangle surrounding the text.

Parameters:

const TGrafPort * =NIL -The grafport within which to draw the text.

Return Value:

The smallest rectangle surrounding the text.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::TransformBy

virtual void TransformBy (const TGrafMatrix &)

Interface Category:

API.

Purpose:

Provides graphic transformation of the text.

Calling Context:

Called for direct graphic transformation by the text and by various MGraphic functions such as TranslateBy and RotateBy to transform the text.

Parameters:

const TGrafMatrix & -The matrix to use in transforming the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TTextGraphic::AdoptBundle

virtual void AdoptBundle (TGrafBundle * adoptedBundle)

Interface Category:

API.

Purpose:

By default, an MGraphic derived class contains a TGrafBundle whose interpretation varies from class to class. Because as there is no reasonable default interpretation for a TGrafBundle in association with text, and because as TText, TTextDisplay, and the various TColorStyle's provide the ability to color text, grafbundles are not used by TTextGraphic. This function overrides the default behavior of MGraphic::AdoptBundle to delete the adoptedBundle.

Calling Context:

Called polymorphically with AdoptBundle for other MGraphic derived classes.

Parameters:

TGrafBundle * adoptedBundle -The grafbundle to adopt. This is deleted by TTextGraphic.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.