|
1 // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // |
|
15 |
|
16 #ifndef __FEPBASE_H__ |
|
17 #define __FEPBASE_H__ |
|
18 |
|
19 #include <e32std.h> |
|
20 #include <e32base.h> |
|
21 #include <f32file.h> |
|
22 #include <w32std.h> |
|
23 #include <coedef.h> |
|
24 #include <coemain.h> |
|
25 #include <fepbutils.h> |
|
26 #include <fepbconfig.h> |
|
27 |
|
28 class CCoeControl; |
|
29 |
|
30 |
|
31 /** Specifies the mixin protocol for observing a FEP transaction. |
|
32 |
|
33 Applications which need to implement this protocol should derive from this |
|
34 class. The functions are not pure virtual because most applications will only |
|
35 need to override one of them. |
|
36 |
|
37 @see CCoeFep::MakeDeferredFunctionCall() |
|
38 @publishedAll |
|
39 @released */ |
|
40 class MCoeFepObserver |
|
41 { |
|
42 public: |
|
43 // both of these functions do nothing by default - the reason that they are not pure |
|
44 // virtual is that most applications will only want to override one of them |
|
45 IMPORT_C virtual void HandleStartOfTransactionL(); // the responsibility of FEPs to call |
|
46 IMPORT_C virtual void HandleCompletionOfTransactionL(); // the responsibility of FEPBASE to call - not to be called if the transaction is canceled |
|
47 private: // reserved. do not override! |
|
48 IMPORT_C virtual void MCoeFepObserver_Reserved_1(); |
|
49 IMPORT_C virtual void MCoeFepObserver_Reserved_2(); |
|
50 }; |
|
51 |
|
52 /** Handles the start of a FEP transaction. |
|
53 |
|
54 This is a non-member function which just calls aFepObserver.HandleStartOfTransactionL(). |
|
55 |
|
56 It is called indirectly by a FEP to notify the application that it is starting a transaction. |
|
57 This is done by calling CCoeEnv::ForEachFepObserverCall() passing in |
|
58 FepObserverHandleStartOfTransactionL. Internally, this calls HandleStartOfTransactionL() for |
|
59 each MCoeFepObserver object that has been registered with the control environment. |
|
60 |
|
61 @param aFepObserver The FEP observer. |
|
62 @see MCoeFepObserver::HandleStartOfTransactionL() |
|
63 @publishedAll |
|
64 @released */ |
|
65 IMPORT_C void FepObserverHandleStartOfTransactionL(MCoeFepObserver& aFepObserver); |
|
66 |
|
67 |
|
68 /** Abstract base class for all FEPs. |
|
69 |
|
70 FEP authors must derive a class from CCoeFep. The CCoeFep-derived class should |
|
71 implement all of its pure virtual functions including the ones which CCoeFep |
|
72 inherits from its base classes. For information on these functions, see the |
|
73 documentation of the base classes. The global NewFepL() function is used to |
|
74 create a fully initialised object of the derived class. |
|
75 |
|
76 FEPs that need to intercept key events should own a CCoeControl-derived object. |
|
77 This object is referred to as the FEP control. The FEP control should |
|
78 be added to the control stack at a priority of ECoeStackPriorityFep, so that |
|
79 it receives first refusal of key events from the window server. |
|
80 |
|
81 In general, focus is retained by the underlying application. This has the |
|
82 advantage that the user can see where the output produced by the FEP will |
|
83 go. When focus is switched between controls, the FEP must be notified in case |
|
84 the input capability of the focussed control changes. For instance, the FEP |
|
85 needs to prevent the user composing a large amount of text only for it to |
|
86 be passed to a newly focussed control that cannot accept text input. CCoeFep |
|
87 derives from MCoeFocusObserver, which enables FEPs to receive notification |
|
88 when the focus for the underlying control changes. The implementation of MCoeFocusObserver's |
|
89 functions can call the enquiry functions of class TCoeInputCapabilities to |
|
90 find out what input capabilities are supported by the new target control (you |
|
91 need to get the TCoeInputCapabilities object from the application UI first: |
|
92 see CCoeAppUi::InputCapabilities()). |
|
93 |
|
94 @see NewFepL() |
|
95 @publishedAll |
|
96 @released */ |
|
97 class CCoeFep : public CBase, protected MFepAttributeStorer, public MCoeForegroundObserver, public MCoeFocusObserver, private MCoeMessageObserver |
|
98 { |
|
99 public: |
|
100 /** Response to key or pointer event */ |
|
101 enum TEventResponse |
|
102 { |
|
103 EEventWasNotConsumed, /** < Indicates that the FEP did not process the event. */ |
|
104 EEventWasConsumed /** < Indicates that the FEP did process the event. */ |
|
105 }; |
|
106 |
|
107 /** Enables FEPs to have some code called but not in the context of the current |
|
108 call stack, hence the name "deferred". |
|
109 |
|
110 For an explanation of the intended use of this class, see |
|
111 CCoeFep::MakeDeferredFunctionCall(). */ |
|
112 class MDeferredFunctionCall |
|
113 { |
|
114 public: |
|
115 /** This function is called from within a high-priority active object's RunL() |
|
116 shortly after the active object has been queued by calling CCoeFep::MakeDeferredFunctionCall(). */ |
|
117 virtual void ExecuteFunctionL()=0; |
|
118 private: // reserved. do not override! |
|
119 IMPORT_C virtual void MDeferredFunctionCall_Reserved_1(); |
|
120 IMPORT_C virtual void MDeferredFunctionCall_Reserved_2(); |
|
121 }; |
|
122 |
|
123 /** FEPs send character codes to the application underneath them using SimulateKeyEventsL(). |
|
124 Occasionally a FEP may wish to also specify the modifiers (e.g. Fn, Ctrl, |
|
125 Shift) to be sent with that character code. In this case, they should use |
|
126 the overload of CCoeFep::SimulateKeyEventsL() which takes an array of MModifiedCharacters. */ |
|
127 class MModifiedCharacter |
|
128 { |
|
129 public: |
|
130 /** Returns the character code of the key combination. |
|
131 |
|
132 @return The character code of the key combination. */ |
|
133 virtual TUint CharacterCode() const=0; |
|
134 /** Returns a TUint which indicates which modifiers to override, rather than using |
|
135 the current state of the keyboard's modifiers. |
|
136 |
|
137 @return The modifiers to override in the key combination. */ |
|
138 virtual TUint ModifierMask() const=0; |
|
139 /** Returns a TUint which indicates which of the modifiers specified in the mask |
|
140 (returned by ModifierMask()) must be on and which must be off. |
|
141 |
|
142 @return Indicates which of the modifiers specified in the mask (returned by |
|
143 ModifierMask()) must be on and which must be off. */ |
|
144 virtual TUint ModifierValues() const=0; |
|
145 private: // reserved. do not override! |
|
146 IMPORT_C virtual void MModifiedCharacter_Reserved_1(); |
|
147 IMPORT_C virtual void MModifiedCharacter_Reserved_2(); |
|
148 }; |
|
149 |
|
150 public: |
|
151 IMPORT_C virtual ~CCoeFep(); |
|
152 IMPORT_C TBool IsSimulatingKeyEvent() const; |
|
153 IMPORT_C TBool IsTurnedOnByL(const TKeyEvent& aKeyEvent) const; |
|
154 IMPORT_C TBool IsTurnedOffByL(const TKeyEvent& aKeyEvent) const; |
|
155 public: // new public virtual functions |
|
156 /** Cancels the FEP transaction. |
|
157 |
|
158 A FEP transaction begins when an event is first intercepted by the FEP and |
|
159 ends either when the processed text is committed to the application underneath, |
|
160 or if it is cancelled. */ |
|
161 virtual void CancelTransaction()=0; |
|
162 public: |
|
163 IMPORT_C void OnStartingHandlingKeyEvent_WithDownUpFilterLC(); |
|
164 IMPORT_C void OnStartingHandlingKeyEvent_NoDownUpFilterLC(); |
|
165 IMPORT_C TKeyResponse OnFinishingHandlingKeyEvent_WithDownUpFilterL(TEventCode aEventCode, const TKeyEvent& aKeyEvent, TKeyResponse aKeyResponse); |
|
166 IMPORT_C TKeyResponse OnFinishingHandlingKeyEvent_NoDownUpFilterL(TEventCode aEventCode, const TKeyEvent& aKeyEvent, TKeyResponse aKeyResponse); |
|
167 protected: |
|
168 IMPORT_C CCoeFep(CCoeEnv& aConeEnvironment); |
|
169 IMPORT_C void BaseConstructL(const CCoeFepParameters& aFepParameters); |
|
170 IMPORT_C void ReadAllAttributesL(); |
|
171 IMPORT_C void MakeDeferredFunctionCall(MDeferredFunctionCall& aDeferredFunctionCall); |
|
172 IMPORT_C void SimulateKeyEventsL(const TArray<TUint>& aArrayOfCharacters); |
|
173 IMPORT_C void SimulateKeyEventsL(const TArray<MModifiedCharacter>& aArrayOfModifiedCharacters); |
|
174 IMPORT_C void WriteAttributeDataAndBroadcastL(TUid aAttributeUid); |
|
175 IMPORT_C void WriteAttributeDataAndBroadcastL(const TArray<TUid>& aAttributeUids); |
|
176 IMPORT_C TBool IsOn() const; |
|
177 public: // not for external use |
|
178 void SetOnState(TBool aOnState); |
|
179 private: |
|
180 class CHighPriorityActive; |
|
181 class CLowPriorityActive; |
|
182 class CCoeFepExtra; |
|
183 private: |
|
184 void DoOnStartingHandlingKeyEventLC(TUint aFlagNoDownUpFilter); |
|
185 TKeyResponse DoOnFinishingHandlingKeyEventL(TEventCode aEventCode, const TKeyEvent& aKeyEvent, TKeyResponse aKeyResponse); |
|
186 static void TurnOffKeyEventHandlingFlags(TAny* aFlags); |
|
187 // from MFepAttributeStorer |
|
188 IMPORT_C virtual void MFepAttributeStorer_Reserved_1(); |
|
189 IMPORT_C virtual void MFepAttributeStorer_Reserved_2(); |
|
190 // from MCoeForegroundObserver |
|
191 IMPORT_C virtual void MCoeForegroundObserver_Reserved_1(); |
|
192 IMPORT_C virtual void MCoeForegroundObserver_Reserved_2(); |
|
193 // from MCoeFocusObserver |
|
194 IMPORT_C virtual void MCoeFocusObserver_Reserved_1(); |
|
195 IMPORT_C virtual void MCoeFocusObserver_Reserved_2(); |
|
196 // from MCoeMessageObserver |
|
197 IMPORT_C virtual TMessageResponse HandleMessageL(TUint32 aClientHandleOfTargetWindowGroup, TUid aMessageUid, const TDesC8& aMessageParameters); |
|
198 IMPORT_C virtual void MCoeMessageObserver_Reserved_1(); |
|
199 IMPORT_C virtual void MCoeMessageObserver_Reserved_2(); |
|
200 // new private virtual functions |
|
201 /** Called to notify the FEP that it has either just been turned on or just been |
|
202 turned off (it can find out which by calling CCoeFep::IsOn()). |
|
203 |
|
204 If FEPs want to change their appearance when they are off (e.g. make themselves |
|
205 invisible), then they should implement this function accordingly. |
|
206 |
|
207 @publishedAll |
|
208 @released */ |
|
209 virtual void IsOnHasChangedState()=0; |
|
210 |
|
211 /** |
|
212 @deprecated */ |
|
213 virtual void OfferKeyEventL(TEventResponse& /*aEventResponse*/, const TKeyEvent& /*aKeyEvent*/, TEventCode /*aEventCode*/){}; |
|
214 |
|
215 /** |
|
216 @deprecated */ |
|
217 virtual void OfferPointerEventL(TEventResponse& /*aEventResponse*/, const TPointerEvent& /*aPointerEvent*/, const CCoeControl* /*aWindowOwningControl*/){}; |
|
218 |
|
219 /** |
|
220 @deprecated */ |
|
221 virtual void OfferPointerBufferReadyEventL(TEventResponse& /*aEventResponse*/, const CCoeControl* /*aWindowOwningControl*/){}; |
|
222 private: // reserved. do not override! |
|
223 IMPORT_C virtual void CCoeFep_Reserved_1(); |
|
224 IMPORT_C virtual void CCoeFep_Reserved_2(); |
|
225 private: |
|
226 class SKeyEvent; |
|
227 CCoeEnv& iConeEnvironment; |
|
228 TUint iFlags; |
|
229 CHighPriorityActive* iHighPriorityActive; |
|
230 CCoeFepExtra* iExtra; |
|
231 SKeyEvent* iLastKeyEvent; |
|
232 TUint iSpare[13]; |
|
233 }; |
|
234 |
|
235 |
|
236 /** Specifies the mixin protocol for handling pointer events in inline text. |
|
237 |
|
238 This class should be overridden by front end processors which support inline editing. |
|
239 |
|
240 An instance of a class which implements this protocol should be passed to |
|
241 MCoeFepAwareTextEditor::StartFepInlineEditL(). |
|
242 |
|
243 @publishedAll |
|
244 @released */ |
|
245 class MFepPointerEventHandlerDuringInlineEdit // to be overridden by inline-editing front-end processors |
|
246 { |
|
247 public: |
|
248 /** This function is called when a pointer event is received within the inline |
|
249 text. It may need to update the cursor position within the inline text and |
|
250 do text selection in response to drag events. |
|
251 |
|
252 @param aType Pointer event types. |
|
253 @param aModifiers Modifier keys (SHIFT, CTRL, FN etc.). |
|
254 @param aPositionInInlineText The position at which the pointer event occurred, |
|
255 as an offset from the start of the inline text string. */ |
|
256 virtual void HandlePointerEventInInlineTextL(TPointerEvent::TType aType, TUint aModifiers, TInt aPositionInInlineText)=0; |
|
257 private: // reserved. do not override! |
|
258 IMPORT_C virtual void MFepPointerEventHandlerDuringInlineEdit_Reserved_1(); |
|
259 IMPORT_C virtual void MFepPointerEventHandlerDuringInlineEdit_Reserved_2(); |
|
260 }; |
|
261 |
|
262 class TCharFormat; |
|
263 class TCursorSelection; |
|
264 class MFormCustomDraw; |
|
265 class MFepInlineTextFormatRetriever; |
|
266 class MCoeFepAwareTextEditor_Extension1; |
|
267 |
|
268 |
|
269 /** Specifies a protocol for FEP-aware text editors. |
|
270 |
|
271 TCoeInputCapabilities::FepAwareTextEditor() returns a pointer to an object |
|
272 of this class. A NULL return value indicates that the interface is not supported |
|
273 by any of the currently focused controls. |
|
274 |
|
275 Inline editing means composing text directly in the target text editor control |
|
276 rather than in the FEP's edit window first. The target text editor must implement |
|
277 the MCoeFepAwareTextEditor interface in order to support inline text. The |
|
278 inline text may be differentiated from the surrounding text by the use of |
|
279 different formatting. These differences are removed when the inline text transaction |
|
280 is committed (causing the inline text to become a real part of the document). |
|
281 Cancelling the inline text transaction deletes the inline text and restores |
|
282 any previously selected text. A benefit of inline editing is that the user |
|
283 only has to concentrate on one area of the screen rather than two. |
|
284 |
|
285 An inline editing transaction consists of the following sequence of function |
|
286 calls: |
|
287 |
|
288 - a call to StartFepInlineEditL() |
|
289 |
|
290 - zero, one or more calls to UpdateFepInlineTextL() |
|
291 |
|
292 - a call to either CommitFepInlineEditL() or CancelFepInlineEdit() |
|
293 |
|
294 @publishedAll |
|
295 @released */ |
|
296 class MCoeFepAwareTextEditor // to be overridden by text-editors |
|
297 { |
|
298 public: |
|
299 /** |
|
300 Starts a FEP inline editing transaction. |
|
301 |
|
302 Inserts a descriptor containing the initial inline text into the text editor. |
|
303 The inline text should normally replace any selected text. |
|
304 |
|
305 The final three parameters are instances of abstract classes, so that the |
|
306 caller of this function must create and instantiate classes deriving from |
|
307 them. These instances must remain in existence for the entire duration of |
|
308 the inline editing transaction. |
|
309 |
|
310 Inline editing should not already be taking place when this function is called. |
|
311 |
|
312 @param aInitialInlineText The inline text to insert into the text editor. |
|
313 @param aPositionOfInsertionPointInInlineText An insertion position within the |
|
314 inline text. This is an offset from the start of the inline text. |
|
315 @param aCursorVisibility ETrue for visible text cursor, EFalse for invisible |
|
316 text cursor in the text editor. |
|
317 @param aCustomDraw Pointer to a custom drawing object. May be used to do advanced |
|
318 formatting of the inline text. This parameter is optional; a NULL pointer |
|
319 may be specified. |
|
320 @param aInlineTextFormatRetriever Defines a single member function, GetFormatOfFepInlineText() |
|
321 which is used by the text editor to find out the formatting to apply to the |
|
322 inline text. It is also possible to apply different formatting to different |
|
323 parts of the inline text. |
|
324 @param aPointerEventHandlerDuringInlineEdit Defines a single function, HandlePointerEventInInlineTextL() |
|
325 which is called when a pointer event is received within the inline text. This |
|
326 function might update the cursor position within the inline text and do text |
|
327 selection. |
|
328 */ |
|
329 virtual void StartFepInlineEditL(const TDesC& aInitialInlineText, TInt aPositionOfInsertionPointInInlineText, |
|
330 TBool aCursorVisibility, const MFormCustomDraw* aCustomDraw, MFepInlineTextFormatRetriever& aInlineTextFormatRetriever, |
|
331 MFepPointerEventHandlerDuringInlineEdit& aPointerEventHandlerDuringInlineEdit)=0; |
|
332 /** Updates the inline text. |
|
333 |
|
334 Called when a character is added to or deleted from the inline text. |
|
335 |
|
336 The descriptor aNewInlineText contains the entire new inline text string, |
|
337 not just the new text to be combined with the old inline text. |
|
338 |
|
339 @param aNewInlineText Descriptor which holds the entire new inline text string. |
|
340 @param aPositionOfInsertionPointInInlineText The position of the insertion |
|
341 point (i.e. the cursor) within the inline text string aNewInlineText. This |
|
342 is an offset from the start of the string. */ |
|
343 virtual void UpdateFepInlineTextL(const TDesC& aNewInlineText, TInt aPositionOfInsertionPointInInlineText)=0; |
|
344 /** Sets the visibility of the text cursor in the text editor. |
|
345 |
|
346 The cursor visibility is initialised using StartFepInlineEditL(). SetInlineEditingCursorVisibilityL() |
|
347 is provided for FEPs which need to change the visibility of the cursor during |
|
348 the inline editing transaction. |
|
349 |
|
350 @param aCursorVisibility ETrue for visible text cursor, EFalse for invisible |
|
351 text cursor. */ |
|
352 virtual void SetInlineEditingCursorVisibilityL(TBool aCursorVisibility)=0; |
|
353 IMPORT_C void CommitFepInlineEditL(CCoeEnv& aConeEnvironment); |
|
354 /** Cancels the inline editing transaction. |
|
355 |
|
356 The edit window should be rolled back to the state it was in before the FEP |
|
357 transaction started, i.e. any inline text in the document which has not yet |
|
358 been committed should be removed. If the inline text has replaced existing text, |
|
359 (e.g. a selection) the replaced text should be reinstated. */ |
|
360 virtual void CancelFepInlineEdit()=0; |
|
361 // with regard to the behaviour of the following functions (except GetScreenCoordinatesForFepL), |
|
362 // note that when inline editing, the contents of the editor will be such that the text constituting |
|
363 // the selection immediately prior to inline editing will be replaced by the inline text |
|
364 // (CancelFepInlineEdit reinstates the previous selection) |
|
365 /** Returns the total number of characters in the text editor. |
|
366 |
|
367 @return The total number of characters in the text editor. */ |
|
368 virtual TInt DocumentLengthForFep() const=0; |
|
369 /** Returns the upper limit (if any) on the length of text that the text editor |
|
370 can hold. |
|
371 |
|
372 @return The maximum number of characters that the text editor can hold. */ |
|
373 virtual TInt DocumentMaximumLengthForFep() const=0; |
|
374 /** Sets the range of characters in the text editor which should be selected. |
|
375 |
|
376 @param aCursorSelection Contains the cursor and anchor positions for the selection. */ |
|
377 virtual void SetCursorSelectionForFepL(const TCursorSelection& aCursorSelection)=0; |
|
378 /** Gets the range of characters in the text editor which are selected. |
|
379 |
|
380 @param aCursorSelection On return, contains the cursor and anchor positions |
|
381 of the selection. */ |
|
382 virtual void GetCursorSelectionForFep(TCursorSelection& aCursorSelection) const=0; |
|
383 /** Copies a portion of the text editor's text content into a descriptor. |
|
384 |
|
385 @param aEditorContent A descriptor; on return contains a copy of a portion |
|
386 of the text. |
|
387 @param aDocumentPosition The document position in the text editor from which |
|
388 to copy. |
|
389 @param aLengthToRetrieve The number of characters to copy. */ |
|
390 virtual void GetEditorContentForFep(TDes& aEditorContent, TInt aDocumentPosition, TInt aLengthToRetrieve) const=0; |
|
391 /** Gets the character formatting which applies to the document position specified. |
|
392 |
|
393 This function allows FEPs to find out the ambient formatting so that the FEP |
|
394 can choose a format for the inline text that will clearly differentiate it |
|
395 from the surrounding text. |
|
396 |
|
397 @param aFormat On return, contains the character formatting which applies |
|
398 to the character at aDocumentPosition. |
|
399 @param aDocumentPosition The document position of interest. */ |
|
400 virtual void GetFormatForFep(TCharFormat& aFormat, TInt aDocumentPosition) const=0; |
|
401 /** Gets the x,y screen coordinates for the left hand side of the baseline of the |
|
402 character located at a specified document position. |
|
403 |
|
404 Also gets the height (ascent + descent) and ascent of the font of the character. |
|
405 This function could be used to position the FEP window as close as possible to |
|
406 the insertion point in the text editor. |
|
407 |
|
408 @param aLeftSideOfBaseLine On return, contains the x,y coordinates of the |
|
409 left side of the baseline of the character located at aDocumentPosition. |
|
410 @param aHeight On return, contains the height (ascent + descent) of the font |
|
411 of the character at aDocumentPosition. |
|
412 @param aAscent On return, contains the ascent of the font of the character |
|
413 at aDocumentPosition. |
|
414 @param aDocumentPosition The document position of interest. */ |
|
415 virtual void GetScreenCoordinatesForFepL(TPoint& aLeftSideOfBaseLine, TInt& aHeight, TInt& aAscent, TInt aDocumentPosition) const=0; |
|
416 |
|
417 IMPORT_C MCoeFepAwareTextEditor_Extension1* Extension1(); |
|
418 private: |
|
419 /** Private function called by CommitFepInlineEditL(). |
|
420 |
|
421 Implementations should commit the inline text to the document. This |
|
422 ends the inline editing transaction and causes the inline text to |
|
423 become a part of the document. |
|
424 |
|
425 @publishedAll |
|
426 @released */ |
|
427 virtual void DoCommitFepInlineEditL()=0; |
|
428 IMPORT_C virtual MCoeFepAwareTextEditor_Extension1* Extension1(TBool& aSetToTrue); |
|
429 private: // reserved. do not override! |
|
430 IMPORT_C virtual void MCoeFepAwareTextEditor_Reserved_2(); |
|
431 }; |
|
432 |
|
433 |
|
434 class MLayDoc; |
|
435 |
|
436 /** |
|
437 MCoeFepLayDocExtension is an interface class which should be derived from by test editors to |
|
438 provide access to the current MLayDoc object, and to set a new MLayDoc object. |
|
439 Used directly from the FEP to decorate the inline edit text, without changing |
|
440 the actual document text. |
|
441 |
|
442 @publishedAll |
|
443 @released |
|
444 */ |
|
445 class MCoeFepLayDocExtension |
|
446 { |
|
447 public: |
|
448 /** |
|
449 Retrives the current MLayDoc object from the text editor |
|
450 |
|
451 @return Pointer to a MLayDoc object. |
|
452 */ |
|
453 virtual MLayDoc* GetCurrentMLayDoc() const = 0; |
|
454 |
|
455 /** |
|
456 Sets a new MLayDoc object into the CTextLayout object |
|
457 |
|
458 @param aLayDoc The new layout document |
|
459 */ |
|
460 virtual void SetMLayDoc(MLayDoc* aLayDoc) = 0; |
|
461 |
|
462 /** |
|
463 Retrives inline edit positioning information from the editor |
|
464 @param "TInt& aPositionInDocument" Position of the text in the document |
|
465 @param "TInt& aCursorPositionInDocument" Position of the cursor in the document |
|
466 @param "TInt& aSelectionLength" The number of characters in the selected text |
|
467 */ |
|
468 virtual void GetFepEditorState(TInt& aPositionInDocument, TInt& aCursorPositionInDocument, TInt& aSelectionLength) = 0; |
|
469 |
|
470 /** |
|
471 Used to tell the editor when the size of the inline edit has changed, so |
|
472 the text layout can update itself. Should be called before and after the inline |
|
473 edit has been decorated. |
|
474 @param "TCursorSelection aSelection" Position of the line edit from the beginning of the text |
|
475 @param "TInt aDeletedChars" Number of character deleted since the last time the text was formatted. |
|
476 |
|
477 */ |
|
478 virtual void HandleInsertDeleteL(TCursorSelection aSelection,TInt aDeletedChars) = 0; |
|
479 private: // reserved. do not override! |
|
480 IMPORT_C virtual void MCoeFepLayDocExtension_Reserved_1(); |
|
481 IMPORT_C virtual void MCoeFepLayDocExtension_Reserved_2(); |
|
482 }; |
|
483 |
|
484 |
|
485 /** An interface class which may be derived from by text editors to enable FEPs |
|
486 to store state information inside the editor. |
|
487 To be overridden by text-editors |
|
488 |
|
489 The CState class, defined within the scope of MCoeFepAwareTextEditor_Extension1 |
|
490 represents the state information. This is information specific to the control |
|
491 which is only of interest to the FEP. |
|
492 |
|
493 A class which implements this interface must implement the pure virtual functions |
|
494 State() and SetStateTransferingOwnershipL() , to get and set the state. The |
|
495 class should also implement the MCoeFepAwareTextEditor interface. It must |
|
496 override the private virtual MCoeFepAwareTextEditor::Extension1() to return |
|
497 a pointer to itself (the default implementation returns NULL). The private |
|
498 virtual MCoeFepAwareTextEditor::Extension1() function is called by the public, |
|
499 non-virtual MCoeFepAwareTextEditor::Extension1() function. |
|
500 |
|
501 For example, if a FEP wants to set some state information in a text editor |
|
502 which is about to lose focus, the FEP should first call the editor's Extension1() |
|
503 function. If this returns non-NULL, the FEP should call the editor's implementation |
|
504 of SetStateTransferingOwnershipL() , passing in an object of a class derived |
|
505 from CState , which holds the state information. It should also pass in a |
|
506 UID which uniquely identifies the FEP. Later, when focus returns to the editor, |
|
507 the FEP can call State() to retrieve the state information it previously set. |
|
508 Note that CState has several reserved functions, to enable it to be extended |
|
509 in future, while retaining backwards compatibility. |
|
510 |
|
511 @publishedAll |
|
512 @released */ |
|
513 class MCoeFepAwareTextEditor_Extension1 |
|
514 { |
|
515 public: |
|
516 class CState : public CBase |
|
517 /** State information for a text editor control. |
|
518 This is information specific to the control which is only of interest to the |
|
519 FEP which sets it. */ |
|
520 { |
|
521 protected: |
|
522 IMPORT_C CState(); |
|
523 IMPORT_C void BaseConstructL(); |
|
524 public: |
|
525 IMPORT_C virtual ~CState(); |
|
526 private: // reserved. do not override! |
|
527 IMPORT_C virtual void CState_Reserved_1(); |
|
528 IMPORT_C virtual void CState_Reserved_2(); |
|
529 IMPORT_C virtual void CState_Reserved_3(); |
|
530 IMPORT_C virtual void CState_Reserved_4(); |
|
531 private: |
|
532 TAny* iSpareForFutureUse; |
|
533 }; |
|
534 public: |
|
535 /** Sets state information in the text editor. |
|
536 |
|
537 This function must only transfer ownership of the state object after it has |
|
538 successfully done everything that can leave. |
|
539 |
|
540 @param aState Pointer to the state information object. |
|
541 @param aTypeSafetyUid A UID which uniquely identifies the FEP which is calling |
|
542 this function. The text editor should store this value for use by the State() |
|
543 function. */ |
|
544 virtual void SetStateTransferingOwnershipL(CState* aState, TUid aTypeSafetyUid)=0; // this function must only transfer ownership after it has successfully done everything that can leave |
|
545 /** Gets the state information previously set using SetStateTransferingOwnershipL(). |
|
546 |
|
547 This function does not transfer ownership. The function should first check |
|
548 that aTypeSafetyUid matches the UID value previously specified by SetStateTransferingOwnershipL(). |
|
549 If it doesn't match, the function should return NULL. |
|
550 |
|
551 @param aTypeSafetyUid A UID which uniquely identifies the FEP which is calling |
|
552 this function. The purpose of this is to enable the FEP to safely downcast |
|
553 the CState pointer returned by this function to a pointer to a derived class |
|
554 known about by the FEP. |
|
555 @return Pointer to the state information object. */ |
|
556 virtual CState* State(TUid aTypeSafetyUid)=0; |
|
557 public: |
|
558 /** Updates the inline text. |
|
559 |
|
560 Called when a character is added to or deleted from the inline text. |
|
561 |
|
562 The descriptor aNewInlineText contains the entire new inline text string, |
|
563 not just the new text to be combined with the old inline text. |
|
564 |
|
565 @param aSetToTrue Boolean set to EFalse by the caller and subsequently to ETrue by the function indicating that |
|
566 this is the implemented version and not the previous reserved funtion. |
|
567 @param aCursorSelection The position of any hilighted text. |
|
568 @param aNewInlineText Descriptor which holds the entire new inline text string. |
|
569 @param aPositionOfInsertionPointInInlineText |
|
570 The position of the insertion point (i.e. the cursor) within the inline text string aNewInlineText. |
|
571 This is an offset from the start of the string. |
|
572 */ |
|
573 IMPORT_C virtual void StartFepInlineEditL(TBool& aSetToTrue, const TCursorSelection& aCursorSelection, |
|
574 const TDesC& aInitialInlineText, TInt aPositionOfInsertionPointInInlineText, TBool aCursorVisibility, |
|
575 const MFormCustomDraw* aCustomDraw, MFepInlineTextFormatRetriever& aInlineTextFormatRetriever, |
|
576 MFepPointerEventHandlerDuringInlineEdit& aPointerEventHandlerDuringInlineEdit); |
|
577 |
|
578 /** Changes the cursor displayed to indicate different modes of operation. For example how text is enterered |
|
579 @param aSetToTrue Boolean set to EFalse by the caller and subsequently to ETrue by the function indicating that |
|
580 this is the implemented version and not the previously reserved funtion. |
|
581 @param aTextCursor The new cursor to be displayed. |
|
582 */ |
|
583 IMPORT_C virtual void SetCursorType(TBool& aSetToTrue, const TTextCursor& aTextCursor); |
|
584 |
|
585 /** |
|
586 Retrieves the current MCoeFepLayDocExtension object from the text editor |
|
587 @param aSetToTrue Boolean set to EFalse by the caller and subsequently to ETrue by the function indicating that |
|
588 this is the implemented version and not the previously reserved funtion. |
|
589 */ |
|
590 IMPORT_C virtual MCoeFepLayDocExtension* GetFepLayDocExtension(TBool& aSetToTrue); |
|
591 private: // reserved. do not override! |
|
592 IMPORT_C virtual void MCoeFepAwareTextEditor_Extension1_Reserved_4(); |
|
593 }; |
|
594 |
|
595 |
|
596 /** Retrieves a control's caption for use by a FEP. |
|
597 |
|
598 An example of a caption is the non-editable text description displayed |
|
599 alongside each item in a dialog. |
|
600 |
|
601 TCoeInputCapabilities::CaptionRetrieverForFep() returns a pointer to an object |
|
602 of this class. A NULL return value indicates that the interface is not supported |
|
603 by any of the currently focused controls. If not NULL, call GetCaptionForFep(), |
|
604 which fills the supplied buffer with the control's caption, truncating it |
|
605 if the supplied buffer is too small for the whole caption. |
|
606 |
|
607 @publishedAll |
|
608 @released */ |
|
609 class MCoeCaptionRetrieverForFep // to be overridden by captioned-controls |
|
610 { |
|
611 public: |
|
612 /** An implementation of this function should fill aCaption with the target control's |
|
613 caption (or as much of the caption as will fit). |
|
614 |
|
615 For example, code similar to the following might be used (assuming that your caption is |
|
616 stored internally in iCaption): |
|
617 |
|
618 @code |
|
619 const TInt maximumLength=aCaption.MaxLength(); |
|
620 if (iCaption.Length()>maximumLength) |
|
621 aCaption=iCaption.Left(maximumLength); |
|
622 else |
|
623 aCaption=iCaption; |
|
624 |
|
625 @endcode |
|
626 @param aCaption On return, this should be set to the caption of the target |
|
627 control. */ |
|
628 virtual void GetCaptionForFep(TDes& aCaption) const=0; // gets as much as will fit in aCaption |
|
629 private: // reserved. do not override! |
|
630 IMPORT_C virtual void MCoeCaptionRetrieverForFep_Reserved_1(); |
|
631 IMPORT_C virtual void MCoeCaptionRetrieverForFep_Reserved_2(); |
|
632 }; |
|
633 |
|
634 #endif // __FEPBASE_H__ |
|
635 |