CCoeFep Class Reference

#include <mw/fepbase.h>

Link against: fepbase.lib

class CCoeFep : public CBase, protected MFepAttributeStorer, public MCoeForegroundObserver, public MCoeFocusObserver, private MCoeMessageObserver

Inherits from

CCoeFep

Nested Classes and Structures

CCoeFep::CHighPriorityActive
CCoeFep::CLowPriorityActive
CCoeFep::MDeferredFunctionCall
CCoeFep::MModifiedCharacter
CCoeFep::SKeyEvent

Public Member Enumerations
enum	TEventResponse { EEventWasNotConsumed, EEventWasConsumed }

Public Member Functions
virtual	~CCoeFep()
pure virtual void	CancelTransaction()
IMPORT_C TBool	IsSimulatingKeyEvent()
IMPORT_C TBool	IsTurnedOffByL(const TKeyEvent &)
IMPORT_C TBool	IsTurnedOnByL(const TKeyEvent &)
IMPORT_C TKeyResponse	OnFinishingHandlingKeyEvent_NoDownUpFilterL(TEventCode, const TKeyEvent &, TKeyResponse)
IMPORT_C TKeyResponse	OnFinishingHandlingKeyEvent_WithDownUpFilterL(TEventCode, const TKeyEvent &, TKeyResponse)
IMPORT_C void	OnStartingHandlingKeyEvent_NoDownUpFilterLC()
IMPORT_C void	OnStartingHandlingKeyEvent_WithDownUpFilterLC()
void	SetOnState(TBool)

Protected Member Functions
	CCoeFep(CCoeEnv &)
IMPORT_C void	BaseConstructL(const CCoeFepParameters &)
IMPORT_C TBool	IsOn()
IMPORT_C void	MakeDeferredFunctionCall(MDeferredFunctionCall &)
IMPORT_C void	ReadAllAttributesL()
IMPORT_C void	SimulateKeyEventsL(const TArray< TUint > &)
IMPORT_C void	SimulateKeyEventsL(const TArray< MModifiedCharacter > &)
IMPORT_C void	WriteAttributeDataAndBroadcastL(TUid)
IMPORT_C void	WriteAttributeDataAndBroadcastL(const TArray< TUid > &)

Inherited Enumerations
	MCoeMessageObserver:TMessageResponse

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()
	MCoeFocusObserver::HandleChangeInFocus()
	MCoeFocusObserver::HandleDestructionOfFocusedItem()
	MCoeFocusObserver::MCoeFocusObserver()
	MCoeForegroundObserver::HandleGainingForeground()
	MCoeForegroundObserver::HandleLosingForeground()
	MCoeForegroundObserver::MCoeForegroundObserver()
	MCoeMessageObserver::MCoeMessageObserver()
	MFepAttributeStorer::AttributeAtIndex(TInt)const
	MFepAttributeStorer::NumberOfAttributes()const
	MFepAttributeStorer::ReadAllAttributesL(CCoeEnv &)
	MFepAttributeStorer::ReadAttributeDataFromStreamL(TUid,RReadStream &)
	MFepAttributeStorer::WriteAttributeDataAndBroadcastL(CCoeEnv &,TUid)
	MFepAttributeStorer::WriteAttributeDataAndBroadcastL(CCoeEnv &,const TArray< TUid > &)
	MFepAttributeStorer::WriteAttributeDataToStreamL(TUid,RWriteStream &)const

Detailed Description

Abstract base class for all FEPs.

FEP authors must derive a class from CCoeFep. The CCoeFep-derived class should implement all of its pure virtual functions including the ones which CCoeFep inherits from its base classes. For information on these functions, see the documentation of the base classes. The global NewFepL() function is used to create a fully initialised object of the derived class.

FEPs that need to intercept key events should own a CCoeControl-derived object. This object is referred to as the FEP control. The FEP control should be added to the control stack at a priority of ECoeStackPriorityFep, so that it receives first refusal of key events from the window server.

In general, focus is retained by the underlying application. This has the advantage that the user can see where the output produced by the FEP will go. When focus is switched between controls, the FEP must be notified in case the input capability of the focussed control changes. For instance, the FEP needs to prevent the user composing a large amount of text only for it to be passed to a newly focussed control that cannot accept text input. CCoeFep derives from MCoeFocusObserver, which enables FEPs to receive notification when the focus for the underlying control changes. The implementation of MCoeFocusObserver's functions can call the enquiry functions of class TCoeInputCapabilities to find out what input capabilities are supported by the new target control (you need to get the TCoeInputCapabilities object from the application UI first: see CCoeAppUi::InputCapabilities()).

