<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-9E2AEFF3-6C6E-5F09-B5C0-A70AECB421B0" xml:lang="en"><title>Text
and Zooming</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<section id="GUID-5E27D8F4-E5F7-4589-801A-4ADE62E9BD59"><title>Text Style and Colour</title><p>Note that the following does
not yet apply for S60 and MOAP. </p><p>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 <codeph>MCoeControlContext</codeph> 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. </p><p>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. </p><p>Text drawers are derived from <xref href="GUID-C8C7B785-B3CF-3488-AEB1-BE0A70F6C1F2.dita"><apiname>CCoeTextDrawerBase</apiname></xref> (a
default <xref href="GUID-4941BB90-573F-3582-AD7D-0769E463ECC6.dita"><apiname>CCoePlainTextDrawer</apiname></xref> 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 <xref href="GUID-2280260C-3A4F-3C1E-ADF2-3219ED7FE0DE.dita"><apiname>XCoeTextDrawer</apiname></xref> class
which acts as a smart-pointer to a single <xref href="GUID-C8C7B785-B3CF-3488-AEB1-BE0A70F6C1F2.dita"><apiname>CCoeTextDrawerBase</apiname></xref> 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. </p><p>A control that draws text calls its <codeph>TextDrawer()</codeph> function
to retrieve the appropriate text drawer from the run-time hierarchy </p><codeblock id="GUID-42C036D2-539B-51CF-94DD-594612EE7B60" xml:space="preserve">XCoeTextDrawer textDrawer( TextDrawer() );
textDrawer-&gt;SetAlignment( iAlignment ); 
textDrawer-&gt;SetMargins( iMargin );
textDrawer-&gt;SetLineGapInPixels( iGapBetweenLines );
textDrawer.SetClipRect( aRect );

textDrawer.DrawText( gc, *iTextToDraw, Rect(), *Font() );
</codeblock><p>Note that <xref href="GUID-2280260C-3A4F-3C1E-ADF2-3219ED7FE0DE.dita"><apiname>XCoeTextDrawer</apiname></xref>'s <codeph>-&gt;()</codeph> operator
is overriden to return a pointer to the <xref href="GUID-C8C7B785-B3CF-3488-AEB1-BE0A70F6C1F2.dita"><apiname>CCoeTextDrawerBase</apiname></xref> object.
i.e. </p><codeblock id="GUID-27F4D9F1-0AAF-57C5-9783-C26F4B0046ED" xml:space="preserve">
    textDrawer-&gt;SetAlignment(iAlignment); 
</codeblock><p>is equivalent to </p><codeblock id="GUID-7AE5D018-8EC8-55AF-BFCE-5D9B5E0A402F" xml:space="preserve">
    textDrawer.(iTextDrawer*).SetAlignment(iAlignment); 
</codeblock><p>Unfortunately, as <codeph>SetClipRect()</codeph> is not a function
of <xref href="GUID-C8C7B785-B3CF-3488-AEB1-BE0A70F6C1F2.dita"><apiname>CCoeTextDrawerBase</apiname></xref>, but of <xref href="GUID-2280260C-3A4F-3C1E-ADF2-3219ED7FE0DE.dita"><apiname>XCoeTextDrawer</apiname></xref>,
it can only be accessed through the . [dot] operator. There are worse things
in life. </p><p>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 <codeph>GetTextDrawer()</codeph>. </p></section>
<section id="GUID-BFE5E25F-A36C-4B33-A283-095F2E60FDBA"><title>Fonts</title><p>The control framework provides a mechanism
for delivering the correct font at run-time. The mechanism consists of a Font
Provider (<xref href="GUID-372CDE49-2148-3A21-8EA3-8D4656548C23.dita"><apiname>CCoeFontProvider</apiname></xref>) and a <xref href="GUID-463C1928-878D-3B06-ABFD-178BE1BAD776.dita"><apiname>TCoeFont</apiname></xref> 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. </p><p> <xref href="GUID-12A9389D-363B-3F54-857F-89EE0EDCDF40.dita"><apiname>CCoeEnv</apiname></xref> includes a
default <xref href="GUID-372CDE49-2148-3A21-8EA3-8D4656548C23.dita"><apiname>CCoeFontProvider</apiname></xref>: UI-variant specific libraries
are expected to provide their own. </p><p>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. </p><p> <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita"><apiname>CCoeControl</apiname></xref> includes
a <codeph>ScreenFont()         </codeph> method which encapsulates the font
provider and zoom APIs to provide a simple means of obtaining a <xref href="GUID-2A12FE3B-47F2-3016-8161-A971CA506491.dita"><apiname>CFont</apiname></xref> object
for drawing text. </p><p>The final line of the code snippet above should,
therefore, look like this: </p><codeblock id="GUID-D4C2C0E7-740B-52B2-9945-8855F4D07F45" xml:space="preserve">textDrawer.DrawText(gc, *iTextToDraw, Rect(), ScreenFont(TCoeFont::NormalFont());</codeblock><p>Controls must not keep references or pointers to <xref href="GUID-2A12FE3B-47F2-3016-8161-A971CA506491.dita"><apiname>CFont</apiname></xref> objects
in member data. Nor should they use the <xref href="GUID-12A9389D-363B-3F54-857F-89EE0EDCDF40.dita"><apiname>CCoeEnv</apiname></xref> functions <codeph>NormalFont()</codeph>, <codeph>LegendFont()</codeph>, <codeph>TitleFont()</codeph>, <codeph>AnnotationFont()</codeph> and <codeph>DenseFont()</codeph>.
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. </p></section>
<section id="GUID-881F77D3-383F-4D48-B56C-35A68B51A57B"><title>Zooming</title><p>Each control may have a <xref href="GUID-DDE4C9C0-7218-385E-B239-0DEFDE19FCCC.dita"><apiname>TZoomFactor</apiname></xref> 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. </p><p> <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita"><apiname>CCoeControl</apiname></xref> has
an <codeph>AccumulatedZoom()</codeph> function which aggregates its own zoom
factor with those of its parents. </p></section>
<section id="GUID-45183B25-33F2-4EB7-A3CB-8A6922B097F1"><title>See also</title> <ul>
<li><p><xref href="GUID-E244744F-4837-5B46-8E37-4666A28BF0B7.dita">Run-time control
hierarchy</xref></p></li>
<li><p><xref href="GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290.dita">How to write
controls</xref></p></li>
</ul> </section>
</conbody></concept>