--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-38679CA2-0066-589C-988F-AC14B7E2F107.dita	Fri Jun 11 12:39:03 2010 +0100
@@ -0,0 +1,144 @@
+<?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>
\ No newline at end of file