How to manipulate simple global text

A global text object has global paragraph and character formatting. Its formatting is stored in a paragraph and a character format layer. To create a global text object, you need to create these layers, and pass them as parameters to the CGlobalText constructor:

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

• The code above constructs a global text object which uses default paragraph and character formatting.

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

• The global text object does not take on ownership of these format layers. 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:

delete iglobalText; // delete contained document
delete icharFormatLayer; // delete char format layer
delete iparaFormatLayer; // and para format layer

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.

Text may be inserted using InsertL(), specifying a document position and the text to insert.

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

• 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 paragraph delimiter and some more text is then inserted.

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 iMessage (a TBuf<80>) is used to display the number of characters, words and paragraphs in the global text object.

ParagraphCount() always returns a count of at least one due to the existence of the terminating paragraph delimiter at the end of every text object.

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->ParagraphCount()); // paras including the final one

In the following example information about the word containing the character at a specified document position, and the word itself, are extracted and printed.

CGlobalText::GetWordInfo() is used to extract information about a word and CGlobalText::Read() to obtain a read-only pointer to the word.

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, &pointer, length, startPos);

// insert huge amounts of text
...

Before any field, apart from the page number field in a header or footer, can be inserted into a document, a field factory must be declared. A field factory is a class which derives from the MTextFieldFactory class, and which defines a NewFieldL() function. NewFieldL() constructs new fields according to a UID passed into the function.

The steps involved before the field factory can be used to create and insert a field are as follwows

1. Instantiate a field factory.

2. Set that factory to be the text object's field factory

3. Construct a field using CPlainText::NewTextFieldL()

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

5. Insert the field at the desired document position

6. 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 UpdateFieldL() 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.

7. CPlainText::FindFields() may be used to get information about a field, including its start position and length.

The following code centre aligns the text. Alignment is a paragraph format attribute and is a member of the CParaFormat class. All paragraph format attributes which are not explicitly set are taken from the system-provided default settings.

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

To set or clear paragraph format attributes, use a TParaFormatMask in conjunction with an object of class CParaFormat. The attributes specified in the mask are set according to the corresponding value contained in CParaFormat. Any attributes not specified in the mask are unaffected.

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

• An alternative method to using ApplyParaFormatL() for global text is to directly set the formatting of the global paragraph format layer upon which the object's paragraph formatting is based. This may be done by using either CParaFormatLayer::SetL(), to reset the formatting of the existing layer, or CGlobalText::SetGlobalParaFormat() which sets a new layer. Both methods cause all attributes to be reset — no mask is specified.

The following code globally sets the bold, italic and underline character format attributes. These attributes are accessed through the iFontPresentation and iFontStyle members of the TCharFormat class. Any attributes not explicitly set are taken from the system-provided default settings.

Global character formatting is applied in a similar manner to paragraph formatting, using a TCharFormatMask in conjunction with a TCharFormat, then calling CGlobalText::ApplyCharFormatL().

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->ApplyCharFormatL(charFormat,charFormatMask,0,0);

• No more than one attribute can be specified in the argument to TCharFormatMask::SetAttrib(). To set more than one attribute in a single call to ApplyCharFormatL(), either use several calls to SetAttrib(), as above, or use TCharFormatMask::SetAll() to set all attributes in the mask.