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