/*

* Copyright (c) 2007-2009 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:  The click maker plugin, which

*                handles key events at window server process.

* Part of:      Tactile Feedback.

*

*/

#ifndef C_TACTILECLICKPLUGIN_H

#define C_TACTILECLICKPLUGIN_H

#include <w32click.h>

#ifdef SYMBIAN_ENABLE_SPLIT_HEADERS

#include <graphics/pointereventdata.h> 

#endif //SYMBIAN_ENABLE_SPLIT_HEADERS

#include <tactilefeedback.h>

#include "tactilefeedbackserver.h"

class RTactileFeedback;

class CTactileAreaRegistry;

/**

 *  The click maker plugin for triggering tactile feedback.

 *

 *  Tactile feedback is generated on each pointer down event, in case the

 *  pointer event hit some area on screen where feedback is enabled.

 *  Feedback triggering has tight latency requirements, and thus this

 *  click maker plugin's purpose is to enable feedback triggering from

 *  window server process (instead of application process when the pointer

 *  event arrives there).

 *

 *  Feedback areas are kept in the Area Registry, and this plug-ins task is

 *  to pass incoming pointer events to the Area registry so that hit tests

 *  can be done to see if any feedback area was hit or not.

 *

 *  The implementation of this plugin relies to the fact that OtherEvent

 *  -function is called with the pointer event + window identifier and

 *  window group identifier as additional parameters (these are Symbian

 *  changes compared to the documented behaviour).

 *

 *  This plug-in is also responsible of providing 

 *  Tactile Feedback AnimDll API for AnimDll plug-ins. That API is 

 *  designed for supporting direct feedback triggering from AnimDll plug-ins,

 *  and it needs to be implemented by this plug-in because this is the only 

 *  component in Tactile Feedback subsystem that is guaranteed to run

 *  in the window server's process (other components have been designed in

 *  such way that they can be moved elsewhere in case necessary).

 *

 *  @lib N/A

 *  @since S60 v5.0

 */

NONSHARABLE_CLASS( CTactileClickPlugin ): 

    public CClickMaker,

    public MTactileFeedbackServer

    {

public:

    static CTactileClickPlugin* NewL();

    virtual ~CTactileClickPlugin();

// from base class CClickMaker

    /**

     * From CClickMaker.

     * This function is called by the window server whenever there is a 

     * key event, to generate the sound.

     *

     * The key events are not used by this plugin actually, because this

     * plug-in's purpose is to handle only pointer events.

     *

     * @since S60 v5.0

     * @param aType  - The type of the key event.

     * @param aEvent - The key event details. 

     */

    void KeyEvent( TEventCode aType,const TKeyEvent& aEvent );

    /**

     * From CClickMaker.

     * This function is called by the window server whenever there is a 

     * pointer event, to generate the sound.

     *

     * Not used by this plug-in because there is not enough information in

     * the pointer event for resolving the actual area and window where

     * pointer event was hit. Intead pointer events are handled in 

     * OtherEvent -function.

     *

     * @since S60 v5.0

     * @param aEvent - The pointer event details.

     */

    void PointerEvent( const TPointerEvent& aEvent );

    /**

     * From CClickMaker.

     * This function is a "future expansion" of the original click maker API,

     * and it has been taken into use by this plugin for getting more 

     * information about the pointer event than what is possible to pass as

     * parameter to PointerEvent -function.

     *

     * @since S60 v5.0

     * @param aType  - The type of the event.

     * @param aParam - Pointer to data package containing the pointer event,

     *                 window identifier where pointer event hit, and window

     *                 group identifier of the window group where the window

     *                 belongs to.

     */

    void OtherEvent( TInt aType, TAny* aParam=NULL );

    /**

     * From CClickMaker.

     * Implemented to enable this plug-in to communicate with the window

     * server client.

     *

     * Area registry management communication (such as creating or closing

     * an application) is communicated through this function.

     *

     * In practice communication is done between this plug-in, and 

     * Tactile Feedback Client API implementation.

     *

     * @since S60 v5.0

     * @param aOpcode - Opcode of the command sent by Client API

     * @param aArgs   - Pointer to the data sent by client.

     */

    TInt CommandReplyL( TInt aOpcode, TAny* aArgs );

// from base class MTactileFeedbackServer

    /**

     * From MTactileFeedbackServer.

     * Direct feedback service for Anim Dll plugins.

     *

     * @since S60 v5.0

     * @param aType - Logical feedback type to play.

     */

    void InstantFeedback( TTouchLogicalFeedback aType );

private:

    CTactileClickPlugin();

    void ConstructL();

    /**

     * Handles data parsing when new client connects to this plugin.

     *

     * Actual functionality is implemented in Tactile Area Registry.

     *

     * @param aArgs - Pointer to the data sent by client.

     */

    void HandleConnectL( TAny* aArgs );

    /**

     * Handles data parsing when client disconnects itself. In practice

     * this happens when application is closed.

     *

     * Actual functionality is implemented in Tactile Area Registry.

     *

     * @param aArgs - Pointer to the data sent by client.

     */

    void HandleDisconnect( TAny* aArgs );

    /**

     * Handles direct feedback request from Tactile Client API.

     *

     * In practice this function only parses the data so that the

     * logical feedback type is known. After that feedback type is passed

     * to Tactile Feedback Resolver, which will then play direct feedback

     * (or block the request if feedback is not enabled on the moment).

     *

     * @param aArgs - Pointer to the data sent by client.

     * @return KErrNone if operation succeeded, otherwise one of standand

     *         Symbian OS error codes.

     */

    TInt HandleImmediateFeedback( TAny* aArgs );

private: // data

    /**

     * Access to tactile feedback server, which actually produces 

     * the feedback.

     * Own.  

     */

    RTactileFeedback iFeedback;

    /**

     * Access to tactile area registry, which stores feedback areas and is

     * used for hit testing the incoming pointer events against registry 

     * content.

     * Own.  

     */

    CTactileAreaRegistry* iAreaRegistry;

    /**

     * Flag to indicate whether resolver construction has been attempted

     * already. We store this information to avoid unnecessary overhead at

     * boot when something is missing and it just is not possible to 

     * construct resolver.  

     */

    TBool iResolverConstructionAttempted;

    };

#endif // C_TACTILECLICKPLUGIN_H