FCL/sf/os/kernelhwsrv: comparison kernel/eka/include/k32keys.h

equal deleted inserted replaced

-:43365a9b78a3
+:d8d70de2bd36
-// Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
+// 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".
 						   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;
+	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;
+	TMaskedModifiers maskedModifiers;
 	TUint numSubTables;
 	const SConvSubTable * const *ppsubTables;
 	};
 /**
+The top level collection of all different translation
+tables.
 @publishedPartner
 @released
 */
 struct SConvTable
 	{
 	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
 	{
 	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;
+	TUint8 state; ///< The next TState to transition to
-	TUint8 func;
+	TUint8 func; ///< A TFuncGeneral action
-	TInt32 funcParam;
+	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;
+	TMaskedModifiers maskedModifiers; ///< Required modifier combination
-	TKeyCodePattern keyCodePattern;
+	TKeyCodePattern keyCodePattern; ///< Required keypress
-	SFuncAndState funcAndNewState;
+	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
 	{
 	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
 	{
 	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
 	{
 	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
 	{
 	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
 	{
-// values used as an index to a table
+	/**
+	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,
+	EPassKeyThru, ///< Pass key through, unchanged
-	EPassSpecialKeyThru,
+	EPassSpecialKeyThru, ///< Translate to a new character
-	EPassCtrlDigitsThru,
+	EPassCtrlDigitsThru, ///< End accumulation of character digits
-	EAddOnCtrlDigit,
+	EAddOnCtrlDigit, ///< Allow another control digit to be entered
 	};
 /**
+Concrete implementation of a CKeyTranslator.
 @internalComponent
 @released
 */
 NONSHARABLE_CLASS(CKeyTranslatorX) : public CKeyTranslator
 	{

changeset 247	d8d70de2bd36
parent 0	a41df078684a
child 257	3e88ff8f41d5