The Paper - Page 9 - Rich Text Editor Control

The Workflow of C++ Game-Development on a Series 60 Platform device

Andreas Jakl, Revision 1.0, July 2004

Chapter 4 – Components

The game called The Journey demonstrates the use of several components which are not well documented. This chapter provides a description of the key factors that are necessary to implement them.

4.1 The RichText editor control

The RichText component is well suited for displaying formatted text as it is powerful and handles many aspects automatically. It is also capable of displaying the scrollbar indicators in the softkey bar at the bottom of the screen. Using the interface it provides, it would not be very difficult to implement an editor where you can choose your own fonts, styles and alignment.

In many situations only static text is needed, for example in an about box or, as in the case of The Journey, to display the game text. The RichText editor has the advantage that the text is automatically wrapped and you do not have to take care of that yourself. The class CJourneyCGame includes this control.

Many border styles are available. To use them you have to include an extra library called egul.lib in your .mmp file. When creating it, the border has to be specified. In this example, no border is being used (the default would be 1 pixel):

    iTextBox = new (ELeave)
        CEikRichTextEditor(TGulBorder::ENone);

Then it is constructed and its flags are set using the command below – in this case they are defined in a way to make the box read only and to hide the cursor.

    TInt edwinFlags = EEikEdwinInclusiveSizeFixed|
                      EEikEdwinNoAutoSelection|
                      EEikEdwinDisplayOnly|
                      EEikEdwinReadOnly|
                      EEikEdwinLineCursor|
                      EEikEdwinNoHorizScrolling|
                      EEikEdwinAvkonDisableCursor;
    iTextBox->ConstructL(this, 4, 0, edwinFlags,
        EGulFontControlAll, EGulAllFonts);
    iTextBox->SetAknEditorFlags(edwinFlags);

The scrollbar frame in the softkey bar can now be activated using these calls:

    iTextBox->CreatePreAllocatedScrollBarFrameL();
    iTextBox->ScrollBarFrame()->SetScrollBarVisibilityL
        (CEikScrollBarFrame::EOff, CEikScrollBarFrame::EAuto);

Next, the hierarchy is defined – the container window and the observer are set to the owning class, in our case CJourneyCGame . After that, the position, size and background color are defined. Finally the control gets the focus.

    // Sets the containing window for the control
    iTextBox->SetContainerWindowL(*this);
    iTextBox->SetObserver(this);
    // Set the size of the textbox
    iTextBox->SetExtent(TPoint(10, 106), TSize(156, 80));
    // The background color can be specified quite easily
    iTextBox->SetBackgroundColorL(TRgb(74, 56, 28));
    iTextBox->SetFocus(ETrue);

The last step to getting a good looking text box is to set the font and text color. If they are set at the beginning, the text we will put into the control later will automatically be displayed with the style defined now. Of course it would be possible to use more than one style in a text block using this control. For example in the game this could be useful to format text in direct speech in italics.

    // Set font type
    TFontSpec fontspec = LatinPlain12()->FontSpecInTwips();
    TCharFormat charFormat( fontspec.iTypeface.iName,
        fontspec.iHeight );
    TCharFormatMask charFormatMask;

    // Set text color
    charFormat.iFontPresentation.iTextColor = KTextColor;

    // Activate the attributes
    charFormatMask.SetAttrib(EAttColor);
    charFormatMask.SetAttrib(EAttFontTypeface);
    charFormatMask.SetAttrib(EAttFontHeight);

    // Apply font to the whole text
    iTextBox->SelectAllL();
    iTextBox->ApplyCharFormatL(charFormat, charFormatMask);
    iTextBox->ClearSelectionL();

Defining font parameters works using the TCharFormat class. Several individual attributes of it can be set, then a mask has to be defined where the attributes you have just set are activated. Finally you can apply the character format together with the mask to a selected text.

Setting the text is straightforward, a &TDesC has to be passed to the class, which takes care of text formatting and displaying automatically. It is very important to set the cursor position to the beginning of the line before replacing the text. Otherwise, if the new text is shorter than the previous one and the cursor position is outside of the new text, the function will leave.

    iTextBox->SetCursorPosL(0, EFalse);
    iTextBox->SetTextL(&textResource);

Finally, scrolling should be done when the according key press is registered [7]. There is a function called MoveDisplayL() , however, there doesn't seem to be a method to easily check when the bottom of the text has been reached and no scrolling down would be possible anymore, because at that point any further calls to the function will leave. Also the scrollbar would not be updated. Because of that, scrolling should to be done using the (invisible) cursor.

    iTextBox->MoveCursorL(TCursorPosition::EFPageDown, EFalse);
    iTextBox->MoveCursorL(TCursorPosition::EFLineBeg, EFalse);
    iTextBox->UpdateScrollBarsL();

In conclusion, using the RichText editor control is not very difficult when information about how to use it is available. However, finding instructions is still difficult. Hopefully, these instructions might help and explain some of the foundations.