--- a/Symbian3/SDK/Source/GUID-38679CA2-0066-589C-988F-AC14B7E2F107-GENID-1-8-1-6-1-1-4-1-8-1-4-1-10-1.dita Wed Mar 31 11:11:55 2010 +0100
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,144 +0,0 @@
-<?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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-10-1" xml:lang="en"><title>Interacting
-with text editor controls</title><prolog><metadata><keywords/></metadata></prolog><conbody>
-<section id="GUID-9C16757D-DC75-5223-A555-550B8D3C1DB4-GENID-1-8-1-6-1-1-4-1-8-1-4-1-10-1-2-1"><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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-10-1-2-1-3" 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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-10-1-2-2"><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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-10-1-2-2-3-1"><p>a call to <codeph>StartFepInlineEditL()</codeph>, </p> </li>
-<li id="GUID-961F900F-946A-5053-8063-D6ED8ECBDF7D-GENID-1-8-1-6-1-1-4-1-8-1-4-1-10-1-2-2-3-2"><p>zero, one or more calls
-to <codeph>UpdateFepInlineTextL()</codeph>, </p> </li>
-<li id="GUID-6C5F14D2-CA78-5194-8B7D-57FD4DA48DD4-GENID-1-8-1-6-1-1-4-1-8-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
-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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-10-1-2-2-7" xml:space="preserve">virtual void GetFormatOfFepInlineText(TCharFormat& aFormat, TInt& 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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-10-1-2-2-10" xml:space="preserve">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;
- }
- }</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-GENID-1-8-1-6-1-1-4-1-8-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
-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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-10-1-2-3"><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-GENID-1-8-1-6-1-1-4-1-8-1-4-1-10-1-2-3-4" 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