Class: TTextLabel

Declaration: Label.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TLabel

Inherited By:

None.

Purpose:

Implements a control label with a text (rather than graphical) representation. TTextLabel maintains a TText object that contains the label's text. TTextLabel also maintains various attributes for the text such as point-size, font and color.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TTextLabel::TTextLabel

TTextLabel ()
TTextLabel (TText * adopted, bool enabled =true)
TTextLabel (const TText &, bool enabled =true)
TTextLabel (const TStandardText &, bool enabled =true)
TTextLabel (const TStandardText &, const TFontFamilyStyle &, const TFontPointSizeStyle &, const TTextColorStyle &, bool enabled =true)
TTextLabel (const TTextLabel &)

Interface Category:

API.

Purpose:

Default constructor.
Creates a new TTextLabel, adopts the specified TText as the new label's text, and enables or disables the new label according to the specified flag.
Creates a new TTextLabel, adopts a copy of the specified TText as the new label's text, and enables or disables the new label according to the specified flag.
Creates a new TTextLabel and enables or disables the new label according to the specified flag. This constructor creates a new TText object and initializes it from the specified TStandardText.
Creates a new TTextLabel and enables or disables the new label according to the specified flag. This constructor creates a new TText object and initializes it from the specified TStandardText and other parameters.
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.
Called to copy an object.

Parameters:

Takes no parameters.
TText * adopted -The text to be adopted as the new label's text.
bool enabled =true -The flag indicating whether to enable or disable the new label. True enables the new label, false disables it. The default is enabled.
const TText & -The text whose copy is adopted as the new label's text.
bool enabled =true -The flag indicating whether to enable or disable the new label. True enables the new label, false disables it. The default is enabled.
const TStandardText & -The text from which the new label's text is initialized.
bool enabled =true -The flag indicating whether to enable or disable the new label. True enables the new label, false disables it. The default is enabled.
const TStandardText & -The text from which the new label's text is initialized.
const TFontFamilyStyle & -The initial font in which to display the new label's text.
const TFontPointSizeStyle & -The initial point size in which to display the new label's text.
const TTextColorStyle & -The initial color in which to display the new label's text.
bool enabled =true -The flag indicating whether to enable or disable the new label. True enables the new label, false disables it. The default is enabled.
const TTextLabel & -The object to be copied.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::~TTextLabel

virtual ~ TTextLabel ()

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

