Interacting with text editor controls

Introduction

The public parts of the MCoeFepAwareTextEditor class (which is defined in epoc32\include\FEPBASE.H) are as follows:

class MCoeFepAwareTextEditor
    {
public:
    virtual void StartFepInlineEditL(const TDesC& aInitialInlineText, TInt aPositionOfInsertionPointInInlineText, TBool aCursorVisibility, const MFormCustomDraw*, MFepInlineTextFormatRetriever&, MFepPointerEventHandlerDuringInlineEdit&)=0;
    virtual void UpdateFepInlineTextL(const TDesC& aNewInlineText, TInt aPositionOfInsertionPointInInlineText)=0;
    virtual void SetInlineEditingCursorVisibilityL(TBool aCursorVisibility)=0;
    IMPORT_C void CommitFepInlineEditL(CCoeEnv& aConeEnvironment);
    virtual void CancelFepInlineEdit()=0;
    virtual TInt DocumentLengthForFep() const=0;
    virtual TInt DocumentMaximumLengthForFep() const=0;
    virtual void SetCursorSelectionForFepL(const TCursorSelection& aCursorSelection)=0;
    virtual void GetCursorSelectionForFep(TCursorSelection& aCursorSelection) const=0;
    virtual void GetEditorContentForFep(TDes& aEditorContent, TInt aDocumentPosition, TInt aLengthToRetrieve) const=0;
    virtual void GetFormatForFep(TCharFormat& aFormat, TInt aDocumentPosition) const=0;
    virtual void GetScreenCoordinatesForFepL(TPoint& aLeftSideOfBaseLine, TInt& aHeight, TInt& aAscent, TInt aDocumentPosition) const=0;
    IMPORT_C MCoeFepAwareTextEditor_Extension1* Extension1();
private:
    virtual void DoCommitFepInlineEditL()=0;
    IMPORT_C virtual MCoeFepAwareTextEditor_Extension1* Extension1(TBool& aSetToTrue);
    };

Inline editing

Inline editing means the text to be sent to the application is composed inside the target text editing control, rather than in the FEP’s floating window. This requires the cooperation of the target text editing control which must implement the MCoeFepAwareTextEditor interface. An inline editing transaction consists of the following sequence:

• a call to StartFepInlineEditL(),

• zero, one or more calls to UpdateFepInlineTextL(),

• finally, a call to either CommitFepInlineEditL() or CancelFepInlineEdit(). (Note that CCoeFep::SimulateKeyEventsL() is not used at all in inline editing: the text is sent to the application via an entirely different mechanism.)

The second parameter (TInt aPositionOfInsertionPointInInlineText) to StartFepInlineEditL() and UpdateFepInlineTextL() indicates where, in the inline text (which is passed as the first parameter), the insertion point, or cursor, is to appear. Note that the first parameter to UpdateFepInlineTextL() must be used to pass the entire inline text, not merely any new text to be combined with the old inline text. The third parameter (TBool aCursorVisibility) controls whether the insertion point is visible or not. As the types of the fourth, fifth and sixth parameters are abstract base classes, the FEP must create objects derived from these classes (MFormCustomDraw, MFepInlineTextFormatRetriever and MFepPointerEventHandlerDuringInlineEdit) and pass references. These object(s) must remain in existence for the entire duration of the inline editing transaction.

Note that MFormCustomDraw pointer may NULL. MFormCustomDraw belongs to the FORM component and is not described here. It enables the FEP to do advanced formatting of the inline text. The details of the other two interface classes used in inline editing are discussed next.

MFepInlineTextFormatRetriever (defined in epoc32\include\FEPITFR.H) has a single (pure) virtual function whose signature is as follows:

virtual void GetFormatOfFepInlineText(TCharFormat& aFormat, TInt& aNumberOfCharactersWithSameFormat, TInt aPositionOfCharacter) const=0;

The first parameter is to be set by the function to the format of the inline text. For example, TFEP1plugin’s implementation of this function sets this parameter to red, underlined text. MCoeFepAwareTextEditor provides a member function for finding out the ambient TCharFormat of the text editor: GetFormatForFep(). This can be called inside the FEP’s implementation of GetFormatOfFepInlineText() to make any necessary adjustments to the format of the inline text to ensure that it differentiates itself from the surrounding text.

