![[Index]](../../../stock/btn_index.gif){kind=small}
![[Glossary]](../../../stock/btn_glossary.gif){kind=small}
![[Previous]](../../../stock/btn_prev.gif){kind=small}
![[Next]](../../../stock/btn_next.gif){kind=small}
| |
|
| |
Location:
fepbase.h
Link against: fepbase.lib
CCoeFep
Supported from 6.0
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 should own a
CCoeControl-derived object — this object is referred to as the FEP
control. The FEP control can be
placed on the control stack so that it receives key events from the window server. It should run at high priority, so that it receives first refusal of key events.
FEPs do not take focus — focus is retained by the underlying application. This has the advantage that the user can see where the output produced by the FEP will be inserted (e.g. the cursor will still be displayed). When focus is switched between controls, the FEP must be notified in case the input capability of the newly focussed control is different. For instance, the FEP needs to avoid the situation where the user composes 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()).
Note that there can be more than one underlying target control at a
time. For instance in an application displaying a dialog, the dialog itself is
a focussed control, as is the captioned control, the edit window and other
intermediary controls. If a FEP enquires about the input capabilities of such
an application (i.e. the merged input capabilities of all its focused
controls), it would be returned a TCoeInputCapabilities object
whose FepAwareTextEditor() and
CaptionRetrieverForFep() member functions return non-NULL, even
though these interfaces are implemented by 2 different focused controls.
|
Defined in CCoeFep:
BaseConstructL(), CCoeFep(), CancelTransaction(), EEventWasConsumed, EEventWasNotConsumed, IsOn(), IsOnHasChangedState(), IsSimulatingKeyEvent(), IsTurnedOffByL(), IsTurnedOnByL(), MDeferredFunctionCall, MModifiedCharacter, MakeDeferredFunctionCall(), OfferKeyEventL(), OfferPointerBufferReadyEventL(), OfferPointerEventL(), ReadAllAttributesL(), SimulateKeyEventsL(), TEventResponse, WriteAttributeDataAndBroadcastL(), ~CCoeFep()
Inherited from CBase:
operator new()
Inherited from MCoeFocusObserver:
HandleChangeInFocus(),
HandleDestructionOfFocusedItem()
Inherited from MCoeForegroundObserver:
HandleGainingForeground(),
HandleLosingForeground()
Inherited from MCoeMessageObserver:
EMessageHandled,
EMessageNotHandled,
HandleMessageL(),
TMessageResponse
Inherited from MFepAttributeStorer:
AttributeAtIndex(),
NumberOfAttributes(),
ReadAttributeDataFromStreamL(),
WriteAttributeDataToStreamL()
protected: CCoeFep(CCoeEnv& aConeEnvironment);
Protected C++ constructor. This function should be called from within the FEP's constructor.
|
protected: void BaseConstructL(const CCoeFepParameters& aFepParameters);
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. Also initialises the FEP as an observer so that it receives notification of changes from the cone 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.
|
virtual ~CCoeFep();
Note:
The destructor removes the FEP from the cone environment's message observer list prior to its destruction.
virtual void CancelTransaction()=0;
Cancels the FEP transaction. Pure virtual function.
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.
|
protected: void ReadAllAttributesL();
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.
protected: void WriteAttributeDataAndBroadcastL(TUid aAttributeUid);
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.
|
protected: void WriteAttributeDataAndBroadcastL(const TArray<TUid>& aAttributeUids);
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.
|
|
protected: void SimulateKeyEventsL(const TArray<TUint>& aArrayOfCharacters);
Simulates a key event for each of the character codes in the array passed to it.
Notes:
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.
|
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.
|
![[Top]](../../../stock/arrow_up_2.gif){kind=icon}
FEP_START_KEY_EVENT_HANDLER_L and FEP_START_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L macros.private: virtual void OfferKeyEventL(TEventResponse& aEventResponse, const TKeyEvent& aKeyEvent, TEventCode aEventCode)=0;
This function is provided to support FEPs in OPL. It is called
when a FEP running over an OPL application receives key events. This function
is completely independent from CCoeControl’s virtual
function of the same name but should be implemented in exactly the same
way.
A number of things should be done in the implementation of this function:
If the type of key event received is a key up or key down,
(EEventKeyUp or EEventKeyDown), then
aEventResponse should return the same value as it does for the
corresponding EEventKey event.
return EEventWasNotConsumed if
the CCoeFep member function IsSimulatingKeyEvent()
returns true
return EEventWasNotConsumed if
the CCoeFep member function IsOn() returns false
return EEventWasConsumed to indicate that it
did process the key event if either of CCoeFep’s member
functions IsTurnedOnByL() or IsTurnedOffByL() return
true
After this has been done, the FEP can do its own processing of
the key event. In general, it is recommended that the implementation
of OfferKeyEventL() should be generous in what gets passed on to
the application when not inside a FEP transaction, and should block all key
events from getting through to the application when it is inside a FEP
transaction.
|
protected: void MakeDeferredFunctionCall(MDeferredFunctionCall& aDeferredFunctionCall);
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 the handling of 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.
|
|
TBool IsTurnedOnByL(const TKeyEvent& aKeyEvent) const;
If the FEP is currently off and is turned on by the key event
specified, the function turns all running instances of the FEP on (and
returns ETrue). Otherwise, it
returns EFalse.
Note:
This function was protected in v6.0.
|
|
TBool IsTurnedOffByL(const TKeyEvent& aKeyEvent) const;
If the FEP is currently on and is turned off by the key event
specified, the function turns all running instances of the FEP off (and
returns ETrue). Otherwise, it
returns EFalse.
Note:
This function was protected in v6.0.
|
|
protected: TBool IsOn() const;
Tests whether the FEP is on or off.
|
private: virtual void IsOnHasChangedState()=0;
Called to notify the FEP that it has either just been turned on
or just been turned off (it can find out which by
calling CCoeFep::IsOn()). If FEPs want to change their visual
appearance when they are off (e.g. make themselves invisible), then they should
implement this function accordingly.
|
private: virtual void OfferPointerEventL(TEventResponse& aEventResponse, const TPointerEvent& aPointerEvent, const CCoeControl* aWindowOwningControl)=0;
This function is provided to support FEPs in OPL. It is called
when a FEP running over an OPL application receives pointer events. It should
behave in the same way as the FEP
control's HandlePointerEventL().
|
private: virtual void OfferPointerBufferReadyEventL(TEventResponse& aEventResponse, const CCoeControl* aWindowOwningControl)=0;
This function is provided to support FEPs in OPL. It is called when a FEP running over an OPL application receives buffered drag events (where multiple mouse/pen positions are received in a single event). Buffered drag events are typically used when the application requires a continuous stream of pointer events, such as in handwriting recognition software.
This function should behave in the same way as the FEP
control's HandlePointerBufferReadyL(). If buffered drag events are
not supported, or if aWindowOwningControl is not the target
control for the drag events, this function should
set aEventResponse to CCoeFep::EEventWasNotConsumed.
Otherwise, set it
to CCoeFep::EEventWasConsumed.
|
|
TEventResponse
Response to key or pointer event
|
MDeferredFunctionCall
Supported from 6.0
Enables FEPs to have some code called but not in the context of the current call stack — hence the name "deferred".
For an explanation of the intended use of this class, see the
documentation of
CCoeFep::MakeDeferredFunctionCall().
Defined in CCoeFep::MDeferredFunctionCall:
ExecuteFunctionL()
virtual void ExecuteFunctionL()=0;
This function is called from within a high-priority active
object's RunL() shortly after the active object has been queued by
calling CCoeFep::MakeDeferredFunctionCall().
MModifiedCharacter
Supported from 6.0
FEPs send character codes to the application underneath them
using SimulateKeyEventsL(). Occasionally a FEP may wish to also
specify the modifiers (e.g. Fn, ctrl, shift) to be sent with that character
code. In this case, they should use the overload
of CCoeFep::SimulateKeyEventsL() which takes an array
of MModifiedCharacters.
Defined in CCoeFep::MModifiedCharacter:
CharacterCode(), ModifierMask(), ModifierValues()
virtual TUint CharacterCode() const=0;
Returns the character code of the key combination.
|
virtual TUint ModifierMask() const=0;
Returns a TUint which indicates which modifiers to
override, rather than using the current state of the keyboard's
modifiers.
|
virtual TUint ModifierValues() const=0;
Returns a TUint which indicates which of the
modifiers specified in the mask (returned by ModifierMask()) must
be on and which must be off.
|
Copyright ©2002 Symbian Ltd. 6.1-00174 |
|
![[Top]](../../../stock/arrow_up.gif){kind=icon}