<?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->SetAlignment( iAlignment ); 

textDrawer->SetMargins( iMargin );

textDrawer->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->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>