1 /*

     2 * Copyright (c) 2007 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 class to be used from server side for accessing registry.

    15 *                Hit testing is done using this API.

    16 * Part of:      Tactile Feedback.

    17 *

    18 */

    19 

    20 

    21 

    22 

    23 #ifndef C_TACTILEAREAREGISTRY_H

    24 #define C_TACTILEAREAREGISTRY_H

    25 

    26 

    27 #include <e32base.h>

    28 #include <w32std.h>

    29 

    30 #include <touchlogicalfeedback.h>

    31 #include "tactileinternaldatatypes.h"

    32 

    33 

    34 /**

    35  *  Access to area registry from server side.

    36  *

    37  *  This class defines the interface that is used from server side for

    38  *  managing area registry (e.g. handling connect and disconnect requests)

    39  *  

    40  *  The main purpose of this class is to do hit testing of pointer events,

    41  *  for knowing if feedback should be triggered based on the pointer event.

    42  *

    43  *  This class also implements bookkeeping of created window groups and

    44  *  corresponding window server connection handles. This information is

    45  *  used for finding correct application's registry entries when a pointer

    46  *  event arrives (application usually has only one window group, but some

    47  *  pop-up controls create additional ones).

    48  *

    49  *  @lib tactilearearegistry.lib

    50  *  @since S60 v5.0

    51   */

    52 class CTactileAreaRegistry: public CBase

    53     {

    54 public:

    55 

    56     IMPORT_C static CTactileAreaRegistry* NewL();

    57 

    58     virtual ~CTactileAreaRegistry();

    59 

    60     /**

    61      * Handles connection requests from client application. This has to be 

    62      * called for every application that connects to the click plugin.

    63      *

    64      * Area registry immediately tries to connect to the chunk created

    65      * by client application. This function leaves with Standard 

    66      * Symbian OS error codes in case connection fails.

    67      *

    68      * @param aData - The data sent by client application.

    69      */

    70     IMPORT_C void HandleConnectL( const TTactileFeedbackConnectData& aData );

    71 

    72 

    73     /**

    74      * Handles disconnect request from client application. This has to be 

    75      * called for every application that disconnects from the click plugin.

    76      *

    77      * @param aData - The data sent by client application.

    78      */

    79     IMPORT_C void HandleDisconnect( 

    80         const TTactileFeedbackDisconnectData& aData );

    81         

    82         

    83     /**

    84      * Records information about a newly created window group.

    85      *

    86      * This function has to be called when click plugin receives a 

    87      * notification about created window group.

    88      *

    89      * @param aIdentifier       - Identifier of the created window group.

    90      * @param aConnectionHandle - Connection handle of the window server

    91      *                            client, who created the window group.

    92      */

    93     IMPORT_C void HandleWindowGroupCreated( 

    94         TInt aIdentifier, TUint aConnectionHandle );

    95         

    96         

    97     /**

    98      * Clears stored information about a window group that is closed.

    99      *

   100      * This function has to be called when click plugin receives a

   101      * notification about closed window group. 

   102      *

   103      * @param aIdentifier - Window group identifier of the window group

   104      *                      that was closed.

   105      */

   106     IMPORT_C void HandleWindowGroupClosed( TInt aIdentifier );    

   107 

   108     /**

   109      * Does hit testing of given pointer event against area registry content.

   110      *

   111      * Hit testing is done in three phases:

   112      *

   113      * 1. First this function uses window group identifier for finding the 

   114      *    application, which shall receive the pointer event (registry

   115      *    contents has to be grouped by applicaitons because window 

   116      *    identifiers are only unique inside one application)

   117      *

   118      * 2. Window handle is used for finding those registry entries, which 

   119      *    are registered to the same window where pointer event hit now 

   120      *    (coordinates are window -relative).

   121      *

   122      * 3. Window's registry entries are hit tested one by one against the

   123      *    given pointer event, and in case a match is found, then 

   124      *    corresponding registry entries feedback type is returned.

   125      *

   126      * @param aPointerEvent - The pointer event.

   127      * @param aWgIdentifier - Identifier of the window group, where pointer

   128      *                        event hit.

   129      * @param aWindowHandle - Handle number of the window, where pointer

   130      *                        event hit.

   131      * @return The logical feedback type that was triggered by the pointer

   132      *         event, or ETouchFeedbackNone in case pointer event did not

   133      *         hit any feedback area.

   134      */

   135     IMPORT_C TTouchLogicalFeedback HitTestPointerEvent( 

   136         const TPointerEvent& aPointerEvent,

   137         TInt aWgIdentifier,

   138         TUint32 aWindowHandle );

   139 

   140 

   141 private:

   142 

   143     CTactileAreaRegistry();

   144     

   145     /**

   146      * This function is used for hit testing one chunk.

   147      *

   148      * It is assumed that the given chunk is the chunk of that application,

   149      * where pointer event shall be delivered.

   150      *

   151      * @param aPointerEvent - The pointer event.

   152      * @param aWgIdentifier - Identifier of the window group, where pointer

   153      *                        event hit.

   154      * @param aWindowHandle - Handle number of the window, where pointer

   155      *                        event hit.

   156      * @return The logical feedback type that was triggered by the pointer

   157      *         event, or ETouchFeedbackNone in case pointer event did not

   158      *         hit any feedback area.

   159      */

   160     TTouchLogicalFeedback HitTestChunk( 

   161         RChunk&              aChunk, 

   162         const TPointerEvent& aPointerEvent,

   163         TInt                 aWgIdentifier, 

   164         TUint32              aWindowHandle );

   165 

   166     /**

   167      * This function checks whether given pointer event and area registry 

   168      * entry match, and sets feedback type accordingly in case they match.

   169      *

   170      * It is assumed that pointer event shall hit that window, where given

   171      * area is registered (as coordinates are window-relative).

   172      *

   173      * Notice that feedback is actually returned in reference parameter

   174      * aFeedback, and the main return value of the function tells whether

   175      * hit testing should be continued on next possible area or not.

   176      * This is because feedback can be "None" even if pointer event

   177      * hit the feedback area (because "None" is a valid type for feedback

   178      * areas)

   179      *

   180      * @param aPointerEvent - The pointer event.

   181      * @param aEntry        - Area registry entry, representing feedback area

   182      *                        in same window where pointer event hit.

   183      * @param aWgIdentifier - Identifier of the window group, where pointer

   184      *                        event hit.

   185      * @param aWindowHandle - Handle number of the window, where pointer

   186      *                        event hit.

   187      * @return ETrue if the given pointer event matched given area registry

   188      *         entry, and hit testing should not be continued anymore. 

   189      *         EFalse indicates that hit testing should be continued with

   190      *         next possibly matching feedback area.

   191      */

   192     TBool HitTestRegistryEntry( 

   193         const TPointerEvent&           aPointerEvent, 

   194         const TFeedbackChunkAreaEntry& aEntry,

   195         TInt                           aWgIdentifier, 

   196         TUint32                        aWindowHandle,

   197         TTouchLogicalFeedback&         aFeedback );

   198 

   199     /**

   200      * Finds the correct shared memory chunk based on window group id.

   201      *

   202      * This is used for performing first phase of hit testing.

   203      *

   204      * @param aWgIdentifier - Identifier of the window group, which chunk

   205      *                        is searched.

   206      * @return Valid index to member variable iChunkArray, or KErrNotFound

   207      *         in case given window group was not found.

   208      */

   209     TInt ChunkIndexByWindowGroupId( TInt aWgIdentifier ) const;

   210     

   211     /**

   212      * Finds window server client's connection handle based on given

   213      * window group identifier.

   214      *

   215      * This is used for finding correct shared memory chunk based on window

   216      * group identifier.

   217      *

   218      * @param aWgIdentifier - The window group identifier.

   219      * @return Connection handle of the client, who has created the given

   220      *         window group. Zero is returned if no client is found.

   221      */

   222     TUint ConnectionHandleByWgId( TInt aWgIdentifier ) const;

   223     

   224 

   225 private: // data types

   226 

   227     /**

   228      * Items of this type are stored into member variable iChunkArray.

   229      * There is one item in the array for each connecting application.

   230      *

   231      * Stored window group id is the identifier of the main window group

   232      * of connecting application. Stored connection handle is the

   233      * window server connection handle of the application.

   234      */

   235     struct TTactileAreaChunk

   236         {

   237         TInt    iWindowGroupId;

   238         TUint   iConnectionHandle;

   239         RChunk  iChunk;

   240         };

   241         

   242     /**

   243      * This type of items are used in member variable iWgArray, which

   244      * is used for mapping window groups and client applications together.

   245      */

   246     struct TTactileWgroupItem

   247         {

   248         TInt iWindowGroupId;

   249         TUint iConnectionHandle;

   250         };    

   251         

   252     

   253     /**

   254      * This auxiliary class is used for storing information about pen down

   255      * event, so that we can know if pen up event happened in same feedback

   256      * area as corresponding pen down event. This information is necessary

   257      * in case we want to play feedback both on down- and up events, but only

   258      * when those happen within same feedback area 

   259      * (to distinguish cancel -case)

   260      */

   261     class TTactilePenDownEvent

   262         {

   263     public:

   264         TTactilePenDownEvent();

   265         TTactilePenDownEvent( TInt aWindowGroupId, 

   266                               TUint32 aWindowHandle, 

   267                               TRect aFeedbackArea );

   268         void Reset();    

   269     public:

   270         TInt iWindowGroupId;

   271         TUint32 iWindowHandle;

   272         TRect iFeedbackArea;

   273         };

   274 

   275 

   276 private: // data

   277 

   278     /**

   279      * Array of chunk handles and identifying window group identifiers.

   280      * Each entry in the array represents one application and its 

   281      * registered feedback areas.

   282      */

   283     RArray<TTactileAreaChunk> iChunkArray;

   284     

   285     /** 

   286      * Here we store the information about created window groups.

   287      * For each group we also store the connection handle, so that we can

   288      * know into which application newly created window groups belong.  

   289      */

   290     RArray<TTactileWgroupItem> iWgArray;

   291 

   292     /**

   293      * Handle to the global semaphore, which is used for mutual exclusion

   294      * when accessing shared memory chunks.

   295      */

   296     RSemaphore iTactileSemaphore;

   297     

   298     

   299     /**

   300      * Information about last received pen down event. This can be used

   301      * for determining whether pen up event should produde feedback or not.

   302      */

   303     TTactilePenDownEvent iLastPenDown;

   304 

   305     };

   306 

   307 

   308 #endif // C_TACTILEAREAREGISTRY_H