// Copyright (c) 2010 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:
// Key Event Routing Plug-in API
/**
@file
@publishedPartner
@prototype
*/
#ifndef WSKEYROUTER_H
#define WSKEYROUTER_H
#include <e32base.h>
#include <w32std.h>
/**
Interface Uid
*/
const TUid KKeyRouterPluginUid = { 0x102872e1 };
/**
Key Capture Type
*/
enum TKeyCaptureType
{
ECaptureTypeKey = 0,
ECaptureTypeLongKey = 1,
ECaptureTypeKeyUpDown = 2
};
/**
Key Capture Request
*/
struct TKeyCaptureRequest
{
/** Capture type */
TKeyCaptureType iType;
/** Keycode or scancode to be captured */
TUint iInputCode;
/** Output keycode or scancode. When iInputCode is captured, RouteKey()
places iOutputCode in TKeyEventRouterOutput.iKeyEvent */
TUint iOutputCode;
/** Bitmask of modifier keys of interest. Key events are captured only
when the modifier keys specified by iModifierMask are in the states
specified by iModifiers */
TUint iModifierMask;
/** Bitmask of modifier key states */
TUint iModifiers;
/** Opaque handle for this request */
TAny* iHandle;
/** Opaque handle to window group through which request was made */
TAny* iWindowGroup;
/** Identifier of the window group through which request was made */
TInt iWindowGroupId;
/** UID of application that made the capture request */
TUid iAppUid;
/** Capture priority for this request. If more than one window group has
requested capture for the same key event, the one with the highest
priority will capture it (unless overridden by application specific
rules). */
TInt iPriority;
/** Reserved for future use */
TInt iReserved[2];
};
/**
Input parameters for RouteKey()
*/
struct TKeyEventRouterInput
{
inline TKeyEventRouterInput(TKeyCaptureType aType, const TKeyEvent& aKeyEvent, TAny* aFocusWindowGroup, TUid aFocusAppUid);
/** Capture type */
TKeyCaptureType iType;
/** Input key event */
TKeyEvent iKeyEvent;
/** Opaque handle to current focussed window group */
TAny* iFocusWindowGroup;
/** UID of client application with current focussed window group */
TUid iFocusAppUid;
/** Reserved for future use */
TInt iReserved[2];
};
/**
Result codes for RouteKey()
*/
enum TKeyEventRouterResult
{
/** Key routed, no capture */
ERouted = 0,
/** Key captured and routed */
ECaptured = 1,
/** Key consumed, do not deliver event */
EConsumed = 2
};
/**
Output parameters for RouteKey()
*/
struct TKeyEventRouterOutput
{
/** Result code */
TKeyEventRouterResult iResult;
/** Output key event as translated by plug-in. Key code may be set by
RWindowGroup::CaptureLongKey() via TKeyCaptureRequest.iOutputCode **/
TKeyEvent iKeyEvent;
/** Opaque handle to destination window group or NULL if captured by WServ
(hotkey). Plug-in must set this to either the window group from the
matching capture request or to TKeyEventRouterInput.iFocusWindowGroup */
TAny* iWindowGroup;
/** Opaque handle from matching capture request or NULL if none */
TAny* iCaptureHandle;
/** Reserved for future use */
TInt iReserved[2];
};
/**
Key Event Router Interface
This class is implemented by a plug-in DLL in order to perform customised
routing of window server key events.
The Key Event Routing plug-in is a polymorphic DLL that implements the
CKeyEventRouter interface. Its UID1 and UID2 must be KDynamicLibraryUid and
KKeyRouterPluginUid respectively. UID3 identifies a particular implementation
of the plug-in. The first and only exported function should create and return
an object of the CKeyEventRouter sub-class.
*/
class CKeyEventRouter : public CBase
{
public:
/**
Create and return an instance of CKeyEventRouter
@return Pointer to new router instance
*/
IMPORT_C static CKeyEventRouter* NewL();
/**
Add a new key capture request
@param aRequest Capture request details
*/
virtual void AddCaptureKeyL(const TKeyCaptureRequest& aRequest) = 0;
/**
Update an existing key capture request
@param aRequest Updated capture request details
*/
virtual void UpdateCaptureKeyL(const TKeyCaptureRequest& aRequest) = 0;
/**
Cancel a key capture request
@param aType Capture type
@param aHandle Opaque handle of request to be cancelled
*/
virtual void CancelCaptureKey(TKeyCaptureType aType, TAny* aHandle) = 0;
/**
Route the key event described by aInput and return its destination
in iOutput.
@param aInput Input data with key event to be routed
@param aOutput Output key event and routing results
*/
virtual void RouteKey(const TKeyEventRouterInput& aInput,
TKeyEventRouterOutput& aOutput) = 0;
/**
Reserved for future use
*/
private:
virtual void Reserved1() {};
virtual void Reserved2() {};
};
inline TKeyEventRouterInput::TKeyEventRouterInput(TKeyCaptureType aType, const TKeyEvent& aKeyEvent, TAny* aFocusWindowGroup, TUid aFocusAppUid) : iType(aType), iKeyEvent(aKeyEvent), iFocusWindowGroup(aFocusWindowGroup), iFocusAppUid(aFocusAppUid)
{
}
#endif // WSKEYROUTER_H