How to handle changes to the text view

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.

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 CTextView::HandleRangeFormatChangeL() function.

In the following example, the code retrieves the current selection and formats it.

// Apply italics to the selected region
TCursorSelection cursorSelection;
charFormat.iFontSpec.iFontStyle.SetPosture(EPostureItalic); 
charFormatMask.SetAttrib(EAttFontPosture); // Want to set posture

When formatting text, set the attribute's value in the TCharFormat object and set the corresponding bit in the format mask.

• Use CTextView::Selection() to get the start position and length of the selected region.

• Apply character formatting to the selection using CRichText::ApplyCharFormatL().

• After reformatting text, handle changes to the layout of the document by an appropriate change handling function. CTextView::HandleRangeFormatChangeL() deals with block reformatting and redraws the view, and is the appropriate change handling function here.

cursorSelection=iTextView->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->HandleRangeFormatChangeL(cursorSelection); // reformat everything from here

• CTextView's change handling functions do not cancel an existing selection. To do so, either of two functions can be used — CancelSelectionL(), or, as demonstrated above, SetPendingSelection(). SetPendingSelection() sets the selection which should take effect after HandleRangeFormatChangeL() or HandleInsertDeleteL() 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 CancelSelectionL() in that the selected region is only drawn once, reducing the likelihood of flicker.

• 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.

To Reformat and redraw the view after inserting, deleting or replacing a block of text, use the CTextView::HandleInsertDeleteL() function.

In the following example the code inserts several lines of text into the document, followed by a paragraph delimiter.

• Before inserting a paragraph delimiter at the end of the text, use CEditableText::DocumentLength() to find the document position of the final character in the document.

• Call CTextView::HandleInsertDeleteL() to handle the block insertion and cause a redraw.

• Use an object of class TCursorSelection to indicate the start position and length of the inserted text. The second argument has a value of zero because no characters were deleted.

// 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->HandleInsertDeleteL(cursorSelection,0); // Handle insertion

To reformat and redraw the view after a global change has been made to the layout, use the CTextView::HandleGlobalChangeL() function.

In the following example, the code sets the formatted band to the part of the document displayed in the view rectangle.

TBuf<80> message;
iLayout->SetAmountToFormat(CTextLayout::EFFormatBand);
iTextView->HandleGlobalChangeL(); // Global document change 

To reformat the whole document, or just the visible text if formatting is set to the band only, use the CTextView::FormatTextL() function.

In the following example, the code inserts several lines of text, with increased height to aid visibility, then sets the formatted band.

• 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.

• Apply character formatting to the selection using CRichText::ApplyCharFormatL().

• Use CTextView::FormatTextL() to global reformat the document. Note that this function does not cause a redraw, which is appropriate here because the document contains no text.

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->FormatTextL();