1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/graphics/windowing/windowserver/inc/Graphics/wskeyrouter.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,216 @@
1.4 +// Copyright (c) 2010 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// Key Event Routing Plug-in API
1.18 +
1.19 +/**
1.20 +@file
1.21 +@publishedPartner
1.22 +@prototype
1.23 +*/
1.24 +
1.25 +#ifndef WSKEYROUTER_H
1.26 +#define WSKEYROUTER_H
1.27 +
1.28 +#include <e32base.h>
1.29 +#include <w32std.h>
1.30 +
1.31 +/**
1.32 +Interface Uid
1.33 +*/
1.34 +const TUid KKeyRouterPluginUid = { 0x102872e1 };
1.35 +
1.36 +/**
1.37 +Key Capture Type
1.38 +*/
1.39 +enum TKeyCaptureType
1.40 + {
1.41 + ECaptureTypeKey = 0,
1.42 + ECaptureTypeLongKey = 1,
1.43 + ECaptureTypeKeyUpDown = 2
1.44 + };
1.45 +
1.46 +/**
1.47 +Key Capture Request
1.48 +*/
1.49 +struct TKeyCaptureRequest
1.50 + {
1.51 + /** Capture type */
1.52 + TKeyCaptureType iType;
1.53 +
1.54 + /** Keycode or scancode to be captured */
1.55 + TUint iInputCode;
1.56 +
1.57 + /** Output keycode or scancode. When iInputCode is captured, RouteKey()
1.58 + places iOutputCode in TKeyEventRouterOutput.iKeyEvent */
1.59 + TUint iOutputCode;
1.60 +
1.61 + /** Bitmask of modifier keys of interest. Key events are captured only
1.62 + when the modifier keys specified by iModifierMask are in the states
1.63 + specified by iModifiers */
1.64 + TUint iModifierMask;
1.65 +
1.66 + /** Bitmask of modifier key states */
1.67 + TUint iModifiers;
1.68 +
1.69 + /** Opaque handle for this request */
1.70 + TAny* iHandle;
1.71 +
1.72 + /** Opaque handle to window group through which request was made */
1.73 + TAny* iWindowGroup;
1.74 +
1.75 + /** Identifier of the window group through which request was made */
1.76 + TInt iWindowGroupId;
1.77 +
1.78 + /** UID of application that made the capture request */
1.79 + TUid iAppUid;
1.80 +
1.81 + /** Capture priority for this request. If more than one window group has
1.82 + requested capture for the same key event, the one with the highest
1.83 + priority will capture it (unless overridden by application specific
1.84 + rules). */
1.85 + TInt iPriority;
1.86 +
1.87 + /** Reserved for future use */
1.88 + TInt iReserved[2];
1.89 + };
1.90 +
1.91 +/**
1.92 +Input parameters for RouteKey()
1.93 +*/
1.94 +struct TKeyEventRouterInput
1.95 + {
1.96 + inline TKeyEventRouterInput(TKeyCaptureType aType, const TKeyEvent& aKeyEvent, TAny* aFocusWindowGroup, TUid aFocusAppUid);
1.97 +
1.98 + /** Capture type */
1.99 + TKeyCaptureType iType;
1.100 +
1.101 + /** Input key event */
1.102 + TKeyEvent iKeyEvent;
1.103 +
1.104 + /** Opaque handle to current focussed window group */
1.105 + TAny* iFocusWindowGroup;
1.106 +
1.107 + /** UID of client application with current focussed window group */
1.108 + TUid iFocusAppUid;
1.109 +
1.110 + /** Reserved for future use */
1.111 + TInt iReserved[2];
1.112 + };
1.113 +
1.114 +/**
1.115 +Result codes for RouteKey()
1.116 +*/
1.117 +enum TKeyEventRouterResult
1.118 + {
1.119 + /** Key routed, no capture */
1.120 + ERouted = 0,
1.121 +
1.122 + /** Key captured and routed */
1.123 + ECaptured = 1,
1.124 +
1.125 + /** Key consumed, do not deliver event */
1.126 + EConsumed = 2
1.127 + };
1.128 +
1.129 +/**
1.130 +Output parameters for RouteKey()
1.131 +*/
1.132 +struct TKeyEventRouterOutput
1.133 + {
1.134 + /** Result code */
1.135 + TKeyEventRouterResult iResult;
1.136 +
1.137 + /** Output key event as translated by plug-in. Key code may be set by
1.138 + RWindowGroup::CaptureLongKey() via TKeyCaptureRequest.iOutputCode **/
1.139 + TKeyEvent iKeyEvent;
1.140 +
1.141 + /** Opaque handle to destination window group or NULL if captured by WServ
1.142 + (hotkey). Plug-in must set this to either the window group from the
1.143 + matching capture request or to TKeyEventRouterInput.iFocusWindowGroup */
1.144 + TAny* iWindowGroup;
1.145 +
1.146 + /** Opaque handle from matching capture request or NULL if none */
1.147 + TAny* iCaptureHandle;
1.148 +
1.149 + /** Reserved for future use */
1.150 + TInt iReserved[2];
1.151 + };
1.152 +
1.153 +/**
1.154 +Key Event Router Interface
1.155 +
1.156 +This class is implemented by a plug-in DLL in order to perform customised
1.157 +routing of window server key events.
1.158 +
1.159 +The Key Event Routing plug-in is a polymorphic DLL that implements the
1.160 +CKeyEventRouter interface. Its UID1 and UID2 must be KDynamicLibraryUid and
1.161 +KKeyRouterPluginUid respectively. UID3 identifies a particular implementation
1.162 +of the plug-in. The first and only exported function should create and return
1.163 +an object of the CKeyEventRouter sub-class.
1.164 +*/
1.165 +class CKeyEventRouter : public CBase
1.166 + {
1.167 +public:
1.168 + /**
1.169 + Create and return an instance of CKeyEventRouter
1.170 +
1.171 + @return Pointer to new router instance
1.172 + */
1.173 + IMPORT_C static CKeyEventRouter* NewL();
1.174 +
1.175 + /**
1.176 + Add a new key capture request
1.177 +
1.178 + @param aRequest Capture request details
1.179 + */
1.180 + virtual void AddCaptureKeyL(const TKeyCaptureRequest& aRequest) = 0;
1.181 +
1.182 + /**
1.183 + Update an existing key capture request
1.184 +
1.185 + @param aRequest Updated capture request details
1.186 + */
1.187 + virtual void UpdateCaptureKeyL(const TKeyCaptureRequest& aRequest) = 0;
1.188 +
1.189 + /**
1.190 + Cancel a key capture request
1.191 +
1.192 + @param aType Capture type
1.193 + @param aHandle Opaque handle of request to be cancelled
1.194 + */
1.195 + virtual void CancelCaptureKey(TKeyCaptureType aType, TAny* aHandle) = 0;
1.196 +
1.197 + /**
1.198 + Route the key event described by aInput and return its destination
1.199 + in iOutput.
1.200 +
1.201 + @param aInput Input data with key event to be routed
1.202 + @param aOutput Output key event and routing results
1.203 + */
1.204 + virtual void RouteKey(const TKeyEventRouterInput& aInput,
1.205 + TKeyEventRouterOutput& aOutput) = 0;
1.206 +
1.207 + /**
1.208 + Reserved for future use
1.209 + */
1.210 +private:
1.211 + virtual void Reserved1() {};
1.212 + virtual void Reserved2() {};
1.213 + };
1.214 +
1.215 +inline TKeyEventRouterInput::TKeyEventRouterInput(TKeyCaptureType aType, const TKeyEvent& aKeyEvent, TAny* aFocusWindowGroup, TUid aFocusAppUid) : iType(aType), iKeyEvent(aKeyEvent), iFocusWindowGroup(aFocusWindowGroup), iFocusAppUid(aFocusAppUid)
1.216 + {
1.217 + }
1.218 +
1.219 +#endif // WSKEYROUTER_H