|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-9E2AEFF3-6C6E-5F09-B5C0-A70AECB421B0" xml:lang="en"><title>Text |
|
13 and Zooming</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <section id="GUID-5E27D8F4-E5F7-4589-801A-4ADE62E9BD59"><title>Text Style and Colour</title><p>Note that the following does |
|
15 not yet apply for S60 and MOAP. </p><p>The style (plain, bold, shadowed etc.) |
|
16 and colour of text in a control typically depends upon the state or properties |
|
17 of its parent control. Prior to Symbian OS 9.1 a control was able to use the <codeph>MCoeControlContext</codeph> interface |
|
18 to share properties. That interface is now deprecated. Text is now drawn using |
|
19 a Text Drawer. The Text Drawer takes the text itself as a parameter along |
|
20 with the font, graphics context and text location rectangle. </p><p>The text |
|
21 drawer is provided by the run-time hierarchy. Each control in the hierarchy, |
|
22 from the topmost downwards, has the option of modifying or replacing the text |
|
23 drawer. </p><p>Text drawers are derived from <xref href="GUID-C8C7B785-B3CF-3488-AEB1-BE0A70F6C1F2.dita"><apiname>CCoeTextDrawerBase</apiname></xref> (a |
|
24 default <xref href="GUID-4941BB90-573F-3582-AD7D-0769E463ECC6.dita"><apiname>CCoePlainTextDrawer</apiname></xref> is provided by Cone) and require |
|
25 special use to avoid multiple allocations on the heap. Instead of being allocated |
|
26 directly text drawers must be used through the <xref href="GUID-2280260C-3A4F-3C1E-ADF2-3219ED7FE0DE.dita"><apiname>XCoeTextDrawer</apiname></xref> class |
|
27 which acts as a smart-pointer to a single <xref href="GUID-C8C7B785-B3CF-3488-AEB1-BE0A70F6C1F2.dita"><apiname>CCoeTextDrawerBase</apiname></xref> derived |
|
28 class on the heap. The smart-pointer deletes or resets the text drawer on |
|
29 the heap if necessary and provides fail-safe measures to ensure that a valid |
|
30 text drawer is returned. </p><p>A control that draws text calls its <codeph>TextDrawer()</codeph> function |
|
31 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() ); |
|
32 textDrawer->SetAlignment( iAlignment ); |
|
33 textDrawer->SetMargins( iMargin ); |
|
34 textDrawer->SetLineGapInPixels( iGapBetweenLines ); |
|
35 textDrawer.SetClipRect( aRect ); |
|
36 |
|
37 textDrawer.DrawText( gc, *iTextToDraw, Rect(), *Font() ); |
|
38 </codeblock><p>Note that <xref href="GUID-2280260C-3A4F-3C1E-ADF2-3219ED7FE0DE.dita"><apiname>XCoeTextDrawer</apiname></xref>'s <codeph>->()</codeph> operator |
|
39 is overriden to return a pointer to the <xref href="GUID-C8C7B785-B3CF-3488-AEB1-BE0A70F6C1F2.dita"><apiname>CCoeTextDrawerBase</apiname></xref> object. |
|
40 i.e. </p><codeblock id="GUID-27F4D9F1-0AAF-57C5-9783-C26F4B0046ED" xml:space="preserve"> |
|
41 textDrawer->SetAlignment(iAlignment); |
|
42 </codeblock><p>is equivalent to </p><codeblock id="GUID-7AE5D018-8EC8-55AF-BFCE-5D9B5E0A402F" xml:space="preserve"> |
|
43 textDrawer.(iTextDrawer*).SetAlignment(iAlignment); |
|
44 </codeblock><p>Unfortunately, as <codeph>SetClipRect()</codeph> is not a function |
|
45 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>, |
|
46 it can only be accessed through the . [dot] operator. There are worse things |
|
47 in life. </p><p>A control that wishes to provide its own text drawer, or to |
|
48 modify its parent's text drawer, may do so by providing its own implementation |
|
49 of the virtual function <codeph>GetTextDrawer()</codeph>. </p></section> |
|
50 <section id="GUID-BFE5E25F-A36C-4B33-A283-095F2E60FDBA"><title>Fonts</title><p>The control framework provides a mechanism |
|
51 for delivering the correct font at run-time. The mechanism consists of a Font |
|
52 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, |
|
53 which represents a font's size (logical or absolute in pixels) and style (plain, |
|
54 bold, italic, subscript or superscript). Along similar lines to the Text Drawer, |
|
55 the Font Provider is attached to a parent control and serves controls further |
|
56 down the run-time hierarchy. </p><p> <xref href="GUID-12A9389D-363B-3F54-857F-89EE0EDCDF40.dita"><apiname>CCoeEnv</apiname></xref> includes a |
|
57 default <xref href="GUID-372CDE49-2148-3A21-8EA3-8D4656548C23.dita"><apiname>CCoeFontProvider</apiname></xref>: UI-variant specific libraries |
|
58 are expected to provide their own. </p><p>The desired font is affected by |
|
59 the control's zoom state (see below) which must be included when requesting |
|
60 a font from a font provider. </p><p> <xref href="GUID-B06F99BD-F032-3B87-AB26-5DD6EBE8C160.dita"><apiname>CCoeControl</apiname></xref> includes |
|
61 a <codeph>ScreenFont() </codeph> method which encapsulates the font |
|
62 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 |
|
63 for drawing text. </p><p>The final line of the code snippet above should, |
|
64 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 |
|
65 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>. |
|
66 Moreover, instances of these calls should be removed from old code and replaced |
|
67 with code like that above. This is so that run-time font changes can be propagated |
|
68 and is essential for zoom support. </p></section> |
|
69 <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. |
|
70 It applies to the control itself and all of its component controls. The factor |
|
71 can be absolute or relative to a control's parent and influences the size |
|
72 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 |
|
73 an <codeph>AccumulatedZoom()</codeph> function which aggregates its own zoom |
|
74 factor with those of its parents. </p></section> |
|
75 <section id="GUID-45183B25-33F2-4EB7-A3CB-8A6922B097F1"><title>See also</title> <ul> |
|
76 <li><p><xref href="GUID-E244744F-4837-5B46-8E37-4666A28BF0B7.dita">Run-time control |
|
77 hierarchy</xref></p></li> |
|
78 <li><p><xref href="GUID-B84FA223-3DFD-58C5-8CEF-C5AA73AA6290.dita">How to write |
|
79 controls</xref></p></li> |
|
80 </ul> </section> |
|
81 </conbody></concept> |