/*

* 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