--- 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 <e32std.h>
+#endif
+#ifndef __E32BASE_H__
+#include <e32base.h>
+#endif
+#ifndef __W32STD_H__
+#include <w32std.h>
+#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