Class: TGraphicLabel

Declaration: Label.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TLabel

Inherited By:

None.

Purpose:

TGraphicLabel derives from TLabel and implements a control label with a graphical (rather than text) representation. TGraphicLabel maintains three different graphics: one representing its normal state, one representing its inactive state, and one representing its selected state. A graphic label's normal state is enabled, active, and unselected. A graphic label's disabled state is represented by a change in color, so a separate graphic is not required. A graphic label's inactive state may also be depicted by a change of color or other look-modifying attribute. The disabled state takes precedence over the inactive state; that is a graphic label which is both inactive and disabled is depicted as being disabled. Deriving from TGraphicLabel is not intended; you should probably derive directly from TLabel instead.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

None. Deriving from TGraphicLabel is not intended; you should probably derive directly from TLabel instead.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TGraphicLabel::TGraphicLabel

TGraphicLabel ()
TGraphicLabel (MGraphic * adopted, bool enabled =true)
TGraphicLabel (const MGraphic &, bool enabled =true)
TGraphicLabel (const TGraphicLabel &)

Interface Category:

API.

Purpose:

Default constructor.
Creates a new TGraphicLabel, adopts the specified MGraphic to represent the new label's normal state, and enables or disables the new label according to the specified flag.
Creates a new TGraphicLabel, adopts a copy of the specified MGraphic to represent the new label's normal state, and enables or disables the new label according to the specified flag.
Copy constructor.

Calling Context:

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

Parameters:

Takes no parameters.
MGraphic * adopted -The graphic to adopt to represent the new label's normal state.
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 MGraphic & -The graphic whose copy is adopted to represent the new label's normal state.
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 TGraphicLabel & -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: TGraphicLabel::~TGraphicLabel

virtual ~ TGraphicLabel ()

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