Member Enumeration Documentation

Enum TEventResponse

Response to key or pointer event

Enumerator	Value	Description
EEventWasNotConsumed
EEventWasConsumed		< Indicates that the FEP did not process the event. < Indicates that the FEP did process the event.

Constructor & Destructor Documentation

CCoeFep ( CCoeEnv & )

IMPORT_C

CCoeFep

(

CCoeEnv &

aConeEnvironment

)

[protected]

Protected C++ constructor.

This function should be called from within the FEP's constructor.

Parameters
aConeEnvironment	Control environment. Provides an interface to the window server, so that the FEP control can receive pointer and key events.

~CCoeFep ( )

IMPORT_C

~CCoeFep

(

)

[virtual]

Destructor.

Removes the FEP from the control environment's message observer list prior to its destruction.

Member Function Documentation

BaseConstructL ( const CCoeFepParameters & )

IMPORT_C void

BaseConstructL

(

const CCoeFepParameters &

aFepParameters

)

[protected]

Initialises the FEP's generic settings (whether the FEP is on or off and what key events should turn it on or off).

During construction, all FEPs must call this member function. It also initialises the FEP as an observer so that it receives notification of changes from the control environment. Examples of such changes are the target control gaining or losing focus or changes to the generic FEP settings made by another running instance of the same FEP.

Parameters
aFepParameters	No longer used.

CancelTransaction ( )

void

CancelTransaction

(

)

[pure virtual]

Cancels the FEP transaction.

A FEP transaction begins when an event is first intercepted by the FEP and ends either when the processed text is committed to the application underneath, or if it is cancelled.

IsOn ( )

IMPORT_C TBool

IsOn

(

)

const [protected]

Tests whether the FEP is on or off.

Return Value: Non-zero if the FEP is on, EFalse if the FEP is off.

IsSimulatingKeyEvent ( )

IMPORT_C TBool

IsSimulatingKeyEvent

(

)

const

Tests whether or not the FEP is simulating key events.

This function should be called early in the FEP's implementation of OfferKeyEventL(). If it returns ETrue, OfferKeyEventL() should immediately return EKeyWasNotConsumed so that the application gets the key event as intended.

It is called by the FEP_START_KEY_EVENT_HANDLER_L and FEP_START_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L macros.

Return Value: ETrue if the FEP is simulating key events, EFalse if not.

IsTurnedOffByL ( const TKeyEvent & )

IMPORT_C TBool

IsTurnedOffByL

(

const TKeyEvent &

aKeyEvent

)

const

Since the advent of Platform security in Symbian OS, the turning on/off of FEPs is handled via a different means (which is secure). Hence this function now only ever returns EFalse.

Deprecated

Parameters
aKeyEvent	No longer used.

Return Value: Always returns EFalse.

IsTurnedOnByL ( const TKeyEvent & )

IMPORT_C TBool

IsTurnedOnByL

(

const TKeyEvent &

aKeyEvent

)

const

Since the advent of Platform security in Symbian OS, the turning on/off of FEPs is handled via a different means (which is secure). Hence this function now only ever returns EFalse.

Deprecated

Parameters
aKeyEvent	No longer used.

Return Value: Always returns EFalse.

MakeDeferredFunctionCall ( MDeferredFunctionCall & )

IMPORT_C void

MakeDeferredFunctionCall

(

MDeferredFunctionCall &

aDeferredFunctionCall

)

[protected]

Uses a high-priority active object to call the specified object's ExecuteFunctionL().

This function must be used to handle an event if that event starts a transaction and if handling that event is dependent on the target control's input capabilities. In such a case, MakeDeferredFunctionCall() should be called by the FEP, (passing in the relevant MDeferredFunctionCall-derived object) before calling HandleStartOfTransactionL().

Note:

The reason why key event handling must be done inside a high priority active object is as follows:

In some UI situations, pressing a key should move focus to a previously non-focused or non-existent text editor control, and should insert the character corresponding to that key event into the newly focused control.

When text entry is via a FEP, for this focus-shift to occur at the right time, when the FEP receives its first key event, it should call MCoeFepObserver::HandleStartOfTransactionL(). The implementation of this function should do whatever focus shift is required (e.g. launch the dialog).

