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

An implementation of this interface is provided by TechView’s CEikEdwin class +(CEikEdwin was part of Uikon until Symbian OS v7.0s). MCoeFepAwareTextEditor member +functions can be divided into two categories:

Functions for inline editing.
Other functions that can broadly be categorized under the title 'context +awareness'.

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.