Class: TRecessedBorder

Declaration: Decoration.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TFramedBorder

Inherited By:

TPictureFrameBorder TRaisedBorder TRecessedBackground

Purpose:

TRecessedBorder derives from TFramedBorder. This class adds highlighting and shadow to its parent class to give the border a 3-D appearance that is recessed below the surrounding drawing surface.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Derive from TRecessedBorder to add further to the border decoration.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TRecessedBorder::~TRecessedBorder

virtual ~ TRecessedBorder ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecessedBorder::operator=

TRecessedBorder & operator =(const TRecessedBorder &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

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

Parameters:

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

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

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

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

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: TRecessedBorder::SetGrooved

virtual void SetGrooved (const bool flag)

Interface Category:

API.

Purpose:

Sets whether the TRecessedBorder appears grooved into the drawing surface. If the input flag is set to true, this function makes the border look grooved by adding extra highlight and shadow lines around the outer edge of the border. By default, a TRecessedBorder is not grooved.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecessedBorder::IsGrooved

virtual bool IsGrooved (void) const

Interface Category:

API.

Purpose:

Determines whether this border is grooved. By default, a TRecessedBorder is not grooved.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns true if this border is grooved, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecessedBorder::AdoptHighlightPaint

virtual void AdoptHighlightPaint (TPaint *)

Interface Category:

API.

Purpose:

Adopts the specified paint object as this border's highlight paint. To reset the highlight paint back to its default value (calculated from the fill paint), specify NIL as the input parameter to this function. AdoptHighlightPaint also deletes the previous highlight paint object. Normally the highlight paint is calculated from the fill paint in the function AdoptPaint. This function provides an override for that default.

Calling Context:

Called from SetHighlightPaint. You can also call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

You can also use SetHighlightPaint to set the highlight paint. 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: TRecessedBorder::CopyHighlightPaint

TPaint * CopyHighlightPaint () const

Interface Category:

API.

Purpose:

Creates a copy of the current highlight paint.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns the newly created copy of the highlight paint, which can be NIL if none was set.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecessedBorder::GetHighlightPaint

TPaint * GetHighlightPaint () const

Interface Category:

API.

Purpose:

Returns a pointer to the current highlight paint object. The current highlight paint object can be set with SetHighlightPaint or AdoptHighlightPaint.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns a pointer to the current highlight paint object, which can be NIL if none was set.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecessedBorder::SetHighlightPaint

virtual void SetHighlightPaint (const TPaint &)

Interface Category:

API.

Purpose:

Sets the highlight paint used for highlighting the frame around this border. SetHighlightPaint creates a copy of the input parameter, then calls AdoptHighlightPaint to adopt the copy as its new highlight paint. Normally the highlight paint is calculated from the fill paint in the function AdoptPaint. This function provides an override for that default.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

You can also use AdoptHighlightPaint to set the frame paint. 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: TRecessedBorder::OrphanHighlightPaint

virtual TPaint * OrphanHighlightPaint ()

Interface Category:

API.

Purpose:

Orphans the current highlight paint object and resets the highlight paint back to the default, which is derived from the current fill paint. This function does not delete the orphaned highlight paint object.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns the orphaned highlight paint object, which can be NIL if none was set.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecessedBorder::AdoptShadowPaint

virtual void AdoptShadowPaint (TPaint *)

Interface Category:

API.

Purpose:

Adopts the specified paint object as this border's shadow paint, which is used to draw the shadow around the border. To reset the shadow paint back to its default value (calculated from the fill paint), specify NIL as the input parameter to this function. AdoptShadowPaint deletes the previous shadow paint object. Normally the shadow paint is calculated from the fill paint in the function AdoptPaint. This function provides an override for that default.

Calling Context:

Called from SetShadowPaint. You can also call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

You can also use SetShadowPaint to set the shadow paint. 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: TRecessedBorder::CopyShadowPaint

TPaint * CopyShadowPaint () const

Interface Category:

API.

Purpose:

Creates a copy of the current shadow paint.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns the newly created copy of the shadow paint, which can be NIL if none was set.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecessedBorder::GetShadowPaint

TPaint * GetShadowPaint () const

Interface Category:

API.

Purpose:

Returns a pointer to the current shadow paint object. The current shadow paint object can be set with AdoptShadowPaint or SetShadowPaint.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns a pointer to the current shadow paint object, which can be NIL if none was set.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecessedBorder::SetShadowPaint

virtual void SetShadowPaint (const TPaint &)

Interface Category:

API.

Purpose:

Sets the shadow paint used for drawing the shadow around this border. SetShadowPaint creates a copy of the input parameter, and then calls AdoptShadowPaint to adopt the copy as its new shadow paint. Normally the shadow paint is calculated from the fill paint in the function AdoptPaint. This function provides an override for that default.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

You can also use AdoptShadowPaint to set the shadow paint. 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: TRecessedBorder::OrphanShadowPaint

virtual TPaint * OrphanShadowPaint ()

Interface Category:

API.

Purpose:

Orphans the current shadow paint object and resets the shadow paint back to the default, which is derived from the current fill paint. This function does not delete the orphaned shadow paint object.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns the orphaned paint object, which can be NIL if none was set.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecessedBorder::Draw

virtual void Draw (TGrafPort &) const

Interface Category:

API.

Purpose:

Draws this recessed border.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

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

Member Function: TRecessedBorder::AdoptPaint

virtual void AdoptPaint (TPaint *)

Interface Category:

API.

Purpose:

Sets the fill paint to the specified paint object and then recalculates the frame, highlight, and shadow paints from it. To reset the fill paint back to its default value, specify NIL as the input parameter to this function. AdoptPaint deletes the previous fill paint object.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides TFramedBorder's function of the same name. 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: TRecessedBorder::OrphanPaint

virtual TPaint * OrphanPaint ()

Interface Category:

API.

Purpose:

Orphans this recessed border's fill paint. This function resets the fill paint to the default and then recalculates the frame, highlight, and shadow paints from it. This function does not delete the orphaned fill paint object.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns the orphaned fill paint, which can be NIL if none was set.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function overrides TFramedBorder's function of the same name. 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: TRecessedBorder::CalculateAngle

virtual GDegrees CalculateAngle (TGrafPort & port) const

Interface Category:

API.

Purpose:

Calculates the angular result of any transformations that have been applied to the specified port. This is used so that the border can maintain the 3-D illusion regardless of rotation. But a border only does this if rotation awareness is set to true. See SetRotationAware. The default is false.

Calling Context:

Called directly by friend classes or classes deriving from TRecessedBorder.

Parameters:

Return Value:

Returns the calculated angle.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TRecessedBorder::CalculateInsets

virtual void CalculateInsets (GDegrees angle, TGRect & highlight, TGRect & groove) const >Interface Category: API.

Purpose:

Calculates where the highlights and shadows should go, given the angle by which this border has been rotated.

Calling Context:

Called directly by friend classes or classes deriving from TRecessedBorder.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TRecessedBorder::CalculateClipPart

virtual EClipPart CalculateClipPart (GDegrees angle) const

Interface Category:

API.

Purpose:

Calculates how to clip the highlight during drawing, given the angle of rotation.

Calling Context:

Called directly by friend classes or classes deriving from TRecessedBorder.

Parameters:

Return Value:

Returns an EClipPart value that indicates the part to clip out while drawing the highlight.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This function is protected.

Member Function: TRecessedBorder::SetDepth

virtual void SetDepth (const GCoordinate depth)

Interface Category:

API.

Purpose:

Sets the depth of the recessed border to the value specified. The default depth is 1. The depth controls the width of the pens used for drawing the shadow and highlights. For a depth of 2 or more, the top-right and bottom-left corners where the shadow and highlight meet are diagonally clipped so that thicker lines still look good. This makes the depth 2 or more decorations considerably more expensive to draw -but they look nice at any DPI. Any depth less than 0 is ignored.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecessedBorder::GetDepth

GCoordinate GetDepth () const

Interface Category:

API.

Purpose:

Returns the depth last set in SetDepth.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns the current depth for this border.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecessedBorder::IsRotationAware

bool IsRotationAware () const

Interface Category:

API.

Purpose:

Determines whether the recessed border is rotation independent. Default is false.

Calling Context:

Call this function directly.

Parameters:

Return Value:

Returns true if the recessed border is rotation independent.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecessedBorder::SetRotationAware

virtual void SetRotationAware (bool aware =true)

Interface Category:

API.

Purpose:

Sets the recessed border to be rotation independent or rotation dependent, depending on the Boolean flag value. To be rotation independent means that the highlighting and shadowing are always drawn as if the light source is at the top-left corner of the screen, regardless of any transformations that might have been applied to the port that is being used for drawing. This makes the decoration marginally more expensive.

Calling Context:

Call this function directly.

Parameters:

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TRecessedBorder::TRecessedBorder

  1. TRecessedBorder ()
  2. TRecessedBorder (const TGRect & bounds, GCoordinate thickness =kDefaultThickness, bool interior =kDefaultInteriorState)
  3. TRecessedBorder (const TGRect & bounds, const TPaint & fill, GCoordinate thickness =kDefaultThickness, bool interior =kDefaultInteriorState)
  4. TRecessedBorder (const MGraphic & bounds, GCoordinate thickness =kDefaultThickness, bool interior =kDefaultInteriorState)
  5. TRecessedBorder (const MGraphic & bounds, const TPaint & fill, GCoordinate thickness =kDefaultThickness, bool interior =kDefaultInteriorState)
  6. TRecessedBorder (const TView & bounds, GCoordinate thickness =kDefaultThickness, bool interior =kDefaultInteriorState)
  7. TRecessedBorder (const TView & bounds, const TPaint & fill, GCoordinate thickness =kDefaultThickness, bool interior =kDefaultInteriorState)
  8. TRecessedBorder (const TRecessedBorder &)

Interface Category:

API.

Purpose:

  1. Default constructor.
    2. 2-7. Creates a new border using the specified bounds, paint, and border thickness.
  2. Copy constructor.

Calling Context:

  1. Called by the stream-in operators.
    2. 2-7. Call these functions directly.
  2. Called to copy an object.

Parameters:

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.
Copyright©1995 Taligent,Inc. All rights reserved.