<?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-9761C39D-30E9-5BFA-ABF0-2C2377E3EADB"><title>How to manipulate rich text</title><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Creating a rich text object</title> <p>Like global text, when a rich text object is constructed, the character and paragraph format layers upon which the rich text object's formatting is based (the "global" layers) must be specified. Here, their formatting is taken from the system-provided default settings. Other variants of <codeph>CRichText::NewL()</codeph> exist for creating rich text objects supporting paragraph styles, fields and pictures.</p> <codeblock id="GUID-77627DFF-30BC-55B5-B732-30BF88C5A7F7" xml:space="preserve">CRichText* iRichText; // rich text document

CParaFormatLayer* iParaFormatLayer;// global paragraph format layer

CCharFormatLayer* iCharFormatLayer;// global character format layer

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

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

iRichText=CRichText::NewL(iParaFormatLayer, iCharFormatLayer);</codeblock> </section> <section><title>Inserting formatted text</title> <p>In the following example, some text is inserted into the text object using the default character and paragraph formatting. Then an italicised text string is inserted at the <keyword>document position</keyword> between the fifth and sixth characters. In rich text, character formatting may be applied to any portion of the rich text object, from a single character to the entire document.</p> <p>After the text has been inserted, call <codeph>CancelInsertCharFormat()</codeph> to cancel the character formatting insertion command. If this is not done and text is subsequently inserted at any document position other than <codeph>pos</codeph>, a panic will occur.</p> <codeblock id="GUID-0E88E743-B8CE-5CFA-93D4-1C1E85F4EB7A" xml:space="preserve">TInt pos=0; // will be insertion position

// insert some rich text

iRichText->InsertL(pos,_L("Hello world!"));

// insert text with different formatting from rest of paragraph

charFormatMask.SetAttrib(EAttFontPosture); // interested in posture

charFormat.iFontSpec.iFontStyle.SetPosture(EPostureItalic); 

pos=5; 

iRichText->SetInsertCharFormatL(charFormat, charFormatMask,pos);

        // set formatting, when inserting at this position

iRichText->InsertL(pos,_L(" all the"));

iRichText->CancelInsertCharFormat();

        // cancel is necessary before inserting anywhere else</codeblock> </section> <section><title>Rich text character formatting</title> <p>The following code applies character formatting to existing text, preserving its format attributes.</p> <codeblock id="GUID-B0E7B745-8D76-5C4D-A58B-E2EFF31D4C64" xml:space="preserve">charFormatMask.SetAttrib(EAttFontUnderline); 

    // interested in underline

charFormat.iFontPresentation.iUnderline=EUnderlineOn; // set it on

iRichText->ApplyCharFormatL(charFormat, charFormatMask,10,9);

    // apply this character formatting, from position 10,9 characters</codeblock> <p><b>Notes</b> </p> <ul><li id="GUID-B04F5523-8FBF-5A7F-9751-6E56A28AE099"><p>The above code applies underlining to the substring "the world" whose existing formatting is a mixture of italics and normal. The string's existing formatting is preserved, with underline added as an additional format layer. </p> </li> <li id="GUID-B7B10D19-1E87-5E61-AC14-C6BED9C64041"><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> </ul> </section> <section><title>Rich text paragraph formatting</title> <p>The following code demonstrates paragraph formatting in rich text by applying right alignment to a single paragraph.</p> <p>Use <codeph>CRichText::CharPosOfParagraph()</codeph> to find the document position of the first character in the second paragraph. The second argument to this function is the offset number of the paragraph so that. paragraph number 1 indicates the second paragraph. Note that when applying paragraph formatting, any character position within the paragraph is equally valid.</p> <p><codeph>ApplyParaFormatL()</codeph> applies formatting to all paragraphs containing one or more characters in the range covered by the third and fourth arguments. In this case, a single character is specified and this is sufficient to apply paragraph formatting to the entire second paragraph.</p> <codeblock id="GUID-0AED5210-B510-58D5-ADD0-D9F1B803587D" xml:space="preserve">// Insert two new paragraphs 

...

...

// make second para right-aligned (para numbering starts at 0)

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

paraFormat->iHorizontalAlignment=CParaFormat::ERightAlign; 

    // right-align

pos=iRichText->CharPosOfParagraph(1,1); // get start of second para

iRichText->ApplyParaFormatL(paraFormat,paraFormatMask,pos,1);

    // apply format to entire para - even length = 1 char will do</codeblock> </section> <section><title>Deleting rich text</title> <p>The following code demonstrates the differences between the two functions available to delete rich text. <codeph>CRichText::DeleteL()</codeph> deletes a range of characters and all formatting within the range.<codeph>CRichText::DelSetInsertCharFormatL()</codeph> deletes text, but retains any inserted formatting. </p> <p>This code deletes all text between document position 10 and the end of document using <codeph>DelSetInsertCharFormatL()</codeph>. The underline attribute which was previously set at document position 10 is retained, so that the new text inserted at position 10 is italicized and underlined.</p> <p>Following the use of <codeph>DelSetInsertCharFormatL()</codeph> a panic will occur if text is inserted at any position other than position 10. This restriction persists until it is cancelled using <codeph>CancelInsertCharFormat()</codeph>.</p> <codeblock id="GUID-BCB62569-8907-5447-86A5-F3843E212698" xml:space="preserve">iRichText-&gt;DelSetInsertCharFormatL

        (10,(iRichText->DocumentLength()-10));

iRichText->InsertL(10,_L("Text deleted, formatting preserved"));

        // ... and then insert text with same format

iRichText->CancelInsertCharFormat(); 

    // must cancel before inserting elsewhere</codeblock> <p>To demonstrate how <codeph>DeleteL()</codeph> differs from<codeph>DelSetInsertCharFormatL()</codeph>, <codeph>DeleteL()</codeph> is used below to delete both the text commencing at document position 10 and the formatting inserted at that position. Only format attributes which apply to position 9 are inherited by the text subsequently inserted at position 10, so the inserted text is italicised but not underlined.</p> <codeblock id="GUID-B95EAF2C-732D-5040-B4B3-9EF8A1C57C81" xml:space="preserve">iRichText-&gt;DeleteL(10,(iRichText-&gt;DocumentLength()-10));

// ... then insert new text at that point

iRichText->InsertL(10,_L("Text and its formatting deleted"));

    // insert, inheriting current formatting from char before 10

    // (no need to cancel anything!)</codeblock> </section> <section><title>Resetting the text object</title> <p>Resetting an editable text object deletes all text and formatting, leaving the end of text paragraph delimiter.</p> <codeblock id="GUID-D790227B-D4FB-5304-A15C-24C9CC736480" xml:space="preserve">iRichText-&gt;CancelInsertCharFormat();

//reset document

iRichText-&gt;Reset();</codeblock> <p>Before resetting a rich text object, it is advisable to clear any outstanding format insertion commands using <codeph>CancelInsertCharFormat()</codeph>.</p> </section> </conbody></concept>