<?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 xml:lang="en" id="GUID-74E69324-7BCC-591F-B2A9-2932A3790966"><title>How to manipulate simple global text</title><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Creating a global text object</title> <p>A <keyword>global text object</keyword> has global <keyword>paragraph</keyword> and <keyword>character</keyword> formatting. Its formatting is stored in a paragraph and a character <keyword>format layer</keyword>. To create a global text object, you need to create these layers, and pass them as parameters to the <xref href="GUID-4F502FE5-44D4-3947-9D73-67EF4886059A.dita"><apiname>CGlobalText</apiname></xref> constructor:</p> <codeblock id="GUID-751BE38C-5DF2-544C-8D5B-3E62F081A212" xml:space="preserve">CGlobalText* iglobalText; // global text document

CParaFormatLayer* iparaFormatLayer;

CCharFormatLayer* icharFormatLayer; 

iparaFormatLayer=CParaFormatLayer::NewL(); // required para format

icharFormatLayer=CCharFormatLayer::NewL(); // required char format

iglobalText=CGlobalText::NewL(iparaFormatLayer, icharFormatLayer);</codeblock> <p><b>Notes</b> </p> <ul><li id="GUID-EC58C950-BAAA-5F3E-92A4-0331872048C9"><p>The code above constructs a global text object which uses default paragraph and character formatting.</p> </li> <li id="GUID-4239E00E-221A-5B14-8630-02629AA17B60"><p>Rich text is formatted in exactly the same way as global text, except that the length and position arguments now are relevant and must specify a valid range of characters. Only characters in the range specified are affected.</p> </li> <li id="GUID-E35FC190-0D69-5E43-9041-3243FE20DD8A"><p>The global text object does <i>not</i> take on ownership of these <keyword>format layers</keyword>. This allows several global text objects to share the same format layers. Therefore, if you have only a single global text object, you must destroy not only it, but the format layers also:</p> </li> </ul> <codeblock id="GUID-EB55D07F-3A79-5372-B25A-418FF0F7F55C" xml:space="preserve">delete iglobalText; // delete contained document

delete icharFormatLayer; // delete char format layer

delete iparaFormatLayer; // and para format layer</codeblock> <p>If you had several global text objects sharing the same format layers, you would destroy the format layers only after all the text objects had been destroyed.</p> </section> <section><title>Inserting text and paragraphs</title> <p>Text may be inserted using <codeph>InsertL()</codeph>, specifying a <keyword>document position</keyword> and the text to insert.</p> <codeblock id="GUID-B5A979D1-D93E-5CB1-93C3-1B234A413335" xml:space="preserve">iGlobalText-&gt;InsertL(0,_L("Hello!"));

iGlobalText->InsertL(5,_L(" World"));

iGlobalText->InsertL(12,CEditableText::EParagraphDelimiter);

    // insert paragraph marker

iGlobalText->InsertL(13,_L("And hello again!"));

    // insert text to follow this marker</codeblock> <p><b>Note</b> </p> <ul><li id="GUID-BE90B234-2B52-5ECC-9280-6898304CDB6C"><p>The code inserts two character strings into the text at document positions 0 and 5. Position 5 is the position between the fifth and sixth characters. A new <keyword>paragraph delimiter</keyword> and some more text is then inserted.</p> </li> </ul> </section> <section><title>Extracting information and text</title> <p>The following example code extracts information about a text object and about a word within the text object and reads the word at a document position. The status message <codeph>iMessage</codeph> (a <codeph>TBuf&lt;80&gt;</codeph>) is used to display the number of <keyword>characters</keyword>, <keyword>words</keyword> and <keyword>paragraphs</keyword> in the global text object.</p> <p><codeph>ParagraphCount()</codeph> always returns a count of at least one due to the existence of the terminating <keyword>paragraph

  delimiter</keyword> at the end of every text object.</p> <codeblock id="GUID-5EE64712-1E94-536E-B590-3F855087EF92" xml:space="preserve">iMessage.Format(_L("chars=%d, words=%d, paras=%d"),

iGlobalText->DocumentLength(),

        // length up to and excluding final para mark

iGlobalText->WordCount(), // white-space delimited words

iGlobalText-&gt;ParagraphCount()); // paras including the final one</codeblock> <p>In the following example information about the word containing the character at a specified document position, and the word itself, are extracted and printed.</p> <p><codeph>CGlobalText::GetWordInfo()</codeph> is used to extract information about a word and <codeph>CGlobalText::Read()</codeph> to obtain a read-only pointer to the word. </p> <codeblock id="GUID-DAB7E1DD-8F18-5125-BE1D-324FB3CD353F" xml:space="preserve">TInt pos=65; // Choose an arbitrary document position

