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.