// Copyright (c) 1997-2010 Nokia Corporation and/or its subsidiary(-ies).

// All rights reserved.

// This component and the accompanying materials are made available

// under the terms of the License "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:

// e32\include\k32keys.h

// 

// WARNING: This file contains some APIs which are internal and are subject

//          to change without notice. Such APIs should therefore not be used

//          outside the Kernel and Hardware Services package.

//

#ifndef __KEYSTD_H__

#define __KEYSTD_H__

////////////////////////////////////////////////////////

//

// Bits required for keyboard translation software

//

////////////////////////////////////////////////////////

#include <e32svr.h>

/**

@internalComponent

@released

*/

const TUint KConvTableSettableModifiers=EModifierAutorepeatable|

                                  EModifierKeypad|

                                  EModifierPureKeycode;

/**

@internalComponent

@released

*/

const TUint KPersistentModifiers=EModifierLeftAlt|

                           EModifierRightAlt|

						   EModifierAlt|

                           EModifierLeftCtrl|

						   EModifierRightCtrl|

                           EModifierCtrl|

						   EModifierLeftShift|

                           EModifierRightShift|

						   EModifierShift|

                           EModifierLeftFunc|

						   EModifierRightFunc|

                           EModifierFunc|

						   EModifierCapsLock|

                           EModifierNumLock|

						   EModifierScrollLock|

						   EModifierKeyboardExtend;

/**

@internalComponent

@released

*/

const TUint KRotationModifiers=EModifierRotateBy90|

						   EModifierRotateBy180|

						   EModifierRotateBy270;

/**

A contiguous range of logical scancodes of type, and ordering, as

defined in TStdScanCode.

Once aligned with an array of target keycodes, a pairwise

association between each scancode and its translation will

be defined.

@publishedPartner

@released

*/

struct SScanCodeBlock

	{

	TUint16 firstScanCode;

	TUint16 lastScanCode;

	};

/**

An array of SScanCodeBlock scancode ranges. This allows

a discontiguous set of scancodes to be treated contiguously.

@publishedPartner

@released

*/

struct SScanCodeBlockList

	{

	TUint numBlocks;

	const SScanCodeBlock *pblocks;

	};

/**

Associates an SScanCodeBlockList with

a specific set of target keycodes. This defines a concrete

translation for the scancodes in the scanCodes block list.

@publishedPartner

@released

*/

struct SConvSubTable

	{

	const TUint16 *pkeyCode; //<! An array of target keycodes

	SScanCodeBlockList scanCodes;

	};

/**

Associates a combination of modifier keys with the translation

table to be used when the combination is active.

@publishedPartner

@released

*/

struct SConvTableNode

	{

	TMaskedModifiers maskedModifiers;

	TUint numSubTables;

	const SConvSubTable * const *ppsubTables;

	};

/**

The top level collection of all different translation

tables.

@publishedPartner

@released

*/

struct SConvTable

	{

	TUint numNodes;

	const SConvTableNode *pnodes;

	};

/**

@publishedPartner

@released

*/

struct SKeyCodeList

	{

	TUint numKeyCodes;

	const TUint16 *pkeyCodes;

	};

/**

Defines an action to perform when a given key press

occurs.

@note This struct should not be used in a keymap table.

It is used within the key translator to represent an

SFuncAndState for the modifier table (where the state

member is not meaningful).

@see SFuncAndState

@publishedPartner

@released

*/

struct SFunc

	{

	TInt32 funcParam;

	TUint8 func;

	TUint8 filler;

	};

/**

Defines an action to perform and the next state transition

when a given key press occurs.

@publishedPartner

@released

*/

struct SFuncAndState

	{

	TUint8 state; ///< The next TState to transition to

	TUint8 func; ///< A TFuncGeneral action

	TInt32 funcParam; ///< Parameter for func (key to translate to for EPassSpecialKeyThru)

	};

/**

Associates a SFuncAndState, which defines an action, with a

key press and modifier combination to trigger it.

@publishedPartner

@released

*/

struct SFuncTableEntry

	{

	TMaskedModifiers maskedModifiers; ///< Required modifier combination

	TKeyCodePattern keyCodePattern; ///< Required keypress

	SFuncAndState funcAndNewState; ///< Action or translation

	};

/**

A function table corresponds to a particular keyboard

mode. When this mode is active this table's entries

are used to perform actions or translations

for certain keypresses.

@see SFuncTableEntry

@publishedPartner

@released

*/

