<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-38679CA2-0066-589C-988F-AC14B7E2F107" xml:lang="en"><title>Interacting

with text editor controls</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-9C16757D-DC75-5223-A555-550B8D3C1DB4"><title>Introduction </title> <p>The

public parts of the <codeph>MCoeFepAwareTextEditor</codeph> class (which is

defined in <filepath>epoc32\include\FEPBASE.H</filepath>) are as follows: </p> <codeblock id="GUID-52B6C9B8-1F43-5CBA-85D9-0D472F4F4396" xml:space="preserve">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);

    };</codeblock> <p>An implementation of this interface is provided by TechView’s <codeph>CEikEdwin</codeph> class

(<codeph>CEikEdwin</codeph> was part of Uikon until Symbian OS v7.0s). <codeph>MCoeFepAwareTextEditor</codeph> member

functions can be divided into two categories: <ul>

<li><p>Functions for inline editing.</p></li>

<li><p>Other functions that can broadly be categorized under the title 'context

awareness'.</p></li>

</ul></p> </section>

<section id="GUID-1CE89EC8-5BE8-4F4B-8B39-57ACF40109DB"><title>Inline editing</title><p>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 <codeph>MCoeFepAwareTextEditor</codeph> interface. An inline editing transaction

consists of the following sequence: </p> <ul>

<li id="GUID-817D5DC0-5C98-5BD2-A3C3-832D4220C970"><p>a call to <codeph>StartFepInlineEditL()</codeph>, </p> </li>

<li id="GUID-961F900F-946A-5053-8063-D6ED8ECBDF7D"><p>zero, one or more calls

to <codeph>UpdateFepInlineTextL()</codeph>, </p> </li>

<li id="GUID-6C5F14D2-CA78-5194-8B7D-57FD4DA48DD4"><p>finally, a call to either <codeph>CommitFepInlineEditL()</codeph> or <codeph>CancelFepInlineEdit()</codeph>. (Note that <codeph>CCoeFep::SimulateKeyEventsL()</codeph> is not used at

all in inline editing: the text is sent to the application via an entirely

different mechanism.) </p> </li>

</ul> <p>The second parameter (<codeph>TInt           aPositionOfInsertionPointInInlineText</codeph>)

to <codeph>StartFepInlineEditL()</codeph> and <codeph>UpdateFepInlineTextL()</codeph> 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 <codeph>UpdateFepInlineTextL()</codeph> must

be used to pass the <i>entire</i> inline text, not merely any new text to

be combined with the old inline text. The third parameter (<codeph>TBool aCursorVisibility</codeph>)

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 (<xref href="GUID-AF2B465F-EFC3-3205-A6D8-2EE19E738385.dita"><apiname>MFormCustomDraw</apiname></xref>, <xref href="GUID-91C8D439-F28E-3417-87B3-4698BE8571DE.dita"><apiname>MFepInlineTextFormatRetriever</apiname></xref> and <xref href="GUID-E7E10DF8-B419-329B-BB9D-D277E1631B0D.dita"><apiname>MFepPointerEventHandlerDuringInlineEdit</apiname></xref>) and pass references. These object(s) must remain in existence for the entire

duration of the inline editing transaction. </p> <p>Note that <xref href="GUID-AF2B465F-EFC3-3205-A6D8-2EE19E738385.dita"><apiname>MFormCustomDraw</apiname></xref> pointer

may NULL. <xref href="GUID-AF2B465F-EFC3-3205-A6D8-2EE19E738385.dita"><apiname>MFormCustomDraw</apiname></xref> 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. </p> <p> <xref href="GUID-91C8D439-F28E-3417-87B3-4698BE8571DE.dita"><apiname>MFepInlineTextFormatRetriever</apiname></xref> (defined

in <filepath>epoc32\include\FEPITFR.H</filepath>) has a single (pure) virtual

function whose signature is as follows: </p> <codeblock id="GUID-06D8A567-223B-5352-B695-6DC3BF1C804A" xml:space="preserve">virtual void GetFormatOfFepInlineText(TCharFormat&amp; aFormat, TInt&amp; aNumberOfCharactersWithSameFormat, TInt aPositionOfCharacter) const=0;</codeblock> <p>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. <xref href="GUID-A5D563D6-A99A-31DF-B844-5F94EF5FFE87.dita"><apiname>MCoeFepAwareTextEditor</apiname></xref> provides

