Symbian3/SDK/Source/GUID-38679CA2-0066-589C-988F-AC14B7E2F107-GENID-1-8-1-3-1-1-9-1-4-1-10-1.dita
changeset 8 ae94777fff8f
parent 7 51a74ef9ed63
child 9 59758314f811
equal deleted inserted replaced
7:51a74ef9ed63 8:ae94777fff8f
     1 <?xml version="1.0" encoding="utf-8"?>
       
     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
       
     3 <!-- This component and the accompanying materials are made available under the terms of the License 
       
     4 "Eclipse Public License v1.0" which accompanies this distribution, 
       
     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
       
     6 <!-- Initial Contributors:
       
     7     Nokia Corporation - initial contribution.
       
     8 Contributors: 
       
     9 -->
       
    10 <!DOCTYPE concept
       
    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
       
    12 <concept id="GUID-38679CA2-0066-589C-988F-AC14B7E2F107-GENID-1-8-1-3-1-1-9-1-4-1-10-1" xml:lang="en"><title>Interacting
       
    13 with text editor controls</title><prolog><metadata><keywords/></metadata></prolog><conbody>
       
    14 <section id="GUID-9C16757D-DC75-5223-A555-550B8D3C1DB4-GENID-1-8-1-3-1-1-9-1-4-1-10-1-2-1"><title>Introduction </title> <p>The
       
    15 public parts of the <codeph>MCoeFepAwareTextEditor</codeph> class (which is
       
    16 defined in <filepath>epoc32\include\FEPBASE.H</filepath>) are as follows: </p> <codeblock id="GUID-52B6C9B8-1F43-5CBA-85D9-0D472F4F4396-GENID-1-8-1-3-1-1-9-1-4-1-10-1-2-1-3" xml:space="preserve">class MCoeFepAwareTextEditor
       
    17     {
       
    18 public:
       
    19     virtual void StartFepInlineEditL(const TDesC&amp; aInitialInlineText, TInt aPositionOfInsertionPointInInlineText, TBool aCursorVisibility, const MFormCustomDraw*, MFepInlineTextFormatRetriever&amp;, MFepPointerEventHandlerDuringInlineEdit&amp;)=0;
       
    20     virtual void UpdateFepInlineTextL(const TDesC&amp; aNewInlineText, TInt aPositionOfInsertionPointInInlineText)=0;
       
    21     virtual void SetInlineEditingCursorVisibilityL(TBool aCursorVisibility)=0;
       
    22     IMPORT_C void CommitFepInlineEditL(CCoeEnv&amp; aConeEnvironment);
       
    23     virtual void CancelFepInlineEdit()=0;
       
    24     virtual TInt DocumentLengthForFep() const=0;
       
    25     virtual TInt DocumentMaximumLengthForFep() const=0;
       
    26     virtual void SetCursorSelectionForFepL(const TCursorSelection&amp; aCursorSelection)=0;
       
    27     virtual void GetCursorSelectionForFep(TCursorSelection&amp; aCursorSelection) const=0;
       
    28     virtual void GetEditorContentForFep(TDes&amp; aEditorContent, TInt aDocumentPosition, TInt aLengthToRetrieve) const=0;
       
    29     virtual void GetFormatForFep(TCharFormat&amp; aFormat, TInt aDocumentPosition) const=0;
       
    30     virtual void GetScreenCoordinatesForFepL(TPoint&amp; aLeftSideOfBaseLine, TInt&amp; aHeight, TInt&amp; aAscent, TInt aDocumentPosition) const=0;
       
    31     IMPORT_C MCoeFepAwareTextEditor_Extension1* Extension1();
       
    32 private:
       
    33     virtual void DoCommitFepInlineEditL()=0;
       
    34     IMPORT_C virtual MCoeFepAwareTextEditor_Extension1* Extension1(TBool&amp; aSetToTrue);
       
    35     };</codeblock> <p>An implementation of this interface is provided by TechView’s <codeph>CEikEdwin</codeph> class
       
    36 (<codeph>CEikEdwin</codeph> was part of Uikon until Symbian OS v7.0s). <codeph>MCoeFepAwareTextEditor</codeph> member
       
    37 functions can be divided into two categories: <ul>
       
    38 <li><p>Functions for inline editing.</p></li>
       
    39 <li><p>Other functions that can broadly be categorized under the title 'context
       
    40 awareness'.</p></li>
       
    41 </ul></p> </section>
       
    42 <section id="GUID-1CE89EC8-5BE8-4F4B-8B39-57ACF40109DB-GENID-1-8-1-3-1-1-9-1-4-1-10-1-2-2"><title>Inline editing</title><p>Inline
       
    43 editing means the text to be sent to the application is composed inside the
       
    44 target text editing control, rather than in the FEP’s floating window. This
       
    45 requires the cooperation of the target text editing control which must implement
       
    46 the <codeph>MCoeFepAwareTextEditor</codeph> interface. An inline editing transaction
       
    47 consists of the following sequence: </p> <ul>
       
    48 <li id="GUID-817D5DC0-5C98-5BD2-A3C3-832D4220C970-GENID-1-8-1-3-1-1-9-1-4-1-10-1-2-2-3-1"><p>a call to <codeph>StartFepInlineEditL()</codeph>, </p> </li>
       
    49 <li id="GUID-961F900F-946A-5053-8063-D6ED8ECBDF7D-GENID-1-8-1-3-1-1-9-1-4-1-10-1-2-2-3-2"><p>zero, one or more calls
       
    50 to <codeph>UpdateFepInlineTextL()</codeph>, </p> </li>
       
    51 <li id="GUID-6C5F14D2-CA78-5194-8B7D-57FD4DA48DD4-GENID-1-8-1-3-1-1-9-1-4-1-10-1-2-2-3-3"><p>finally, a call to either <codeph>CommitFepInlineEditL()</codeph> or <codeph>CancelFepInlineEdit()</codeph>. (Note that <codeph>CCoeFep::SimulateKeyEventsL()</codeph> is not used at
       
    52 all in inline editing: the text is sent to the application via an entirely
       
    53 different mechanism.) </p> </li>
       
    54 </ul> <p>The second parameter (<codeph>TInt           aPositionOfInsertionPointInInlineText</codeph>)
       
    55 to <codeph>StartFepInlineEditL()</codeph> and <codeph>UpdateFepInlineTextL()</codeph> indicates
       
    56 where, in the inline text (which is passed as the first parameter), the insertion
       
    57 point, or cursor, is to appear. Note that the first parameter to <codeph>UpdateFepInlineTextL()</codeph> must
       
    58 be used to pass the <i>entire</i> inline text, not merely any new text to
       
    59 be combined with the old inline text. The third parameter (<codeph>TBool aCursorVisibility</codeph>)
       
    60 controls whether the insertion point is visible or not. As the types of the
       
    61 fourth, fifth and sixth parameters are abstract base classes, the FEP must
       
    62 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
       
    63 duration of the inline editing transaction. </p> <p>Note that <xref href="GUID-AF2B465F-EFC3-3205-A6D8-2EE19E738385.dita"><apiname>MFormCustomDraw</apiname></xref> pointer
       
    64 may NULL. <xref href="GUID-AF2B465F-EFC3-3205-A6D8-2EE19E738385.dita"><apiname>MFormCustomDraw</apiname></xref> belongs to the FORM component
       
    65 and is not described here. It enables the FEP to do advanced formatting of
       
    66 the inline text. The details of the other two interface classes used in inline
       
    67 editing are discussed next. </p> <p> <xref href="GUID-91C8D439-F28E-3417-87B3-4698BE8571DE.dita"><apiname>MFepInlineTextFormatRetriever</apiname></xref> (defined
       
    68 in <filepath>epoc32\include\FEPITFR.H</filepath>) has a single (pure) virtual
       
    69 function whose signature is as follows: </p> <codeblock id="GUID-06D8A567-223B-5352-B695-6DC3BF1C804A-GENID-1-8-1-3-1-1-9-1-4-1-10-1-2-2-7" 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
       
    70 inline text. For example, TFEP1plugin’s implementation of this function sets
       
    71 this parameter to red, underlined text. <xref href="GUID-A5D563D6-A99A-31DF-B844-5F94EF5FFE87.dita"><apiname>MCoeFepAwareTextEditor</apiname></xref> provides
       
    72 a member function for finding out the ambient <codeph>TCharFormat</codeph> of
       
    73 the text editor: <codeph>GetFormatForFep()</codeph>. This can be called inside
       
    74 the FEP’s implementation of <codeph>GetFormatOfFepInlineText()</codeph> to
       
    75 make any necessary adjustments to the format of the inline text to ensure
       
    76 that it differentiates itself from the surrounding text. </p> <p>The second
       
    77 and third parameters to <codeph>GetFormatOfFepInlineText()</codeph> enable
       
    78 different parts of the inline text to have different formats. Their use is
       
    79 best illustrated by an example (albeit an artificial one). Suppose the FEP
       
    80 requires the first four characters of the inline text to be red, the next
       
    81 two characters (if there are any) to be green, and any subsequent characters
       
    82 to be blue, the <codeph>GetFormatOfFepInlineText()</codeph> function would
       
    83 look as follows: </p> <codeblock id="GUID-F4A7F35F-5EA1-5D6E-9570-44ADBC9D7AB5-GENID-1-8-1-3-1-1-9-1-4-1-10-1-2-2-10" xml:space="preserve">void Xxxxx::GetFormatOfFepInlineText(TCharFormat&amp; aFormat, TInt&amp; aNumberOfCharactersWithSameFormat, TInt aPositionOfCharacter) const
       
    84     {
       
    85     const TInt lengthOfRemainderOfInlineText=iBuffer.Length()-aPositionOfCharacter;
       
    86     aFormat=iBaseFormatForInlineText;
       
    87     aFormat.iFontPresentation.iTextColor.SetRed(0);
       
    88     aFormat.iFontPresentation.iTextColor.SetGreen(0);
       
    89     aFormat.iFontPresentation.iTextColor.SetBlue(0);
       
    90     if (aPositionOfCharacter==0)
       
    91         {
       
    92         // first four characters are red
       
    93         aFormat.iFontPresentation.iTextColor.SetRed(255);
       
    94         aNumberOfCharactersWithSameFormat=Min(4, lengthOfRemainderOfInlineText);
       
    95         }
       
    96     else if (aPositionOfCharacter==4)
       
    97         {
       
    98         // next two characters are green
       
    99         aFormat.iFontPresentation.iTextColor.SetGreen(255);
       
   100         aNumberOfCharactersWithSameFormat=Min(2, lengthOfRemainderOfInlineText);
       
   101         }
       
   102     else if (aPositionOfCharacter==6)
       
   103         {
       
   104         // any subsequent characters are blue
       
   105         aFormat.iFontPresentation.iTextColor.SetBlue(255);
       
   106         aNumberOfCharactersWithSameFormat=lengthOfRemainderOfInlineText;
       
   107         }
       
   108     }</codeblock> <p> <xref href="GUID-E7E10DF8-B419-329B-BB9D-D277E1631B0D.dita"><apiname>MFepPointerEventHandlerDuringInlineEdit</apiname></xref> (which
       
   109 is defined in <filepath>epoc32\include\FEPBASE.H</filepath>) gives the FEP
       
   110 the opportunity to handle pointer events which occur in the area on the screen
       
   111 occupied by the inline text. It has a single (pure) virtual function whose
       
   112 signature is as follows: </p> <codeblock id="GUID-3AF75EEB-2FDA-57FD-AC09-7FAE30ACB1FE-GENID-1-8-1-3-1-1-9-1-4-1-10-1-2-2-12" 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
       
   113 down, pointer drag or pointer up), the keyboard modifiers (for instance caps
       
   114 lock and shift) and the logical position of the event in the inline text. </p></section>
       
   115 <section id="GUID-0BEE5B61-5ACC-4847-996E-E659D518646E-GENID-1-8-1-3-1-1-9-1-4-1-10-1-2-3"><title>Context awareness</title><p>As
       
   116 well as providing support for inline editing, the <xref href="GUID-A5D563D6-A99A-31DF-B844-5F94EF5FFE87.dita"><apiname>MCoeFepAwareTextEditor</apiname></xref> interface
       
   117 class enables the FEP to find out information about the text editor control
       
   118 with focus. <codeph>DocumentLengthForFep()</codeph> returns the length of
       
   119 the text held in the text editor. <codeph>DocumentMaximumLengthForFep()</codeph> returns
       
   120 the upper limit (if any) on the length of text that the text editor can hold. <codeph>SetCursorSelectionForFepL()</codeph> selects
       
   121 the specified text range in the text editor, and <codeph>GetCursorSelectionForFep()</codeph> sets
       
   122 its parameter to the selected text range in the text editor. <codeph>GetEditorContentForFep()</codeph> allows
       
   123 the FEP to retrieve any segment of the text held in the text editor. <codeph>GetFormatForFep()</codeph> sets
       
   124 its first parameter according to the character format at the position in the
       
   125 text editor specified by the second parameter. <codeph>GetScreenCoordinatesForFepL()</codeph> sets
       
   126 the first parameter to the screen coordinates of the left end of the baseline
       
   127 of the character glyph whose position in the text editor is specified by the
       
   128 last parameter. The second and third parameters are set, respectively, to
       
   129 the height and ascent of the font used at that document position. This function
       
   130 can be used, for example, to position a FEP window as close as possible to
       
   131 the text editor’s insertion point (in other words, the cursor position). </p> <p>The <codeph>Extension1()</codeph> member
       
   132 function of <xref href="GUID-A5D563D6-A99A-31DF-B844-5F94EF5FFE87.dita"><apiname>MCoeFepAwareTextEditor</apiname></xref> returns a pointer to
       
   133 an object of the interface class <xref href="GUID-C8F42D8B-D03B-3559-9E7C-BBE94C4E7F66.dita"><apiname>MCoeFepAwareTextEditor_Extension1
       
   134           </apiname></xref> (defined in <filepath>epoc32\include\FEPBASE.H</filepath>).
       
   135 This class has two public (pure) virtual functions whose signatures are as
       
   136 follows: </p> <codeblock id="GUID-3E87C57E-AF43-5268-BC0A-AC34B62C8BAA-GENID-1-8-1-3-1-1-9-1-4-1-10-1-2-3-4" xml:space="preserve">virtual void SetStateTransferingOwnershipL(CState* aState, TUid aTypeSafetyUid)=0;
       
   137 virtual CState* State(TUid aTypeSafetyUid)=0;</codeblock> <p>The <codeph>CState</codeph> class
       
   138 is defined within the scope of the <xref href="GUID-C8F42D8B-D03B-3559-9E7C-BBE94C4E7F66.dita"><apiname>MCoeFepAwareTextEditor_Extension1</apiname></xref> class.
       
   139 The purpose of the UIDs in the two functions above is to enable the FEP to
       
   140 safely downcast the <codeph>CState</codeph> pointer returned by the <codeph>State()</codeph> function
       
   141 to a pointer to a derived class known about by the FEP. The <codeph>CState</codeph> class
       
   142 is provided to enable FEPs to store state information inside text editor controls,
       
   143 where that state information is only of interest to the FEP. </p></section>
       
   144 </conbody></concept>