TInt startPos, length; // results of function

iGlobalText->GetWordInfo(pos,startPos,length,EFalse,ETrue);

// Read length (the length of the word at position pos) number of 

// characters beginning at startPos (start of word at pos). 

TPtrC pointer=iGlobalText->Read(startPos,length);

// Print word and word info

iMessage.Format(_L("Word at pos %d (\"%S\") has"

        " %d characters, starts at position %d"),

            pos, &amp;pointer, length, startPos);</codeblock> <codeblock id="GUID-DB34A490-10EE-59C1-81DB-974C319493A0" xml:space="preserve">// insert huge amounts of text

...</codeblock> </section> <section><title>Using fields</title> <p>Before any field, apart from the page number field in a<keyword>header</keyword> or <keyword>footer</keyword>, can be inserted into a document, a field factory must be declared. A field factory is a class which derives from the <xref href="GUID-6202B0B7-663C-3172-BE13-88D77081B42C.dita"><apiname>MTextFieldFactory</apiname></xref> class, and which defines a <xref href="GUID-6202B0B7-663C-3172-BE13-88D77081B42C.dita#GUID-6202B0B7-663C-3172-BE13-88D77081B42C/GUID-0391FC8A-9206-3118-A057-5549E49D2309"><apiname>MTextFieldFactory::NewFieldL()</apiname></xref> function. The function constructs new fields according to a<keyword>UID</keyword> passed into the function.</p> <p> The steps involved before the field factory can be used to create and insert a field are as follwows</p> <ol id="GUID-FFE9F7BC-A4A1-5B27-BA07-FE2985F9BEF1"><li id="GUID-7232879E-58FF-50F7-8E40-5BEC68193FC1"><p>Instantiate a field factory. </p> </li> <li id="GUID-EF54FC5C-F23D-5E84-A2E9-72239B96FF08"><p>Set that factory to be the text object's field factory</p> </li> <li id="GUID-5B5CF95A-5280-5E80-AAD0-FCFD0343944C"><p>Construct a field using <codeph>CPlainText::NewTextFieldL()</codeph> </p> </li> <li id="GUID-E9F3EFAD-5307-5E6D-BA91-5653ED4537DF"><p>If, for example, a date/time field is to be inserted, format it as required. By default, the date/time is formatted as dd/mm/yyyy. </p> </li> <li id="GUID-65F09753-B14B-5F7E-97F8-8D873ED8C7CE"><p>Insert the field at the desired document position</p> </li> <li id="GUID-851024F4-E31D-5020-92D1-22DE1685EAA0"><p>Update the field. Until this is done, no field text will be visible. Also, care must be taken that the field length is not greater than 20 characters (the maximum field length), otherwise <codeph>UpdateFieldL()</codeph> will panic. The first time the field is updated, the position specified must be the position at which the field was inserted. Subsequent updates may specify any position within the field.</p> </li> <li id="GUID-C451C955-CDEB-5940-9D9D-182E1F33545C"><p><xref href="GUID-ED1FFBC5-23C3-3C9E-B5D1-04B72B9369E6.dita#GUID-ED1FFBC5-23C3-3C9E-B5D1-04B72B9369E6/GUID-DAC0984B-2AE1-3BE0-A76B-7226D162D709"><apiname>CPlainText::FindFields()</apiname></xref> may be used to get information about a field, including its start position and length.</p> </li> </ol> </section> <section><title>Paragraph formatting</title> <p>The following code centre aligns the text. Alignment is a<keyword>paragraph format attribute</keyword> and is a member of the <xref href="GUID-2F795E02-0704-39AE-8EC6-06CB5D5D670F.dita"><apiname>CParaFormat</apiname></xref> class. All paragraph format attributes which are not explicitly set are taken from the system-provided default settings. </p> <p>Use <xref href="GUID-4F502FE5-44D4-3947-9D73-67EF4886059A.dita#GUID-4F502FE5-44D4-3947-9D73-67EF4886059A/GUID-E5B80F41-D2A1-322D-85F7-8C016F2F9519"><apiname>CGlobalText::ApplyParaFormatL()</apiname></xref> to globally change the paragraph formatting. In this example, the position and the length arguments are redundant because the formatting is applied globally. However, they must be specified, although their values are irrelevant. </p> <p>To set or clear paragraph format attributes, use a<xref href="GUID-C4220B5C-1037-342E-A409-B62F0429E7F2.dita"><apiname>TParaFormatMask</apiname></xref> in conjunction with an object of class<codeph>CParaFormat</codeph>. The attributes specified in the mask are set according to the corresponding value contained in <codeph>CParaFormat</codeph>. Any attributes not specified in the mask are unaffected.</p> <codeblock id="GUID-2D7DCFFC-70AE-599E-AF13-B7D800080905" xml:space="preserve">CParaFormat* paraFormat=CParaFormat::NewLC();

