1.1 --- a/epoc32/include/w32click.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/w32click.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,247 @@
1.4 -w32click.h
1.5 +// Copyright (c) 2001-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +// All rights reserved.
1.7 +// This component and the accompanying materials are made available
1.8 +// 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
1.9 +// which accompanies this distribution, and is available
1.10 +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.11 +//
1.12 +// Initial Contributors:
1.13 +// Nokia Corporation - initial contribution.
1.14 +//
1.15 +// Contributors:
1.16 +//
1.17 +// Description:
1.18 +// Definition of class that needs to be provided by a Key Click plugin
1.19 +//
1.20 +//
1.21 +
1.22 +#ifndef __W32CLICK_H__
1.23 +#define __W32CLICK_H__
1.24 +
1.25 +#ifndef __E32STD_H__
1.26 +#include <e32std.h>
1.27 +#endif
1.28 +#ifndef __E32BASE_H__
1.29 +#include <e32base.h>
1.30 +#endif
1.31 +#ifndef __W32STD_H__
1.32 +#include <w32std.h>
1.33 +#endif
1.34 +
1.35 +
1.36 +class CClickMaker: public CBase
1.37 +/** Key or pointer click plug-in provider interface.
1.38 +
1.39 +This class should be implemented by a plug-in DLL in order to produce a sound
1.40 +when a key is pressed, a key auto repeats or when the screen is tapped with
1.41 +a pointer. When any of these events occur, the window server informs the plug-in
1.42 +DLL, which can then make the sound.
1.43 +
1.44 +The details of the event are also passed to the plug-in so that the sound
1.45 +can be tailored to the precise event, for example clicking on different keys on the
1.46 +keypad or on different parts of the screen could make different sounds.
1.47 +
1.48 +The name of the initial plug-in to use can be specified in the wsini.ini configuration
1.49 +file using the KEYCLICKPLUGIN or KEYCLICKPLUGINFIXED keywords. When the operating
1.50 +system boots, wsini.ini is read for the name of this plug-in. If a plug-in
1.51 +name exists, the window server will try to load it. At a later time, any client
1.52 +of the window server can request a new plug-in to be loaded or the current
1.53 +one to be unloaded, using the RSoundPlugIn class.
1.54 +
1.55 +The plug-in is a polymorphic DLL which implements the CClickMaker interface.
1.56 +Its first UID is KDynamicLibraryUidValue and its second UID is 0x10004F63.
1.57 +Its first exported function should create an object of the CClickMaker sub-class
1.58 +and should have the following signature:
1.59 +
1.60 +EXPORT_C CClickMaker* CreateClickMakerL()
1.61 +
1.62 +@publishedAll
1.63 +@released
1.64 +@see RSoundPlugIn */
1.65 + {
1.66 +public:
1.67 + /** This function is called by the window server whenever there is a key event,
1.68 + to generate the sound.
1.69 +
1.70 + It must be implemented by the key or pointer click plug-in.
1.71 +
1.72 + If the sound cannot be made, the function should continue without leaving.
1.73 +
1.74 + @param aType The type of key event: EEventKey, EEventKeyUp, EEventKeyDown
1.75 + or EEventKeyRepeat.
1.76 + @param aEvent The key event details. */
1.77 + virtual void KeyEvent(TEventCode aType,const TKeyEvent& aEvent)=0;
1.78 +
1.79 + /** This function is called by the window server whenever there is a pointer event,
1.80 + to generate the sound.
1.81 +
1.82 + It must be implemented by the key or pointer click plug-in.
1.83 +
1.84 + If the sound cannot be made, the function should continue without leaving.
1.85 +
1.86 + The iParentPosition data member of aEvent is not the position of the pointer
1.87 + event relative to origin of the parent window. Instead it is the position
1.88 + on the screen. This is because the parent window has no meaning inside the
1.89 + plug-in as it does to the window server client and also knowledge
1.90 + of the screen position may be useful to the plug-in.
1.91 +
1.92 + @param aEvent The pointer event details. */
1.93 + virtual void PointerEvent(const TPointerEvent& aEvent)=0;
1.94 +
1.95 + /** This function is intended for future expansion of the interface, in case it
1.96 + needs to support sounds for other types of event.
1.97 +
1.98 + Currently it is called by the window server, with several values for aType.
1.99 + For each of these aParam will need to be cast to a different class type
1.100 + to get the data:
1.101 + EEventPointer: cast to TPointerEventData*
1.102 + EEventScreenDeviceChanged: TClickMakerData*
1.103 + EEventGroupWindowOpen: TGroupWindowOpenData*
1.104 + EEventGroupWindowClose: TInt (the identifier of the window group being closed)
1.105 + EEventWindowClose: TWindowCloseData*
1.106 +
1.107 + @param aType One of the above listed values, in future may be used with other values.
1.108 + @param aParam See above. */
1.109 + virtual void OtherEvent(TInt aType,TAny* aParam=NULL)=0;
1.110 +
1.111 + /** This function may be implemented by the key or pointer click plug-in to enable
1.112 + the plug-in to communicate with the window server client.
1.113 +
1.114 + If this is not required, the implementation may simply return zero.
1.115 +
1.116 + It is called by RSoundPlugIn::CommandReply() which returns the value returned
1.117 + by this function.
1.118 +
1.119 + The return value can be generated either by returning it from the function
1.120 + or by leaving with the value. In either case, the client will get back the
1.121 + value concerned.
1.122 +
1.123 + @param aOpcode Opcode understood by both the window server client and the
1.124 + plug-in DLL.
1.125 + @param aArgs Arguments packaged by the window server client.
1.126 + @return A value passed back to the client. This may be KErrNone or another
1.127 + of the system-wide error codes. */
1.128 + virtual TInt CommandReplyL(TInt aOpcode, TAny *aArgs)=0;
1.129 + };
1.130 +
1.131 +struct TClickMakerData
1.132 +/**
1.133 +Passed to a Key Click Plug-in using the function CClickMaker::OtherEvent when the
1.134 +aType value is EEventScreenDeviceChanged.
1.135 +
1.136 +@publishedAll
1.137 +@released
1.138 +*/
1.139 + {
1.140 + TInt screenDeviceMode;
1.141 + };
1.142 +
1.143 +class TPointerEventData
1.144 +/**
1.145 +Passed to a Key Click Plug-in using the function CClickMaker::OtherEvent when the
1.146 +aType value is EEventPointer.
1.147 +This includes information about the window the pointer event will be sent to.
1.148 +This is the normally the window being clicked on by the user, but pointer capturing
1.149 +and grabbing may affect this.
1.150 +
1.151 +@publishedAll
1.152 +@released
1.153 +*/
1.154 + {
1.155 +public:
1.156 + enum TSource
1.157 + /**
1.158 + A list of locations that WSERV receives events from
1.159 + */
1.160 + {
1.161 + /** The source is not specified. */
1.162 + EUnspecified,
1.163 + /** The event came from the kernel. */
1.164 + EKernel,
1.165 + /** The event came from a client API. */
1.166 + EClient,
1.167 + /** The event came from an Anim DLL. */
1.168 + EAnimDLL,
1.169 + };
1.170 +public:
1.171 + /**
1.172 + The version number of the data passed with EEventPointer, current always 0.
1.173 + */
1.174 + TInt iVersion;
1.175 + /**
1.176 + The screen position of pointer event.
1.177 + */
1.178 + TPoint iCurrentPos;
1.179 + /**
1.180 + The full pointer event data previously passed to the CClickMaker::PointerEvent function,
1.181 + except that the iParentPosition will be the actual parent position, when previously passed
1.182 + to the plug-in this value was the screen position.
1.183 + */
1.184 + TPointerEvent iPointerEvent;
1.185 + /**
1.186 + The client handle of the window or zero if the window is not a client window.
1.187 + */
1.188 + TUint32 iClientHandle;
1.189 + /**
1.190 + The current top left of the window on the screen.
1.191 + */
1.192 + TPoint iWindowOrigin;
1.193 + /**
1.194 + The Window Group Identifier of the window group that is a parent (or grand parent etc.)
1.195 + of the window the event is sent to or zero if the window is not a client window.
1.196 + */
1.197 + TInt iWindowGroupId;
1.198 + /**
1.199 + The source that WSERV recieves the event from,
1.200 + currently set to EUnspecified as this is for future expansion.
1.201 + */
1.202 + TSource iSource;
1.203 + };
1.204 +
1.205 +class TGroupWindowOpenData
1.206 +/**
1.207 +Passed to a Key Click Plug-in using the function CClickMaker::OtherEvent when the
1.208 +aType value is EEventGroupWindowOpen.
1.209 +
1.210 +@publishedAll
1.211 +@released
1.212 +*/
1.213 + {
1.214 +public:
1.215 + /**
1.216 + The Window Group Identifier of the window being created.
1.217 + */
1.218 + TInt iIdentifier;
1.219 + /**
1.220 + A number unique to the client creating the window group - allows the Plug-in to tell
1.221 + different clients apart.
1.222 + */
1.223 + TUint iClient;
1.224 + /**
1.225 + The number of Window Groups currently owned by that client (not including the one being created).
1.226 + */
1.227 + TInt iNumClientWindowGroups;
1.228 + };
1.229 +
1.230 +class TWindowCloseData
1.231 +/**
1.232 +Passed to a Key Click Plug-in using the function CClickMaker::OtherEvent when the aType value
1.233 +is EEventWindowClose.
1.234 +
1.235 +@publishedAll
1.236 +@released
1.237 +*/
1.238 + {
1.239 +public:
1.240 + /**
1.241 + The client handle of the window being closed.
1.242 + */
1.243 + TUint32 iClientHandle;
1.244 + /**
1.245 + The Window Group Identifier of the window group that is a parent (or grandparent etc.)
1.246 + of the window being closed, or 0 if the window has been orphaned.
1.247 + */
1.248 + TInt iWindowGroupId;
1.249 + };
1.250 +
1.251 +#endif