However, if it is a waiting dialog, text cannot now be entered into the FEP until the dialog's RunLD() or ExecuteLD() returns (this occurs when the dialog is either cancelled or committed). Therefore, HandleStartOfTransactionL() will block. The solution is for the FEP to handle the key event from within a high priority active object.

Parameters
aDeferredFunctionCall	Implements key event handling in its ExecuteFunctionL() function. This is deferred in that it is executed when the active object's RunL() is called.

OnFinishingHandlingKeyEvent_NoDownUpFilterL ( TEventCode, const TKeyEvent &, TKeyResponse )

IMPORT_C TKeyResponse	OnFinishingHandlingKeyEvent_NoDownUpFilterL	(	TEventCode	aEventCode,
			const TKeyEvent &	aKeyEvent,
			TKeyResponse	aKeyResponse
		)

Note that we should maintain BC for this function as it is used by the published-All macros FEP_START_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L and FEP_END_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L

OnFinishingHandlingKeyEvent_WithDownUpFilterL ( TEventCode, const TKeyEvent &, TKeyResponse )

IMPORT_C TKeyResponse	OnFinishingHandlingKeyEvent_WithDownUpFilterL	(	TEventCode	aEventCode,
			const TKeyEvent &	aKeyEvent,
			TKeyResponse	aKeyResponse
		)

Note that we should maintain BC for this function as it is used by the published-All macros FEP_START_KEY_EVENT_HANDLER_L and FEP_END_KEY_EVENT_HANDLER_L

OnStartingHandlingKeyEvent_NoDownUpFilterLC ( )

IMPORT_C void

OnStartingHandlingKeyEvent_NoDownUpFilterLC

(

)

Note that we should maintain BC for this function as it is used by the published-All macro FEP_START_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L

OnStartingHandlingKeyEvent_WithDownUpFilterLC ( )

IMPORT_C void

OnStartingHandlingKeyEvent_WithDownUpFilterLC

(

)

Note that we should maintain BC for this function as it is used by the published-All macro FEP_START_KEY_EVENT_HANDLER_L

ReadAllAttributesL ( )

IMPORT_C void

ReadAllAttributesL

(

)

[protected]

Sets this FEP's attributes with values from the global settings.

Calls the FEP's implementation of MFepAttributeStorer::ReadAttributeDataFromStreamL() for each FEP attribute which needs to be synchronised.

SetOnState ( TBool )

void

SetOnState

(

TBool

aOnState

)

SimulateKeyEventsL ( const TArray< TUint > & )

IMPORT_C void

SimulateKeyEventsL

(

const TArray< TUint > &

aArrayOfCharacters

)

[protected]

Simulates a key event for each of the character codes in the array passed to it.

This function should be called in order to send key events to the application underneath the FEP (unless inline editing is taking place, in which case a different mechanism is used). FEPs should not use CCoeEnv::SimulateKeyEventL() to simulate key events.

Parameters
aArrayOfCharacters	An array of characters.

SimulateKeyEventsL ( const TArray< MModifiedCharacter > & )

IMPORT_C void

SimulateKeyEventsL

(

const TArray< MModifiedCharacter > &

aArrayOfModifiedCharacters

)

[protected]

WriteAttributeDataAndBroadcastL ( TUid )

IMPORT_C void

WriteAttributeDataAndBroadcastL

(

TUid

aAttributeUid

)

[protected]

After changing the value of a single FEP attribute that needs to be synchronised, call this function to synchronise other running instances of the FEP.

It first calls MFepAttributeStorer::WriteAttributeDataToStreamL() which writes the attribute's new value to the stream and then it causes all other running instances of the FEP to be notified of the change.

Parameters
aAttributeUid	The UID of the attribute that has changed.

Capability
WriteDeviceData

WriteAttributeDataAndBroadcastL ( const TArray< TUid > & )

IMPORT_C void

WriteAttributeDataAndBroadcastL

(

const TArray< TUid > &

aAttributeUids

)

[protected]

After changing the value of multiple FEP attributes that need to be synchronised, call this function to synchronise other running instances of the FEP.

It first calls MFepAttributeStorer::WriteAttributeDataToStreamL() which writes the attributes' new values to the stream and then it causes all other running instances of the FEP to be notified of the changes.

Parameters
aAttributeUids	Array of UIDs for the attribute that have changed.

Capability
WriteDeviceData