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.

Run-time control hierarchy

How to write controls