<?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-E9E26499-1102-578E-93F6-A8E14181A25C"><title>How to handle changes to the text view</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>After a change has been made to the text layout, a reformat and redraw should normally take place, otherwise a panic will occur, as the text view needs to be kept up to date with changes to the text content. The following examples demonstrate which handling functions should be used to carry out the necessary reformatting.</p> <section><title>Reformatting and redrawing after changes to the formatting of a block of text. </title> <p> To reformat either from the start of the line or the start of the paragraph containing the cursor position and redraw the view, after changes to the formatting of a block of text, use the <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita#GUID-CF377A98-F11F-380F-AD10-7F3E261D4421/GUID-00FEB3AA-E153-35BE-9BF2-05A8269C1780"><apiname>CTextView::HandleRangeFormatChangeL()</apiname></xref> function.</p> <p>In the following example, the code retrieves the current selection and formats it. </p> <codeblock id="GUID-42FFE4EF-2BEF-5AA2-A373-C5A9D494DA13" xml:space="preserve">// Apply italics to the selected region

TCursorSelection cursorSelection;

charFormat.iFontSpec.iFontStyle.SetPosture(EPostureItalic); 

charFormatMask.SetAttrib(EAttFontPosture); // Want to set posture</codeblock> <p>When formatting text, set the attribute's value in the <xref href="GUID-3518B92C-D1BD-36D1-B447-728A1052292F.dita"><apiname>TCharFormat</apiname></xref> object and set the corresponding bit in the format mask.</p> <ul><li id="GUID-62AF121F-3BC4-5874-8351-578E687C5ED9"><p>Use <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita#GUID-CF377A98-F11F-380F-AD10-7F3E261D4421/GUID-E5F8E21C-20B3-3095-BB04-56C5401B674D"><apiname>CTextView::Selection()</apiname></xref> to get the start position and length of the selected region.</p> </li> <li id="GUID-6092691E-80AB-5E48-B3A5-260762848D16"><p>Apply character formatting to the selection using <xref href="GUID-39945DA4-B362-3DF6-BF9E-DD079EEA7934.dita#GUID-39945DA4-B362-3DF6-BF9E-DD079EEA7934/GUID-3E10E796-78C1-31FB-BDF4-5EDA2B36B20B"><apiname>CRichText::ApplyCharFormatL()</apiname></xref>.</p> </li> <li id="GUID-0C61B3B0-9839-5F27-B1ED-D511D3D8AB6D"><p>After reformatting text, handle changes to the layout of the document by an appropriate change handling function. <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita#GUID-CF377A98-F11F-380F-AD10-7F3E261D4421/GUID-00FEB3AA-E153-35BE-9BF2-05A8269C1780"><apiname>CTextView::HandleRangeFormatChangeL()</apiname></xref> deals with block reformatting and redraws the view, and is the appropriate change handling function here.</p> </li> </ul> <codeblock id="GUID-A129080C-9828-5B99-A48E-F3B07E1305FD" xml:space="preserve">cursorSelection=iTextView-&gt;Selection(); // get limits of selection

TInt lowerPos=cursorSelection.LowerPos();

TInt length=cursorSelection.Length();

// Apply format to selected region

iRichText->ApplyCharFormatL(charFormat,charFormatMask,lowerPos,length);

// Ensure selection is cancelled after reformatting

TInt cursorPos=cursorSelection.iCursorPos; // Get new cursor position

// Set pending selection of length zero

TCursorSelection pendingSelection(cursorPos,cursorPos);

// Zero length selection, beginning and ending at new cursor position

iTextView->SetPendingSelection(pendingSelection);

        // Cancels selection after reformatting complete 

