williamr@2: // Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@2: // All rights reserved.
williamr@2: // This component and the accompanying materials are made available
williamr@2: // under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
williamr@2: // which accompanies this distribution, and is available
williamr@2: // at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2: //
williamr@2: // Initial Contributors:
williamr@2: // Nokia Corporation - initial contribution.
williamr@2: //
williamr@2: // Contributors:
williamr@2: //
williamr@2: // Description:
williamr@2: //
williamr@2: 
williamr@2: #ifndef __FEPBUTILS_H__
williamr@2: #define __FEPBUTILS_H__
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: /** Macro to be called by a keyboard-based FEP at the start of its CCoeControl::OfferKeyEventL()-overriding 
williamr@2: function.
williamr@2: 
williamr@2: It causes key up and key down events to be consumed so that the FEP only receives 
williamr@2: standard key events (of type EEventKey, see the TEventCode enumeration). It 
williamr@2: also causes key events that turn the FEP on or off to be consumed. If the 
williamr@2: FEP is simulating key events, or is off, no key events are consumed (so that 
williamr@2: all are passed on to the underlying application) and the macro returns with 
williamr@2: EKeyWasNotConsumed.
williamr@2: 
williamr@2: This should be the first thing called in the OfferKeyEventL() function. The 
williamr@2: FEP_END_KEY_EVENT_HANDLER_L macro should be used to return from the function.
williamr@2: 
williamr@2: @param aFep The CCoeFep object, should not be a pointer
williamr@2: @param aKeyEvent The TKeyEvent object from OfferKeyEventL()
williamr@2: @param aEventCode The TEventCode object from OfferKeyEventL()
williamr@2: 
williamr@2: @see TEventCode 
williamr@2: @publishedAll
williamr@2: @released */
williamr@2: #define FEP_START_KEY_EVENT_HANDLER_L(aFep, aKeyEvent, aEventCode)\
williamr@2: 	{\
williamr@2: 	if ((aFep).IsSimulatingKeyEvent())\
williamr@2: 		{\
williamr@2: 		return EKeyWasNotConsumed;\
williamr@2: 		}\
williamr@2: 	(aFep).OnStartingHandlingKeyEvent_WithDownUpFilterLC();\
williamr@2: 	if (((aEventCode)!=EEventKey))\
williamr@2: 		{\
williamr@2: 		return (aFep).OnFinishingHandlingKeyEvent_WithDownUpFilterL((aEventCode), (aKeyEvent), EKeyWasConsumed);\
williamr@2: 		}\
williamr@2: 	if (!(aFep).IsOn())\
williamr@2: 		{\
williamr@2: 		return (aFep).OnFinishingHandlingKeyEvent_WithDownUpFilterL((aEventCode), (aKeyEvent), EKeyWasNotConsumed);\
williamr@2: 		}\
williamr@2: 	}
williamr@2: 
williamr@2: /** Macro to be called by a keyboard-based FEP to return from its CCoeControl::OfferKeyEventL()-overriding 
williamr@2: function.
williamr@2: 
williamr@2: It should be used instead of the return statement. It should only be used 
williamr@2: if the FEP_START_KEY_EVENT_HANDLER_L macro was used at the start of the function. 
williamr@2: 
williamr@2: @param aFep The CCoeFep object, should not be a pointer
williamr@2: @param aKeyEvent The TKeyEvent object from OfferKeyEventL()
williamr@2: @param aKeyResponse Defined in EPOC32\INCLUDE\COEDEF.H 
williamr@2: 					If set to EKeyWasNotConsumed, allows the key event to reach the underlying application. 
williamr@2: 					If set to EKeyWasConsumed, prevents the key event reaching the underlying application.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released */
williamr@2: #define FEP_END_KEY_EVENT_HANDLER_L(aFep, aKeyEvent, aKeyResponse)\
williamr@2: 	{\
williamr@2: 	return (aFep).OnFinishingHandlingKeyEvent_WithDownUpFilterL(EEventKey, (aKeyEvent), (aKeyResponse));\
williamr@2: 	}
williamr@2: 
williamr@2: /** Macro to be called by a keyboard-based FEP at the start of its CCoeControl::OfferKeyEventL()-overriding 
williamr@2: function.
williamr@2: 
williamr@2: It causes events that turn the FEP on or off to be consumed. This variant 
williamr@2: of the macro ignores key up and key down events so that it should be used 
williamr@2: in preference to FEP_START_KEY_EVENT_HANDLER_L in the rare cases where the 
williamr@2: FEP wishes to handle EEventKeyDown or EEventKeyUp events. If the FEP is simulating 
williamr@2: key events, or is off, no key events are consumed and OfferKeyEventL() returns 
williamr@2: with EKeyWasNotConsumed. 
williamr@2: 
williamr@2: This should be the first thing called in the OfferKeyEventL() function. The 
williamr@2: FEP_END_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L macro should be used to return 
williamr@2: from the function. 
williamr@2: 
williamr@2: @param aFep The CCoeFep object, should not be a pointer
williamr@2: @param aKeyEvent The TKeyEvent object from OfferKeyEventL()
williamr@2: @param aEventCode The TEventCode object from OfferKeyEventL()
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released */
williamr@2: #define FEP_START_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L(aFep, aKeyEvent, aEventCode)\
williamr@2: 	{\
williamr@2: 	if ((aFep).IsSimulatingKeyEvent())\
williamr@2: 		{\
williamr@2: 		return EKeyWasNotConsumed;\
williamr@2: 		}\
williamr@2: 	(aFep).OnStartingHandlingKeyEvent_NoDownUpFilterLC();\
williamr@2: 	if ((aEventCode)==EEventKey)\
williamr@2: 		{\
williamr@2: 		if (!(aFep).IsOn())\
williamr@2: 			{\
williamr@2: 			return (aFep).OnFinishingHandlingKeyEvent_NoDownUpFilterL((aEventCode), (aKeyEvent), EKeyWasNotConsumed);\
williamr@2: 			}\
williamr@2: 		}\
williamr@2: 	}
williamr@2: 
williamr@2: /** Macro to be called by a keyboard-based FEP to return from its CCoeControl::OfferKeyEventL()-overriding 
williamr@2: function.
williamr@2: 
williamr@2: It should be used instead of the return statement. This variant of the macro 
williamr@2: should only be used if the FEP_START_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L 
williamr@2: macro was used at the start of the function. 
williamr@2: 
williamr@2: @param aFep The CCoeFep object, should not be a pointer
williamr@2: @param aKeyEvent The TKeyEvent object from OfferKeyEventL()
williamr@2: @param aEventCode The TEventCode object from OfferKeyEventL()
williamr@2: @param aKeyResponse Defined in EPOC32\INCLUDE\COEDEF. 
williamr@2: 					If set to EKeyWasNotConsumed, allows the key event to reach the underlying application. 
williamr@2: 					If set to EKeyWasConsumed, prevents the key event reaching the underlying application.
williamr@2: 
williamr@2: @publishedAll
williamr@2: @released */
williamr@2: #define FEP_END_KEY_EVENT_HANDLER_NO_DOWN_UP_FILTER_L(aFep, aKeyEvent, aEventCode, aKeyResponse)\
williamr@2: 	{\
williamr@2: 	return (aFep).OnFinishingHandlingKeyEvent_NoDownUpFilterL((aEventCode), (aKeyEvent), (aKeyResponse));\
williamr@2: 	}
williamr@2: 
williamr@2: 
williamr@2: 
williamr@2: #endif // __FEPBUTILS_H__