Symbian3/SDK/Source/GUID-9E2AEFF3-6C6E-5F09-B5C0-A70AECB421B0-GENID-1-8-1-6-1-1-4-1-6-1-7-1-10-1.dita
changeset 7 51a74ef9ed63
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-9E2AEFF3-6C6E-5F09-B5C0-A70AECB421B0-GENID-1-8-1-6-1-1-4-1-6-1-7-1-10-1.dita	Wed Mar 31 11:11:55 2010 +0100
@@ -0,0 +1,81 @@
+<?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-GENID-1-8-1-6-1-1-4-1-6-1-7-1-10-1" xml:lang="en"><title>Text
+and Zooming</title><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section id="GUID-5E27D8F4-E5F7-4589-801A-4ADE62E9BD59-GENID-1-8-1-6-1-1-4-1-6-1-7-1-10-1-2-1"><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-GENID-1-8-1-6-1-1-4-1-6-1-7-1-10-1-2-1-7" 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-GENID-1-8-1-6-1-1-4-1-6-1-7-1-10-1-2-1-9" xml:space="preserve">
+    textDrawer-&gt;SetAlignment(iAlignment); 
+</codeblock><p>is equivalent to </p><codeblock id="GUID-7AE5D018-8EC8-55AF-BFCE-5D9B5E0A402F-GENID-1-8-1-6-1-1-4-1-6-1-7-1-10-1-2-1-11" 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-GENID-1-8-1-6-1-1-4-1-6-1-7-1-10-1-2-2"><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-GENID-1-8-1-6-1-1-4-1-6-1-7-1-10-1-2-2-7" 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-GENID-1-8-1-6-1-1-4-1-6-1-7-1-10-1-2-3"><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-GENID-1-8-1-6-1-1-4-1-6-1-7-1-10-1-2-4"><title>See also</title> <ul>
+<li><p><xref href="GUID-E244744F-4837-5B46-8E37-4666A28BF0B7-GENID-1-8-1-3-1-1-7-1-7-1-5-1.dita">Run-time control
+hierarchy</xref></p></li>
+<li><p><xref href="GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290-GENID-1-8-1-3-1-1-7-1-9-1.dita">How to write
+controls</xref></p></li>
+</ul> </section>
+</conbody></concept>
\ No newline at end of file