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.