williamr@2: // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies). williamr@2: // All rights reserved. williamr@2: // This component and the accompanying materials are made available williamr@4: // under the terms of "Eclipse Public License v1.0" williamr@2: // which accompanies this distribution, and is available williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@2: // williamr@2: // Initial Contributors: williamr@2: // Nokia Corporation - initial contribution. williamr@2: // williamr@2: // Contributors: williamr@2: // williamr@2: // Description: williamr@2: // williamr@2: williamr@2: #ifndef __FEPBASE_H__ williamr@2: #define __FEPBASE_H__ williamr@2: williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: class CCoeControl; williamr@2: williamr@2: williamr@2: /** Specifies the mixin protocol for observing a FEP transaction. williamr@2: williamr@2: Applications which need to implement this protocol should derive from this williamr@2: class. The functions are not pure virtual because most applications will only williamr@2: need to override one of them. williamr@2: williamr@2: @see CCoeFep::MakeDeferredFunctionCall() williamr@2: @publishedAll williamr@2: @released */ williamr@2: class MCoeFepObserver williamr@2: { williamr@2: public: williamr@2: // both of these functions do nothing by default - the reason that they are not pure williamr@2: // virtual is that most applications will only want to override one of them williamr@2: IMPORT_C virtual void HandleStartOfTransactionL(); // the responsibility of FEPs to call williamr@2: IMPORT_C virtual void HandleCompletionOfTransactionL(); // the responsibility of FEPBASE to call - not to be called if the transaction is canceled williamr@2: private: // reserved. do not override! williamr@2: IMPORT_C virtual void MCoeFepObserver_Reserved_1(); williamr@2: IMPORT_C virtual void MCoeFepObserver_Reserved_2(); williamr@2: }; williamr@2: williamr@2: /** Handles the start of a FEP transaction. williamr@2: williamr@2: This is a non-member function which just calls aFepObserver.HandleStartOfTransactionL(). williamr@2: williamr@2: It is called indirectly by a FEP to notify the application that it is starting a transaction. williamr@2: This is done by calling CCoeEnv::ForEachFepObserverCall() passing in williamr@2: FepObserverHandleStartOfTransactionL. Internally, this calls HandleStartOfTransactionL() for williamr@2: each MCoeFepObserver object that has been registered with the control environment. williamr@2: williamr@2: @param aFepObserver The FEP observer. williamr@2: @see MCoeFepObserver::HandleStartOfTransactionL() williamr@2: @publishedAll williamr@2: @released */ williamr@2: IMPORT_C void FepObserverHandleStartOfTransactionL(MCoeFepObserver& aFepObserver); williamr@2: williamr@2: williamr@2: /** Abstract base class for all FEPs. williamr@2: williamr@2: FEP authors must derive a class from CCoeFep. The CCoeFep-derived class should williamr@2: implement all of its pure virtual functions including the ones which CCoeFep williamr@2: inherits from its base classes. For information on these functions, see the williamr@2: documentation of the base classes. The global NewFepL() function is used to williamr@2: create a fully initialised object of the derived class. williamr@2: williamr@2: FEPs that need to intercept key events should own a CCoeControl-derived object. williamr@2: This object is referred to as the FEP control. The FEP control should williamr@2: be added to the control stack at a priority of ECoeStackPriorityFep, so that williamr@2: it receives first refusal of key events from the window server. williamr@2: williamr@2: In general, focus is retained by the underlying application. This has the williamr@2: advantage that the user can see where the output produced by the FEP will williamr@2: go. When focus is switched between controls, the FEP must be notified in case williamr@2: the input capability of the focussed control changes. For instance, the FEP williamr@2: needs to prevent the user composing a large amount of text only for it to williamr@2: be passed to a newly focussed control that cannot accept text input. CCoeFep williamr@2: derives from MCoeFocusObserver, which enables FEPs to receive notification williamr@2: when the focus for the underlying control changes. The implementation of MCoeFocusObserver's williamr@2: functions can call the enquiry functions of class TCoeInputCapabilities to williamr@2: find out what input capabilities are supported by the new target control (you williamr@2: need to get the TCoeInputCapabilities object from the application UI first: williamr@2: see CCoeAppUi::InputCapabilities()). williamr@2: williamr@2: @see NewFepL() williamr@2: @publishedAll williamr@2: @released */ williamr@2: class CCoeFep : public CBase, protected MFepAttributeStorer, public MCoeForegroundObserver, public MCoeFocusObserver, private MCoeMessageObserver williamr@2: { williamr@2: public: williamr@2: /** Response to key or pointer event */ williamr@2: enum TEventResponse williamr@2: { williamr@2: EEventWasNotConsumed, /** < Indicates that the FEP did not process the event. */ williamr@2: EEventWasConsumed /** < Indicates that the FEP did process the event. */ williamr@2: }; williamr@2: williamr@2: /** Enables FEPs to have some code called but not in the context of the current williamr@2: call stack, hence the name "deferred". williamr@2: williamr@2: For an explanation of the intended use of this class, see williamr@2: CCoeFep::MakeDeferredFunctionCall(). */ williamr@2: class MDeferredFunctionCall williamr@2: { williamr@2: public: williamr@2: /** This function is called from within a high-priority active object's RunL() williamr@2: shortly after the active object has been queued by calling CCoeFep::MakeDeferredFunctionCall(). */ williamr@2: virtual void ExecuteFunctionL()=0; williamr@2: private: // reserved. do not override! williamr@2: IMPORT_C virtual void MDeferredFunctionCall_Reserved_1(); williamr@2: IMPORT_C virtual void MDeferredFunctionCall_Reserved_2(); williamr@2: }; williamr@2: williamr@2: /** FEPs send character codes to the application underneath them using SimulateKeyEventsL(). williamr@2: Occasionally a FEP may wish to also specify the modifiers (e.g. Fn, Ctrl, williamr@2: Shift) to be sent with that character code. In this case, they should use williamr@2: the overload of CCoeFep::SimulateKeyEventsL() which takes an array of MModifiedCharacters. */ williamr@2: class MModifiedCharacter williamr@2: { williamr@2: public: williamr@2: /** Returns the character code of the key combination. williamr@2: williamr@2: @return The character code of the key combination. */ williamr@2: virtual TUint CharacterCode() const=0; williamr@2: /** Returns a TUint which indicates which modifiers to override, rather than using williamr@2: the current state of the keyboard's modifiers. williamr@2: williamr@2: @return The modifiers to override in the key combination. */ williamr@2: virtual TUint ModifierMask() const=0; williamr@2: /** Returns a TUint which indicates which of the modifiers specified in the mask williamr@2: (returned by ModifierMask()) must be on and which must be off. williamr@2: williamr@2: @return Indicates which of the modifiers specified in the mask (returned by williamr@2: ModifierMask()) must be on and which must be off. */ williamr@2: virtual TUint ModifierValues() const=0; williamr@2: private: // reserved. do not override! williamr@2: IMPORT_C virtual void MModifiedCharacter_Reserved_1(); williamr@2: IMPORT_C virtual void MModifiedCharacter_Reserved_2(); williamr@2: }; williamr@2: williamr@2: public: williamr@2: IMPORT_C virtual ~CCoeFep(); williamr@2: IMPORT_C TBool IsSimulatingKeyEvent() const; williamr@2: IMPORT_C TBool IsTurnedOnByL(const TKeyEvent& aKeyEvent) const; williamr@2: IMPORT_C TBool IsTurnedOffByL(const TKeyEvent& aKeyEvent) const; williamr@2: public: // new public virtual functions williamr@2: /** Cancels the FEP transaction. williamr@2: williamr@2: A FEP transaction begins when an event is first intercepted by the FEP and williamr@2: ends either when the processed text is committed to the application underneath, williamr@2: or if it is cancelled. */ williamr@2: virtual void CancelTransaction()=0; williamr@2: public: williamr@2: IMPORT_C void OnStartingHandlingKeyEvent_WithDownUpFilterLC(); williamr@2: IMPORT_C void OnStartingHandlingKeyEvent_NoDownUpFilterLC(); williamr@2: IMPORT_C TKeyResponse OnFinishingHandlingKeyEvent_WithDownUpFilterL(TEventCode aEventCode, const TKeyEvent& aKeyEvent, TKeyResponse aKeyResponse); williamr@2: IMPORT_C TKeyResponse OnFinishingHandlingKeyEvent_NoDownUpFilterL(TEventCode aEventCode, const TKeyEvent& aKeyEvent, TKeyResponse aKeyResponse); williamr@2: protected: williamr@2: IMPORT_C CCoeFep(CCoeEnv& aConeEnvironment); williamr@2: IMPORT_C void BaseConstructL(const CCoeFepParameters& aFepParameters); williamr@2: IMPORT_C void ReadAllAttributesL(); williamr@2: IMPORT_C void MakeDeferredFunctionCall(MDeferredFunctionCall& aDeferredFunctionCall); williamr@2: IMPORT_C void SimulateKeyEventsL(const TArray& aArrayOfCharacters); williamr@2: IMPORT_C void SimulateKeyEventsL(const TArray& aArrayOfModifiedCharacters); williamr@2: IMPORT_C void WriteAttributeDataAndBroadcastL(TUid aAttributeUid); williamr@2: IMPORT_C void WriteAttributeDataAndBroadcastL(const TArray& aAttributeUids); williamr@2: IMPORT_C TBool IsOn() const; williamr@2: public: // not for external use williamr@2: void SetOnState(TBool aOnState); williamr@2: private: williamr@2: class CHighPriorityActive; williamr@2: class CLowPriorityActive; williamr@2: class CCoeFepExtra; williamr@2: private: williamr@2: void DoOnStartingHandlingKeyEventLC(TUint aFlagNoDownUpFilter); williamr@2: TKeyResponse DoOnFinishingHandlingKeyEventL(TEventCode aEventCode, const TKeyEvent& aKeyEvent, TKeyResponse aKeyResponse); williamr@2: static void TurnOffKeyEventHandlingFlags(TAny* aFlags); williamr@2: // from MFepAttributeStorer williamr@2: IMPORT_C virtual void MFepAttributeStorer_Reserved_1(); williamr@2: IMPORT_C virtual void MFepAttributeStorer_Reserved_2(); williamr@2: // from MCoeForegroundObserver williamr@2: IMPORT_C virtual void MCoeForegroundObserver_Reserved_1(); williamr@2: IMPORT_C virtual void MCoeForegroundObserver_Reserved_2(); williamr@2: // from MCoeFocusObserver williamr@2: IMPORT_C virtual void MCoeFocusObserver_Reserved_1(); williamr@2: IMPORT_C virtual void MCoeFocusObserver_Reserved_2(); williamr@2: // from MCoeMessageObserver williamr@2: IMPORT_C virtual TMessageResponse HandleMessageL(TUint32 aClientHandleOfTargetWindowGroup, TUid aMessageUid, const TDesC8& aMessageParameters); williamr@2: IMPORT_C virtual void MCoeMessageObserver_Reserved_1(); williamr@2: IMPORT_C virtual void MCoeMessageObserver_Reserved_2(); williamr@2: // new private virtual functions williamr@2: /** Called to notify the FEP that it has either just been turned on or just been williamr@2: turned off (it can find out which by calling CCoeFep::IsOn()). williamr@2: williamr@2: If FEPs want to change their appearance when they are off (e.g. make themselves williamr@2: invisible), then they should implement this function accordingly. williamr@2: williamr@2: @publishedAll williamr@2: @released */ williamr@2: virtual void IsOnHasChangedState()=0; williamr@2: williamr@2: /** williamr@2: @deprecated */ williamr@2: virtual void OfferKeyEventL(TEventResponse& /*aEventResponse*/, const TKeyEvent& /*aKeyEvent*/, TEventCode /*aEventCode*/){}; williamr@2: williamr@2: /** williamr@2: @deprecated */ williamr@2: virtual void OfferPointerEventL(TEventResponse& /*aEventResponse*/, const TPointerEvent& /*aPointerEvent*/, const CCoeControl* /*aWindowOwningControl*/){}; williamr@2: williamr@2: /** williamr@2: @deprecated */ williamr@2: virtual void OfferPointerBufferReadyEventL(TEventResponse& /*aEventResponse*/, const CCoeControl* /*aWindowOwningControl*/){}; williamr@2: private: // reserved. do not override! williamr@2: IMPORT_C virtual void CCoeFep_Reserved_1(); williamr@2: IMPORT_C virtual void CCoeFep_Reserved_2(); williamr@2: private: williamr@2: class SKeyEvent; williamr@2: CCoeEnv& iConeEnvironment; williamr@2: TUint iFlags; williamr@2: CHighPriorityActive* iHighPriorityActive; williamr@2: CCoeFepExtra* iExtra; williamr@2: SKeyEvent* iLastKeyEvent; williamr@2: TUint iSpare[13]; williamr@2: }; williamr@2: williamr@2: williamr@2: /** Specifies the mixin protocol for handling pointer events in inline text. williamr@2: williamr@2: This class should be overridden by front end processors which support inline editing. williamr@2: williamr@2: An instance of a class which implements this protocol should be passed to williamr@2: MCoeFepAwareTextEditor::StartFepInlineEditL(). williamr@2: williamr@2: @publishedAll williamr@2: @released */ williamr@2: class MFepPointerEventHandlerDuringInlineEdit // to be overridden by inline-editing front-end processors williamr@2: { williamr@2: public: williamr@2: /** This function is called when a pointer event is received within the inline williamr@2: text. It may need to update the cursor position within the inline text and williamr@2: do text selection in response to drag events. williamr@2: williamr@2: @param aType Pointer event types. williamr@2: @param aModifiers Modifier keys (SHIFT, CTRL, FN etc.). williamr@2: @param aPositionInInlineText The position at which the pointer event occurred, williamr@2: as an offset from the start of the inline text string. */ williamr@2: virtual void HandlePointerEventInInlineTextL(TPointerEvent::TType aType, TUint aModifiers, TInt aPositionInInlineText)=0; williamr@2: private: // reserved. do not override! williamr@2: IMPORT_C virtual void MFepPointerEventHandlerDuringInlineEdit_Reserved_1(); williamr@2: IMPORT_C virtual void MFepPointerEventHandlerDuringInlineEdit_Reserved_2(); williamr@2: }; williamr@2: williamr@2: class TCharFormat; williamr@2: class TCursorSelection; williamr@2: class MFormCustomDraw; williamr@2: class MFepInlineTextFormatRetriever; williamr@2: class MCoeFepAwareTextEditor_Extension1; williamr@2: williamr@2: williamr@2: /** Specifies a protocol for FEP-aware text editors. williamr@2: williamr@2: TCoeInputCapabilities::FepAwareTextEditor() returns a pointer to an object williamr@2: of this class. A NULL return value indicates that the interface is not supported williamr@2: by any of the currently focused controls. williamr@2: williamr@2: Inline editing means composing text directly in the target text editor control williamr@2: rather than in the FEP's edit window first. The target text editor must implement williamr@2: the MCoeFepAwareTextEditor interface in order to support inline text. The williamr@2: inline text may be differentiated from the surrounding text by the use of williamr@2: different formatting. These differences are removed when the inline text transaction williamr@2: is committed (causing the inline text to become a real part of the document). williamr@2: Cancelling the inline text transaction deletes the inline text and restores williamr@2: any previously selected text. A benefit of inline editing is that the user williamr@2: only has to concentrate on one area of the screen rather than two. williamr@2: williamr@2: An inline editing transaction consists of the following sequence of function williamr@2: calls: williamr@2: williamr@2: - a call to StartFepInlineEditL() williamr@2: williamr@2: - zero, one or more calls to UpdateFepInlineTextL() williamr@2: williamr@2: - a call to either CommitFepInlineEditL() or CancelFepInlineEdit() williamr@2: williamr@2: @publishedAll williamr@2: @released */ williamr@2: class MCoeFepAwareTextEditor // to be overridden by text-editors williamr@2: { williamr@2: public: williamr@2: /** williamr@2: Starts a FEP inline editing transaction. williamr@2: williamr@2: Inserts a descriptor containing the initial inline text into the text editor. williamr@2: The inline text should normally replace any selected text. williamr@2: williamr@2: The final three parameters are instances of abstract classes, so that the williamr@2: caller of this function must create and instantiate classes deriving from williamr@2: them. These instances must remain in existence for the entire duration of williamr@2: the inline editing transaction. williamr@2: williamr@2: Inline editing should not already be taking place when this function is called. williamr@2: williamr@2: @param aInitialInlineText The inline text to insert into the text editor. williamr@2: @param aPositionOfInsertionPointInInlineText An insertion position within the williamr@2: inline text. This is an offset from the start of the inline text. williamr@2: @param aCursorVisibility ETrue for visible text cursor, EFalse for invisible williamr@2: text cursor in the text editor. williamr@2: @param aCustomDraw Pointer to a custom drawing object. May be used to do advanced williamr@2: formatting of the inline text. This parameter is optional; a NULL pointer williamr@2: may be specified. williamr@2: @param aInlineTextFormatRetriever Defines a single member function, GetFormatOfFepInlineText() williamr@2: which is used by the text editor to find out the formatting to apply to the williamr@2: inline text. It is also possible to apply different formatting to different williamr@2: parts of the inline text. williamr@2: @param aPointerEventHandlerDuringInlineEdit Defines a single function, HandlePointerEventInInlineTextL() williamr@2: which is called when a pointer event is received within the inline text. This williamr@2: function might update the cursor position within the inline text and do text williamr@2: selection. williamr@2: */ williamr@2: virtual void StartFepInlineEditL(const TDesC& aInitialInlineText, TInt aPositionOfInsertionPointInInlineText, williamr@2: TBool aCursorVisibility, const MFormCustomDraw* aCustomDraw, MFepInlineTextFormatRetriever& aInlineTextFormatRetriever, williamr@2: MFepPointerEventHandlerDuringInlineEdit& aPointerEventHandlerDuringInlineEdit)=0; williamr@2: /** Updates the inline text. williamr@2: williamr@2: Called when a character is added to or deleted from the inline text. williamr@2: williamr@2: The descriptor aNewInlineText contains the entire new inline text string, williamr@2: not just the new text to be combined with the old inline text. williamr@2: williamr@2: @param aNewInlineText Descriptor which holds the entire new inline text string. williamr@2: @param aPositionOfInsertionPointInInlineText The position of the insertion williamr@2: point (i.e. the cursor) within the inline text string aNewInlineText. This williamr@2: is an offset from the start of the string. */ williamr@2: virtual void UpdateFepInlineTextL(const TDesC& aNewInlineText, TInt aPositionOfInsertionPointInInlineText)=0; williamr@2: /** Sets the visibility of the text cursor in the text editor. williamr@2: williamr@2: The cursor visibility is initialised using StartFepInlineEditL(). SetInlineEditingCursorVisibilityL() williamr@2: is provided for FEPs which need to change the visibility of the cursor during williamr@2: the inline editing transaction. williamr@2: williamr@2: @param aCursorVisibility ETrue for visible text cursor, EFalse for invisible williamr@2: text cursor. */ williamr@2: virtual void SetInlineEditingCursorVisibilityL(TBool aCursorVisibility)=0; williamr@2: IMPORT_C void CommitFepInlineEditL(CCoeEnv& aConeEnvironment); williamr@2: /** Cancels the inline editing transaction. williamr@2: williamr@2: The edit window should be rolled back to the state it was in before the FEP williamr@2: transaction started, i.e. any inline text in the document which has not yet williamr@2: been committed should be removed. If the inline text has replaced existing text, williamr@2: (e.g. a selection) the replaced text should be reinstated. */ williamr@2: virtual void CancelFepInlineEdit()=0; williamr@2: // with regard to the behaviour of the following functions (except GetScreenCoordinatesForFepL), williamr@2: // note that when inline editing, the contents of the editor will be such that the text constituting williamr@2: // the selection immediately prior to inline editing will be replaced by the inline text williamr@2: // (CancelFepInlineEdit reinstates the previous selection) williamr@2: /** Returns the total number of characters in the text editor. williamr@2: williamr@2: @return The total number of characters in the text editor. */ williamr@2: virtual TInt DocumentLengthForFep() const=0; williamr@2: /** Returns the upper limit (if any) on the length of text that the text editor williamr@2: can hold. williamr@2: williamr@2: @return The maximum number of characters that the text editor can hold. */ williamr@2: virtual TInt DocumentMaximumLengthForFep() const=0; williamr@2: /** Sets the range of characters in the text editor which should be selected. williamr@2: williamr@2: @param aCursorSelection Contains the cursor and anchor positions for the selection. */ williamr@2: virtual void SetCursorSelectionForFepL(const TCursorSelection& aCursorSelection)=0; williamr@2: /** Gets the range of characters in the text editor which are selected. williamr@2: williamr@2: @param aCursorSelection On return, contains the cursor and anchor positions williamr@2: of the selection. */ williamr@2: virtual void GetCursorSelectionForFep(TCursorSelection& aCursorSelection) const=0; williamr@2: /** Copies a portion of the text editor's text content into a descriptor. williamr@2: williamr@2: @param aEditorContent A descriptor; on return contains a copy of a portion williamr@2: of the text. williamr@2: @param aDocumentPosition The document position in the text editor from which williamr@2: to copy. williamr@2: @param aLengthToRetrieve The number of characters to copy. */ williamr@2: virtual void GetEditorContentForFep(TDes& aEditorContent, TInt aDocumentPosition, TInt aLengthToRetrieve) const=0; williamr@2: /** Gets the character formatting which applies to the document position specified. williamr@2: williamr@2: This function allows FEPs to find out the ambient formatting so that the FEP williamr@2: can choose a format for the inline text that will clearly differentiate it williamr@2: from the surrounding text. williamr@2: williamr@2: @param aFormat On return, contains the character formatting which applies williamr@2: to the character at aDocumentPosition. williamr@2: @param aDocumentPosition The document position of interest. */ williamr@2: virtual void GetFormatForFep(TCharFormat& aFormat, TInt aDocumentPosition) const=0; williamr@2: /** Gets the x,y screen coordinates for the left hand side of the baseline of the williamr@2: character located at a specified document position. williamr@2: williamr@2: Also gets the height (ascent + descent) and ascent of the font of the character. williamr@2: This function could be used to position the FEP window as close as possible to williamr@2: the insertion point in the text editor. williamr@2: williamr@2: @param aLeftSideOfBaseLine On return, contains the x,y coordinates of the williamr@2: left side of the baseline of the character located at aDocumentPosition. williamr@2: @param aHeight On return, contains the height (ascent + descent) of the font williamr@2: of the character at aDocumentPosition. williamr@2: @param aAscent On return, contains the ascent of the font of the character williamr@2: at aDocumentPosition. williamr@2: @param aDocumentPosition The document position of interest. */ williamr@2: virtual void GetScreenCoordinatesForFepL(TPoint& aLeftSideOfBaseLine, TInt& aHeight, TInt& aAscent, TInt aDocumentPosition) const=0; williamr@2: williamr@2: IMPORT_C MCoeFepAwareTextEditor_Extension1* Extension1(); williamr@2: private: williamr@2: /** Private function called by CommitFepInlineEditL(). williamr@2: williamr@2: Implementations should commit the inline text to the document. This williamr@2: ends the inline editing transaction and causes the inline text to williamr@2: become a part of the document. williamr@2: williamr@2: @publishedAll williamr@2: @released */ williamr@2: virtual void DoCommitFepInlineEditL()=0; williamr@2: IMPORT_C virtual MCoeFepAwareTextEditor_Extension1* Extension1(TBool& aSetToTrue); williamr@2: private: // reserved. do not override! williamr@2: IMPORT_C virtual void MCoeFepAwareTextEditor_Reserved_2(); williamr@2: }; williamr@2: williamr@2: williamr@2: class MLayDoc; williamr@2: williamr@2: /** williamr@2: MCoeFepLayDocExtension is an interface class which should be derived from by test editors to williamr@2: provide access to the current MLayDoc object, and to set a new MLayDoc object. williamr@2: Used directly from the FEP to decorate the inline edit text, without changing williamr@2: the actual document text. williamr@2: williamr@2: @publishedAll williamr@2: @released williamr@2: */ williamr@2: class MCoeFepLayDocExtension williamr@2: { williamr@2: public: williamr@2: /** williamr@2: Retrives the current MLayDoc object from the text editor williamr@2: williamr@2: @return Pointer to a MLayDoc object. williamr@2: */ williamr@2: virtual MLayDoc* GetCurrentMLayDoc() const = 0; williamr@2: williamr@2: /** williamr@2: Sets a new MLayDoc object into the CTextLayout object williamr@2: williamr@2: @param aLayDoc The new layout document williamr@2: */ williamr@2: virtual void SetMLayDoc(MLayDoc* aLayDoc) = 0; williamr@2: williamr@2: /** williamr@2: Retrives inline edit positioning information from the editor williamr@2: @param "TInt& aPositionInDocument" Position of the text in the document williamr@2: @param "TInt& aCursorPositionInDocument" Position of the cursor in the document williamr@2: @param "TInt& aSelectionLength" The number of characters in the selected text williamr@2: */ williamr@2: virtual void GetFepEditorState(TInt& aPositionInDocument, TInt& aCursorPositionInDocument, TInt& aSelectionLength) = 0; williamr@2: williamr@2: /** williamr@2: Used to tell the editor when the size of the inline edit has changed, so williamr@2: the text layout can update itself. Should be called before and after the inline williamr@2: edit has been decorated. williamr@2: @param "TCursorSelection aSelection" Position of the line edit from the beginning of the text williamr@2: @param "TInt aDeletedChars" Number of character deleted since the last time the text was formatted. williamr@2: williamr@2: */ williamr@2: virtual void HandleInsertDeleteL(TCursorSelection aSelection,TInt aDeletedChars) = 0; williamr@2: private: // reserved. do not override! williamr@2: IMPORT_C virtual void MCoeFepLayDocExtension_Reserved_1(); williamr@2: IMPORT_C virtual void MCoeFepLayDocExtension_Reserved_2(); williamr@2: }; williamr@2: williamr@2: williamr@2: /** An interface class which may be derived from by text editors to enable FEPs williamr@2: to store state information inside the editor. williamr@2: To be overridden by text-editors williamr@2: williamr@2: The CState class, defined within the scope of MCoeFepAwareTextEditor_Extension1 williamr@2: represents the state information. This is information specific to the control williamr@2: which is only of interest to the FEP. williamr@2: williamr@2: A class which implements this interface must implement the pure virtual functions williamr@2: State() and SetStateTransferingOwnershipL() , to get and set the state. The williamr@2: class should also implement the MCoeFepAwareTextEditor interface. It must williamr@2: override the private virtual MCoeFepAwareTextEditor::Extension1() to return williamr@2: a pointer to itself (the default implementation returns NULL). The private williamr@2: virtual MCoeFepAwareTextEditor::Extension1() function is called by the public, williamr@2: non-virtual MCoeFepAwareTextEditor::Extension1() function. williamr@2: williamr@2: For example, if a FEP wants to set some state information in a text editor williamr@2: which is about to lose focus, the FEP should first call the editor's Extension1() williamr@2: function. If this returns non-NULL, the FEP should call the editor's implementation williamr@2: of SetStateTransferingOwnershipL() , passing in an object of a class derived williamr@2: from CState , which holds the state information. It should also pass in a williamr@2: UID which uniquely identifies the FEP. Later, when focus returns to the editor, williamr@2: the FEP can call State() to retrieve the state information it previously set. williamr@2: Note that CState has several reserved functions, to enable it to be extended williamr@2: in future, while retaining backwards compatibility. williamr@2: williamr@2: @publishedAll williamr@2: @released */ williamr@2: class MCoeFepAwareTextEditor_Extension1 williamr@2: { williamr@2: public: williamr@2: class CState : public CBase williamr@2: /** State information for a text editor control. williamr@2: This is information specific to the control which is only of interest to the williamr@2: FEP which sets it. */ williamr@2: { williamr@2: protected: williamr@2: IMPORT_C CState(); williamr@2: IMPORT_C void BaseConstructL(); williamr@2: public: williamr@2: IMPORT_C virtual ~CState(); williamr@2: private: // reserved. do not override! williamr@2: IMPORT_C virtual void CState_Reserved_1(); williamr@2: IMPORT_C virtual void CState_Reserved_2(); williamr@2: IMPORT_C virtual void CState_Reserved_3(); williamr@2: IMPORT_C virtual void CState_Reserved_4(); williamr@2: private: williamr@2: TAny* iSpareForFutureUse; williamr@2: }; williamr@2: public: williamr@2: /** Sets state information in the text editor. williamr@2: williamr@2: This function must only transfer ownership of the state object after it has williamr@2: successfully done everything that can leave. williamr@2: williamr@2: @param aState Pointer to the state information object. williamr@2: @param aTypeSafetyUid A UID which uniquely identifies the FEP which is calling williamr@2: this function. The text editor should store this value for use by the State() williamr@2: function. */ williamr@2: virtual void SetStateTransferingOwnershipL(CState* aState, TUid aTypeSafetyUid)=0; // this function must only transfer ownership after it has successfully done everything that can leave williamr@2: /** Gets the state information previously set using SetStateTransferingOwnershipL(). williamr@2: williamr@2: This function does not transfer ownership. The function should first check williamr@2: that aTypeSafetyUid matches the UID value previously specified by SetStateTransferingOwnershipL(). williamr@2: If it doesn't match, the function should return NULL. williamr@2: williamr@2: @param aTypeSafetyUid A UID which uniquely identifies the FEP which is calling williamr@2: this function. The purpose of this is to enable the FEP to safely downcast williamr@2: the CState pointer returned by this function to a pointer to a derived class williamr@2: known about by the FEP. williamr@2: @return Pointer to the state information object. */ williamr@2: virtual CState* State(TUid aTypeSafetyUid)=0; williamr@2: public: williamr@2: /** Updates the inline text. williamr@2: williamr@2: Called when a character is added to or deleted from the inline text. williamr@2: williamr@2: The descriptor aNewInlineText contains the entire new inline text string, williamr@2: not just the new text to be combined with the old inline text. williamr@2: williamr@2: @param aSetToTrue Boolean set to EFalse by the caller and subsequently to ETrue by the function indicating that williamr@2: this is the implemented version and not the previous reserved funtion. williamr@2: @param aCursorSelection The position of any hilighted text. williamr@2: @param aNewInlineText Descriptor which holds the entire new inline text string. williamr@2: @param aPositionOfInsertionPointInInlineText williamr@2: The position of the insertion point (i.e. the cursor) within the inline text string aNewInlineText. williamr@2: This is an offset from the start of the string. williamr@2: */ williamr@2: IMPORT_C virtual void StartFepInlineEditL(TBool& aSetToTrue, const TCursorSelection& aCursorSelection, williamr@2: const TDesC& aInitialInlineText, TInt aPositionOfInsertionPointInInlineText, TBool aCursorVisibility, williamr@2: const MFormCustomDraw* aCustomDraw, MFepInlineTextFormatRetriever& aInlineTextFormatRetriever, williamr@2: MFepPointerEventHandlerDuringInlineEdit& aPointerEventHandlerDuringInlineEdit); williamr@2: williamr@2: /** Changes the cursor displayed to indicate different modes of operation. For example how text is enterered williamr@2: @param aSetToTrue Boolean set to EFalse by the caller and subsequently to ETrue by the function indicating that williamr@2: this is the implemented version and not the previously reserved funtion. williamr@2: @param aTextCursor The new cursor to be displayed. williamr@2: */ williamr@2: IMPORT_C virtual void SetCursorType(TBool& aSetToTrue, const TTextCursor& aTextCursor); williamr@2: williamr@2: /** williamr@2: Retrieves the current MCoeFepLayDocExtension object from the text editor williamr@2: @param aSetToTrue Boolean set to EFalse by the caller and subsequently to ETrue by the function indicating that williamr@2: this is the implemented version and not the previously reserved funtion. williamr@2: */ williamr@2: IMPORT_C virtual MCoeFepLayDocExtension* GetFepLayDocExtension(TBool& aSetToTrue); williamr@2: private: // reserved. do not override! williamr@2: IMPORT_C virtual void MCoeFepAwareTextEditor_Extension1_Reserved_4(); williamr@2: }; williamr@2: williamr@2: williamr@2: /** Retrieves a control's caption for use by a FEP. williamr@2: williamr@2: An example of a caption is the non-editable text description displayed williamr@2: alongside each item in a dialog. williamr@2: williamr@2: TCoeInputCapabilities::CaptionRetrieverForFep() returns a pointer to an object williamr@2: of this class. A NULL return value indicates that the interface is not supported williamr@2: by any of the currently focused controls. If not NULL, call GetCaptionForFep(), williamr@2: which fills the supplied buffer with the control's caption, truncating it williamr@2: if the supplied buffer is too small for the whole caption. williamr@2: williamr@2: @publishedAll williamr@2: @released */ williamr@2: class MCoeCaptionRetrieverForFep // to be overridden by captioned-controls williamr@2: { williamr@2: public: williamr@2: /** An implementation of this function should fill aCaption with the target control's williamr@2: caption (or as much of the caption as will fit). williamr@2: williamr@2: For example, code similar to the following might be used (assuming that your caption is williamr@2: stored internally in iCaption): williamr@2: williamr@2: @code williamr@2: const TInt maximumLength=aCaption.MaxLength(); williamr@2: if (iCaption.Length()>maximumLength) williamr@2: aCaption=iCaption.Left(maximumLength); williamr@2: else williamr@2: aCaption=iCaption; williamr@2: williamr@2: @endcode williamr@2: @param aCaption On return, this should be set to the caption of the target williamr@2: control. */ williamr@2: virtual void GetCaptionForFep(TDes& aCaption) const=0; // gets as much as will fit in aCaption williamr@2: private: // reserved. do not override! williamr@2: IMPORT_C virtual void MCoeCaptionRetrieverForFep_Reserved_1(); williamr@2: IMPORT_C virtual void MCoeCaptionRetrieverForFep_Reserved_2(); williamr@2: }; williamr@2: williamr@2: #endif // __FEPBASE_H__ williamr@4: