Text -and Zooming

Text Style and Colour

Note that the following does -not yet apply for S60 and MOAP.

The style (plain, bold, shadowed etc.) -and colour of text in a control typically depends upon the state or properties -of its parent control. Prior to Symbian OS 9.1 a control was able to use the MCoeControlContext interface -to share properties. That interface is now deprecated. Text is now drawn using -a Text Drawer. The Text Drawer takes the text itself as a parameter along -with the font, graphics context and text location rectangle.

The text -drawer is provided by the run-time hierarchy. Each control in the hierarchy, -from the topmost downwards, has the option of modifying or replacing the text -drawer.

Text drawers are derived from CCoeTextDrawerBase (a -default CCoePlainTextDrawer is provided by Cone) and require -special use to avoid multiple allocations on the heap. Instead of being allocated -directly text drawers must be used through the XCoeTextDrawer class -which acts as a smart-pointer to a single CCoeTextDrawerBase derived -class on the heap. The smart-pointer deletes or resets the text drawer on -the heap if necessary and provides fail-safe measures to ensure that a valid -text drawer is returned.

A control that draws text calls its TextDrawer() function -to retrieve the appropriate text drawer from the run-time hierarchy

XCoeTextDrawer textDrawer( TextDrawer() ); -textDrawer->SetAlignment( iAlignment ); -textDrawer->SetMargins( iMargin ); -textDrawer->SetLineGapInPixels( iGapBetweenLines ); -textDrawer.SetClipRect( aRect ); - -textDrawer.DrawText( gc, *iTextToDraw, Rect(), *Font() ); -

Note that XCoeTextDrawer's ->() operator -is overriden to return a pointer to the CCoeTextDrawerBase object. -i.e.

- textDrawer->SetAlignment(iAlignment); -

is equivalent to

- textDrawer.(iTextDrawer*).SetAlignment(iAlignment); -

Unfortunately, as SetClipRect() is not a function -of CCoeTextDrawerBase, but of XCoeTextDrawer, -it can only be accessed through the . [dot] operator. There are worse things -in life.

A control that wishes to provide its own text drawer, or to -modify its parent's text drawer, may do so by providing its own implementation -of the virtual function GetTextDrawer().

Fonts

The control framework provides a mechanism -for delivering the correct font at run-time. The mechanism consists of a Font -Provider (CCoeFontProvider) and a TCoeFont class, -which represents a font's size (logical or absolute in pixels) and style (plain, -bold, italic, subscript or superscript). Along similar lines to the Text Drawer, -the Font Provider is attached to a parent control and serves controls further -down the run-time hierarchy.

CCoeEnv includes a -default CCoeFontProvider: UI-variant specific libraries -are expected to provide their own.

The desired font is affected by -the control's zoom state (see below) which must be included when requesting -a font from a font provider.

CCoeControl includes -a ScreenFont() method which encapsulates the font -provider and zoom APIs to provide a simple means of obtaining a CFont object -for drawing text.

The final line of the code snippet above should, -therefore, look like this:

textDrawer.DrawText(gc, *iTextToDraw, Rect(), ScreenFont(TCoeFont::NormalFont());

Controls must not keep references or pointers to CFont objects -in member data. Nor should they use the CCoeEnv functions NormalFont(), LegendFont(), TitleFont(), AnnotationFont() and DenseFont(). -Moreover, instances of these calls should be removed from old code and replaced -with code like that above. This is so that run-time font changes can be propagated -and is essential for zoom support.

Zooming

Each control may have a TZoomFactor attached. -It applies to the control itself and all of its component controls. The factor -can be absolute or relative to a control's parent and influences the size -of the font in the control and all of its children.

CCoeControl has -an AccumulatedZoom() function which aggregates its own zoom -factor with those of its parents.