<?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&amp; aInitialInlineText, TInt aPositionOfInsertionPointInInlineText, TBool aCursorVisibility, const MFormCustomDraw*, MFepInlineTextFormatRetriever&amp;, MFepPointerEventHandlerDuringInlineEdit&amp;)=0;
    virtual void UpdateFepInlineTextL(const TDesC&amp; aNewInlineText, TInt aPositionOfInsertionPointInInlineText)=0;
    virtual void SetInlineEditingCursorVisibilityL(TBool aCursorVisibility)=0;
    IMPORT_C void CommitFepInlineEditL(CCoeEnv&amp; aConeEnvironment);
    virtual void CancelFepInlineEdit()=0;
    virtual TInt DocumentLengthForFep() const=0;
    virtual TInt DocumentMaximumLengthForFep() const=0;
    virtual void SetCursorSelectionForFepL(const TCursorSelection&amp; aCursorSelection)=0;
    virtual void GetCursorSelectionForFep(TCursorSelection&amp; aCursorSelection) const=0;
    virtual void GetEditorContentForFep(TDes&amp; aEditorContent, TInt aDocumentPosition, TInt aLengthToRetrieve) const=0;
    virtual void GetFormatForFep(TCharFormat&amp; aFormat, TInt aDocumentPosition) const=0;
    virtual void GetScreenCoordinatesForFepL(TPoint&amp; aLeftSideOfBaseLine, TInt&amp; aHeight, TInt&amp; aAscent, TInt aDocumentPosition) const=0;
    IMPORT_C MCoeFepAwareTextEditor_Extension1* Extension1();
private:
    virtual void DoCommitFepInlineEditL()=0;
    IMPORT_C virtual MCoeFepAwareTextEditor_Extension1* Extension1(TBool&amp; 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>
</conbody></concept>