TGraphicLabel & operator =(const TGraphicLabel &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const TGraphicLabel & -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: TGraphicLabel::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: TGraphicLabel::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: TGraphicLabel::IsEmpty

virtual bool IsEmpty () const

Interface Category:

API.

Purpose:

Reports whether the label is empty. A graphic label is considered empty if the MGraphic representing its normal state is NIL.

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: TGraphicLabel::AdoptGraphic

virtual void AdoptGraphic (MGraphic *)

Interface Category:

API.

Purpose:

Adopts the specified MGraphic to represent this label's normal state. This function deletes the previously adopted graphic.

Calling Context:

Call this function directly.

Parameters:

MGraphic * -The graphic to be adopted to represent this label's normal state.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGraphicLabel::GetGraphic

virtual const MGraphic * GetGraphic () const

Interface Category:

API.

Purpose:

Returns the graphic representing this label's normal state.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the graphic representing this label's normal state.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Use AdoptGraphic to assign an MGraphic to represent a graphic label's normal-state.

Member Function: TGraphicLabel::OrphanGraphic

virtual MGraphic * OrphanGraphic ()

Interface Category:

API.

Purpose:

Orphans the graphic representing this label's normal state, but does not delete it. This function sets the label's normal state graphic to NIL.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the orphaned object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGraphicLabel::AdoptInactiveGraphic

virtual void AdoptInactiveGraphic (MGraphic *)

Interface Category:

API.

Purpose:

Adopts the specified MGraphic to represent the label's inactive state. This function deletes the previously adopted graphic.

Calling Context:

Call this function directly.

Parameters:

MGraphic * -The graphic to be adopted to represent this label's inactive state.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Use OrphanInactiveGraphic to orphan but not delete the object this function installs.

Member Function: TGraphicLabel::GetInactiveGraphic

virtual const MGraphic * GetInactiveGraphic () const

Interface Category:

API.

Purpose:

Returns the graphic representing this label's inactive state.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the graphic representing this label's inactive state.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Use the function AdoptInactiveGraphic to set the graphic that a TGraphicLabel displays when it is inactive.

Member Function: TGraphicLabel::OrphanInactiveGraphic

virtual MGraphic * OrphanInactiveGraphic ()

Interface Category:

API.

Purpose:

Orphans the graphic representing this label's inactive state, but does not delete it. This function sets the label's inactive state graphic to NIL.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the orphaned object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGraphicLabel::AdoptSelectedGraphic

virtual void AdoptSelectedGraphic (MGraphic *)

Interface Category:

API.

Purpose:

Adopts the specified MGraphic to represent this label's selected state. This function deletes the previously adopted graphic.

Calling Context:

Call this function directly.

Parameters:

MGraphic * -The graphic to be adopted to depict this label's selected state.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Use OrphanSelectedGraphic to remove the image this function installs.

Member Function: TGraphicLabel::GetSelectedGraphic

virtual const MGraphic * GetSelectedGraphic () const

Interface Category:

API.

Purpose:

Returns the graphic representing this label's selected state.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the graphic representing this label's selected state.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Use AdoptSelectedGraphic to install the image that depicts the TGraphicLabel's selected state.

Member Function: TGraphicLabel::OrphanSelectedGraphic

virtual MGraphic * OrphanSelectedGraphic ()

Interface Category:

API.

Purpose:

Orphans the graphic representing this label's selected state, but does not delete it. This function sets the label's selected state graphic to NIL.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the orphaned object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGraphicLabel::TranslateBy

virtual void TranslateBy (const TGPoint &)

Interface Category:

API.

Purpose:

Translates this label by the specified delta x and delta y values. This function achieves the translation by individually translating each of the label's state-graphics.

Calling Context:

Call this function directly.

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: TGraphicLabel::TransformBy

virtual void TransformBy (const TGrafMatrix &)

Interface Category:

API.

Purpose:

Transforms this label using matrix operations. This function achieves the transformation by individually transforming the matrix for each of the label's state graphics. 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: TGraphicLabel::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: TGraphicLabel::GetBounds

virtual TGRect GetBounds () const

Interface Category:

API.

Purpose:

GetBounds computes and returns the bounding rectangle for this label. GetBounds calls GetGeometricBounds on this label's current drawing graphic--the graphic representing the label's current state.

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: TGraphicLabel::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, then 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:

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

Member Function: TGraphicLabel::MoveBy

virtual void MoveBy (const TGPoint &)

Interface Category:

API.

Purpose:

MoveBy adjusts the position of this label by the specified delta x and delta y values. This function calls TranslateBy and TranslateBy moves all the label's drawing graphics--the graphics representing the label's normal, disabled, and inactive states.

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: TGraphicLabel::GetDrawingGraphic

virtual MGraphic * GetDrawingGraphic () const

Interface Category:

API.

Purpose:

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

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the state 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. It is possible for this function to return NIL--typically when the current state of the graphic label does not have a graphic image to represent it and TGraphicLabel can not construct one. (TGraphicLabel can construct graphics to represent some states by changing the look-attributes (such as color) of the normal state.) The disabled state takes precedence over the inactive state; that is a graphic label which is both inactive and disabled is depicted as being disabled. Both the inactive and the disabled state take precedence over the selected state.

Member Function: TGraphicLabel::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:

A graphic label's disabled state can be represented by a change in color, so a separate graphic is not required, but is allowed. This function deletes any adopted DisabledGraphic so that GetDrawingGraphic can reconstruct the MGraphic with the newly adopted paint. A color difference is typically what distinguishes a disabled graphic from a graphic 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 could also be used.

Member Function: TGraphicLabel::AdoptInactivePaint

virtual void AdoptInactivePaint (TPaint * paint)

Interface Category:

API.

Purpose:

Allows a label's inactive state to be indicated with a color difference, rather than a separate graphic image.

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 function deletes any adopted InactiveGraphic so that it can be recalculated by GetDrawingGraphic.

Member Function: TGraphicLabel::OrphanDisabledGraphic

virtual MGraphic * OrphanDisabledGraphic ()

Interface Category:

API.

Purpose:

Orphans the current graphic used to depict the disabled state of the graphic label.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

MGraphic * orphanedGraphic -The graphic that will no longer represent the disabled state of the label.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

Does not delete the orphaned graphic. After calling this function, GetDisabledGraphic returns NIL.

Member Function: TGraphicLabel::GetDisabledGraphic

virtual const MGraphic * GetDisabledGraphic () const

Interface Category:

API.

Purpose:

Provides the graphic that depicts the label's disabled state.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

const MGraphic * -The graphic that depicts the label's disabled state.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGraphicLabel::AdoptDisabledGraphic

virtual void AdoptDisabledGraphic (MGraphic *)

Interface Category:

API.

Purpose:

Adopts the specified MGraphic to represent the label's disabled state. This function deletes the previously adopted graphic.

Calling Context:

Call this function directly.

Parameters:

MGraphic * -The graphic to be adopted to represent this label's disabled state.

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.