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__