iTextView-&gt;HandleRangeFormatChangeL(cursorSelection); // reformat everything from here</codeblock> <p><b>Notes</b> </p> <ul><li id="GUID-A1E0FEB8-C5B3-5B09-84C2-4B79BC1E9F04"><p><codeph>CTextView</codeph>'s change handling functions do not cancel an existing selection. To do so, either of two functions can be used — <codeph>CancelSelectionL()</codeph>, or, as demonstrated above, <codeph>SetPendingSelection()</codeph>. <codeph>SetPendingSelection()</codeph> sets the selection which should take effect after <codeph>HandleRangeFormatChangeL()</codeph> or <codeph>HandleInsertDeleteL()</codeph> has returned. If the selection's anchor and cursor positions are set to the new cursor position, this has the effect of cancelling any selection. This method has the advantage over calling <codeph>CancelSelectionL()</codeph> in that the selected region is only drawn once, reducing the likelihood of flicker.</p> </li> <li id="GUID-630CD46C-1615-537D-8229-1852EA8AAC6C"><p>Formatting can either be applied to the entire document (the default), or just to the visible part of it (the band). Setting the formatting to the band may be desirable when the document has expanded over a certain size. </p> </li> </ul> </section> <section><title>Reformatting and redrawing after inserting, deleting or replacing text</title> <p>To Reformat and redraw the view after inserting, deleting or replacing a block of text, use the <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita#GUID-CF377A98-F11F-380F-AD10-7F3E261D4421/GUID-44D29E1D-3FBF-374E-AE3F-A6CA98A044F1"><apiname>CTextView::HandleInsertDeleteL()</apiname></xref> function.</p> <p>In the following example the code inserts several lines of text into the document, followed by a paragraph delimiter.</p> <ul><li id="GUID-989A336F-1E0B-5E9C-831A-5F1283C6B18D"><p>Before inserting a paragraph delimiter at the end of the text, use <xref href="GUID-49DBB305-A043-3D23-AC33-6E5C8ABAD1EE.dita#GUID-49DBB305-A043-3D23-AC33-6E5C8ABAD1EE/GUID-2445FFDF-E85C-3AA8-9776-BF349F6D8436"><apiname>CEditableText::DocumentLength()</apiname></xref> to find the document position of the final character in the document.</p> </li> <li id="GUID-13A1E9E3-194C-5AD8-832E-05D9C2FE3291"><p>Call <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita#GUID-CF377A98-F11F-380F-AD10-7F3E261D4421/GUID-44D29E1D-3FBF-374E-AE3F-A6CA98A044F1"><apiname>CTextView::HandleInsertDeleteL()</apiname></xref> to handle the block insertion and cause a redraw.</p> </li> <li id="GUID-05D2B596-3760-569B-A128-91FC90934285"><p>Use an object of class <xref href="GUID-E2ED2E4B-C428-355D-84CC-A4FA0ED50B74.dita"><apiname>TCursorSelection</apiname></xref> to indicate the start position and length of the inserted text. The second argument has a value of zero because no characters were deleted.</p> </li> </ul> <codeblock id="GUID-6D026081-0D3A-5CAE-8F84-09F45816F0DF" xml:space="preserve">// Insert lots of text

iRichText->InsertL(iRichText->DocumentLength(),_L(

    "To be, or not to be, that is the question "

    ...

    ..."));

iRichText->InsertL(iRichText->DocumentLength(),

    CEditableText::EParagraphDelimiter); // end para

TCursorSelection cursorSelection(0,iRichText->DocumentLength());

iTextView-&gt;HandleInsertDeleteL(cursorSelection,0); // Handle insertion</codeblock> </section> <section><title>Reformatting and redrawing after a global change</title> <p>To reformat and redraw the view after a global change has been made to the layout, use the <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita#GUID-CF377A98-F11F-380F-AD10-7F3E261D4421/GUID-903D1087-42CB-32EB-8379-7B019936AD16"><apiname>CTextView::HandleGlobalChangeL()</apiname></xref> function. </p> <p>In the following example, the code sets the <keyword>formatted

        band</keyword> to the part of the document displayed in the view rectangle. </p> <codeblock id="GUID-0ECA95FD-410F-5B94-9DDB-E5D0C5D97EE1" xml:space="preserve">TBuf&lt;80&gt; message;

iLayout->SetAmountToFormat(CTextLayout::EFFormatBand);

iTextView-&gt;HandleGlobalChangeL(); // Global document change </codeblock> </section> <section><title>Reformatting the whole document or visible text</title> <p>To reformat the whole document, or just the visible text if formatting is set to the band only, use the <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita#GUID-CF377A98-F11F-380F-AD10-7F3E261D4421/GUID-7A878B50-A9AF-3D54-8035-1DF4FE819454"><apiname>CTextView::FormatTextL()</apiname></xref> function. </p> <p>In the following example, the code inserts several lines of text, with increased height to aid visibility, then sets the <keyword>formatted

        band</keyword>.</p> <ul><li id="GUID-721E9015-0F7E-59AD-980C-9CB5878AB544"><p>The following code sets the font height to 200 twips and ensures that this height will be applied to all text subsequently inserted. All other character and paragraph formatting is taken from the system-provided default settings. </p> </li> <li id="GUID-345B17D2-381D-5049-968F-EE5DF872801C"><p>Apply character formatting to the selection using <xref href="GUID-39945DA4-B362-3DF6-BF9E-DD079EEA7934.dita#GUID-39945DA4-B362-3DF6-BF9E-DD079EEA7934/GUID-3E10E796-78C1-31FB-BDF4-5EDA2B36B20B"><apiname>CRichText::ApplyCharFormatL()</apiname></xref>.</p> </li> <li id="GUID-CB155905-65EE-51B8-9627-98D120590E27"><p>Use <xref href="GUID-CF377A98-F11F-380F-AD10-7F3E261D4421.dita#GUID-CF377A98-F11F-380F-AD10-7F3E261D4421/GUID-7A878B50-A9AF-3D54-8035-1DF4FE819454"><apiname>CTextView::FormatTextL()</apiname></xref> to global reformat the document. Note that this function does not cause a redraw, which is appropriate here because the document contains no text.</p> </li> </ul> <codeblock id="GUID-096F32AB-1F09-55F9-9511-D41DC8FCBE56" xml:space="preserve">TCharFormat charFormat;

TCharFormatMask charFormatMask;

charFormatMask.SetAttrib(EAttFontHeight); // want to set height to 10 point (200 twips)

charFormat.iFontSpec.iHeight=200;    

iRichText->ApplyCharFormatL(charFormat,charFormatMask,0,1);

    // apply format from position 0, for 1 character

iTextView-&gt;FormatTextL();</codeblock> </section> </conbody></concept>