
SYMBIAN OS V6.1 EDITION FOR C++

» Symbian OS v6.1 Edition for C++ » API Reference » UI Graphics Utilities » TGulBorder

Location: gulbordr.h
Link against: egul.lib

Class `TGulBorder`

TGulBorder

Support

Supported from 6.0

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.

Defined in TGulBorder:
Adjacent(), BorderInnerRect(), BorderMargins(), BorderRounding(), Depth(), Draw(), DrawBottomRight(), DrawInline(), DrawInvertedTwoStep(), DrawOneStep(), DrawOutline(), DrawRectOutline(), DrawRoundedBottomRight(), DrawRoundedCorner(), DrawRoundedTopLeft(), DrawThreeStep(), DrawTopLeft(), DrawTwoStep(), EAddFourPixels, EAddFourRoundingPixels, EAddOnePixel, EAddOneRoundingPixel, EAddTwoPixels, EAddTwoRoundingPixels, EContainerFamily, EControlFamily, EDeepRaised, EDeepRaisedWithOutline, EDeepSunken, EDeepSunkenWithOutline, EDottedOutline, EFlat, EFlatContainer, EFlatControl, EFocusedRaisedControl, EFocusedSunkenControl, EHorizontalBar, EInvertedTwoStep, ENone, EOneStep, ERaised, ERaisedContainer, ERaisedControl, EShallowRaised, EShallowSunken, ESingleBlack, ESingleDotted, ESingleGray, ESunken, ESunkenContainer, ESunkenControl, EThickDeepRaisedWithOutline, EThreeStep, ETwoStep, EVerticalBar, EWindow, EWindowFamily, EWithInline, EWithOutline, HasBorder(), InlineMargins(), InlineRounding(), InnerRect(), InternalType(), IsSunken(), Margins(), OuterRect(), OutlineInnerRect(), OutlineMargins(), Rounding(), RoundingMargin(), SetAdjacent(), SetType(), SizeDelta(), T3DStyle, TBorderType, TColors, TConstructionStyle, TGulBorder(), TInlineStyle, TLogicalFamily, TLogicalType, TOutlineStyle, TRounding, TThickness, Thickness(), TranslateLegacyTypes(), Type(), iType

Construction

`TGulBorder()`

TGulBorder();

Description

Default constructor.

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

`TGulBorder()`

TGulBorder(TBorderType aType);

Description

Constructor with a border type.

Parameters

TBorderType aType

The border type.

`TGulBorder()`

TGulBorder(TBorderType aType,TGulAdjacent aAdjacent);

Description

Constructor with a border type and an adjacency.

Parameters

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

`TGulBorder()`

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.

`TGulBorder()`

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.

Member functions

`Draw()`

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 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().

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.

`Draw()`

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().

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 TColors& aBorderColors`	The border colours.

`InnerRect()`

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.

`OuterRect()`

TRect OuterRect(const TRect& aInnerRect) const;

Description

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

Parameters

const
TRect& aInnerRect

The inner rectangular area.

Return value

TRect

The enclosing rectangular area.

`SetType()`

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.

`SetAdjacent()`

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.

`SizeDelta()`

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.

`Margins()`

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().

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.

`HasBorder()`

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.

`Adjacent()`

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.

`Type()`

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.

Member classes

Class `TColors`

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().

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.

Defined in TGulBorder::TColors:
TColors(), iBack, iDark, iInternalBack, iLight, iLine, iMid, iMidlight

Construction

`TColors()`

TColors();

Description

Default constructor.

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

Data members

`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 currently used.

By default, KRgbWhite.

Member enumerations

Enum `TOutlineStyle`

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.

Enum `TInlineStyle`

TInlineStyle

Description

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

By default there is none.

EWithInline

The border has an interior border.

Enum `T3DStyle`

T3DStyle

Description

Defines the 3D border style.

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

Enum `TConstructionStyle`

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`.

Enum `TThickness`

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`	Tbe border has two extra pixels.
`EAddFourPixels`	The border has four extra pixels.

Enum `TRounding`

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.

Enum `TLogicalFamily`

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.

Enum `TBorderType`

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.

Enum `TLogicalType`

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.