TTextLabel & operator =(const TTextLabel &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

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

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

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

virtual 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 TInvalidVersionError if it encounters an object whose version number indicates it cannot be streamed in. Passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::IsEmpty

virtual bool IsEmpty () const

Interface Category:

API.

Purpose:

Reports whether this label is empty. A text label is considered empty if the length of its text is zero.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this label is empty.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides TLabel's pure virtual function of the same name.

Member Function: TTextLabel::Draw

virtual void Draw (TGrafPort &) const

Interface Category:

API.

Purpose:

Draws this label to the specified TGrafPort.

Calling Context:

Call this function directly.

Parameters:

TGrafPort & -The port into which to draw.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides TLabel's pure virtual function of the same name.

Member Function: TTextLabel::GetBounds

virtual TGRect GetBounds () const

Interface Category:

API.

Purpose:

GetBounds returns the bounding rectangle for this label. If the cached values are invalid, GetBounds recomputes them first.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the bounding rectangle for this label.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides TLabel's pure virtual function of the same name.

Member Function: TTextLabel::TranslateBy

virtual void TranslateBy (const TGPoint &)

Interface Category:

API.

Purpose:

Translates this label by the specified delta x and delta y values.

Calling Context:

Called from MoveBy. You can also call this function directly. If you have the destination coordinates, you can call MoveTo.

Parameters:

const TGPoint & -The delta x and delta y values by which to translate this label.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

MoveBy is a synonym of TranslateBy.

Member Function: TTextLabel::TransformBy

virtual void TransformBy (const TGrafMatrix &)

Interface Category:

API.

Purpose:

Transforms this label using matrix operations. Transformations can include rotation, scaling, and translation.

Calling Context:

Call this function directly.

Parameters:

const TGrafMatrix & -The matrix by which to transform this label.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::MoveTo

virtual void MoveTo (const TGPoint &)

Interface Category:

API.

Purpose:

Moves the label so that its upper left corner attains the specified position. MoveTo calculates the difference between the label's current position and the specified position and calls MoveBy with the calculated delta values.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & -The point to which to move the upper left corner of this label.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Member Function: TTextLabel::MoveBy

virtual void MoveBy (const TGPoint &)

Interface Category:

API.

Purpose:

Adjusts the position of this label by the specified delta x and delta y values.

Calling Context:

Call this function directly. If you have the destination coordinates, you can call MoveTo.

Parameters:

const TGPoint & -The TGPoint containing the delta x and delta y values by which to move this label.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides TLabel's pure virtual function of the same name. MoveBy is a synonym of TranslateBy.

Member Function: TTextLabel::GetDrawingGraphic

virtual MGraphic * GetDrawingGraphic () const

Interface Category:

API.

Purpose:

Creates and returns a graphic that most appropriately represents this label's current state.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a graphic that most appropriately represents this label's current state.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTextLabel::CalculateTextCachedValues

virtual void CalculateTextCachedValues ()

Interface Category:

API.

Purpose:

Calculates and caches the bounding rectangle for this label's text. This function calls GetBounds on its TText object which is an expensive call. Call InvalidateTextCachedValues to invalidate the current cache and force its recalculation.

Calling Context:

Called from the constructors. Also called from GetBounds if the cache has been invalidated.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTextLabel::InvalidateTextCachedValues

virtual void InvalidateTextCachedValues ()

Interface Category:

API.

Purpose:

Invalidates the cache containing the bounding rectangle for this label's text. Use CalculateTextCachedValues to update the cache with valid data.

Calling Context:

Called whenever the text label changes size.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTextLabel::GetFontSubstitutionProcessing

virtual bool GetFontSubstitutionProcessing () const

Interface Category:

API.

Purpose:

Reports whether this label's text allows font substitution. This function calls GetFontSubstitutionProcessing on the label's text object.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this label's text object allows font substitution.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::SetFontSubstitutionProcessing

virtual void SetFontSubstitutionProcessing (const bool)

Interface Category:

API.

Purpose:

Sets whether or not this label's text allows font substitution. This function calls SetFontSubstitutionProcessing on the label's text object.

Calling Context:

Call this function directly.

Parameters:

const bool -The flag indicating whether or not to allow font substitution.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::GetPointSize

virtual TFontPointSizeStyle GetPointSize () const

Interface Category:

API.

Purpose:

Returns the point size used to display this label's text.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the point size used to display this label's text.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::SetPointSize

virtual void SetPointSize (const TFontPointSizeStyle & size)

Interface Category:

API.

Purpose:

Sets the point size in which to display this label's text.

Calling Context:

Call this function directly.

Parameters:

const TFontPointSizeStyle & size -The new point size for the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::GetDisabledColor

virtual TTextColorStyle GetDisabledColor () const

Interface Category:

API.

Purpose:

Returns the color used to display this label's text, when the label is disabled.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the color used to display this label's text, when the label is disabled.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::SetDisabledColor

virtual void SetDisabledColor (const TTextColorStyle & color)

Interface Category:

API.

Purpose:

Assigns the color in which to display this label's text when the label is disabled.

Calling Context:

Call this function directly.

Parameters:

const TTextColorStyle & color -The new color for the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::GetColor

virtual TTextColorStyle GetColor () const

Interface Category:

API.

Purpose:

Returns the color used to display this label's text.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the color used to display this label's text.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::SetColor

virtual void SetColor (const TTextColorStyle & color)

Interface Category:

API.

Purpose:

Assigns the color in which to display this label's text when the label is enabled and active.

Calling Context:

Call this function directly or specify the color when you create TTextLabel with the constructor form that specifies the text and its attributes.

Parameters:

const TTextColorStyle & color -The color for the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::SetFont

virtual void SetFont (const TFontFamilyStyle & name)

Interface Category:

API.

Purpose:

Sets the font in which to display this label's text.

Calling Context:

Call this function directly.

Parameters:

const TFontFamilyStyle & name -The new font for the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::SetOrigin

virtual void SetOrigin (const TGPoint & origin)

Interface Category:

API.

Purpose:

Sets the origin to the specified point.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & origin -The point which should be made the origin.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTextLabel::GetOrigin

virtual void GetOrigin (TGPoint & origin) const

Interface Category:

API.

Purpose:

Provides the origin point of the text of the label.

Calling Context:

Call this function directly.

Parameters:

TGPoint & origin -A reference, which this function fills in with the origin's coordinates.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TTextLabel::SetActive

virtual void SetActive (bool)

Interface Category:

API.

Purpose:

Activates or deactivates the label, according to the specified flag. (Labels usually have different looks for active and inactive states.)

Calling Context:

Call this function directly.

Parameters:

bool -The flag indicating whether to set this label to be active or inactive. True sets the label to be active; false sets the label to be inactive.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::SetEnabled

virtual void SetEnabled (bool)

Interface Category:

API.

Purpose:

Enables or disables the label, according to the specified flag. (Labels usually have different looks for enabled and disabled states.)

Calling Context:

Call this function directly.

Parameters:

bool -The flag indicating whether to set this label to be enabled or disabled. True sets the label to be enabled; false sets the label to be disabled.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::AdoptDisabledPaint

virtual void AdoptDisabledPaint (TPaint * paint)

Interface Category:

API.

Purpose:

Adopts an object that governs the look of a label's disabled state.

Calling Context:

Call this function directly.

Parameters:

TPaint * paint -The TPaint object to be adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function is an alternative to using SetDisabledColor. A color difference is typically what distinguishes a disabled label from a label in its normal (enabled, active, and unselected) state. However, since TPaint is a generalized descriptor, other look-attributes such as patterns, transfer modes, and gradients can also be used.

Member Function: TTextLabel::AdoptInactivePaint

virtual void AdoptInactivePaint (TPaint * paint)

Interface Category:

API.

Purpose:

Adopts an object that governs the look of a label's inactive state.

Calling Context:

Call this function directly.

Parameters:

TPaint * paint -The TPaint object to be adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function is an alternative to using SetInactiveColor. A color difference is typically what distinguishes an inactive label from a label in its normal (enabled, active, and unselected) state. However, since TPaint is a generalized descriptor, other look-attributes such as patterns, transfer modes, and gradients can also be used.

Member Function: TTextLabel::GetLineOrientation

virtual void GetLineOrientation (TSingleLineOrientation &) const

Interface Category:

API.

Purpose:

Reports the orientation of the text in the label, for example whether it is vertical or horizontal.

Calling Context:

Call this function directly.

Parameters:

TSingleLineOrientation & -An object whose members this function fills. Those data members describe the orientation of the text.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

You can also discover whether the label's text is displayed forward or backward with this function. Use SetLineOrientation to change the orientation of the label's text.

Member Function: TTextLabel::SetLineOrientation

virtual void SetLineOrientation (const TSingleLineOrientation &)

Interface Category:

API.

Purpose:

Assigns an object that controls text orientation. This can affect whether the text label is displayed vertically or horizontally and whether the text runs forward or backward.

Calling Context:

Call this function directly.

Parameters:

const TSingleLineOrientation & -An object whose members control several aspects of the text label's orientation.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::GetInactiveColor

virtual TTextColorStyle GetInactiveColor () const

Interface Category:

API.

Purpose:

Reports which color is used to depict the inactive state of the label.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

TTextColorStyle -An object describing the color the text appears when the label is inactive.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If no inactive color has yet been assigned, this function gets the current color for disabled states. Look-attributes for inactive states default to those of disabled states because the system does not provide predetermined look-attributes for inactive states.

Member Function: TTextLabel::SetInactiveColor

virtual void SetInactiveColor (const TTextColorStyle & color)

Interface Category:

API.

Purpose:

Assigns a color that will be used to display text when the label is inactive.

Calling Context:

Call this function directly.

Parameters:

const TTextColorStyle & color -An object describing the color the text will appear when the label is inactive.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function creates its own copy of the TTextColorStyle passed it.

Member Function: TTextLabel::GetText

virtual const TText * GetText () const

Interface Category:

API.

Purpose:

Allows you to discover what text is in the label.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

const TText * -The text contained in the label.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Use SetText to assign text to the label.

Member Function: TTextLabel::GetFontFamily

virtual TFontFamilyStyle GetFontFamily () const

Interface Category:

API.

Purpose:

Gets the font in which to display this label's text.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The new font for the text.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TTextLabel::SetText

virtual void SetText (const TText & text)

Interface Category:

API.

Purpose:

Sets the specified text as this label's text. SetText creates and adopts a copy of the input parameter. This function invalidates the cached values.

Calling Context:

Call this function directly.

Parameters:

const TText & text -The text object whose copy is adopted as this label's text.

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.