Class: TDecoration

Declaration: Decoration.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MGraphic, MGUIAttributeUser

Inherited By:

TBorder

Purpose:

TDecoration derives from MGraphic and is an abstract base class that provides for a family of rectangular decorations commonly used in user interfaces. Decorations include raised and recessed borders. Decorations can be adopted into some UI elements to affect the look of the object.

Instantiation:

Abstract base class; do not allocate.

Deriving Classes:

Derive from TDecoration to provide concrete decoration classes.

Concurrency:

Not multithread safe.

Resource Use:

The paints used in decorations tend to be relatively expensive to construct, therefore an alternative mechanism for specifying all the paints has been implemented via the MGUIAttributeUser mixin, which is an internal class at this time. When this alternative is being used, as is the case with all the standard UI elements, the SetPaint member functions and the CreateXxxxPaint member functions are bypassed, resulting in faster and cheaper decorations.

Member Function: TDecoration::~TDecoration

virtual ~ TDecoration ()

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

TDecoration & operator =(const TDecoration &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

const TDecoration & -The object to copy.

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:

None.

Member Function: TDecoration::operator==

bool operator ==(const TDecoration &) const

Interface Category:

API.

Purpose:

Tests whether two objects equal.

Calling Context:

Call this function by using the operator in an expression.

Parameters:

const TDecoration & -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:

None.

Member Function: TDecoration::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

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

Not multithread safe.

Other Considerations:

None.

Member Function: TDecoration::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

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

Return Value:

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

Exceptions:

Throws TInvalidVersionError if the object has detected an unsupportable version during the stream-in process.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDecoration::GetGeometricBounds

virtual TGRect GetGeometricBounds () const

Interface Category:

API.

Purpose:

Returns the bounding rectangle of this decoration, without considering any area determined by the attribute bundle information. Geometric bounds and loose fit bounds for decorations are identical.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the rectangle that encloses this decoration, in world space coordinates.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides MGraphic's function of the same name.

Member Function: TDecoration::GetBounds

virtual TGRect GetBounds () const

Interface Category:

API.

Purpose:

Returns the bounds of this decoration. This function returns the same results as both GetGeometricBounds and GetLooseFitBounds.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the bounds of this decoration.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDecoration::Inset

virtual void Inset (GCoordinate x, GCoordinate y)

Interface Category:

API.

Purpose:

Insets the bounds of this decoration by the specified delta values. To inset the bounds, this function moves the horizontal edges in opposite directions from one another by the specified delta x value, and moves the vertical edges in opposite directions from one another by the specified delta y value. If delta x (delta y) is positive, the horizontal (vertical) edges are moved closer together; if delta y (delta y) is negative, the horizontal (vertical) edges are moved further apart.

Calling Context:

Call this function directly. Also called from Outset.

Parameters:

GCoordinate x -The amount by which to inset the horizontal edges of the decoration's bounds.
GCoordinate y -The amount by which to inset the vertical edges of the decoration's bounds.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDecoration::Outset

virtual void Outset (GCoordinate x, GCoordinate y)

Interface Category:

API.

Purpose:

Outsets the bounds of this decoration by the specified delta values. This function negates its input parameters and calls Inset with those values.

Calling Context:

Call this function directly.

Parameters:

GCoordinate x -The amount by which to outset the horizontal edges of the decoration's bounds.
GCoordinate y -The amount by which to outset the vertical edges of the decoration's bounds.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDecoration::MoveTo

virtual void MoveTo (const TGPoint &)
virtual void MoveTo (GCoordinate x, GCoordinate y)

Interface Category:

API.

Purpose:

Moves this decoration so that the top-left corner is positioned at the specified location.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & -The point at which to place the top-left corner of this decoration.
GCoordinate x -The location at which to place the left edge of this decoration.
GCoordinate y -The location at which to place the upper edge of this decoration.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDecoration::SetBounds

virtual void SetBounds (const TGRect &)
virtual void SetBounds (const MGraphic &)
virtual void SetBounds (const TView &)

Interface Category:

API.

Purpose:

Sets the bounds of this decoration to specified rectangle.
Derives the bounds of this decoration from the bounds of the specified MGraphic.
Derives the bounds of this decoration from the bounds of the specified TView.

Calling Context:

Call this function directly.

Parameters:

const TGRect & -The new bounds for this decoration.
const MGraphic & -The MGraphic object from which to set this decoration's bounds.
const TView & -The TView object from which to set this decoration's bounds.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TDecoration::TranslateBy

virtual void TranslateBy (const TGPoint &)

Interface Category:

API.

Purpose:

Moves this decoration by the specified amount. The x-component of the TGPoint parameter indicates the horizontal delta; the y-component of the TGPoint parameter indicates the vertical delta.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & -The amount by which to move this decoration.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides MGraphic's function of the same name.

Member Function: TDecoration::TDecoration

TDecoration ()
TDecoration (const TGRect & bounds)
TDecoration (const MGraphic & bounds)
TDecoration (const TView & bounds)
TDecoration (const TDecoration &)

Interface Category:

API.

Purpose:

Default constructor.
Creates a new TDecoration object with the specified bounds.
Creates a new TDecoration object whose bounds are the same as the specified MGraphic.
Creates a new TDecoration object whose bounds are the same as the specified TView.
Copy constructor.

Calling Context:

Called by the stream-in operators.
Called directly by friend classes or classes deriving from TDecoration.
Called directly by friend classes or classes deriving from TDecoration.
Called directly by friend classes or classes deriving from TDecoration.
Called to copy an object.

Parameters:

Takes no parameters.
const TGRect & bounds -The bounds for the new decoration.
const MGraphic & bounds -The MGraphic from which to derive the bounds for the new decoration.
const TView & bounds -The TView from which to derive the bounds for the new decoration.
const TDecoration & -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

TDecoration is an abstract base class--all the constructors are protected. Do not instantiate this class.

Member Function: TDecoration::CreateFillPaint

static TPaint * CreateFillPaint ()

Interface Category:

API.

Purpose:

Creates and returns the default fill paint used to fill the interior of this decoration. The default fill paint is 87% gray.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the default fill paint.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This member function is not used by the standard UI elements. The internal MGUIAttributeUser mixin is used instead.

Member Function: TDecoration::CreateFrameFromFill

static TPaint * CreateFrameFromFill (const TPaint &)

Interface Category:

API.

Purpose:

Calculates a shade of the specified fill paint appropriate for framing an area filled with the fill paint. This function creates a new TColorPaint object, initializes it with the calculated frame color, and returns it.

Calling Context:

Call this function directly.

Parameters:

const TPaint & -The fill paint for which to calculate a frame paint.

Return Value:

Returns the frame paint created by this function.

Exceptions:

Throws TStandardException if the paint style of the specified TPaint object is not TPaint::kColorPaint.

Concurrency:

Not multithread safe.

Other Considerations:

This member function is not used by the standard UI elements. The internal MGUIAttributeUser mixin is used instead to provide the various paints.

Member Function: TDecoration::CreateShadowFromFill

static TPaint * CreateShadowFromFill (const TPaint &)

Interface Category:

API.

Purpose:

Calculates a shade of the specified fill paint appropriate for putting shadows around an area filled with the specified fill paint. This function creates a new TColorPaint object, initializes it with the calculated shadow color, and returns it.

Calling Context:

Call this function directly.

Parameters:

const TPaint & -The fill paint for which to calculate a shadow paint.

Return Value:

Returns the shadow paint created by this function.

Exceptions:

Throws TStandardException if the paint style of the specified TPaint object is not TPaint::kColorPaint.

Concurrency:

Not multithread safe.

Other Considerations:

This member function is not used by the standard UI elements. The internal MGUIAttributeUser mixin is used instead to provide the various paints.

Member Function: TDecoration::CreateLightShadowFromFill

static TPaint * CreateLightShadowFromFill (const TPaint &)

Interface Category:

API.

Purpose:

Calculates a shade of the specified fill paint appropriate for putting light shadows around an area filled with the specified fill paint. This function creates a new TColorPaint object, initializes it with the calculated light shadow color, and returns it.

Calling Context:

Call this function directly.

Parameters:

const TPaint & -The fill paint for which to calculate a light shadow paint.

Return Value:

Returns the light shadow paint created by this function.

Exceptions:

Throws TStandardException if the paint style of the specified TPaint object is not TPaint::kColorPaint.

Concurrency:

Not multithread safe.

Other Considerations:

This member function is not used by the standard UI elements. The internal MGUIAttributeUser mixin is used instead to provide the various paints.

Member Function: TDecoration::CreateHighlightFromFill

static TPaint * CreateHighlightFromFill (const TPaint &)

Interface Category:

API.

Purpose:

Calculates a shade of the specified fill paint appropriate for putting highlight lines around an area filled with the specified fill paint. This function creates a new TColorPaint object, initializes it with the calculated highlight color, and returns it.

Calling Context:

Call this function directly.

Parameters:

const TPaint & -The fill paint for which to calculate a highlight paint.

Return Value:

Returns the highlight paint created by this function.

Exceptions:

Throws TStandardException if the paint style of the specified TPaint object is not TPaint::kColorPaint.

Concurrency:

Not multithread safe.

Other Considerations:

This member function is not used by the standard UI elements. The internal MGUIAttributeUser mixin is used instead to provide the various paints.

Member Function: TDecoration::FastGetBounds

const TGRect * FastGetBounds () const

Interface Category:

API.

Purpose:

Returns a pointer to the decoration's bounding rectangle, including any area determined by the attribute bundle information.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A pointer to the decoration's bounding rectangle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TDecoration::GetLooseFitBounds

virtual TGRect GetLooseFitBounds (const TGrafPort * port =NIL) const

Interface Category:

API.

Purpose:

Returns the entire decoration's bounding rectangle, including any area determined by the attribute bundle information. Geometric bounds and loose fit bounds for decorations are identical.

Calling Context:

Call this function directly.

Parameters:

const TGrafPort * port =NIL -The grafport--not actually used by this function.

Return Value:

Returns the rectangle that encloses this entire decoration, in world space coordinates.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides MGraphic's function of the same name.

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