The second and third parameters to GetFormatOfFepInlineText() enable different parts of the inline text to have different formats. Their use is best illustrated by an example (albeit an artificial one). Suppose the FEP requires the first four characters of the inline text to be red, the next two characters (if there are any) to be green, and any subsequent characters to be blue, the GetFormatOfFepInlineText() function would look as follows:

void Xxxxx::GetFormatOfFepInlineText(TCharFormat& aFormat, TInt& aNumberOfCharactersWithSameFormat, TInt aPositionOfCharacter) const
    {
    const TInt lengthOfRemainderOfInlineText=iBuffer.Length()-aPositionOfCharacter;
    aFormat=iBaseFormatForInlineText;
    aFormat.iFontPresentation.iTextColor.SetRed(0);
    aFormat.iFontPresentation.iTextColor.SetGreen(0);
    aFormat.iFontPresentation.iTextColor.SetBlue(0);
    if (aPositionOfCharacter==0)
        {
        // first four characters are red
        aFormat.iFontPresentation.iTextColor.SetRed(255);
        aNumberOfCharactersWithSameFormat=Min(4, lengthOfRemainderOfInlineText);
        }
    else if (aPositionOfCharacter==4)
        {
        // next two characters are green
        aFormat.iFontPresentation.iTextColor.SetGreen(255);
        aNumberOfCharactersWithSameFormat=Min(2, lengthOfRemainderOfInlineText);
        }
    else if (aPositionOfCharacter==6)
        {
        // any subsequent characters are blue
        aFormat.iFontPresentation.iTextColor.SetBlue(255);
        aNumberOfCharactersWithSameFormat=lengthOfRemainderOfInlineText;
        }
    }

MFepPointerEventHandlerDuringInlineEdit (which is defined in epoc32\include\FEPBASE.H) gives the FEP the opportunity to handle pointer events which occur in the area on the screen occupied by the inline text. It has a single (pure) virtual function whose signature is as follows:

virtual void HandlePointerEventInInlineTextL(TPointerEvent::TType aType, TUint aModifiers, TInt aPositionInInlineText)=0;

The parameters indicate to the FEP the event’s type (for instance pointer down, pointer drag or pointer up), the keyboard modifiers (for instance caps lock and shift) and the logical position of the event in the inline text.

Context awareness

As well as providing support for inline editing, the MCoeFepAwareTextEditor interface class enables the FEP to find out information about the text editor control with focus. DocumentLengthForFep() returns the length of the text held in the text editor. DocumentMaximumLengthForFep() returns the upper limit (if any) on the length of text that the text editor can hold. SetCursorSelectionForFepL() selects the specified text range in the text editor, and GetCursorSelectionForFep() sets its parameter to the selected text range in the text editor. GetEditorContentForFep() allows the FEP to retrieve any segment of the text held in the text editor. GetFormatForFep() sets its first parameter according to the character format at the position in the text editor specified by the second parameter. GetScreenCoordinatesForFepL() sets the first parameter to the screen coordinates of the left end of the baseline of the character glyph whose position in the text editor is specified by the last parameter. The second and third parameters are set, respectively, to the height and ascent of the font used at that document position. This function can be used, for example, to position a FEP window as close as possible to the text editor’s insertion point (in other words, the cursor position).

The Extension1() member function of MCoeFepAwareTextEditor returns a pointer to an object of the interface class MCoeFepAwareTextEditor_Extension1 (defined in epoc32\include\FEPBASE.H). This class has two public (pure) virtual functions whose signatures are as follows:

virtual void SetStateTransferingOwnershipL(CState* aState, TUid aTypeSafetyUid)=0;
virtual CState* State(TUid aTypeSafetyUid)=0;

The CState class is defined within the scope of the MCoeFepAwareTextEditor_Extension1 class. The purpose of the UIDs in the two functions above is to enable the FEP to safely downcast the CState pointer returned by the State() function to a pointer to a derived class known about by the FEP. The CState class is provided to enable FEPs to store state information inside text editor controls, where that state information is only of interest to the FEP.