1 /*

     2 * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  The click maker plugin, which

    15 *                handles key events at window server process.

    16 * Part of:      Tactile Feedback.

    17 *

    18 */

    19 

    20 

    21 #ifndef C_TACTILECLICKPLUGIN_H

    22 #define C_TACTILECLICKPLUGIN_H

    23 

    24 

    25 

    26 #include <w32click.h>

    27 

    28 #ifdef SYMBIAN_ENABLE_SPLIT_HEADERS

    29 #include <graphics/pointereventdata.h> 

    30 #endif //SYMBIAN_ENABLE_SPLIT_HEADERS

    31 

    32 #include <tactilefeedback.h>

    33 

    34 #include "tactilefeedbackserver.h"

    35 

    36 class RTactileFeedback;

    37 class CTactileAreaRegistry;

    38 

    39 

    40 /**

    41  *  The click maker plugin for triggering tactile feedback.

    42  *

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

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

    45  *  Feedback triggering has tight latency requirements, and thus this

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

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

    48  *  event arrives there).

    49  *

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

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

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

    53  *

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

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

    56  *  window group identifier as additional parameters (these are Symbian

    57  *  changes compared to the documented behaviour).

    58  *

    59  *  This plug-in is also responsible of providing 

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

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

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

    63  *  component in Tactile Feedback subsystem that is guaranteed to run

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

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

    66  *

    67  *  @lib N/A

    68  *  @since S60 v5.0

    69  */

    70 NONSHARABLE_CLASS( CTactileClickPlugin ): 

    71     public CClickMaker,

    72     public MTactileFeedbackServer

    73     {

    74 public:

    75 

    76     static CTactileClickPlugin* NewL();

    77 

    78     virtual ~CTactileClickPlugin();

    79 

    80 // from base class CClickMaker

    81 

    82     /**

    83      * From CClickMaker.

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

    85      * key event, to generate the sound.

    86      *

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

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

    89      *

    90      * @since S60 v5.0

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

    92      * @param aEvent - The key event details. 

    93      */

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

    95 

    96     /**

    97      * From CClickMaker.

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

    99      * pointer event, to generate the sound.

   100      *

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

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

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

   104      * OtherEvent -function.

   105      *

   106      * @since S60 v5.0

   107      * @param aEvent - The pointer event details.

   108      */

   109     void PointerEvent( const TPointerEvent& aEvent );

   110 

   111     /**

   112      * From CClickMaker.

   113 

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

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

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

   117      * parameter to PointerEvent -function.

   118      *

   119      * @since S60 v5.0

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

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

   122      *                 window identifier where pointer event hit, and window

   123      *                 group identifier of the window group where the window

   124      *                 belongs to.

   125      */

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

   127 

   128     /**

   129      * From CClickMaker.

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

   131      * server client.

   132      *

   133      * Area registry management communication (such as creating or closing

   134      * an application) is communicated through this function.

   135      *

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

   137      * Tactile Feedback Client API implementation.

   138      *

   139      * @since S60 v5.0

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

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

   142      */

   143     TInt CommandReplyL( TInt aOpcode, TAny* aArgs );

   144 

   145 

   146 // from base class MTactileFeedbackServer

   147 

   148     /**

   149      * From MTactileFeedbackServer.

   150      * Direct feedback service for Anim Dll plugins.

   151      *

   152      * @since S60 v5.0

   153      * @param aType - Logical feedback type to play.

   154      */

   155     void InstantFeedback( TTouchLogicalFeedback aType );

   156 

   157 private:

   158 

   159     CTactileClickPlugin();

   160 

   161     void ConstructL();

   162     

   163     /**

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

   165      *

   166      * Actual functionality is implemented in Tactile Area Registry.

   167      *

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

   169      */

   170     void HandleConnectL( TAny* aArgs );

   171 

   172     /**

   173      * Handles data parsing when client disconnects itself. In practice

   174      * this happens when application is closed.

   175      *

   176      * Actual functionality is implemented in Tactile Area Registry.

   177      *

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

   179      */

   180     void HandleDisconnect( TAny* aArgs );

   181 

   182     /**

   183      * Handles direct feedback request from Tactile Client API.

   184      *

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

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

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

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

   189      *

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

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

   192      *         Symbian OS error codes.

   193      */

   194     TInt HandleImmediateFeedback( TAny* aArgs );

   195 

   196 

   197 private: // data

   198 

   199     /**

   200      * Access to tactile feedback server, which actually produces 

   201      * the feedback.

   202      * Own.  

   203      */

   204     RTactileFeedback iFeedback;

   205 

   206     /**

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

   208      * used for hit testing the incoming pointer events against registry 

   209      * content.

   210      * Own.  

   211      */

   212     CTactileAreaRegistry* iAreaRegistry;

   213     

   214     /**

   215      * Flag to indicate whether resolver construction has been attempted

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

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

   218      * construct resolver.  

   219      */

   220     TBool iResolverConstructionAttempted;

   221     };

   222 

   223 

   224 #endif // C_TACTILECLICKPLUGIN_H