FCL/sf/mw/classicui: comparison uifw/AvKon/animdllinc/AknKeyEventMap.h

equal deleted inserted replaced

--1:000000000000
+:2f259fa3e83a
+/*
+* Copyright (c) 2005 Nokia Corporation and/or its subsidiary(-ies).
+* All rights reserved.
+* This component and the accompanying materials are made available
+* under the terms of "Eclipse Public License v1.0"
+* which accompanies this distribution, and is available
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
+*
+* Initial Contributors:
+* Nokia Corporation - initial contribution.
+*
+* Contributors:
+*
+* Description:  A configurable key translation table class.
+*
+*/
+#ifndef AKNKEYEVENTMAP_H
+#define AKNKEYEVENTMAP_H
+// INCLUDES
+#include <e32base.h>
+#include <w32adll.h>
+#include "AknAnimKeySound.h"
+#include "aknkeyeventmapinternal.hrh"
+#include "AknKefSubscriber.h"
+// DATA TYPES
+enum TAknPost
+{
+EAknPostRaw = 0,
+EAknPostKey = 1
+};
+/**
+* Flag for short key event.
+* @since Series 60 3.0
+*/
+#define KAknIsShortKey 0x01
+/**
+* Flag for long key event.
+* @since Series 60 3.0
+*/
+#define KAknIsLongKey 0x02
+/**
+* Flag for long key press.
+* @since Series 60 3.0
+*/
+#define KAknIsLongPress 0x04
+/**
+* Flag for long key event only.
+* @since Series 60 3.0
+*/
+#define KAknIsLongOnly 0x08
+/**
+* Structure encapsulating key event type.
+* @since Series 60 3.0
+*/
+struct TAknKeyEvent
+{
+TUint16 iShortPress;
+TUint16 iLongPress;
+TUint8  iEventType;
+//
+// iEventType does not contain the KAknType-flags directly.  Instead
+// the necessary information is bitflagged using the KAknIs* flags,
+// as follows:
+//
+// bit 0: 0 when Short keypress is sent as raw,
+//        1 when it is sent as key (KAknIsShortKey)
+// bit 1: 0 when Long keypress is sent as raw,
+//        1 when it is sent as key  (KAknIsLongKey)
+// bit 2: 0 when the scancode has no long keypresses defined
+//        (required for combos to work) (KAknIsLongPress)
+// bit 3: 0 when the short keypress before a long one can be generated,
+//        1 when it must be delayed until press is long (KAknIsLongOnly)
+// bit 4: reserved
+// bit 5: reserved
+// bit 6: reserved
+// bit 7: reserved
+//
+// This means that the default event type (=0) is
+// KAknTypeShort | KAknTypeRaw, with successful mappings sent out
+// immediately on the down event.
+};
+/**
+* Encapsulates key event data during initialization of the key table.
+* @since Series 60 3.0
+*/
+struct TAknKeyDefinition
+{
+CArrayFixFlat<TUint16>* iScanCodes;
+TUint16 iKeyCode;
+TUint16 iDeviceMode;
+TUint8 iEventType;
+};
+/**
+* Key Beacon contains the on-time information necessary for posting
+* out correct kind of events.
+* @since Series 60 3.0
+*/
+struct TAknKeyBeacon
+{
+TUint16 iKeyCode;
+TUint8  iEventType;
+};
+/**
+* Structure containing repeat rate definition.
+*/
+struct TAknKeyRepeatRate
+{
+TUint16 iMode;
+TUint16 iModeMask;
+TUint8 iRate;
+};
+// CLASS DECLARATION
+/**
+* CAknKeyEventMap is the main class of the Key Event Framework.
+*
+* It is responsible for configuring the keyboard mapping table(s) from
+* resource files; listening to raw events from the device; performing
+* the key translation and subsequently passing the resolved event for
+* Window Server, which further passes it to interested clients.
+*
+* @lib AknAnimDll.lib
+* @since Series 60 3.0
+*/
+NONSHARABLE_CLASS( CAknKeyEventMap )
+: public CBase,
+public MAknKefPropertyResponder
+{
+public: // Construction and destruction
+/**
+* Constructor.
+*/
+CAknKeyEventMap(CAknAsynchTonePlayer& aAsyncTonePlayer);
+/**
+* 2nd phase constructor.
+* @param aFunctions pointer to interface providing general functions.
+*/
+void ConstructL( MAnimGeneralFunctions* aFunctions );
+/**
+* Destructor.
+*/
+~CAknKeyEventMap();
+public: // New functions
+/**
+* Checks if key event map is enabled.
+* @return ETrue if enabled, EFalse otherwise.
+*/
+TBool IsKeyEventMapEnabled() const;
+/**
+* Handles raw events.
+* @param aRawEvent the raw event from the kernel    .
+* @return ETrue if the event is consumed, EFalse otherwise.
+*/
+TBool OfferRawEvent( const TRawEvent& aRawEvent );
+/**
+* Handles raw events.
+* @param aRawEvent the raw event from the kernel
+* @param aSilentEvent If set, the event will not generate keysound.
+* @return ETrue if the event is consumed, EFalse otherwise.
+*/
+TBool OfferRawEvent( const TRawEvent& aRawEvent, TBool aSilentEvent );
+public: // Functions from base classes
+/**
+* From MAknKefPropertyResponder, handles changes in monitored
+* Publish & Subscribe variables.
+*
+* @param aCategory Category of the variable that was modified.
+* @param aKey Key of the variable that was modified.
+*/
+virtual void HandlePropertyChangedL(
+const TUid& aCategory,
+const TUint aKey );
+private:
+/**
+* Loads a resource file and sets up the translation table.
+* @param aConfigFile Name of the configuration resource file
+*/
+void InitializeKeyTableFromResourceL(
+const TDesC& aConfigFile );
+/**
+* Sets the repeat rate for long key presses.
+* @param aRepeatRate repeat rate.
+*/
+void SetRepeatRate( TUint8 aRepeatRate );
+/**
+* Sets a key mapping for scan code(s) in a given devicemode.
+* @param aKey A struct containing all information to set up
+*        the mapping.
+*/
+void SetKeyMappingL( const TAknKeyDefinition& aKey );
+/**
+* This method creates an array containing indices of all device
+* modes (iKeyMap rows) that are affected by the processed mapping.
+* @param aModes it will contain array of modes.
+* @param aMode device mode identifier (from the resource file).
+*/
+void ResolveDeviceModeL( RArray<TUint>& aModes, TUint16 aMode );
+/**
+* This method converts the eventtype-flags (KAknType*) used in the resource file
+* into TAknKeyEvent::iEventType.  Notice that the resource file
+* definitions are translated into KAknIs* flags.
+*
+* @param aEventType Event type indentifier (from the resource file).
+* @return event type data in a format that can be put in TAknKeyEvent.
+*/
+TUint8 ResolveEventType( TUint8 aEventType );
+/**
+* Performs a lookup on key map to find out the correct
+* mapping for a (single) scan code in a given device mode
+* @param aScanCode The scan code that is to be looked up.
+* @param aDeviceMode The device mode for which the mapping is done.
+* @returns result of the mapping
+*/
+TAknKeyBeacon GetKeyMapping( TUint16 aScanCode, TUint16 aDeviceMode );
+/**
+* Performs a search on combination key mapping to find out the correct
+* mapping for a combination of scan codes, if any.
+* @param aComboCandidate reference to iDownEvents.
+* @returns result of the mapping
+*/
+TAknKeyBeacon GetComboMapping( RArray<TUint32>& aComboCandidate );
+/**
+* Resolves correct keycode for the last keypress / combo that
+* came in / is coming in.
+* @return result of the mapping.
+*/
+TAknKeyBeacon ResolveMapping();
+/**
+* A callback for the CPeriodic timer that tracks the length of the
+* keypress,and subsequently the amount of repeats (if any).
+*
+* @param aMyPtr a pointer to an instance of this class.
+* @return 1 if the callback should be called again, 0 otherwise.
+*/
+static TInt KeyPressDuration( TAny *aMyPtr );
+/**
+* Helper function for posting the re-mapped event.
+*
+* @param aType type of event to send;
+*         default is TAknPost::ERaw for a raw event
+*         TAknPost::Ekey posts a key event
+*/
+void PostEvent(TUint aType = 0);
+/**
+* A macro that stops the timer and resets all variables.
+*/
+void CancelProcessingKeyPress();
+private:
+/**
+* This is the 'main' translation table that corresponds to a
+* M x N matrix, where M is the number of scan codes, and N is
+* the number of device modes.
+*
+* Each device mode is identified by a bit-encoded integer, and each
+* device mode's key mapping can be found from a separate row in
+* iKeyMap.
+*
+* The first row, ie. iKeyMap[i][0] contains the 'Default' mode mapping.
+* If this mapping is not EKeyNull (the initial value), then it is
+* returned regardless of what the actual device mode is, IF non-EKeyNull
+* mapping for that mode is not found.  If it is EKeyDisabled, then the
+* raw event is consumed but nothing is passed on.
+*/
+TAknKeyEvent iKeyMap[ KAknKeyMapColumns ][ KAknKeyMapRows ];
+/**
+* This array of arrays of integers stores combined keypresses. For
+* each combo,  *(*iCombos)[i], there's an array whose first two
+* elements contain the key code AND the device mode this
+* combo is active in, AND the event type (long or short keypress).
+* Subsequent elements contain the participating scan codes.
+*
+* Information about the device mode and the event type is encoded into
+* the higher 16 bits of the keycode value.
+*/
+RArray<RArray<TUint32>*>* iCombos;
+/**
+* Support for combined keypresses, this array accumulates down events
+* until an up event comes and resets the array. The contents of this
+* array are matched against each element of iCombos.
+*/
+RArray<TUint32> iDownEvents;
+/**
+* Support for sending out raw events, this array accumulates the
+* results for mapped DOWN raw events.  Then when an UP raw event
+* is got from the keyb driver, this array is used to make sure that
+* for every event that was sent out as raw DOWN there will
+* also be the raw UP.
+*/
+RArray<TUint32> iUpEvents;
+/**
+* Repeat rate definitions.
+*/
+RArray< TAknKeyRepeatRate > iRepeatRates;
+/**
+* Contains the character value to be sent in PostKeyEvent, if any.
+* Possible values:
+*  EKeyNull: default, disables PostEvent.
+*  KAknKeyDisabled: disables PostEvent, and indicates that
+*  the current raw event should be consumed.
+*  any other value: the key code to be sent in PostEvent().
+*/
+TAknKeyBeacon iKeyBeacon;
+/**
+* EFalse = key, ETrue = raw
+*
+* This variable is currently OBSOLETE; i'm leaving it in nonetheless,
+* so someone remembers to add KAknTypeRepeatable and associated functionality.
+*
+*/
+TBool iSendRepeats;
+/**
+* Scan code of the last incoming down or up type raw event,
+* excluding raw events generated by this class.
+*/
+TUint32 iCurrentScanCode;
+/**
+* The device mode.  This is updated via a P&S key.
+*/
+TUint16 iCurrentDeviceMode;
+/**
+* Timer for the latest incoming down type raw event
+*/
+CPeriodic* iDownTimer;
+/**
+* Interval to poll.
+*/
+TTimeIntervalMicroSeconds32 iKeyPollInterval;
+/**
+* Key press duration.
+*/
+TReal32 iKeyPressDuration;
+/**
+* Support for key presses that must not generate
+* any event until the key press type is fully resolved.
+* Currently this is used for KAknTypeLongOnly.
+*/
+TAknKeyBeacon iPostMeOnUp;
+/**
+* Safeguard against active scheduler problems.
+*/
+TBool iIsCanceled;
+/**
+* ETrue when iDownTimer > KLongPressThreshold.
+*/
+TBool iIsLongKeyPress;
+/**
+* For ignoring self-generated raw events.
+*/
+TInt iScanCodeIJustGenerated;
+/**
+* Key repeat rate.
+*/
+TUint8 iRepeatRate;
+/**
+* Amount of repeats.
+*/
+TInt32 iRepeats;
+/**
+* Boolean flag indicating whether the processed event
+* should be consumed
+*/
+TBool iConsume;
+/**
+* Owned array of Publish & Subscribe variable monitors.
+*/
+RPointerArray< CAknKefSubscriber > iKefSubscribers;
+/**
+* Not owned key sound session.
+*/
+CAknAsynchTonePlayer& iSoundSession;
+// ETrue if key event map is enabled.
+TBool iKeyEventMapEnabled;
+// General functions for plug-ins.
+MAnimGeneralFunctions* iFunctions;
+};
+#endif // AKNKEYEVENTMAP_H
+// End of File