|
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& aInitialInlineText, TInt aPositionOfInsertionPointInInlineText, TBool aCursorVisibility, const MFormCustomDraw*, MFepInlineTextFormatRetriever&, MFepPointerEventHandlerDuringInlineEdit&)=0; |
|
20 virtual void UpdateFepInlineTextL(const TDesC& aNewInlineText, TInt aPositionOfInsertionPointInInlineText)=0; |
|
21 virtual void SetInlineEditingCursorVisibilityL(TBool aCursorVisibility)=0; |
|
22 IMPORT_C void CommitFepInlineEditL(CCoeEnv& aConeEnvironment); |
|
23 virtual void CancelFepInlineEdit()=0; |
|
24 virtual TInt DocumentLengthForFep() const=0; |
|
25 virtual TInt DocumentMaximumLengthForFep() const=0; |
|
26 virtual void SetCursorSelectionForFepL(const TCursorSelection& aCursorSelection)=0; |
|
27 virtual void GetCursorSelectionForFep(TCursorSelection& aCursorSelection) const=0; |
|
28 virtual void GetEditorContentForFep(TDes& aEditorContent, TInt aDocumentPosition, TInt aLengthToRetrieve) const=0; |
|
29 virtual void GetFormatForFep(TCharFormat& aFormat, TInt aDocumentPosition) const=0; |
|
30 virtual void GetScreenCoordinatesForFepL(TPoint& aLeftSideOfBaseLine, TInt& aHeight, TInt& 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& 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& aFormat, TInt& 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& aFormat, TInt& 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> |