TParaFormatMask paraFormatMask; 

paraFormat->iHorizontalAlignment=CParaFormat::ECenterAlign; 

        // set centered

paraFormatMask.SetAttrib(EAttAlignment); // interested in alignment

iglobalText->ApplyParaFormatL(paraFormat,paraFormatMask,0,0);

        // apply format under mask - pos and length irrelevant

CleanupStack::PopAndDestroy();  // paraFormat </codeblock> <p><b>Note</b> </p> <ul><li id="GUID-327FE937-FB69-58EF-9032-71DDBCF913E6"><p>An alternative method to using <codeph>ApplyParaFormatL()</codeph> for global text is to directly set the formatting of the global <keyword>paragraph

format layer</keyword> upon which the object's paragraph formatting is based. This may be done by using either <xref href="GUID-C5A6B3D4-1BDE-35B4-AC6B-DF517A4D4147.dita#GUID-C5A6B3D4-1BDE-35B4-AC6B-DF517A4D4147/GUID-25234E88-E9B8-399D-8279-0B74EBF01746"><apiname>CParaFormatLayer::SetL()</apiname></xref>, to reset the formatting of the existing layer, or<xref href="GUID-4F502FE5-44D4-3947-9D73-67EF4886059A.dita#GUID-4F502FE5-44D4-3947-9D73-67EF4886059A/GUID-A0FE0C07-EF67-3C70-9FF7-AECAC66B2F0D"><apiname>CGlobalText::SetGlobalParaFormat()</apiname></xref> which sets a new layer. Both methods cause all attributes to be reset; no mask is specified.</p> </li> </ul> </section> <section><title>Character formatting</title> <p>The following code globally sets the bold, italic and underline<keyword>character format attributes</keyword>. These attributes are accessed through the <codeph>iFontPresentation</codeph> and<codeph>iFontStyle</codeph> members of the <xref href="GUID-3518B92C-D1BD-36D1-B447-728A1052292F.dita"><apiname>TCharFormat</apiname></xref> class. Any attributes not explicitly set are taken from the system-provided default settings. </p> <p>Global character formatting is applied in a similar manner to paragraph formatting, using a <xref href="GUID-4FD3211A-DFF8-3487-8DFF-5C7F2EF3997D.dita"><apiname>TCharFormatMask</apiname></xref> in conjunction with a<codeph>TCharFormat</codeph>, then calling<codeph>CGlobalText::ApplyCharFormatL()</codeph>.</p> <codeblock id="GUID-0E31A055-55A4-5806-9B9A-62AD53E78C6E" xml:space="preserve">charFormatMask.SetAttrib(EAttFontUnderline); // set underline

charFormatMask.SetAttrib(EAttFontPosture); // and posture (for italic)

charFormatMask.SetAttrib(EAttFontStrokeWeight); // and weight (for 

    // bold)

charFormat.iFontPresentation.iUnderline=EUnderlineOn;

charFormat.iFontSpec.iFontStyle.SetPosture(EPostureItalic);

charFormat.iFontSpec.iFontStyle.SetStrokeWeight(EStrokeWeightBold);

// apply format under mask

iGlobalText-&gt;ApplyCharFormatL(charFormat,charFormatMask,0,0);</codeblock> <p><b>Note</b> </p> <ul><li id="GUID-DF042F94-88C1-5F1C-B21A-17DF58EEBCD4"><p>No more than one attribute can be specified in the argument to<xref href="GUID-4FD3211A-DFF8-3487-8DFF-5C7F2EF3997D.dita#GUID-4FD3211A-DFF8-3487-8DFF-5C7F2EF3997D/GUID-B110FDDE-1E2C-3969-8E9E-A8FC8633932E"><apiname>TCharFormatMask::SetAttrib()</apiname></xref>. To set more than one attribute in a single call to <codeph>ApplyCharFormatL()</codeph>, either use several calls to<codeph>SetAttrib()</codeph>, as above, or use<xref href="GUID-4FD3211A-DFF8-3487-8DFF-5C7F2EF3997D.dita#GUID-4FD3211A-DFF8-3487-8DFF-5C7F2EF3997D/GUID-CAFA619F-81A3-337B-9EE0-E27152F2BDBE"><apiname>TCharFormatMask::SetAll()</apiname></xref> to set all attributes in the mask.</p> </li> </ul> </section> </conbody></concept>