How to manipulate rich text

Creating a rich text object

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 CRichText::NewL() exist for creating rich text objects supporting paragraph styles, fields and pictures.

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

Inserting formatted text

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 document position 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.

After the text has been inserted, call CancelInsertCharFormat() to cancel the character formatting insertion command. If this is not done and text is subsequently inserted at any document position other than pos , a panic will occur.

       
        
       
       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
      

Rich text character formatting

The following code applies character formatting to existing text, preserving its format attributes.

       
        
       
       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
      

Notes

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

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

Rich text paragraph formatting

The following code demonstrates paragraph formatting in rich text by applying right alignment to a single paragraph.

Use CRichText::CharPosOfParagraph() 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.

ApplyParaFormatL() 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.

       
        
       
       // 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
      

Deleting rich text

The following code demonstrates the differences between the two functions available to delete rich text. CRichText::DeleteL() deletes a range of characters and all formatting within the range. CRichText::DelSetInsertCharFormatL() deletes text, but retains any inserted formatting.

This code deletes all text between document position 10 and the end of document using DelSetInsertCharFormatL() . 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.

Following the use of DelSetInsertCharFormatL() a panic will occur if text is inserted at any position other than position 10. This restriction persists until it is cancelled using CancelInsertCharFormat() .

       
        
       
       iRichText->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
      

To demonstrate how DeleteL() differs from DelSetInsertCharFormatL() , DeleteL() 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.

       
        
       
       iRichText->DeleteL(10,(iRichText->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!)
      

Resetting the text object

Resetting an editable text object deletes all text and formatting, leaving the end of text paragraph delimiter.

       
        
       
       iRichText->CancelInsertCharFormat();
//reset document
iRichText->Reset();
      

Before resetting a rich text object, it is advisable to clear any outstanding format insertion commands using CancelInsertCharFormat() .