1 touchfeedback.h

     1 /*

     2 * Copyright (c) 2007-2008 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:  Interface for using area registry and direct feedback from

    15 *                applications and UI controls.

    16 *

    17 */

    18 

    19 

    20 

    21 #ifndef M_TOUCHFEEDBACK_H

    22 #define M_TOUCHFEEDBACK_H

    23 

    24 #include <e32std.h>

    25 #include <e32base.h>

    26 #include <coemain.h>

    27 

    28 #include <touchlogicalfeedback.h>

    29 

    30 class CCoeControl;

    31 

    32 

    33 /**

    34  *  This is the Tactile Feedback interface for UI Controls.

    35  *

    36  *  Provides an interface to add, modify and remove feedback areas

    37  *  in the registry. There is also an option to trigger direct feedback, 

    38  *  hence bypassing the registry.

    39  *

    40  *  Feedback areas must always be related to some UI Control (derived

    41  *  from CCoeControl). Areas are distinguished from each other based on

    42  *  control's address and an index number (so that it is possible

    43  *  to register and maintain multiple areas for same control).

    44  *

    45  *  Clients must add, maintain and remove their feedback areas using this

    46  *  API according to the state changes of the application / control, and

    47  *  according to for e.g. device wide layout changes.

    48  *

    49  *  There are two cases when tactile framework automatically updates the

    50  *  feedback areas for control: Feedback is always disabled when control

    51  *  becomes dimmed and re-enabled when control becomes undimmed again.

    52  *  If control becomes invisible, then feedback areas are (temporarily)

    53  *  removed, and they will be automatically added again when control

    54  *  becomes visible again.

    55  *

    56  *  This class is not intended for derivation outside the library.

    57  *

    58  *  @lib touchfeedback.lib

    59  *  @since S60 v5.0

    60  */

    61 class MTouchFeedback

    62     {

    63 public:

    64 

    65     /**

    66      * Used for acquiring a pointer to touch feedback instance.

    67      *

    68      * Pointer is retrieved from thread local storage, and thus it is best

    69      * to store the returned pointer as member variable in case it will

    70      * be needed frequently.

    71      *

    72      * NULL is returned in case there is no instance. In that case 

    73      * CreateInstanceL -function can be used for creating a new instance.

    74      *

    75      * @since S60 5.0

    76      * @return Pointer to touch feedback instance created for this

    77      *         application process.

    78      */

    79     IMPORT_C static MTouchFeedback* Instance();

    80 

    81     /**

    82      * Creates a new touch feedback instance. The usage of

    83      * this function should only be necessary from processes which

    84      * are not GUI applications, but which still have user interface

    85      * (or want to play direct feedback).

    86      *

    87      * DestroyInstance -function must be called for deleting the instance

    88      * when it is no longer needed.

    89      *

    90      * @since S60 5.0

    91      * @return Pointer to new touch feedback instance.

    92      */

    93     IMPORT_C static MTouchFeedback* CreateInstanceL();

    94 

    95     /**

    96      * Destroys the touch feedback instance and clears pointer in 

    97      * thread local storage.

    98      *

    99      * This function must only be used in case touch feedback has been

   100      * created with CreateInstanceL -function. I.e. normal GUI applications

   101      * should never call this function.

   102      *

   103      * @since S60 5.0

   104      */

   105     IMPORT_C static void DestroyInstance();

   106 

   107     /**

   108      * This function can be used to check, whether touch feedback is

   109      * supported at all in the device.

   110      *

   111      * All the API functions can be called safely even if touch feedback

   112      * is not enabled (for e.g. in devices without touch screen). But in

   113      * some situations registry updates can require complex calculations, 

   114      * which can be skipped if touch feedback is not enabled at all.

   115      *

   116      * Notice that the settings related to touch feedback have no effect

   117      * on the behavior of this function. I.e. even if user turns touch

   118      * feedback OFF from settings, this function still returns 

   119      * ETrue. The reason for this is that registry updates must be done

   120      * anyway even if the feedback is not on for the moment, because 

   121      * user can turn it on at anytime, and it is not possible to force

   122      * an update for all applications in that case.

   123      *

   124      * @since S60 5.0

   125      * @return ETrue if touch feedback is supported in this device.

   126      */

   127     virtual TBool TouchFeedbackSupported() = 0;

   128 

   129     /**

   130      * Used for disabling or enabling feedback in the application.

   131      *

   132      * Tactile feedback is enabled by default, and thus standard 

   133      * S60 components (such as CBA, lists and options menu) automatically 

   134      * give feedback even if the application itself would make no effort 

   135      * for producing feedback.

   136      * 

   137      * For some applications (such as games) feedback might not be

   138      * wanted at all. In addition some applications may need to disable

   139      * feedback in some specific situations. For example: A camera 

   140      * application may need to disable feedback during video recording,

   141      * because otherwise feedbacks may cause disturbing sounds that 

   142      * will be recorded into the video clip.

   143      *

   144      * Notice that this function only affects direct feedback and 

   145      * area registry based feedback for this application. I.e. if this 

   146      * application is taken to background, other applications can still 

   147      * produce feedback.

   148      *

   149      * Also notice that enabling feedback doesn't still mean that feedback

   150      * would necessarily be generated, because user may have disabled the

   151      * feedback for whole device from the settings.

   152      *

   153      * @since S60 5.0

   154      * @param aEnabled - Give ETrue as parameter for enabling feedback, and

   155      *                   EFalse for disabling feedback.

   156      */

   157     virtual void SetFeedbackEnabledForThisApp( TBool aEnabled ) = 0;

   158 

   159     /**

   160      * Used to check whether feedback is enabled for this application.

   161      *

   162      * Notice that this function only returns what was given as parameter

   163      * to SetFeedbackEnabledForThisApp -function. I.e. this function

   164      * can return ETrue even if  feedback would be currently disabled

   165      * from settings.

   166      *

   167      * If only vibra or audio feedback is enabled, this function still

   168      * returns ETrue.

   169      *

   170      * @since S60 5.0

   171      * @return ETrue if feedback is enabled for this application.

   172      */

   173     virtual TBool FeedbackEnabledForThisApp() = 0;

   174 

   175     /**

   176      * Sets or updates rectangular feedback area to registry.

   177      *

   178      * If this is new area (i.e. there is not yet area with given control

   179      * address and area index in the registry), then this area will be 

   180      * added as the top priority area for its window, i.e. this

   181      * area will be hit test first when pointer event arrives. 

   182      *

   183      * Notice however, that this area will remain as top priority area only

   184      * until the next new area is added to the registry, or until 

   185      * MoveFeedbackAreaToFirstPriority -function is called. I.e. new areas

   186      * are always put on top priority, but they will only remain on top

   187      * until they will be overridden by next area.

   188      *

   189      * The control that is given as parameter should usually be the one

   190      * that is responsible of handling the pointer events on the 

   191      * corresponding feedback area.

   192      *

   193      * The area can later be identified by passing control pointer and

   194      * index as parameters to the other functions (for modifying or 

   195      * removing the feedback area). In case control only

   196      * registers one area, then index 0 can always be used. Usually most

   197      * sensible approach is to use indexes 1, 2, 3 etc. for additional 

   198      * feedback areas, but in practice any desired index values can be

   199      * used.

   200      *

   201      * Notice that if given control is dimmed, then feedback type will

   202      * be set to "None". If given control is not visible, then feedback

   203      * area will not be added to registry at all (for now). However, 

   204      * registry is automatically updated when control's dimming or 

   205      * visibility changes, so one can call this function also for

   206      * dimmed and invisible control.

   207      *

   208      * When the control given as parameter to this function is destroyed,

   209      * then the RemoveFeedbackForControl -function must be called while

   210      * giving the same control as parameter again. This is necessary

   211      * for removing all the feedback areas, and also for resetting the

   212      * state information stored by the API implementation.

   213      *

   214      * @since S60 5.0

   215      * @param aControl      - The control handling pointer events on this

   216                               feedback area.

   217      * @param aIndex        - The index number of the area to be added.

   218      * @param aRect         - The feedback area rectangle.

   219      * @param aFeedbackType - The logical feedback type given

   220      * @param aEventType    - The pointer event type that triggers the 

   221      *                        feedback (currently only ETouchEventStylusDown

   222      *                        is supported).

   223      * @return KErrNone, or one of standard Symbian OS error codes

   224      *         if setting of area to registry failed. 

   225      *         Some specific error codes:

   226      *         KErrArgument - A NULL pointer was given as first parameter, or

   227      *                        the given control does not have any window

   228      *                        associated to it.

   229      *         KErrNotSupported - Unsupported logical feedback type or

   230      *                            event type was given as parameter.

   231      */

   232     virtual TInt SetFeedbackArea( const CCoeControl* aControl, 

   233                                   TUint32 aIndex,

   234                                   TRect aRect, 

   235                                   TTouchLogicalFeedback aFeedbackType, 

   236                                   TTouchEventType aEventType ) = 0;

   237     

   238     /**

   239      * Removes feedback area from the registry.

   240      *

   241      * This function is designed to be used in case feedback areas

   242      * need to be removed elsewhere than in control's destructor. In 

   243      * control's destructor RemoveFeedbackForControl -function must be 

   244      * used instead.

   245      *

   246      * @since S60 5.0

   247      * @param aControl - The control, who has registered the area.

   248      * @param aIndex   - The index of the area to be removed.

   249      */

   250     virtual void RemoveFeedbackArea( const CCoeControl* aControl, 

   251                                      TUint32 aIndex ) = 0;

   252     

   253     /**

   254      * Removes all feedback areas of specified control from registry.

   255      *

   256      * This function also clears all related data that has been cached

   257      * by the API implementation, and thus it must always be called from 

   258      * control's destructor in case control has used any of the following 

   259      * functions:

   260      *   - SetFeedbackArea

   261      *   - EnableFeedbackForControl 

   262      *

   263      * Especially notice that it is not enough to remove all feedback areas 

   264      * individually by using RemoveFeedbackArea -function.

   265      *

   266      * The difference between this function and EnableFeedbackForControl

   267      * -function is that this function really removes all areas related

   268      * to this control from registry, whereas EnableFeedbackForControl

   269      * (when EFalse if given as parameter) only temporarily disables 

   270      * those areas.

   271      *

   272      * @since S60 5.0

   273      * @param aControl - Pointer to the control, whose area registry 

   274      *                   entries and cached information will be removed.

   275      */

   276     virtual void RemoveFeedbackForControl( const CCoeControl* aControl ) = 0;

   277 

   278     /**

   279      * Changes feedback area in the registry.

   280      *

   281      * The area must have been originally added to the registry with 

   282      * SetFeedbackArea -function, or otherwise this function will

   283      * do nothing.

   284      *

   285      * This function is intended to be used especially in 

   286      * portrait / landscape changes.

   287      *

   288      * If given CCoeControl pointer is NULL, then this function call

   289      * does nothing.

   290      *

   291      * @since S60 5.0

   292      * @param aControl - The control, who has registered the area.

   293      * @param aIndex   - The index number of the area, that will be changed.

   294      * @param aNewRect - New area rectangle for given feedback area.

   295      */

   296     virtual void ChangeFeedbackArea( const CCoeControl* aControl, 

   297                                      TUint32 aIndex, 

   298                                      TRect aNewRect ) = 0;

   299 

   300     /**

   301      * Changes feedback type in the registry.

   302      *

   303      * Feedback can be temporarily disabled by giving ETouchFeedbackNone

   304      * as parameter (although using EnableFeedbackForControl function with

   305      * parameter EFalse is usually better for this functionality).

   306      *

   307      * The area must have been originally added to the registry with 

   308      * SetFeedbackArea -function, or otherwise this function will

   309      * do nothing.

   310      *

   311      * If given control pointer is NULL, then this function call

   312      * is ignored.

   313      *

   314      * @since S60 5.0

   315      * @param aControl - The control, who has registered the area.

   316      * @param aIndex   - The index number of the area, that will be changed.

   317      * @param aNewType - New feedback type for the area.

   318      */

   319     virtual void ChangeFeedbackType( const CCoeControl* aControl, 

   320                                      TUint32 aIndex, 

   321                                      TTouchLogicalFeedback aNewType ) = 0;

   322 

   323     

   324     /**

   325      * Makes the given feedback area the first priority area in the window

   326      * where it is located.

   327      *

   328      * In practice this means that this will be the first area that is 

   329      * hit tested when a pointer event arrives.

   330      *

   331      * Notice however, that this area will only keep its top priority status

   332      * until the next area is added to the registry, or until 

   333      * this function is called again for some other area. I.e. there is no 

   334      * way for giving any area a permanent status as top priority area

   335      * (Registry works as a stack, and new items are added on top).

   336      *

   337      * If given control pointer is NULL, this function call does nothing.

   338      *

   339      * @since S60 5.0

   340      * @param aControl - The control, who has registered the area.

   341      * @param aIndex   - The index number of the area, which 

   342      *                   will be prioritized.

   343      */

   344     virtual void MoveFeedbackAreaToFirstPriority( const CCoeControl* aControl, 

   345                                                   TUint32 aIndex ) = 0;

   346 

   347     /**

   348      * This function forces all registry changes made on client side to be

   349      * sent to server side immediately.

   350      *

   351      * This operation causes always immediate and synchronous client-server 

   352      * transaction, and can possibly also cause flushing of window server

   353      * client side buffer. Hence this function should only be used in case 

   354      * there is a synchronization problem so that feedback triggered from 

   355      * area registry does not correspond to the areas defined by application.

   356      *

   357      * This function is only likely to help in such situation, where this

   358      * application's active objects are running all the time for several seconds,

   359      * because in that case updates won't be transferred to server immediately.

   360      *

   361      * Calling this function has no effect in case there are no pending 

   362      * area registry updates.

   363      *

   364      * @since S60 5.0

   365      */

   366     virtual void FlushRegistryUpdates( ) = 0;

   367     

   368     /**

   369      * Gives direct feedback.

   370      *

   371      * Notice that the feedback might not be actually played, if 

   372      * for example user has disabled the feedback from the settings.

   373      *

   374      * This function always causes a synchronous client-server transaction, 

   375      * and potentially flushing of window server client-side buffer.

   376      *

   377      * @since S60 5.0

   378      * @param aType - The logical feedback type to play.

   379      */

   380     virtual void InstantFeedback( TTouchLogicalFeedback aType ) = 0;

   381 

   382     /**

   383      * Gives direct feedback if given control has not disabled it.

   384      *

   385      * This function only gives feedback, if EnableFeedbackForControl

   386      * function has NOT been called on given control with second

   387      * parameter EFalse.

   388      * 

   389      * This overload is recommended when

   390      * feedback is triggered from UI controls, because then the owner

   391      * of the control can decide whether both area registry based and

   392      * direct feedback should be enabled or not.

   393      *

   394      * If feedback is enabled for the given control, then this function 

   395      * causes a synchronous client-server transaction, 

   396      * and potentially flushing of window server client-side buffer.

   397      *

   398      * @since S60 5.0

   399      * @param aControl - The control, who fishes to play feedback.

   400      * @param aType    - The logical feedback type to play.

   401      */

   402     virtual void InstantFeedback( const CCoeControl* aControl,

   403                                   TTouchLogicalFeedback aType ) = 0;

   404                                   

   405     

   406     /**

   407      * Can be used for querying, whether given control has any feedback

   408      * areas registered.

   409      *

   410      * It does not matter whether the areas are disabled or enabled for

   411      * the moment.

   412      *

   413      * Notice that one should not usually call this function, as it

   414      * is always allowed to call for example RemoveFeedbackArea

   415      * -function without checking if the area really exists (this

   416      * is done internally in the API implementation anyway).

   417      *

   418      * @since S60 5.0

   419      * @param aControl - Pointer to the control, whose feedback is

   420      *                   queried.

   421      * @return ETrue if the given control has at least one feedback

   422      *         area defined. EFalse otherwise.

   423      */

   424     virtual TBool ControlHasFeedback( const CCoeControl* aControl ) = 0;

   425     

   426     /**

   427      * Can be used for querying, whether given control has a feedback

   428      * area defined with given index number.

   429      *

   430      * It does not matter whether the areas are disabled or enabled for

   431      * the moment.

   432      *

   433      * Notice that one should not usually call this function, as it

   434      * is always allowed to call for example RemoveFeedbackArea

   435      * -function without checking if the area really exists (this

   436      * is done internally in the API implementation anyway).

   437      *

   438      * @since S60 5.0

   439      * @param aControl - Pointer to the control, whose feedback is

   440      *                   queried.

   441      * @param aIndex   - The index number of the area which is queried.

   442      * @return ETrue if the given control has a feedback area defined

   443      *         with given index number. EFalse otherwise.

   444      */

   445     virtual TBool ControlHasFeedback( const CCoeControl* aControl, 

   446                                       TUint32 aIndex ) = 0;

   447             

   448     /**

   449      * This function enables or disables all feedback areas registered for 

   450      * the given control. Disabling also affects to the overloaded version

   451      * of InstantFeedback -function, so that feedback is not played if

   452      * the control given as parameter has its feedback disabled.

   453      *

   454      * This function can be used for temporarily disabling

   455      * the feedback for some given control. Calling with second parameter 

   456      * ETrue re-enables feedback areas, but it still does not

   457      * guarantee any feedback (control can be dimmed, invisible, of may not

   458      * even have any feedback areas registered).

   459      *

   460      * This function affects both vibra- and audio feedback.

   461      *

   462      * Any control that uses this function must call RemoveFeedbackForControl

   463      * -function in its destructor.

   464      *

   465      * @since S60 5.0

   466      * @param aControl - Pointer to control, whose feedback will be 

   467      *                   enabled or disabled according to second parameter.

   468      * @param aEnable  - Use EFalse for temporary disabling the feedback for

   469      *                   this control, and ETrue for restoring the situation

   470      *                   to normal.

   471      */

   472     virtual void EnableFeedbackForControl( const CCoeControl* aControl,

   473                                            TBool aEnable ) = 0;       

   474                                            

   475     /**

   476      * This function can be used for separately enabling or disabling audio-

   477      * and vibra feedback for the given control.

   478      *

   479      * Otherwise the function behaves in the same way as the overload with

   480      * only one TBool parameter.

   481      *

   482      * Any control that uses this function must call RemoveFeedbackForControl

   483      * -function in its destructor.

   484      *

   485      * @since S60 5.0

   486      * @param aControl - Pointer to control, whose audio- and vibra 

   487      *                   feedback will be enabled or disabled according 

   488      *                   to given parameters.

   489      * @param aEnableVibra  - Use EFalse for temporary disabling the vibra 

   490      *                        feedback for this control, and ETrue for 

   491      *                        restoring the situation to normal.

   492      * @param aEnableAudio  - Use EFalse for temporary disabling the audio 

   493      *                        feedback for this control, and ETrue for 

   494      *                        restoring the situation to normal.

   495      */

   496     virtual void EnableFeedbackForControl( const CCoeControl* aControl,

   497                                            TBool aEnableVibra,

   498                                            TBool aEnableAudio ) = 0; 

   499                                            

   500     /**

   501      * Used for disabling or enabling feedback in the application.

   502      *

   503      * This is identical with the overload which has only one parameter, 

   504      * with the exception that one can disable audio and vibra feedback 

   505      * separately with this version.

   506      *

   507      * @since S60 5.0

   508      * @param aVibraEnabled - Give ETrue as parameter for enabling vibra 

   509      *                        feedback, and EFalse for disabling vibra 

   510      *                        feedback for this application.

   511      * @param aAudioEnabled - Give ETrue as parameter for enabling audio 

   512      *                        feedback, and EFalse for disabling audio

   513      *                        feedback for this application.

   514      */

   515     virtual void SetFeedbackEnabledForThisApp( TBool aVibraEnabled,

   516                                                TBool aAudioEnabled ) = 0;                                                 

   517     };

   518 

   519 

   520 

   521 #endif //  M_TOUCHFEEDBACK_H