Class TGulBorder

class TGulBorder;

Description

Draws a border around a control.

The rectangular areas enclosed by borders are typically working areas of the graphics context so the class supplies a number of methods which describe how it occupies the area.

A distinction between descriptive and logical borders is made. For descriptive borders the appearance of the border is known and fixed. The type of border drawn is determined by flags which describe how it is to be constructed. These flags can be combined to achieve many different effects, and standard combinations have been supplied (see the TBorderType enumeration). For logical borders the use of the border is known and fixed but the appearance is not specified. The appearance and sizing functions must be supplied in custom written code.

Members

Defined in TGulBorder:

• Adjacent()constGets the border adjacency.
• Draw(CGraphicsContext &,const TRect &)constDraws the border using a graphics context, inside a containing rectangle, and us...
• Draw(CGraphicsContext &,const TRect &,const TColors &)constDraws the border using a graphics context, inside a containing rectangle, and us...
• EAddFourPixelsThe border has four extra pixels.
• EAddFourRoundingPixelsBorder rounded by by removing four extra pixels.
• EAddOnePixelThe border has one extra pixel.
• EAddOneRoundingPixelBorder rounded by removing one extra pixel.
• EAddTwoPixelsThe border has two extra pixels.
• EAddTwoRoundingPixelsBorder rounded by removing two extra pixels.
• EContainerFamilyLogical border around a container.
• EControlFamilyLogical border around a control.
• EDeepRaisedA 3D raised border, with outline, and 2 pixel thickness.
• EDeepRaisedWithOutlineThe same as EDeepRaised.
• EDeepSunkenA 3D sunken border, with outline, and 2 pixel thickness.
• EDeepSunkenWithOutlineThe same as EDeepSunken.
• EDottedOutlineThe border outline is drawn using a dotted pen.
• EFlatA flat border.
• EFlatContainerFlat border around a container.
• EFlatControlFlat border around a control.
• EFocusedRaisedControlRaised border around a control with focus.
• EFocusedSunkenControlSunken border around a control with focus.
• EHorizontalBarA 3D raised border, with 2 pixels thickness and no outline on the top and bottom...
• EInvertedTwoStepInverted two step border construction.
• ENoneNo border.
• EOneStepOne step border construction.
• ERaisedA 3D effect raised border.
• ERaisedContainerRaised border around a container.
• ERaisedControlRaised border around a control.
• EShallowRaisedA 3D raised border, with 1 pixel thickness.
• EShallowSunkenA 3D sunken border, with 1 pixel thickness.
• ESingleBlackBorder is a 1 pixel wide black outline.
• ESingleDottedBorder is a 1 pixel wide dotted outline.
• ESingleGrayBorder is a 1 pixel wide grey outline.
• ESunkenA 3D effect sunken border.
• ESunkenContainerSunken border around a container.
• ESunkenControlSunken border around a control.
• EThickDeepRaisedWithOutlineA 3D raised border, with outline, and 3 pixel thickness.
• EThreeStepThree step border construction.
• ETwoStepTwo step border construction.
• EVerticalBarA 3D raised border, with 2 pixels thickness and no outline on the left and right...
• EWindowRaised border around a window.
• EWindowFamilyLogical border around a window.
• EWithInlineThe border has an interior border.
• EWithOutlineThe border has a single pixel outline, either solid (by default) or dotted.
• HasBorder()constTests whether a border is present.
• InnerRect(const TRect &)constReturns the rectangular area enclosed by the border.
• Margins()constReturns the border margins.
• OuterRect(const TRect &)constReturns the rectangular area required to accommodate the inner rectangle aInnerR...
• SetAdjacent(TInt)Sets the border adjacency.
• SetType(TInt)Sets the border type.
• SizeDelta()constReturns the size difference between the inner and outer rectangles of the border...
• T3DStyleDefines the 3D border style.
• TBorderTypeDefines the descriptive border types.
• TColorsRepresents the colours used within the border and for the optional single pixel ...
• TConstructionStyleDefines the border's construction style.
• TGulBorder()Default constructor.
• TGulBorder(TBorderType)Constructor with a border type.
• TGulBorder(TBorderType,TGulAdjacent)Constructor with a border type and an adjacency.
• TGulBorder(TInt)Constructor with a border type, specified as a TInt.
• TGulBorder(TInt,TGulAdjacent)Constructor with a border type, specified as a TInt, and a border adjacency.
• TInlineStyleDefines whether or not the border has a single pixel interior border.
• TLogicalFamilyFor logical borders, defines whether the border encloses a window, a container c...
• TLogicalTypeDefines the logical border types.
• TOutlineStyleDefines the border outline style.
• TRoundingDefines the number of pixels that are removed to produce rounded corners.
• TThicknessDefines the number of pixels to add to the border thickness.
• Type()constGets the border type.

IMPORT_C TGulBorder();

Description

Default constructor.

The border type is initialised to zero (i.e. no border).

IMPORT_C TGulBorder(TBorderType aType);

