MFormCustomDraw

Support

Supported from 6.0

Description

An abstract class which specifies the protocol for customising the way the text and its background are drawn.

Common uses for this are to implement custom highlighting or to draw a background bitmap. You must create an object of a class derived from this class and call CTextLayout::SetCustomDraw(), passing a pointer to the object. All of these functions have default implementations. Your class can override any of the virtual functions listed below.

Defined in MFormCustomDraw:
DrawBackground(), DrawLineGraphics(), DrawText(), TLineInfo, TParam

virtual void DrawBackground(const TParam& aParam,const TRgb& aBackground,TRect& aDrawn) const;

Description

This function is called whenever part of the background of a CTextLayout or CTextView object needs to be drawn. The default implementation fills aParam.iDrawRect with the colour specified in aBackground.

The default background colour is contained in aBackground. This is the background colour of the paragraph if drawing text, or the background colour specified in the TDrawTextLayoutContext object passed to CTextLayout::DrawL() if drawing outside the text area.

The rectangle which is drawn by this function, (this may not be the whole of aParam.iDrawRect) must be returned in aDrawn; areas not drawn by you are automatically filled using the colour aBackground.

Parameters

const TParam& aParam Contains the drawing parameters: aParam.iGc is the graphics context to use. aParam.iMap is the graphics device map, which allows you to convert between pixels and twips and create fonts. aParam.iTextLayoutTopLeft is the origin of the text; bitmaps and other graphics must be drawn relative to this position. aParam.iDrawRect is the area to be drawn; do not draw outside this rectangle. const TRgb& aBackground The default background colour. This is the background colour of the paragraph if drawing text, or the background colour specified in the TDrawTextLayoutContext object passed to CTextLayout::DrawL() if drawing outside the text area. TRect& aDrawn Must return the rectangle you actually draw. This may not be the whole of aParam.iDrawRect (for instance, if you are drawing a non-tiled bitmap that occupies only part of aRect).

virtual void DrawLineGraphics(const TParam& aParam,const TLineInfo& aLineInfo) const;

Description

This function is called after the background has been drawn by DrawBackground(), and before drawing the text. This function might be used to draw a ruled line under each line of text.

The default implementation of this function does nothing.

Parameters

const TParam& aParam Contains the drawing parameters. You should only draw to aParam.iDrawRect. There is no need to fill aParam.iDrawRect or to indicate the rectangle drawn. const TLineInfo& aLineInfo Contains the line metrics: aLineInfo.iOuterLineRect specifies the bounding rectangle of the line, including margins, indents and automatic space above and below paragraphs, aLineInfo.iInnerLineRect specifies the bounds of the text only, aLineInfo.iBaseline specifies the baseline of the text.

virtual void DrawText(const TParam& aParam,const TLineInfo& aLineInfo,const TCharFormat& aFormat, const TDesC& aText,const TPoint& aTextOrigin,TInt aExtraPixels) const;

Description

This function is called to draw the text and its highlighted background, if any, after bidirectional reordering and other character mappings have taken place.

The default implementation of this function draws the text with no special effects and supports standard, round-cornered and shadowed highlighting only. The text is drawn with the left end of its baseline located at aTextOrigin after drawing the background, if any, in aParam.iDrawRect.

The main reason to override this function is to apply custom text highlighting, (for this, aFormat.iFontPresentation.iHighlightStyle should be in the range EFontHighlightFirstCustomStyle to EFontHighlightLastCustomStyle).

The horizontal spacing between the characters in the text string is increased by the number of pixels specified in aExtraPixels. The standard way to do this is by calling CGraphicsContext::SetCharJustification().

The font and other graphics parameters (e.g. pen colour, font style), are specified in aParam.iGc but a character format container (aFormat) is supplied so that a different font can be used. Note that any graphics drawn cannot exceed the bounds of aParam.iDrawRect, so changes are usually restricted to drawing shadows, outlines, etc. if custom highlighting is in use.

Parameters

const TParam& aParam Contains the drawing parameters. Drawing can only occur within aParam.iDrawRect. const TLineInfo& aLineInfo Contains the line metrics. const TCharFormat& aFormat Specifies the character formatting to apply to the text, including the type of text highlighting. const TDesC& aText The text string to be drawn. const TPoint& aTextOrigin The point at which the left end of the baseline of the text should be drawn. TInt aExtraPixels The number of additional pixels to insert between the characters in the text string, in order to increase its length.

MFormCustomDraw::TParam

Description

Contains the drawing parameters used by all custom draw functions.

Defined in MFormCustomDraw::TParam:
iDrawRect, iGc, iMap, iTextLayoutTopLeft

CGraphicsContext& iGc

Description

The graphics context to use.

MGraphicsDeviceMap& iMap

Description

The graphics device map, which allows you to convert between pixels and twips and create fonts.

const TPoint& iTextLayoutTopLeft

Description

The origin for the coordinates at which the text, bitmaps and other graphics are drawn.

const TRect& iDrawRect

Description

The area to be drawn. Do not draw outside this rectangle.

MFormCustomDraw::TLineInfo

Description

Contains the line metrics.

Defined in MFormCustomDraw::TLineInfo:
iBaseline, iInnerRect, iOuterRect

const TRect& iOuterRect

Description

The bounding rectangle of the line, including margins, indents and automatic space above and below paragraphs.

const TRect& iInnerRect

Description

The bounds of the text only.

TInt iBaseline

Description

The baseline of the text.