1.1 --- a/epoc32/include/fepbase.h Tue Mar 16 16:12:26 2010 +0000
1.2 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000
1.3 @@ -1,634 +0,0 @@
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__