Class: TLabel

Declaration: Label.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MDrawable, MGUIAttributeUser

Inherited By:

TTextLabel TGraphicLabel

Purpose:

TLabel derives from MDrawable and is the base class that defines the protocol for text and graphic labels used by controls. Control labels can be active or inactive, enabled or disabled, and selected or unselected; the label can draw something different for each of these states. For example, the text label on a push button might display gray text when the button is disabled.

Instantiation:

TLabel is an abstract class, so it should not be instantiated.

Deriving Classes:

Classes deriving from TLabel must override the pure virtual functions: IsEmpty, GetBounds, MoveTo, MoveBy, and Draw. Derived classes which use an equality test should probably override the IsEqual function to test the contents of the label.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TLabel::TLabel

TLabel ()
TLabel (bool enabled)
TLabel (const TLabel &)

Interface Category:

API.

Purpose:

Default constructor.
Creates a new TLabel whose initial state is enabled or disabled according to the specified flag.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Call this function directly.
Called to copy an object.

Parameters:

Takes no parameters.
bool enabled -The flag indicating whether to enable or disable the new label. True enables the new label; false disables it.
const TLabel & -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: TLabel::~TLabel

virtual ~ TLabel ()

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

TLabel & operator =(const TLabel &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const TLabel & -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: TLabel::operator==

bool operator ==(const TLabel &) const

Interface Category:

API.

Purpose:

Tests whether the two objects on either side of the ==symbol are equal.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TLabel & -The object to be compared to this object.

Return Value:

Returns true if the two objects are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Equivalent to calling IsEqual. Overriding the IsEqual function also effectively overrides the ==operator with the same test.

Member Function: TLabel::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: TLabel::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: TLabel::IsEmpty

virtual bool IsEmpty () const

Interface Category:

API.

Purpose:

Reports whether this label is empty. Classes deriving from TLabel must provide their own definitions of empty.

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 is a pure virtual function and must be overridden by classes deriving from TLabel.

Member Function: TLabel::IsActive

bool IsActive () const

Interface Category:

API.

Purpose:

IsActive reports whether this label is active. Labels usually have different looks for active and inactive states.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this label is active.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLabel::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: TLabel::IsEnabled

bool IsEnabled () const

Interface Category:

API.

Purpose:

Reports whether this label is enabled. Typically, labels have different looks for enabled and disabled states.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this label is active.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLabel::SetEnabled

virtual void SetEnabled (bool)

Interface Category:

API.

Purpose:

Enables or disables this label according to the specified flag. Typically, labels have different looks for enabled and disabled states.

Calling Context:

Call this function directly.

Parameters:

bool -The flag indicating whether to enable or disable this label. True enables the label; false disables it.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLabel::IsSelected

bool IsSelected () const

Interface Category:

API.

Purpose:

Reports whether this label is selected. Labels usually have different looks for active and inactive states.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this label is selected.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLabel::SetSelected

virtual void SetSelected (bool)

Interface Category:

API.

Purpose:

Selects or deselects this label according to the specified flag. Typically, labels have different looks for selected and unselected states.

Calling Context:

Call this function directly.

Parameters:

bool -The flag indicating whether to select or deselect this label. True selects the label; false deselects it.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLabel::GetBounds

virtual TGRect GetBounds () const

Interface Category:

API.

Purpose:

Computes and returns the bounding rectangle for this label.

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 is a pure virtual function and must be overridden by classes deriving from TLabel.

Member Function: TLabel::GetSize

virtual TGPoint GetSize () const

Interface Category:

API.

Purpose:

Computes and returns the height and width of the bounding rectangle for this label. This function calls GetBounds to compute the height and width of this label; therefore classes deriving from TLabel need not override this function--overriding GetBounds is sufficient.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a TGPoint whose x component is the width of this label, and whose y component is the height of this label.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLabel::MoveTo

virtual void MoveTo (const TGPoint &)

Interface Category:

API.

Purpose:

Moves the label so that its upper left corner attains the specified position.

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:

This function is a pure virtual function and must be overridden by classes deriving from TLabel.

Member Function: TLabel::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 is a pure virtual function and must be overridden by classes deriving from TLabel.

Member Function: TLabel::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 is a pure virtual function and must be overridden by classes deriving from TLabel.

Member Function: TLabel::GetInactivePaint

virtual const TPaint * GetInactivePaint () const

Interface Category:

API.

Purpose:

Gets the current color or other look-attributes that depict an inactive state of a label.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a TPaint containing the look-attributes.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

If no inactive paint attributes have yet been adopted, this function gets the current look-attributes 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: TLabel::AdoptInactivePaint

virtual void AdoptInactivePaint (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 -An object to be adopted containing the look-attributes for the label's inactive state.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Unless this function is used, the label's inactive state will have the look of a disabled state because the system does not provide predetermined look-attributes for inactive states. Classes derived from TLabel may provide alternative member functions of depicting inactive states. For example, TGraphicLabel allows a client to adopt a complete MGraphic to represent the inactive state, even though a graphic label's disabled state is represented by a change in color. Adoption of an MGraphic allows arbitrary images to represent the inactive state instead of restricting the distinction to such look-attributes as color, transfer modes, and patterns, which a TPaint provides.

Member Function: TLabel::GetDisabledPaint

virtual const TPaint * GetDisabledPaint () const

Interface Category:

API.

Purpose:

Gets the look of a label's disabled state.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

TPaint * paint -The look-attributes for the label's disabled state.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLabel::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 -An object to be adopted containing the look-attributes for the label's disabled state.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Unless this function is used, the look of the label's disabled state will default to that defined by the general look-attributes for disabled states.

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