struct SFuncTable

	{

	TUint numEntries;

	const SFuncTableEntry *pentries;

	};

/**

Collection of all keyboard mode function tables

@publishedPartner

@released

*/

struct SFuncTables

	{

	/**

	This table is searched for a match if a match has not been

	found in the current state's table

	*/

	SFuncTable defaultTable;

	/**

	This table controls which keys change which modifiers;

	the state field in this table is ignored

	*/

	SFuncTable modifierTable;

	/**

	Number of entries in array pgenFuncTables.

	This must in fact, always be equal to 13.

	*/

	TUint numGenFuncTables;

	/**

	Array of pointers to general state control tables.

	Indicies 1-12 are possible tables, index 0

	should be unused.

	If a state is not used its SFuncTable array size should be set to

	zero and the pointer to NULL

	*/

	const SFuncTable *pgenFuncTables;

	};

/**

Extends TChar with some extra utility functions

@internalComponent

@released

*/

class TCharExtended: public TChar

	{

public:

	inline TCharExtended();

	inline TCharExtended(TUint aChar);

	TCharExtended &operator=(TUint aChar);

	TBool IsDigitGivenRadix(TRadix aRadix) const;

	TBool IsModifier() const;

	TInt DigitValue() const;

	TBool MatchesPattern(const TKeyCodePattern &aKeyCodePattern, TRadix aRadix=EDecimal) const;

	};

/**

Responsible for loading and performing lookups

in a keyboard function table.

@internalComponent

@released

*/

class TFuncTable

	{

public:

	TFuncTable();

	void Update(RLibrary aLibrary);

	SFunc GetModifierFunc(const TCharExtended &aChar, const TInt &aModifiers) const;

	SFuncAndState GetGeneralFuncAndState(const TCharExtended &aChar, const TInt &aModifiers,

															TUint aCurState, TRadix aRadix) const;

private:

	SFuncTables iFuncTables;

	SFuncTableEntry getDefault(const TCharExtended &aChar, const TInt &aModifiers) const;

	};

/**

@internalComponent

@released

*/

struct SConvKeyData

	{

	TInt modifiers;

	TUint16 keyCode;

	TUint16 filler;

	};

/**

Used by a keymap to state what method is used to

enter multi digit control codes for special characters.

@publishedPartner

@released

*/

enum TCtrlDigitsTermination

	{

	/**

	Keyboard will stay in code entry mode for a set number

	of key presses.

	*/

	ETerminationByCount,

	/**

	Keyboard will stay in code entry mode while Ctrl is held

	down.

	*/

	ETerminationByCtrlUp

	};

/**

Responsible for loading and walking through a keymap conversion table.

@internalComponent

@released

*/

class TConvTable

	{

public:

	TConvTable();

	void Update(RLibrary aLibrary);

	SConvKeyData Convert(TUint aScanCode, const TInt &aModifiers) const;

	SConvKeyData ConvertBaseCase(TUint aScanCode, const TInt &aModifiers) const;

	inline TUint FirstScanCode() const;

	inline TUint LastScanCode() const;

private:

	SConvTable iConvTable;

	TUint iFirstScanCode;

	TUint iLastScanCode;

	SScanCodeBlockList iKeypadScanCodes;

	SKeyCodeList iNonAutorepKeyCodes;

	TBool onKeypad(TUint aScanCode) const;

	TBool autorepeatable(TUint aKeyCode) const;

	};

/**

Responsible for aggregating a series of digits

from separate keypresses into a single character.

@internalComponent

@released

*/

class TCtrlDigits

	{

public:

	TCtrlDigits();

	void Update(RLibrary aLibrary);

	void Reset();

	void AppendDigit(TUint aKeyCode, TUint aModifiers);

	inline void SetRadix(TRadix aRadix);

	inline void SetMaxCount(TInt aMaxCount);

	inline TRadix GetRadix() const;

	TBool Terminated(TInt aModifiers) const;

	TUint SetStateToCtrlDigits() const;

	inline TBool WithinLimits() const;

	inline TUint GetDigits() const;

	inline TBool Error() const;

private:

	TInt iCount;

	TInt iMaxCount;

	TInt iMaximumCtrlDigitsMaxCount;

	TUint32 iDigits;

	TRadix iRadix;

	TBool iErrorFlag;

	TCtrlDigitsTermination iTermination;

	};

