diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/w32click.h --- a/epoc32/include/w32click.h Tue Nov 24 13:55:44 2009 +0000 +++ b/epoc32/include/w32click.h Tue Mar 16 16:12:26 2010 +0000 @@ -1,1 +1,247 @@ -w32click.h +// Copyright (c) 2001-2009 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 "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members +// which accompanies this distribution, and is available +// at the URL "http://www.symbianfoundation.org/legal/licencesv10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// Definition of class that needs to be provided by a Key Click plugin +// +// + +#ifndef __W32CLICK_H__ +#define __W32CLICK_H__ + +#ifndef __E32STD_H__ +#include +#endif +#ifndef __E32BASE_H__ +#include +#endif +#ifndef __W32STD_H__ +#include +#endif + + +class CClickMaker: public CBase +/** Key or pointer click plug-in provider interface. + +This class should be implemented by a plug-in DLL in order to produce a sound +when a key is pressed, a key auto repeats or when the screen is tapped with +a pointer. When any of these events occur, the window server informs the plug-in +DLL, which can then make the sound. + +The details of the event are also passed to the plug-in so that the sound +can be tailored to the precise event, for example clicking on different keys on the +keypad or on different parts of the screen could make different sounds. + +The name of the initial plug-in to use can be specified in the wsini.ini configuration +file using the KEYCLICKPLUGIN or KEYCLICKPLUGINFIXED keywords. When the operating +system boots, wsini.ini is read for the name of this plug-in. If a plug-in +name exists, the window server will try to load it. At a later time, any client +of the window server can request a new plug-in to be loaded or the current +one to be unloaded, using the RSoundPlugIn class. + +The plug-in is a polymorphic DLL which implements the CClickMaker interface. +Its first UID is KDynamicLibraryUidValue and its second UID is 0x10004F63. +Its first exported function should create an object of the CClickMaker sub-class +and should have the following signature: + +EXPORT_C CClickMaker* CreateClickMakerL() + +@publishedAll +@released +@see RSoundPlugIn */ + { +public: + /** This function is called by the window server whenever there is a key event, + to generate the sound. + + It must be implemented by the key or pointer click plug-in. + + If the sound cannot be made, the function should continue without leaving. + + @param aType The type of key event: EEventKey, EEventKeyUp, EEventKeyDown + or EEventKeyRepeat. + @param aEvent The key event details. */ + virtual void KeyEvent(TEventCode aType,const TKeyEvent& aEvent)=0; + + /** This function is called by the window server whenever there is a pointer event, + to generate the sound. + + It must be implemented by the key or pointer click plug-in. + + If the sound cannot be made, the function should continue without leaving. + + The iParentPosition data member of aEvent is not the position of the pointer + event relative to origin of the parent window. Instead it is the position + on the screen. This is because the parent window has no meaning inside the + plug-in as it does to the window server client and also knowledge + of the screen position may be useful to the plug-in. + + @param aEvent The pointer event details. */ + virtual void PointerEvent(const TPointerEvent& aEvent)=0; + + /** This function is intended for future expansion of the interface, in case it + needs to support sounds for other types of event. + + Currently it is called by the window server, with several values for aType. + For each of these aParam will need to be cast to a different class type + to get the data: + EEventPointer: cast to TPointerEventData* + EEventScreenDeviceChanged: TClickMakerData* + EEventGroupWindowOpen: TGroupWindowOpenData* + EEventGroupWindowClose: TInt (the identifier of the window group being closed) + EEventWindowClose: TWindowCloseData* + + @param aType One of the above listed values, in future may be used with other values. + @param aParam See above. */ + virtual void OtherEvent(TInt aType,TAny* aParam=NULL)=0; + + /** This function may be implemented by the key or pointer click plug-in to enable + the plug-in to communicate with the window server client. + + If this is not required, the implementation may simply return zero. + + It is called by RSoundPlugIn::CommandReply() which returns the value returned + by this function. + + The return value can be generated either by returning it from the function + or by leaving with the value. In either case, the client will get back the + value concerned. + + @param aOpcode Opcode understood by both the window server client and the + plug-in DLL. + @param aArgs Arguments packaged by the window server client. + @return A value passed back to the client. This may be KErrNone or another + of the system-wide error codes. */ + virtual TInt CommandReplyL(TInt aOpcode, TAny *aArgs)=0; + }; + +struct TClickMakerData +/** +Passed to a Key Click Plug-in using the function CClickMaker::OtherEvent when the +aType value is EEventScreenDeviceChanged. + +@publishedAll +@released +*/ + { + TInt screenDeviceMode; + }; + +class TPointerEventData +/** +Passed to a Key Click Plug-in using the function CClickMaker::OtherEvent when the +aType value is EEventPointer. +This includes information about the window the pointer event will be sent to. +This is the normally the window being clicked on by the user, but pointer capturing +and grabbing may affect this. + +@publishedAll +@released +*/ + { +public: + enum TSource + /** + A list of locations that WSERV receives events from + */ + { + /** The source is not specified. */ + EUnspecified, + /** The event came from the kernel. */ + EKernel, + /** The event came from a client API. */ + EClient, + /** The event came from an Anim DLL. */ + EAnimDLL, + }; +public: + /** + The version number of the data passed with EEventPointer, current always 0. + */ + TInt iVersion; + /** + The screen position of pointer event. + */ + TPoint iCurrentPos; + /** + The full pointer event data previously passed to the CClickMaker::PointerEvent function, + except that the iParentPosition will be the actual parent position, when previously passed + to the plug-in this value was the screen position. + */ + TPointerEvent iPointerEvent; + /** + The client handle of the window or zero if the window is not a client window. + */ + TUint32 iClientHandle; + /** + The current top left of the window on the screen. + */ + TPoint iWindowOrigin; + /** + The Window Group Identifier of the window group that is a parent (or grand parent etc.) + of the window the event is sent to or zero if the window is not a client window. + */ + TInt iWindowGroupId; + /** + The source that WSERV recieves the event from, + currently set to EUnspecified as this is for future expansion. + */ + TSource iSource; + }; + +class TGroupWindowOpenData +/** +Passed to a Key Click Plug-in using the function CClickMaker::OtherEvent when the +aType value is EEventGroupWindowOpen. + +@publishedAll +@released +*/ + { +public: + /** + The Window Group Identifier of the window being created. + */ + TInt iIdentifier; + /** + A number unique to the client creating the window group - allows the Plug-in to tell + different clients apart. + */ + TUint iClient; + /** + The number of Window Groups currently owned by that client (not including the one being created). + */ + TInt iNumClientWindowGroups; + }; + +class TWindowCloseData +/** +Passed to a Key Click Plug-in using the function CClickMaker::OtherEvent when the aType value +is EEventWindowClose. + +@publishedAll +@released +*/ + { +public: + /** + The client handle of the window being closed. + */ + TUint32 iClientHandle; + /** + The Window Group Identifier of the window group that is a parent (or grandparent etc.) + of the window being closed, or 0 if the window has been orphaned. + */ + TInt iWindowGroupId; + }; + +#endif