Description

Constructor with a border type.

Parameters

TGulBorder::TBorderType aType The border type.

IMPORT_C TGulBorder(TBorderType aType, TGulAdjacent aAdjacent);

Description

Constructor with a border type and an adjacency.

Parameters

TGulBorder::TBorderType aType The border type. TGulAdjacent aAdjacent Border adjacency. No outline is drawn for border sides that are adjacent.

IMPORT_C TGulBorder(TInt aType);

Description

Constructor with a border type, specified as a TInt.

Parameters

TInt aType The border type. Possible values are defined in the TBorderType enumeration.

IMPORT_C TGulBorder(TInt aType, TGulAdjacent aAdjacent);

Description

Constructor with a border type, specified as a TInt, and a border adjacency.

Parameters

TInt aType The border type. TGulAdjacent aAdjacent Border adjacency. No outline is drawn for border sides that are adjacent.

IMPORT_C void Draw(CGraphicsContext &aGc, const TRect &aRect, const TColors &aBorderColors) const;

Description

Draws the border using a graphics context, inside a containing rectangle, and using the border colours specified.

This function does nothing if the border type is ENone. If the border is a logical border, drawing is delegated to its implementation of MGulLogicalBorder::Draw(const TGulBorder &,CGraphicsContext &,const TRect &,const TGulBorder::TColors &)const.

Parameters

CGraphicsContext &aGc The graphics context to draw through. const TRect &aRect The containing rectangle. This defines the border's outline, i.e. the border is drawn inside this rectangle. const TGulBorder::TColors &aBorderColors The border colours.

IMPORT_C void Draw(CGraphicsContext &aGc, const TRect &aRect) const;

Description

Draws the border using a graphics context, inside a containing rectangle, and using default values for the border colours.

For details of the default border colours, see class TGulBorder::TColors.

This function does nothing if the border type is ENone. If the border is a logical border, drawing is delegated to its implementation of MGulLogicalBorder::Draw(const TGulBorder &,CGraphicsContext &,const TRect &,const TGulBorder::TColors &)const.

Parameters

CGraphicsContext &aGc The graphics context to draw through. const TRect &aRect The containing rectangle. This defines the border's outline, i.e. the border is drawn inside this rectangle.

IMPORT_C TRect InnerRect(const TRect &aOuterRect) const;

Description

Returns the rectangular area enclosed by the border.

Parameters

const TRect &aOuterRect The border's containing rectangle.

Return value

TRect The inner rectangle.

IMPORT_C TRect OuterRect(const TRect &aInnerRect) const;

Description

Returns the rectangular area required to accommodate the inner rectangle aInnerRect and the border.

Parameters

const TRect &aInnerRect The inner rectangular area.

Return value

TRect The enclosing rectangular area.

IMPORT_C void SetType(TInt aType);

Description

Sets the border type.

Descriptive borders use one of the values from the TBorderType enum. Logical borders use one of the TLogicalType values. Custom border types can be created by selecting one value from each of the enums T3DStyle and TConstructionStyle, one or more values from each of the enums TOutlineStyle and TInlineStyle, one or more values from the enums TThickness and TRounding and ORing all these values together.

Parameters

TInt aType The border type.

IMPORT_C void SetAdjacent(TInt aAdjacent);

Description

Sets the border adjacency.

No outline is drawn for border sides that are adjacent.

Parameters

TInt aAdjacent The border adjacency. For possible values, see the TGulAdjacent enum.

IMPORT_C TSize SizeDelta() const;

Description

Returns the size difference between the inner and outer rectangles of the border.

Return value

TSize The size difference between the inner and outer rectangles.

IMPORT_C TMargins Margins() const;

Description

Returns the border margins.

The border margins are four integers that represent the widths in pixels of the top, bottom, left and right hand sides of the border.

If the border is a logical border, then calculating the margins is delegated to its implementation of MGulLogicalBorder::Margins(const TGulBorder &)const.

Otherwise, the margins are calculated by adding together the single pixel border outline, if present (this is zero for adjacent sides), the border thickness (containing the mid-tone highlights and lowlights), and the single pixel interior outline, if present.

Return value

TMargins The border margins.

IMPORT_C TBool HasBorder() const;

Description

Tests whether a border is present.

No border is present if its type is ENoBorder.

Return value

TBool True if a border is present, otherwise false.

IMPORT_C TInt Adjacent() const;

Description

Gets the border adjacency.

No outline is drawn for border sides that are adjacent.

Return value

TInt The border adjacency. For possible values, see the TGulAdjacent enum.

IMPORT_C TInt Type() const;

Description

Gets the border type.

Return value

TInt The border type. This is one of the values from the TBorderType (for descriptive borders) or TLogicalType (for logical borders) enums.

class TColors;

Description

Represents the colours used within the border and for the optional single pixel border outlines.

These colours are stored using TRgb values.

An object of this type can be populated using ColorUtils::GetRgbDerivedBorderColors(TGulBorder::TColors &,TRgb,TDisplayMode).