a member function for finding out the ambient <codeph>TCharFormat</codeph> of

the text editor: <codeph>GetFormatForFep()</codeph>. This can be called inside

the FEP’s implementation of <codeph>GetFormatOfFepInlineText()</codeph> to

make any necessary adjustments to the format of the inline text to ensure

that it differentiates itself from the surrounding text. </p> <p>The second

and third parameters to <codeph>GetFormatOfFepInlineText()</codeph> 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 <codeph>GetFormatOfFepInlineText()</codeph> function would

look as follows: </p> <codeblock id="GUID-F4A7F35F-5EA1-5D6E-9570-44ADBC9D7AB5" xml:space="preserve">void Xxxxx::GetFormatOfFepInlineText(TCharFormat&amp; aFormat, TInt&amp; 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;

        }

    }</codeblock> <p> <xref href="GUID-E7E10DF8-B419-329B-BB9D-D277E1631B0D.dita"><apiname>MFepPointerEventHandlerDuringInlineEdit</apiname></xref> (which

is defined in <filepath>epoc32\include\FEPBASE.H</filepath>) 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: </p> <codeblock id="GUID-3AF75EEB-2FDA-57FD-AC09-7FAE30ACB1FE" xml:space="preserve">virtual void HandlePointerEventInInlineTextL(TPointerEvent::TType aType, TUint aModifiers, TInt aPositionInInlineText)=0;</codeblock> <p>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. </p></section>

<section id="GUID-0BEE5B61-5ACC-4847-996E-E659D518646E"><title>Context awareness</title><p>As

well as providing support for inline editing, the <xref href="GUID-A5D563D6-A99A-31DF-B844-5F94EF5FFE87.dita"><apiname>MCoeFepAwareTextEditor</apiname></xref> interface

class enables the FEP to find out information about the text editor control

with focus. <codeph>DocumentLengthForFep()</codeph> returns the length of

the text held in the text editor. <codeph>DocumentMaximumLengthForFep()</codeph> returns

the upper limit (if any) on the length of text that the text editor can hold. <codeph>SetCursorSelectionForFepL()</codeph> selects

the specified text range in the text editor, and <codeph>GetCursorSelectionForFep()</codeph> sets

its parameter to the selected text range in the text editor. <codeph>GetEditorContentForFep()</codeph> allows

the FEP to retrieve any segment of the text held in the text editor. <codeph>GetFormatForFep()</codeph> sets

its first parameter according to the character format at the position in the

text editor specified by the second parameter. <codeph>GetScreenCoordinatesForFepL()</codeph> 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). </p> <p>The <codeph>Extension1()</codeph> member

function of <xref href="GUID-A5D563D6-A99A-31DF-B844-5F94EF5FFE87.dita"><apiname>MCoeFepAwareTextEditor</apiname></xref> returns a pointer to

an object of the interface class <xref href="GUID-C8F42D8B-D03B-3559-9E7C-BBE94C4E7F66.dita"><apiname>MCoeFepAwareTextEditor_Extension1

          </apiname></xref> (defined in <filepath>epoc32\include\FEPBASE.H</filepath>).

This class has two public (pure) virtual functions whose signatures are as

follows: </p> <codeblock id="GUID-3E87C57E-AF43-5268-BC0A-AC34B62C8BAA" xml:space="preserve">virtual void SetStateTransferingOwnershipL(CState* aState, TUid aTypeSafetyUid)=0;

virtual CState* State(TUid aTypeSafetyUid)=0;</codeblock> <p>The <codeph>CState</codeph> class

is defined within the scope of the <xref href="GUID-C8F42D8B-D03B-3559-9E7C-BBE94C4E7F66.dita"><apiname>MCoeFepAwareTextEditor_Extension1</apiname></xref> class.

The purpose of the UIDs in the two functions above is to enable the FEP to

safely downcast the <codeph>CState</codeph> pointer returned by the <codeph>State()</codeph> function

to a pointer to a derived class known about by the FEP. The <codeph>CState</codeph> 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. </p></section>