Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: gulbordr.h
Link against: egul.lib

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(), Draw(), Draw(), 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(), InnerRect(), Margins(), OuterRect(), SetAdjacent(), SetType(), SizeDelta(), T3DStyle, TBorderType, TColors, TConstructionStyle, TGulBorder(), TGulBorder(), TGulBorder(), TGulBorder(), TGulBorder(), TInlineStyle, TLogicalFamily, TLogicalType, TOutlineStyle, TRounding, TThickness, Type()


Construction and destruction


TGulBorder()

IMPORT_C TGulBorder();

Description

Default constructor.

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


TGulBorder()

IMPORT_C TGulBorder(TBorderType aType);

Description

Constructor with a border type.

Parameters

TBorderType aType

The border type.


TGulBorder()

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

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.


TGulBorder()

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.

[Top]


Member functions


Draw()

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

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.


Draw()

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


InnerRect()

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.


OuterRect()

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.


SetType()

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.


SetAdjacent()

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.


SizeDelta()

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.


Margins()

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

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

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.


Adjacent()

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.


Type()

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.

[Top]


Member classes


Class TColors

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

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(), iBack, iDark, iInternalBack, iLight, iLine, iMid, iMidlight

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.

[Top]


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 it does not.

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

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