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:  This class implements Tactile Feedback Client API

    15 * Part of:      Tactile Feedback.

    16 *

    17 */

    18 

    19 

    20 

    21 #ifndef C_TOUCHFEEDBACKIMPL_H

    22 #define C_TOUCHFEEDBACKIMPL_H

    23 

    24 #include <e32std.h>

    25 #include <e32base.h>

    26 #include <coemain.h>

    27 

    28 #include "touchlogicalfeedback.h"

    29 #include "touchfeedback.h"

    30 

    31 

    32 class CTouchFeedbackRegistry;

    33 class CTouchFeedbackClient;

    34 

    35 

    36 /**

    37  * This structure stores one index / area id pair.

    38  * This kind of entries are stored for each control, which have

    39  * feedback areas defined.

    40  */

    41 struct TAreaIndexEntry

    42     {

    43     TUint32 iIndex;

    44     TInt iAreaId;

    45     };

    46 

    47 /**

    48  * This structure stores one control's information on client-side.

    49  * This information includes control's visibility, dimming and feedback

    50  * disabled information, as well as array of the feedback area

    51  * identifiers.

    52  *

    53  * Notice that the client handle is stored for two reasons: Firstly

    54  * it is an optimization to store it as this way we can avoid unnecessary

    55  * client-server transaction (window server client-side API does not 

    56  * cache the handle). Secondly some times control's window may have been

    57  * deleted before control removes it's feedback areas. In these situations

    58  * we even wouldn't be able to use the control for getting the handle 

    59  * anymore.

    60  */

    61 struct TControlCacheEntry

    62     {

    63     const CCoeControl* iControl;

    64     TUint32 iClientHandle;

    65     TBool iVibraDisabled;

    66     TBool iAudioDisabled;

    67     TBool iVisible;

    68     TBool iDimmed;

    69     RArray<TAreaIndexEntry> iAreaArray;

    70     };

    71 

    72 /**

    73  *  This class implements the Client API that is provided for UI Controls

    74  *  and applications.

    75  *

    76  *  The implemented interface is defined by MTouchFeedback -class.

    77  *

    78  *  This class' main task is to have a bookkeeping of all the controls

    79  *  that have feedback areas defined. Services such as automatic disabling

    80  *  of the feedback areas of dimmed or invisible controls are implemented

    81  *  here.

    82  *

    83  *  @lib touchfeedback.lib

    84  *  @since S60 v5.0

    85  */

    86 NONSHARABLE_CLASS( CTouchFeedbackImpl ): 

    87     public CBase,

    88     public MTouchFeedback

    89     {

    90 public:

    91     /**

    92      * Instantiation method.

    93      *

    94      * @since S60 5.0

    95      * @return New CTouchFeedbackImpl instance.

    96      */

    97     static CTouchFeedbackImpl* New();

    98 

    99     /**

   100      * Destructor.

   101      * @since S60 5.0

   102      */

   103     virtual ~CTouchFeedbackImpl();

   104 

   105     /**

   106      * @see MTouchFeedback.

   107      */

   108     TBool TouchFeedbackSupported();

   109 

   110     /**

   111      * @see MTouchFeedback.

   112      */

   113     void SetFeedbackEnabledForThisApp( TBool aEnabled );

   114     

   115     /**

   116      * @see MTouchFeedback.

   117      */

   118     TBool FeedbackEnabledForThisApp(); 

   119 

   120     /**

   121      * @see MTouchFeedback.

   122      */

   123     TInt SetFeedbackArea( const CCoeControl* aControl, 

   124                           TUint32 aIndex,

   125                           TRect aRect, 

   126                           TTouchLogicalFeedback aFeedbackType, 

   127                           TTouchEventType aEventType );

   128 

   129     

   130     

   131     /**

   132      * @see MTouchFeedback.

   133      */

   134     void RemoveFeedbackArea( const CCoeControl* aControl, TUint32 aIndex );

   135     

   136     /**

   137      * @see MTouchFeedback.

   138      */

   139     void RemoveFeedbackForControl( const CCoeControl* aControl );

   140     

   141     /**

   142      * @see MTouchFeedback.

   143      */

   144     void ChangeFeedbackArea( const CCoeControl* aControl, 

   145                              TUint32 aIndex, 

   146                              TRect aNewRect );

   147      

   148     /**

   149      * @see MTouchFeedback.

   150      */

   151     void ChangeFeedbackType( const CCoeControl* aControl, 

   152                              TUint32 aIndex, 

   153                              TTouchLogicalFeedback aNewType );

   154 

   155     /**

   156      * @see MTouchFeedback.

   157      */

   158     void MoveFeedbackAreaToFirstPriority( const CCoeControl* aControl, 

   159                                           TUint32 aIndex );

   160          

   161     /**

   162      * @see MTouchFeedback.

   163      */

   164     void FlushRegistryUpdates( );

   165     

   166     /**

   167      * @see MTouchFeedback.

   168      */

   169     void InstantFeedback( TTouchLogicalFeedback aType );

   170         

   171     /**

   172      * @see MTouchFeedback.

   173      */

   174     void InstantFeedback( const CCoeControl* aControl,

   175                           TTouchLogicalFeedback aType ); 

   176 

   177     /**

   178      * @see MTouchFeedback.

   179      */

   180     TBool ControlHasFeedback( const CCoeControl* aControl );

   181     

   182     /**

   183      * @see MTouchFeedback.

   184      */

   185     TBool ControlHasFeedback( const CCoeControl* aControl, TUint32 aIndex );

   186     

   187     /**

   188      * @see MTouchFeedback.

   189      */

   190     void EnableFeedbackForControl( 

   191         const CCoeControl* aControl, TBool aEnable );       

   192 

   193     /**

   194      * @see MTouchFeedback.

   195      */

   196     void EnableFeedbackForControl( const CCoeControl* aControl,

   197                                    TBool aEnableVibra,

   198                                    TBool aEnableAudio );       

   199 

   200     /**

   201      * @see MTouchFeedback.

   202      */

   203     virtual void SetFeedbackEnabledForThisApp( TBool aVibraEnabled,

   204                                                TBool aAudioEnabled );

   205        

   206 public:    

   207     /**

   208      * This function provides a way for getting the registry content.

   209      *

   210      * Used by CTouchFeedbackClient for listing all the registry

   211      * areas, so that they can be put to shared memory.

   212      *

   213      * @since S60 5.0

   214      */

   215     RPointerArray<CTouchFeedbackRegistry>* RegistryArray();

   216     

   217     /**

   218      * This function can be used for getting the number of areas in the

   219      * registry.

   220      *

   221      * @since S60 5.0

   222      * @param aAreaCount - The total number of areas in the registry.

   223      * @param aWindowCount - Number of different windows is returned here.

   224      */

   225     void GetAreaCount( TInt& aAreaCount, TInt& aWindowCount );

   226     

   227     /**

   228      * This should be called  for informing

   229      * that given control's state (i.e. visiblity or dimming status)

   230      * has been changed. This way Tactile FW knows to disable or enable

   231      * the feedback for that control again.

   232      *

   233      * @since S60 5.0

   234      * @param aControl - Pointer to the control, which visiblity 

   235      *                   or dimming status has changed.

   236      */

   237     void ControlVisibilityChanged( const CCoeControl* aControl );

   238   

   239     /**

   240      * This should be called when the layout is changed.

   241      *

   242      * @since S60 5.0     

   243      * The motivation is to disable this application's feedback areas

   244      * for this application in case pen usage is not supported in current 

   245      * layout.

   246      */

   247     void LayoutChanged();

   248 

   249 public: // new API functions since 5.2, defined in MTouchFeedback

   250     /**

   251      * @see MTouchFeedback.

   252      */

   253     TBool FeedbackEnabledForThisApp( TTouchFeedbackType aFeedbackType );

   254     

   255     /**

   256      * @see MTouchFeedback.

   257      */

   258     void StartFeedback( const CCoeControl* aControl,

   259                         TTouchContinuousFeedback aType,

   260                         const TPointerEvent* aPointerEvent,

   261                         TInt aIntensity,

   262                         TTimeIntervalMicroSeconds32 aTimeout );

   263 

   264     /**

   265      * @see MTouchFeedback.

   266      */

   267     void ModifyFeedback( const CCoeControl* aControl,

   268                          TInt aIntensity );

   269 

   270     /**

   271      * @see MTouchFeedback.

   272      */

   273     void StopFeedback( const CCoeControl* aControl );

   274 

   275     /**

   276      * @see MTouchFeedback.

   277      */

   278     TInt SetFeedbackEnabledForDevice( TTouchFeedbackType aFeedbackType );

   279 

   280     /**

   281      * @see MTouchFeedback.

   282      */

   283     TTouchFeedbackType FeedbackEnabledForDevice();

   284 

   285     /**

   286      * @see MTouchFeedback.

   287      */

   288     void InstantFeedback( const CCoeControl* aControl,

   289                           TTouchLogicalFeedback aType,

   290                           const TPointerEvent& aPointerEvent );

   291 

   292     /**

   293      * @see MTouchFeedback.

   294      */

   295     TInt SetFeedbackArea( const CCoeControl* aControl, 

   296                           TUint32 aIndex,

   297                           TRect aRect, 

   298                           CFeedbackSpec* aFeedbackSpec );

   299 

   300     /**

   301      * @see MTouchFeedback.

   302      */                          

   303     void InstantFeedback( const CCoeControl* aControl,

   304                           TTouchLogicalFeedback aType,

   305                           TTouchFeedbackType aFeedbackType,

   306                           const TPointerEvent& aPointerEvent );

   307       

   308 private:

   309     /**

   310      * Constructor.

   311      */

   312     CTouchFeedbackImpl();

   313 

   314     /**

   315      * 2nd phase constructor.

   316      */

   317     void ConstructL();

   318     

   319     /**

   320      * Actual functionality of setting a feedback area.

   321      *

   322      * The API function SetFeedbackArea does the basic parameter checks and

   323      * runs this function under trap harness so that we can leave here.

   324      *

   325      * @see MTouchFeedback.

   326      */

   327     void DoSetFeedbackAreaL( const CCoeControl* aControl, 

   328                              TUint32 aIndex,

   329                              TRect aRect, 

   330                              CFeedbackSpec* aSpec, 

   331                              TUint32 aClientHandle );

   332     

   333     

   334     /**

   335      * Finds window from the registry if it exists.

   336      *

   337      * Returns an index to iResolverArray, or KErrNotFound if

   338      * there is no entry for the window yet.

   339      *

   340      * @since S60 5.0

   341      * @param aWindowHandle - The window id to find from the array

   342      * @return KErrNotFound if an area with given ID is not found from the registry.

   343      */

   344     TInt FindWindowFromRegistry( TUint aWindowHandle );

   345     

   346     /**

   347      * Generates a unique identifier inside this application process.

   348      *

   349      * This is the id that is used to distinguish the area registry

   350      * entries from each other.

   351      *

   352      * @since S60 5.0

   353      * @return Unique identifier.

   354      */

   355     TUint GenerateUniqueIdL();

   356     

   357     /**

   358      * Can be used to check whether feedback area with given id exists or not.

   359      *

   360      * This is as helper function when generating unique identifiers for

   361      * new feedback areas.

   362      *

   363      * @since S60 5.0

   364      * @return ETrue if feedback area with given identifier exists already.

   365      *         EFalse otherwise.

   366      */

   367     TBool FeedbackAreaExists( TUint aAreaId );

   368     

   369     /**

   370      * Returns the client handle of the window, where given control

   371      * is located. Client handle is either directly casted from first

   372      * window-owning control's address, or then asked from window 

   373      * server.

   374      *

   375      * @since S60 5.0

   376      * @param aControl - Pointer to the control.

   377      * @return Client handle of the window where given control is.

   378      */

   379     TUint32 ClientHandle( const CCoeControl* aControl );

   380         

   381     /**

   382      * Finds given control from the cache.

   383      *

   384      * @since S60 5.0

   385      * @param aControl - Pointer to the control, which is searched

   386      * @return The position in cache array, where searhed entry is found,

   387      *         or KErrNotFound if it is not found.

   388      */

   389     TInt FindControlFromCache( const CCoeControl* aControl );

   390     

   391         

   392     /**

   393      * Finds specific feedback area from control cache.

   394      *

   395      * @since S60 5.0

   396      * @param aControl - Pointer to the control.

   397      * @param aIndex   - Area index (given by client)

   398      * @param aCacheIndex  - If control is found, then index to control cache is

   399      *                       returned here.

   400      * @param aAreaIndex   - If area is found, then index to area array in

   401      *                       corresponding control cache entry is returned

   402      *                       here.

   403      */

   404     void FindAreaFromCache( const CCoeControl* aControl, 

   405                             TUint32 aIndex, 

   406                             TInt& aCacheIndex, 

   407                             TInt& aAreaIndex );    

   408           

   409                             

   410     /**

   411      * Removes control with given index number from the control cache.

   412      *

   413      * @since S60 5.0

   414      * @param aControlIndex - Index number of the control in the control

   415      *                        array.

   416      */

   417     void RemoveControlFromCache( TInt aControlIndex );       

   418     

   419     /**

   420      * Can be used for querying, whether control's areas should be active

   421      * according to it's recorced dimming-, visibility-, and feedback

   422      * disabling status.

   423      *

   424      * @since S60 5.0

   425      * @param aControlIndex - Index number of the control in the control

   426      *                        array.

   427      * @return ETrue if control's areas should be active, EFalse otherwise.

   428      */

   429     TBool ControlsAreasActive( TInt aControlIndex );  

   430     

   431     /**

   432      * Can be used for disabling or enabling control's feedback areas

   433      * in the registry.

   434      *

   435      * This function only modifies the registry, and not the control cache.

   436      *

   437      * @since S60 5.0

   438      * @param aControlIndex - Index number of the control in the control

   439      *                        array.

   440      * @param aEnableVibra   - New disable / enable status for vibra

   441      * @param aEnableAudio   - New disable / enable status for audio

   442      * @param aVisible       - Visibility status of the control. If

   443      *                         control is invisible, it's feedback areas

   444      *                         will be temporarily removed from the 

   445      *                         registry.

   446      */

   447     void DoEnableControlsAreasInRegistry( 

   448         TInt aControlIndex,

   449         TBool aEnableVibra, 

   450         TBool aEnableAudio,

   451         TBool aVisible );               

   452     

   453 private: // data

   454 

   455     /**

   456      * Array of area registries. There is one entry for each window.

   457      * Own.

   458      */

   459     RPointerArray<CTouchFeedbackRegistry> iRegistryArray;

   460 

   461     /**

   462      * The id what was given to the area that was last added to the array.

   463      */

   464     TUint iCurrentId;

   465     

   466     /**

   467      * We maintain a bookkeeping to know in case the currently used 

   468      * feedback area id has already reached its maximum value at 

   469      * least once. This way we save some time for e.g. during boot-up

   470      * when plenty of areas are added to the registry.

   471      */

   472     TBool iCurrentIdCounterRotated;

   473     

   474     /**

   475      * Pointer to client, used to inform it about registry changes.

   476      * Own.

   477      */

   478     CTouchFeedbackClient* iClient;

   479     

   480     /**

   481      * Array of controls and their feedback area ids. This way users of the

   482      * API don't have to store the ids themselves.

   483      */    

   484     RArray<TControlCacheEntry> iControlCache;

   485 

   486     /**

   487      * Used to store the status of audio feedback for this application.

   488      */

   489     TBool iAudioEnabledForThisApp;

   490     

   491     /**

   492      * Used to store the status of vibra feedback for this application.

   493      */

   494     TBool iVibraEnabledForThisApp;

   495     

   496     /**

   497      * For bookkeeping about feedback areas. We need this information for

   498      * recognizing the situation when we cannot add another area to the

   499      * registry anymore (for e.g. due to Id generation problem).

   500      */    

   501     TInt iNbOfFeedbackAreas;

   502     

   503     /**

   504      * For bookkeeping wheater pen is enabled in current layout or not. This

   505      * way we can optimize layout change handling so that we only react

   506      * to changes from non-pen enabled to pen enabled layout and vice versa,

   507      * but do nothing when layout changes without effect to pen support.

   508      */    

   509     TBool iPenEnabled;

   510     };

   511 

   512 

   513 

   514 #endif //  C_TOUCHFEEDBACKIMPL_H