epoc32/include/mw/fepbase.h
branchSymbian2
changeset 3 e1b950c65cb4
parent 2 2fe1408b6811
child 4 837f303aceeb
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/epoc32/include/mw/fepbase.h	Wed Mar 31 12:27:01 2010 +0100
     1.3 @@ -0,0 +1,634 @@
     1.4 +// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
     1.5 +// All rights reserved.
     1.6 +// This component and the accompanying materials are made available
     1.7 +// under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
     1.8 +// which accompanies this distribution, and is available
     1.9 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
    1.10 +//
    1.11 +// Initial Contributors:
    1.12 +// Nokia Corporation - initial contribution.
    1.13 +//
    1.14 +// Contributors:
    1.15 +//
    1.16 +// Description:
    1.17 +//
    1.18 +
    1.19 +#ifndef __FEPBASE_H__
    1.20 +#define __FEPBASE_H__
    1.21 +
    1.22 +#include <e32std.h>
    1.23 +#include <e32base.h>
    1.24 +#include <f32file.h>
    1.25 +#include <w32std.h>
    1.26 +#include <coedef.h>
    1.27 +#include <coemain.h>
    1.28 +#include <fepbutils.h>
    1.29 +#include <fepbconfig.h>
    1.30 +
    1.31 +class CCoeControl;
    1.32 +
    1.33 +
    1.34 +/** Specifies the mixin protocol for observing a FEP transaction.
    1.35 +
    1.36 +Applications which need to implement this protocol should derive from this 
    1.37 +class. The functions are not pure virtual because most applications will only 
    1.38 +need to override one of them.
    1.39 +
    1.40 +@see CCoeFep::MakeDeferredFunctionCall() 
    1.41 +@publishedAll 
    1.42 +@released */
    1.43 +class MCoeFepObserver
    1.44 +	{
    1.45 +public:
    1.46 +	// both of these functions do nothing by default - the reason that they are not pure 
    1.47 +	// virtual is that most applications will only want to override one of them
    1.48 +	IMPORT_C virtual void HandleStartOfTransactionL(); // the responsibility of FEPs to call
    1.49 +	IMPORT_C virtual void HandleCompletionOfTransactionL(); // the responsibility of FEPBASE to call - not to be called if the transaction is canceled
    1.50 +private: // reserved. do not override!	
    1.51 +	IMPORT_C virtual void MCoeFepObserver_Reserved_1();
    1.52 +	IMPORT_C virtual void MCoeFepObserver_Reserved_2();
    1.53 +	};
    1.54 +
    1.55 +/** Handles the start of a FEP transaction. 
    1.56 +
    1.57 +This is a non-member function which just calls aFepObserver.HandleStartOfTransactionL().
    1.58 +
    1.59 +It is called indirectly by a FEP to notify the application that it is starting a transaction. 
    1.60 +This is done by calling CCoeEnv::ForEachFepObserverCall() passing in 
    1.61 +FepObserverHandleStartOfTransactionL. Internally, this calls HandleStartOfTransactionL() for 
    1.62 +each MCoeFepObserver object that has been registered with the control environment.
    1.63 +
    1.64 +@param aFepObserver The FEP observer.
    1.65 +@see MCoeFepObserver::HandleStartOfTransactionL()
    1.66 +@publishedAll 
    1.67 +@released */
    1.68 +IMPORT_C void FepObserverHandleStartOfTransactionL(MCoeFepObserver& aFepObserver);
    1.69 +
    1.70 +
    1.71 +/** Abstract base class for all FEPs.
    1.72 +
    1.73 +FEP authors must derive a class from CCoeFep. The CCoeFep-derived class should 
    1.74 +implement all of its pure virtual functions including the ones which CCoeFep 
    1.75 +inherits from its base classes. For information on these functions, see the 
    1.76 +documentation of the base classes. The global NewFepL() function is used to 
    1.77 +create a fully initialised object of the derived class. 
    1.78 +
    1.79 +FEPs that need to intercept key events should own a CCoeControl-derived object. 
    1.80 +This object is referred to as the FEP control. The FEP control should 
    1.81 +be added to the control stack at a priority of ECoeStackPriorityFep, so that 
    1.82 +it receives first refusal of key events from the window server.
    1.83 +
    1.84 +In general, focus is retained by the underlying application. This has the 
    1.85 +advantage that the user can see where the output produced by the FEP will 
    1.86 +go. When focus is switched between controls, the FEP must be notified in case 
    1.87 +the input capability of the focussed control changes. For instance, the FEP 
    1.88 +needs to prevent the user composing a large amount of text only for it to 
    1.89 +be passed to a newly focussed control that cannot accept text input. CCoeFep 
    1.90 +derives from MCoeFocusObserver, which enables FEPs to receive notification 
    1.91 +when the focus for the underlying control changes. The implementation of MCoeFocusObserver's 
    1.92 +functions can call the enquiry functions of class TCoeInputCapabilities to 
    1.93 +find out what input capabilities are supported by the new target control (you 
    1.94 +need to get the TCoeInputCapabilities object from the application UI first: 
    1.95 +see CCoeAppUi::InputCapabilities()).
    1.96 +
    1.97 +@see NewFepL() 
    1.98 +@publishedAll 
    1.99 +@released */
   1.100 +class CCoeFep : public CBase, protected MFepAttributeStorer, public MCoeForegroundObserver, public MCoeFocusObserver, private MCoeMessageObserver
   1.101 +	{
   1.102 +public:
   1.103 +	/** Response to key or pointer event */
   1.104 +	enum TEventResponse
   1.105 +		{
   1.106 +		EEventWasNotConsumed,	/** < Indicates that the FEP did not process the event. */
   1.107 +		EEventWasConsumed		/** < Indicates that the FEP did process the event. */
   1.108 +		};
   1.109 +
   1.110 +	/** Enables FEPs to have some code called but not in the context of the current 
   1.111 +	call stack, hence the name "deferred".
   1.112 +
   1.113 +	For an explanation of the intended use of this class, see 
   1.114 +	CCoeFep::MakeDeferredFunctionCall(). */
   1.115 +	class MDeferredFunctionCall
   1.116 +		{
   1.117 +	public:
   1.118 +		/** This function is called from within a high-priority active object's RunL() 
   1.119 +		shortly after the active object has been queued by calling CCoeFep::MakeDeferredFunctionCall(). */
   1.120 +		virtual void ExecuteFunctionL()=0;
   1.121 +	private: // reserved. do not override!	
   1.122 +		IMPORT_C virtual void MDeferredFunctionCall_Reserved_1();
   1.123 +		IMPORT_C virtual void MDeferredFunctionCall_Reserved_2();
   1.124 +		};
   1.125 +
   1.126 +	/** FEPs send character codes to the application underneath them using SimulateKeyEventsL(). 
   1.127 +	Occasionally a FEP may wish to also specify the modifiers (e.g. Fn, Ctrl, 
   1.128 +	Shift) to be sent with that character code. In this case, they should use 
   1.129 +	the overload of CCoeFep::SimulateKeyEventsL() which takes an array of MModifiedCharacters. */
   1.130 +	class MModifiedCharacter
   1.131 +		{
   1.132 +	public:
   1.133 +		/** Returns the character code of the key combination.
   1.134 +		
   1.135 +		@return The character code of the key combination. */
   1.136 +		virtual TUint CharacterCode() const=0;
   1.137 +		/** Returns a TUint which indicates which modifiers to override, rather than using 
   1.138 +		the current state of the keyboard's modifiers.
   1.139 +	
   1.140 +		@return The modifiers to override in the key combination. */
   1.141 +		virtual TUint ModifierMask() const=0;
   1.142 +		/** Returns a TUint which indicates which of the modifiers specified in the mask 
   1.143 +		(returned by ModifierMask()) must be on and which must be off.
   1.144 +	
   1.145 +		@return Indicates which of the modifiers specified in the mask (returned by 
   1.146 +		ModifierMask()) must be on and which must be off. */
   1.147 +		virtual TUint ModifierValues() const=0;
   1.148 +	private: // reserved. do not override!	
   1.149 +		IMPORT_C virtual void MModifiedCharacter_Reserved_1();
   1.150 +		IMPORT_C virtual void MModifiedCharacter_Reserved_2();
   1.151 +		};
   1.152 +
   1.153 +public:
   1.154 +	IMPORT_C virtual ~CCoeFep();
   1.155 +	IMPORT_C TBool IsSimulatingKeyEvent() const;
   1.156 +	IMPORT_C TBool IsTurnedOnByL(const TKeyEvent& aKeyEvent) const;
   1.157 +	IMPORT_C TBool IsTurnedOffByL(const TKeyEvent& aKeyEvent) const;
   1.158 +public: // new public virtual functions
   1.159 +	/** Cancels the FEP transaction.
   1.160 +	
   1.161 +	A FEP transaction begins when an event is first intercepted by the FEP and 
   1.162 +	ends either when the processed text is committed to the application underneath, 
   1.163 +	or if it is cancelled. */
   1.164 +	virtual void CancelTransaction()=0;
   1.165 +public:
   1.166 +	IMPORT_C void OnStartingHandlingKeyEvent_WithDownUpFilterLC();
   1.167 +	IMPORT_C void OnStartingHandlingKeyEvent_NoDownUpFilterLC();
   1.168 +	IMPORT_C TKeyResponse OnFinishingHandlingKeyEvent_WithDownUpFilterL(TEventCode aEventCode, const TKeyEvent& aKeyEvent, TKeyResponse aKeyResponse);
   1.169 +	IMPORT_C TKeyResponse OnFinishingHandlingKeyEvent_NoDownUpFilterL(TEventCode aEventCode, const TKeyEvent& aKeyEvent, TKeyResponse aKeyResponse);
   1.170 +protected:
   1.171 +	IMPORT_C CCoeFep(CCoeEnv& aConeEnvironment);
   1.172 +	IMPORT_C void BaseConstructL(const CCoeFepParameters& aFepParameters);
   1.173 +	IMPORT_C void ReadAllAttributesL();
   1.174 +	IMPORT_C void MakeDeferredFunctionCall(MDeferredFunctionCall& aDeferredFunctionCall);
   1.175 +	IMPORT_C void SimulateKeyEventsL(const TArray<TUint>& aArrayOfCharacters);
   1.176 +	IMPORT_C void SimulateKeyEventsL(const TArray<MModifiedCharacter>& aArrayOfModifiedCharacters);
   1.177 +	IMPORT_C void WriteAttributeDataAndBroadcastL(TUid aAttributeUid);
   1.178 +	IMPORT_C void WriteAttributeDataAndBroadcastL(const TArray<TUid>& aAttributeUids);
   1.179 +	IMPORT_C TBool IsOn() const;
   1.180 +public: // not for external use
   1.181 +	void SetOnState(TBool aOnState);
   1.182 +private:
   1.183 +	class CHighPriorityActive;
   1.184 +	class CLowPriorityActive;
   1.185 +	class CCoeFepExtra;
   1.186 +private:
   1.187 +	void DoOnStartingHandlingKeyEventLC(TUint aFlagNoDownUpFilter);
   1.188 +	TKeyResponse DoOnFinishingHandlingKeyEventL(TEventCode aEventCode, const TKeyEvent& aKeyEvent, TKeyResponse aKeyResponse);
   1.189 +	static void TurnOffKeyEventHandlingFlags(TAny* aFlags);
   1.190 +	// from MFepAttributeStorer
   1.191 +	IMPORT_C virtual void MFepAttributeStorer_Reserved_1();
   1.192 +	IMPORT_C virtual void MFepAttributeStorer_Reserved_2();
   1.193 +	// from MCoeForegroundObserver
   1.194 +	IMPORT_C virtual void MCoeForegroundObserver_Reserved_1();
   1.195 +	IMPORT_C virtual void MCoeForegroundObserver_Reserved_2();
   1.196 +	// from MCoeFocusObserver
   1.197 +	IMPORT_C virtual void MCoeFocusObserver_Reserved_1();
   1.198 +	IMPORT_C virtual void MCoeFocusObserver_Reserved_2();
   1.199 +	// from MCoeMessageObserver
   1.200 +	IMPORT_C virtual TMessageResponse HandleMessageL(TUint32 aClientHandleOfTargetWindowGroup, TUid aMessageUid, const TDesC8& aMessageParameters);
   1.201 +	IMPORT_C virtual void MCoeMessageObserver_Reserved_1();
   1.202 +	IMPORT_C virtual void MCoeMessageObserver_Reserved_2();
   1.203 +	// new private virtual functions
   1.204 +	/** Called to notify the FEP that it has either just been turned on or just been 
   1.205 +	turned off (it can find out which by calling CCoeFep::IsOn()). 
   1.206 +	
   1.207 +	If FEPs want to change their appearance when they are off (e.g. make themselves 
   1.208 +	invisible), then they should implement this function accordingly. 
   1.209 +
   1.210 +	@publishedAll
   1.211 +	@released */
   1.212 +	virtual void IsOnHasChangedState()=0;
   1.213 +	
   1.214 +	/**
   1.215 +	@deprecated */
   1.216 +	virtual void OfferKeyEventL(TEventResponse& /*aEventResponse*/, const TKeyEvent& /*aKeyEvent*/, TEventCode /*aEventCode*/){};
   1.217 +
   1.218 +	/**
   1.219 +	@deprecated */
   1.220 +	virtual void OfferPointerEventL(TEventResponse& /*aEventResponse*/, const TPointerEvent& /*aPointerEvent*/, const CCoeControl* /*aWindowOwningControl*/){};
   1.221 +
   1.222 +	/**
   1.223 +	@deprecated */
   1.224 +	virtual void OfferPointerBufferReadyEventL(TEventResponse& /*aEventResponse*/, const CCoeControl* /*aWindowOwningControl*/){};
   1.225 +private:	// reserved. do not override!	
   1.226 +	IMPORT_C virtual void CCoeFep_Reserved_1();
   1.227 +	IMPORT_C virtual void CCoeFep_Reserved_2();
   1.228 +private:
   1.229 +	class SKeyEvent;
   1.230 +	CCoeEnv& iConeEnvironment;
   1.231 +	TUint iFlags;
   1.232 +	CHighPriorityActive* iHighPriorityActive;
   1.233 +	CCoeFepExtra* iExtra;
   1.234 +	SKeyEvent* iLastKeyEvent;
   1.235 +	TUint iSpare[13];
   1.236 +	};
   1.237 +
   1.238 +
   1.239 +/** Specifies the mixin protocol for handling pointer events in inline text. 
   1.240 +
   1.241 +This class should be overridden by front end processors which support inline editing.
   1.242 +
   1.243 +An instance of a class which implements this protocol should be passed to 
   1.244 +MCoeFepAwareTextEditor::StartFepInlineEditL(). 
   1.245 +
   1.246 +@publishedAll 
   1.247 +@released */
   1.248 +class MFepPointerEventHandlerDuringInlineEdit // to be overridden by inline-editing front-end processors
   1.249 +	{
   1.250 +public:
   1.251 +	/** This function is called when a pointer event is received within the inline 
   1.252 +	text. It may need to update the cursor position within the inline text and 
   1.253 +	do text selection in response to drag events.
   1.254 +	
   1.255 +	@param aType Pointer event types.
   1.256 +	@param aModifiers Modifier keys (SHIFT, CTRL, FN etc.).
   1.257 +	@param aPositionInInlineText The position at which the pointer event occurred, 
   1.258 +	as an offset from the start of the inline text string. */
   1.259 +	virtual void HandlePointerEventInInlineTextL(TPointerEvent::TType aType, TUint aModifiers, TInt aPositionInInlineText)=0;
   1.260 +private: // reserved. do not override!	
   1.261 +	IMPORT_C virtual void MFepPointerEventHandlerDuringInlineEdit_Reserved_1();
   1.262 +	IMPORT_C virtual void MFepPointerEventHandlerDuringInlineEdit_Reserved_2();
   1.263 +	};
   1.264 +
   1.265 +class TCharFormat;
   1.266 +class TCursorSelection;
   1.267 +class MFormCustomDraw;
   1.268 +class MFepInlineTextFormatRetriever;
   1.269 +class MCoeFepAwareTextEditor_Extension1;
   1.270 +
   1.271 +
   1.272 +/** Specifies a protocol for FEP-aware text editors.
   1.273 +
   1.274 +TCoeInputCapabilities::FepAwareTextEditor() returns a pointer to an object 
   1.275 +of this class. A NULL return value indicates that the interface is not supported 
   1.276 +by any of the currently focused controls.
   1.277 +
   1.278 +Inline editing means composing text directly in the target text editor control 
   1.279 +rather than in the FEP's edit window first. The target text editor must implement 
   1.280 +the MCoeFepAwareTextEditor interface in order to support inline text. The 
   1.281 +inline text may be differentiated from the surrounding text by the use of 
   1.282 +different formatting. These differences are removed when the inline text transaction 
   1.283 +is committed (causing the inline text to become a real part of the document). 
   1.284 +Cancelling the inline text transaction deletes the inline text and restores 
   1.285 +any previously selected text. A benefit of inline editing is that the user 
   1.286 +only has to concentrate on one area of the screen rather than two. 
   1.287 +
   1.288 +An inline editing transaction consists of the following sequence of function 
   1.289 +calls:
   1.290 +
   1.291 +- a call to StartFepInlineEditL()
   1.292 +
   1.293 +- zero, one or more calls to UpdateFepInlineTextL()
   1.294 +
   1.295 +- a call to either CommitFepInlineEditL() or CancelFepInlineEdit() 
   1.296 +
   1.297 +@publishedAll 
   1.298 +@released */
   1.299 +class MCoeFepAwareTextEditor // to be overridden by text-editors
   1.300 +	{
   1.301 +public:
   1.302 +	/** 
   1.303 +	Starts a FEP inline editing transaction. 
   1.304 +	
   1.305 +	Inserts a descriptor containing the initial inline text into the text editor. 
   1.306 +	The inline text should normally replace any selected text.
   1.307 +	
   1.308 +	The final three parameters are instances of abstract classes, so that the 
   1.309 +	caller of this function must create and instantiate classes deriving from 
   1.310 +	them. These instances must remain in existence for the entire duration of 
   1.311 +	the inline editing transaction.
   1.312 +	
   1.313 +	Inline editing should not already be taking place when this function is called.
   1.314 +	
   1.315 +	@param aInitialInlineText The inline text to insert into the text editor.
   1.316 +	@param aPositionOfInsertionPointInInlineText An insertion position within the 
   1.317 +	inline text. This is an offset from the start of the inline text.
   1.318 +	@param aCursorVisibility ETrue for visible text cursor, EFalse for invisible 
   1.319 +	text cursor in the text editor.
   1.320 +	@param aCustomDraw Pointer to a custom drawing object. May be used to do advanced 
   1.321 +	formatting of the inline text. This parameter is optional; a NULL pointer 
   1.322 +	may be specified.
   1.323 +	@param aInlineTextFormatRetriever Defines a single member function, GetFormatOfFepInlineText() 
   1.324 +	which is used by the text editor to find out the formatting to apply to the 
   1.325 +	inline text. It is also possible to apply different formatting to different 
   1.326 +	parts of the inline text.
   1.327 +	@param aPointerEventHandlerDuringInlineEdit Defines a single function, HandlePointerEventInInlineTextL() 
   1.328 +	which is called when a pointer event is received within the inline text. This 
   1.329 +	function might update the cursor position within the inline text and do text 
   1.330 +	selection. 
   1.331 +	*/
   1.332 +	virtual void StartFepInlineEditL(const TDesC& aInitialInlineText, TInt aPositionOfInsertionPointInInlineText, 
   1.333 +		TBool aCursorVisibility, const MFormCustomDraw* aCustomDraw, MFepInlineTextFormatRetriever& aInlineTextFormatRetriever, 
   1.334 +		MFepPointerEventHandlerDuringInlineEdit& aPointerEventHandlerDuringInlineEdit)=0;
   1.335 +	/** Updates the inline text. 
   1.336 +	
   1.337 +	Called when a character is added to or deleted from the inline text. 
   1.338 +	
   1.339 +	The descriptor aNewInlineText contains the entire new inline text string, 
   1.340 +	not just the new text to be combined with the old inline text.
   1.341 +	
   1.342 +	@param aNewInlineText Descriptor which holds the entire new inline text string.
   1.343 +	@param aPositionOfInsertionPointInInlineText The position of the insertion 
   1.344 +	point (i.e. the cursor) within the inline text string aNewInlineText. This 
   1.345 +	is an offset from the start of the string. */
   1.346 +	virtual void UpdateFepInlineTextL(const TDesC& aNewInlineText, TInt aPositionOfInsertionPointInInlineText)=0;
   1.347 +	/** Sets the visibility of the text cursor in the text editor.
   1.348 +	
   1.349 +	The cursor visibility is initialised using StartFepInlineEditL(). SetInlineEditingCursorVisibilityL() 
   1.350 +	is provided for FEPs which need to change the visibility of the cursor during 
   1.351 +	the inline editing transaction.
   1.352 +	
   1.353 +	@param aCursorVisibility ETrue for visible text cursor, EFalse for invisible 
   1.354 +	text cursor. */
   1.355 +	virtual void SetInlineEditingCursorVisibilityL(TBool aCursorVisibility)=0;
   1.356 +	IMPORT_C void CommitFepInlineEditL(CCoeEnv& aConeEnvironment);
   1.357 +	/** Cancels the inline editing transaction. 
   1.358 +	
   1.359 +	The edit window should be rolled back to the state it was in before the FEP 
   1.360 +	transaction started, i.e. any inline text in the document which has not yet 
   1.361 +	been committed should be removed. If the inline text has replaced existing text, 
   1.362 +	(e.g. a selection) the replaced text should be reinstated. */
   1.363 +	virtual void CancelFepInlineEdit()=0;
   1.364 +	// with regard to the behaviour of the following functions (except GetScreenCoordinatesForFepL), 
   1.365 +	// note that when inline editing, the contents of the editor will be such that the text constituting 
   1.366 +	// the selection immediately prior to inline editing will be replaced by the inline text 
   1.367 +	// (CancelFepInlineEdit reinstates the previous selection)
   1.368 +	/** Returns the total number of characters in the text editor.
   1.369 +	
   1.370 +	@return The total number of characters in the text editor. */
   1.371 +	virtual TInt DocumentLengthForFep() const=0;
   1.372 +	/** Returns the upper limit (if any) on the length of text that the text editor 
   1.373 +	can hold.
   1.374 +	
   1.375 +	@return The maximum number of characters that the text editor can hold. */
   1.376 +	virtual TInt DocumentMaximumLengthForFep() const=0;
   1.377 +	/** Sets the range of characters in the text editor which should be selected.
   1.378 +	
   1.379 +	@param aCursorSelection Contains the cursor and anchor positions for the selection. */
   1.380 +	virtual void SetCursorSelectionForFepL(const TCursorSelection& aCursorSelection)=0;
   1.381 +	/** Gets the range of characters in the text editor which are selected.
   1.382 +	
   1.383 +	@param aCursorSelection On return, contains the cursor and anchor positions 
   1.384 +	of the selection. */
   1.385 +	virtual void GetCursorSelectionForFep(TCursorSelection& aCursorSelection) const=0;
   1.386 +	/** Copies a portion of the text editor's text content into a descriptor.
   1.387 +	
   1.388 +	@param aEditorContent A descriptor; on return contains a copy of a portion 
   1.389 +	of the text.
   1.390 +	@param aDocumentPosition The document position in the text editor from which 
   1.391 +	to copy.
   1.392 +	@param aLengthToRetrieve The number of characters to copy. */
   1.393 +	virtual void GetEditorContentForFep(TDes& aEditorContent, TInt aDocumentPosition, TInt aLengthToRetrieve) const=0;
   1.394 +	/** Gets the character formatting which applies to the document position specified. 
   1.395 +
   1.396 +	This function allows FEPs to find out the ambient formatting so that the FEP 
   1.397 +	can choose a format for the inline text that will clearly differentiate it 
   1.398 +	from the surrounding text.
   1.399 +	
   1.400 +	@param aFormat On return, contains the character formatting which applies 
   1.401 +	to the character at aDocumentPosition.
   1.402 +	@param aDocumentPosition The document position of interest. */
   1.403 +	virtual void GetFormatForFep(TCharFormat& aFormat, TInt aDocumentPosition) const=0;
   1.404 +	/** Gets the x,y screen coordinates for the left hand side of the baseline of the 
   1.405 +	character located at a specified document position. 
   1.406 +
   1.407 +	Also gets the height (ascent + descent) and ascent of the font of the character. 
   1.408 +	This function could be used to position the FEP window as close as possible to 
   1.409 +	the insertion point in the text editor.
   1.410 +	
   1.411 +	@param aLeftSideOfBaseLine On return, contains the x,y coordinates of the 
   1.412 +	left side of the baseline of the character located at aDocumentPosition.
   1.413 +	@param aHeight On return, contains the height (ascent + descent) of the font 
   1.414 +	of the character at aDocumentPosition.
   1.415 +	@param aAscent On return, contains the ascent of the font of the character 
   1.416 +	at aDocumentPosition.
   1.417 +	@param aDocumentPosition The document position of interest. */
   1.418 +	virtual void GetScreenCoordinatesForFepL(TPoint& aLeftSideOfBaseLine, TInt& aHeight, TInt& aAscent, TInt aDocumentPosition) const=0;
   1.419 +	
   1.420 +	IMPORT_C MCoeFepAwareTextEditor_Extension1* Extension1();
   1.421 +private:
   1.422 +	/** Private function called by CommitFepInlineEditL(). 
   1.423 +	
   1.424 +	Implementations should commit the inline text to the document. This 
   1.425 +	ends the inline editing transaction and causes the inline text to 
   1.426 +	become a part of the document. 
   1.427 +
   1.428 +	@publishedAll
   1.429 +	@released */
   1.430 +	virtual void DoCommitFepInlineEditL()=0;
   1.431 +	IMPORT_C virtual MCoeFepAwareTextEditor_Extension1* Extension1(TBool& aSetToTrue);
   1.432 +private: // reserved. do not override!	
   1.433 +	IMPORT_C virtual void MCoeFepAwareTextEditor_Reserved_2();
   1.434 +	};
   1.435 +
   1.436 +
   1.437 +class MLayDoc;
   1.438 +
   1.439 +/**
   1.440 +MCoeFepLayDocExtension is an interface class which should be derived from by test editors to
   1.441 +provide access to the current MLayDoc object, and to set a new MLayDoc object.
   1.442 +Used directly from the FEP to decorate the inline edit text, without changing
   1.443 +the actual document text.
   1.444 +
   1.445 +@publishedAll 
   1.446 +@released  
   1.447 +*/
   1.448 +class MCoeFepLayDocExtension
   1.449 +	{
   1.450 +public:
   1.451 +	/**
   1.452 +	Retrives the current MLayDoc object from the text editor
   1.453 +	
   1.454 +	@return Pointer to a MLayDoc object.
   1.455 +	*/
   1.456 +	virtual MLayDoc* GetCurrentMLayDoc() const = 0;
   1.457 +	
   1.458 +	/**
   1.459 +	Sets a new MLayDoc object into the CTextLayout object
   1.460 +	
   1.461 +	@param aLayDoc The new layout document
   1.462 +	*/
   1.463 +	virtual void SetMLayDoc(MLayDoc* aLayDoc) = 0;
   1.464 +	
   1.465 +	/**
   1.466 +	Retrives inline edit positioning information from the editor
   1.467 +	@param 	"TInt& aPositionInDocument" 		Position of the text in the document
   1.468 +	@param 	"TInt& aCursorPositionInDocument" 	Position of the cursor in the document
   1.469 +	@param 	"TInt& aSelectionLength"			The number of characters in the selected text
   1.470 +	*/	 
   1.471 +	virtual void GetFepEditorState(TInt& aPositionInDocument, TInt& aCursorPositionInDocument, TInt& aSelectionLength) = 0;
   1.472 +
   1.473 +	/**
   1.474 +	Used to tell the editor when the size of the inline edit has changed, so
   1.475 +	the text layout can update itself. Should be called before and after the inline
   1.476 +	edit has been decorated.
   1.477 +	@param     	"TCursorSelection aSelection" 	Position of the line edit from the beginning of the text
   1.478 +    @param     	"TInt aDeletedChars" 			Number of character deleted since the last time the text was formatted.
   1.479 +	
   1.480 +	*/
   1.481 +	virtual void HandleInsertDeleteL(TCursorSelection aSelection,TInt aDeletedChars) = 0;
   1.482 +private: // reserved. do not override!	
   1.483 +	IMPORT_C virtual void MCoeFepLayDocExtension_Reserved_1();
   1.484 +	IMPORT_C virtual void MCoeFepLayDocExtension_Reserved_2();
   1.485 +	};
   1.486 +
   1.487 +
   1.488 +/** An interface class which may be derived from by text editors to enable FEPs 
   1.489 +to store state information inside the editor. 
   1.490 +To be overridden by text-editors
   1.491 +
   1.492 +The CState class, defined within the scope of MCoeFepAwareTextEditor_Extension1 
   1.493 +represents the state information. This is information specific to the control 
   1.494 +which is only of interest to the FEP.
   1.495 +
   1.496 +A class which implements this interface must implement the pure virtual functions 
   1.497 +State() and SetStateTransferingOwnershipL() , to get and set the state. The 
   1.498 +class should also implement the MCoeFepAwareTextEditor interface. It must 
   1.499 +override the private virtual MCoeFepAwareTextEditor::Extension1() to return 
   1.500 +a pointer to itself (the default implementation returns NULL). The private 
   1.501 +virtual MCoeFepAwareTextEditor::Extension1() function is called by the public, 
   1.502 +non-virtual MCoeFepAwareTextEditor::Extension1() function.
   1.503 +
   1.504 +For example, if a FEP wants to set some state information in a text editor 
   1.505 +which is about to lose focus, the FEP should first call the editor's Extension1() 
   1.506 +function. If this returns non-NULL, the FEP should call the editor's implementation 
   1.507 +of SetStateTransferingOwnershipL() , passing in an object of a class derived 
   1.508 +from CState , which holds the state information. It should also pass in a 
   1.509 +UID which uniquely identifies the FEP. Later, when focus returns to the editor, 
   1.510 +the FEP can call State() to retrieve the state information it previously set. 
   1.511 +Note that CState has several reserved functions, to enable it to be extended 
   1.512 +in future, while retaining backwards compatibility. 
   1.513 +
   1.514 +@publishedAll 
   1.515 +@released */
   1.516 +class MCoeFepAwareTextEditor_Extension1 
   1.517 +	{
   1.518 +public:
   1.519 +	class CState : public CBase
   1.520 +	/** State information for a text editor control. 
   1.521 +	This is information specific to the control which is only of interest to the 
   1.522 +	FEP which sets it. */
   1.523 +		{
   1.524 +	protected:
   1.525 +		IMPORT_C CState();
   1.526 +		IMPORT_C void BaseConstructL();
   1.527 +	public:
   1.528 +		IMPORT_C virtual ~CState();
   1.529 +	private: // reserved. do not override!	
   1.530 +		IMPORT_C virtual void CState_Reserved_1();
   1.531 +		IMPORT_C virtual void CState_Reserved_2();
   1.532 +		IMPORT_C virtual void CState_Reserved_3();
   1.533 +		IMPORT_C virtual void CState_Reserved_4();
   1.534 +	private:
   1.535 +		TAny* iSpareForFutureUse;
   1.536 +		};
   1.537 +public:
   1.538 +	/** Sets state information in the text editor.
   1.539 +	
   1.540 +	This function must only transfer ownership of the state object after it has 
   1.541 +	successfully done everything that can leave.
   1.542 +	
   1.543 +	@param aState Pointer to the state information object.
   1.544 +	@param aTypeSafetyUid A UID which uniquely identifies the FEP which is calling 
   1.545 +	this function. The text editor should store this value for use by the State() 
   1.546 +	function. */
   1.547 +	virtual void SetStateTransferingOwnershipL(CState* aState, TUid aTypeSafetyUid)=0; // this function must only transfer ownership after it has successfully done everything that can leave
   1.548 +	/** Gets the state information previously set using SetStateTransferingOwnershipL(). 
   1.549 +
   1.550 +	This function does not transfer ownership. The function should first check 
   1.551 +	that aTypeSafetyUid matches the UID value previously specified by SetStateTransferingOwnershipL(). 
   1.552 +	If it doesn't match, the function should return NULL.
   1.553 +	
   1.554 +	@param aTypeSafetyUid A UID which uniquely identifies the FEP which is calling 
   1.555 +	this function. The purpose of this is to enable the FEP to safely downcast 
   1.556 +	the CState pointer returned by this function to a pointer to a derived class 
   1.557 +	known about by the FEP.
   1.558 +	@return Pointer to the state information object. */
   1.559 +	virtual CState* State(TUid aTypeSafetyUid)=0;
   1.560 +public:
   1.561 +	/** Updates the inline text. 
   1.562 +	
   1.563 +	Called when a character is added to or deleted from the inline text. 
   1.564 +	
   1.565 +	The descriptor aNewInlineText contains the entire new inline text string, 
   1.566 +	not just the new text to be combined with the old inline text.
   1.567 +	
   1.568 +	@param aSetToTrue 		Boolean set to EFalse by the caller and subsequently to ETrue by the function indicating that
   1.569 +							this is the implemented version and not the previous reserved funtion.
   1.570 +	@param aCursorSelection The position of any hilighted text.
   1.571 +	@param aNewInlineText 	Descriptor which holds the entire new inline text string.
   1.572 +	@param aPositionOfInsertionPointInInlineText 
   1.573 +	The position of the insertion point (i.e. the cursor) within the inline text string aNewInlineText. 
   1.574 +	This is an offset from the start of the string. 
   1.575 +	*/
   1.576 +	IMPORT_C virtual void StartFepInlineEditL(TBool& aSetToTrue, const TCursorSelection& aCursorSelection, 
   1.577 +		const TDesC& aInitialInlineText, TInt aPositionOfInsertionPointInInlineText, TBool aCursorVisibility, 
   1.578 +		const MFormCustomDraw* aCustomDraw, MFepInlineTextFormatRetriever& aInlineTextFormatRetriever, 
   1.579 +		MFepPointerEventHandlerDuringInlineEdit& aPointerEventHandlerDuringInlineEdit);
   1.580 +	
   1.581 +	/** Changes the cursor displayed to indicate different modes of operation. For example how text is enterered
   1.582 +	@param aSetToTrue 		Boolean set to EFalse by the caller and subsequently to ETrue by the function indicating that
   1.583 +							this is the implemented version and not the previously reserved funtion.
   1.584 +	@param aTextCursor		The new cursor to be displayed.
   1.585 +	*/	
   1.586 +	IMPORT_C virtual void SetCursorType(TBool& aSetToTrue, const TTextCursor& aTextCursor);
   1.587 +	
   1.588 +	/**
   1.589 +	Retrieves the current MCoeFepLayDocExtension object from the text editor
   1.590 +	@param aSetToTrue 		Boolean set to EFalse by the caller and subsequently to ETrue by the function indicating that
   1.591 +							this is the implemented version and not the previously reserved funtion.
   1.592 +	*/
   1.593 +	IMPORT_C virtual MCoeFepLayDocExtension* GetFepLayDocExtension(TBool& aSetToTrue);
   1.594 +private: // reserved. do not override!	
   1.595 +	IMPORT_C virtual void MCoeFepAwareTextEditor_Extension1_Reserved_4();
   1.596 +	};
   1.597 +
   1.598 +
   1.599 +/** Retrieves a control's caption for use by a FEP. 
   1.600 +
   1.601 +An example of a caption is the non-editable text description displayed 
   1.602 +alongside each item in a dialog.
   1.603 +
   1.604 +TCoeInputCapabilities::CaptionRetrieverForFep() returns a pointer to an object 
   1.605 +of this class. A NULL return value indicates that the interface is not supported 
   1.606 +by any of the currently focused controls. If not NULL, call GetCaptionForFep(), 
   1.607 +which fills the supplied buffer with the control's caption, truncating it 
   1.608 +if the supplied buffer is too small for the whole caption. 
   1.609 +
   1.610 +@publishedAll
   1.611 +@released */
   1.612 +class MCoeCaptionRetrieverForFep // to be overridden by captioned-controls
   1.613 +	{
   1.614 +public:
   1.615 +	/** An implementation of this function should fill aCaption with the target control's 
   1.616 +	caption (or as much of the caption as will fit).
   1.617 +	
   1.618 +	For example, code similar to the following might be used (assuming that your caption is 
   1.619 +	stored internally in iCaption):
   1.620 +	
   1.621 +	@code
   1.622 +	const TInt maximumLength=aCaption.MaxLength();
   1.623 +	if (iCaption.Length()>maximumLength)
   1.624 +	    aCaption=iCaption.Left(maximumLength);
   1.625 +	else
   1.626 +	    aCaption=iCaption;
   1.627 +
   1.628 +	@endcode
   1.629 +	@param aCaption On return, this should be set to the caption of the target 
   1.630 +	control. */
   1.631 +	virtual void GetCaptionForFep(TDes& aCaption) const=0; // gets as much as will fit in aCaption
   1.632 +private: // reserved. do not override!	
   1.633 +	IMPORT_C virtual void MCoeCaptionRetrieverForFep_Reserved_1();
   1.634 +	IMPORT_C virtual void MCoeCaptionRetrieverForFep_Reserved_2();
   1.635 +	};
   1.636 +
   1.637 +#endif	// __FEPBASE_H__