The colours used inside the border are derived from iBack, the border's background colour, so that border colours can be lighter or darker shades of the colour used in the main body of the control they enclose. Different combinations of light and dark shades are used to draw opposite border sides, to achieve a raised or sunken effect.

Members

Defined in TGulBorder::TColors:

• TColors()Default constructor.
• iBackThe background colour for the border.
• iDarkThe darkest colour.
• iInternalBackNot used.
• iLightThe lightest colour.
• iLineThe line colour.
• iMidThe mid dark colour.
• iMidlightThe mid light colour.

Construction and destruction

---

TColors()

IMPORT_C TColors();

Description

Default constructor.

Initialises the border colours to blacks, whites and greys. For details, see the data members.

Member data

---

iLine

TRgb iLine;

Description

The line colour.

This is the colour used to draw the outlines on either side of the border. Not all border types have an outline. By default, KRgbBlack.

---

iBack

TRgb iBack;

Description

The background colour for the border.

The other colours used in the border are derived from this.

By default, KRgbWhite.

---

iLight

TRgb iLight;

Description

The lightest colour.

By default, KRgbWhite.

---

iMidlight

TRgb iMidlight;

Description

The mid light colour.

This colour is midway between iBack and iLight. By default, KRgbWhite.

---

iMid

TRgb iMid;

Description

The mid dark colour.

This colour is midway between iBack and iDark. By default, KRgbDarkGray.

---

iDark

TRgb iDark;

Description

The darkest colour.

By default, KRgbDarkGray.

---

iInternalBack

TRgb iInternalBack;

Description

Not used.

TOutlineStyle

Description

Defines the border outline style.

Note that not all border types have an outline.

EWithOutline The border has a single pixel outline, either solid (by default) or dotted. EDottedOutline The border outline is drawn using a dotted pen.

TInlineStyle

Description

Defines whether or not the border has a single pixel interior border.

By default it does not.

EWithInline The border has an interior border.

T3DStyle

Description

Defines the 3D border style.

EFlat A flat border. ESunken A 3D effect sunken border. ERaised A 3D effect raised border.

TConstructionStyle

Description

Defines the border's construction style.

EOneStep One step border construction. This type of border is drawn using the mid light and mid dark colours on opposite sides of the border. ETwoStep Two step border construction. This type of border uses light and dark colours for the main border frame (or mid light for the flat border), and an additional half frame using mid light or mid dark colours. EThreeStep Three step border construction. This type of border is drawn with an outer frame, a repeating one pixel band in mid tones, and an inner frame. EInvertedTwoStep Inverted two step border construction. This is the same as ETwoStep except that for raised and sunken borders, the additional half frame is drawn on the opposite side to that used in ETwoStep.

TThickness

Description

Defines the number of pixels to add to the border thickness.

The border thickness is the central part of the border, coloured in the mid-tone highlights and lowlights.

For two step-constructed borders, the additional pixels are only added to either the top left or bottom right hand sides.

EAddOnePixel The border has one extra pixel. EAddTwoPixels The border has two extra pixels. EAddFourPixels The border has four extra pixels.

TRounding

Description

Defines the number of pixels that are removed to produce rounded corners.

EAddOneRoundingPixel Border rounded by removing one extra pixel. EAddTwoRoundingPixels Border rounded by removing two extra pixels. EAddFourRoundingPixels Border rounded by by removing four extra pixels.

TLogicalFamily

Description

For logical borders, defines whether the border encloses a window, a container control or a control.

EWindowFamily Logical border around a window. EContainerFamily Logical border around a container. EControlFamily Logical border around a control.

TBorderType

Description

Defines the descriptive border types.

ENone No border. ESingleGray Border is a 1 pixel wide grey outline. ESingleBlack Border is a 1 pixel wide black outline. ESingleDotted Border is a 1 pixel wide dotted outline. EShallowRaised A 3D raised border, with 1 pixel thickness. EShallowSunken A 3D sunken border, with 1 pixel thickness. EDeepRaised A 3D raised border, with outline, and 2 pixel thickness. EDeepRaisedWithOutline The same as EDeepRaised. EDeepSunken A 3D sunken border, with outline, and 2 pixel thickness. EDeepSunkenWithOutline The same as EDeepSunken. EThickDeepRaisedWithOutline A 3D raised border, with outline, and 3 pixel thickness. EVerticalBar A 3D raised border, with 2 pixels thickness and no outline on the left and right hand sides. EHorizontalBar A 3D raised border, with 2 pixels thickness and no outline on the top and bottom.

TLogicalType

Description

Defines the logical border types.

EWindow Raised border around a window. EFlatContainer Flat border around a container. ERaisedContainer Raised border around a container. ESunkenContainer Sunken border around a container. EFlatControl Flat border around a control. ERaisedControl Raised border around a control. ESunkenControl Sunken border around a control. EFocusedRaisedControl Raised border around a control with focus. EFocusedSunkenControl Sunken border around a control with focus.