/**

Definitions for keyboard states.

The first 3 values identify special keyboard states and

are used as an index to these states' tables. This is

only a partial list of possible states, states 1-9

are also valid, and should be used for translating

isolated characters e.g. to apply diacritics to vowels.

The next 3 do not specify particular states, but give

information to the key translator so that it can

decide the next state.

@internalComponent

@released

*/

enum TState

	{

	/**

	Normal keyboard state, which defines keys

	that transition	to the other states.

	*/

	EStateNormal						=0x0a,

	/**

	Allow characters to be specified

	by a decimal code. The state will be transitioned

	back to EStateNormal after a given count.

	*/

	EStateCtrlDigitsUntilCount			=0x0b,

	/**

	Allow characters to be specified

	by a decimal code. The state will be transitioned

	back to EStateNormal once Ctrl is released.

	*/

	EStateCtrlDigitsUntilCtrlUp			=0x0c,

// values used as "rules" to be processed in a switch statement

	EStateUnchanged						=0x40,

	EStateDerivedFromDigitEntered,

	EStateCtrlDigits

	};

/**

Defines an action to be performed for a keypress.

@see SFuncAndState::func

@internalComponent

@released

*/

enum TFuncGeneral

	{

	EDoNothing							=0x00,

	EPassKeyThru, ///< Pass key through, unchanged

	EPassSpecialKeyThru, ///< Translate to a new character

	EPassCtrlDigitsThru, ///< End accumulation of character digits

	EAddOnCtrlDigit, ///< Allow another control digit to be entered

	};

/**

Concrete implementation of a CKeyTranslator.

@internalComponent

@released

*/

NONSHARABLE_CLASS(CKeyTranslatorX) : public CKeyTranslator

	{

    friend class CKeyTranslator;

public:

	CKeyTranslatorX();

    virtual TInt GetModifierState();

    virtual void SetModifierState(TEventModifier aModifier,TModifierState aState);

	virtual TBool TranslateKey(TUint aScanCode, TBool aKeyUp,

								const CCaptureKeys &aCaptureKeys, TKeyData &aKeyData);

    virtual void UpdateModifiers(TInt aModifiers);

    virtual TInt ChangeKeyData(const TDesC& aLibraryName);

    TBool currentlyUpperCase(void);

    TUint executeFunctionsAndSetState(TCharExtended aChar);

	TInt Initialise();

private:

    TInt iCurModifiers;

	TMaskedModifiers iTogglingModifiers;

	TCtrlDigits iCurCtrlDigits;

	TConvTable iConvTable;

	TFuncTable iFuncTable;

	TUint iCurState;

	TBool iIsdefaultKeyData;

	RLibrary iKeyDataLib;

	RLibrary iDefaultKeyDataLib;

	};

/**

@internalComponent

@released

*/

enum TCP850Char

	{

	ECP850LogicNot=0x00aa,

	ECP850LcAe=0x0091,

	ECP850LcCcedilla=0x0087,

	ECP850EsTset=0x00e1,

	ECP850LcOslash=0x009b,

	ECP850LcThorn=0x00d0,

	ECP850LcSoftTh=0x00e7,

	ECP850LeftChevron=0x00ae,

	ECP850RightChevron=0x00af,

	ECP850InvExclam=0x00ad,

	ECP850InvQuest=0x00a8,

	ECP850LcAo=0x0086,

	ECP850Pound=0x009c,

	ECP850LcAumlaut=0x0084,

	ECP850LcEumlaut=0x0089,

	ECP850LcIumlaut=0x008b,

	ECP850LcOumlaut=0x0094,

	ECP850LcUumlaut=0x009a,

	ECP850LcYumlaut=0x0098,

	ECP850SpaceUmlaut=0x00f9,

	ECP850LcAgrave=0x0085,

	ECP850LcEgrave=0x008a,

	ECP850LcIgrave=0x008d,

	ECP850LcOgrave=0x0095,

	ECP850LcUgrave=0x0097,

	ECP850SpaceGrave=0x0060,

	ECP850LcAacute=0x00a0,

	ECP850LcEacute=0x0082,

	ECP850LcIacute=0x00a1,

	ECP850LcOacute=0x00a2,

	ECP850LcUacute=0x00a3,

	ECP850LcYacute=0x00ec,

	ECP850LcSpaceAcute=0x0027,

	ECP850LcAtilde=0x00c6,

	ECP850LcNtilde=0x00a4,