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:  Transition utilities.

    15 *

    16 */

    17 

    18 

    19 #ifndef __AKN_TRANSITION_UTILS_H__

    20 #define __AKN_TRANSITION_UTILS_H__

    21 

    22 #include <coemain.h>

    23 #include <gfxtranseffect/gfxtranseffect.h>

    24 

    25 class CRepository;

    26 

    27 // Constants for component appear/disappear actions

    28 const TInt KGfxControlAppearAction = 3;

    29 const TInt KGfxControlDisappearAction = 4;

    30 

    31 // Constants for the types of component effects

    32 #define KGfxOptionsMenuControlUid TUid::Uid(0x10281F88)

    33 #define KGfxOptionsMenuCascadeControlUid TUid::Uid(0x10281F89)

    34 #define KGfxTouchToolbarControlUid TUid::Uid(0x10282E49)

    35 #define KGfxToolbarControlUid TUid::Uid(0x10282E4A)

    36 #define KGfxContextMenuControlUid TUid::Uid(0x10282E4C)

    37 #define KGfxTaskSwapperControlUid TUid::Uid(0x10281F90)

    38 #define KGfxNumberEntryPopupUid TUid::Uid( 0x10282E4D )

    39 #define KGfxMediaBarControlUid TUid::Uid( 0x20007B17 )

    40 

    41 #define KGfxErrorNoteControlUid TUid::Uid( 0x10282E50 )

    42 #define KGfxWarningNoteControlUid TUid::Uid( 0x10282E51 )

    43 #define KGfxInformationNoteControlUid TUid::Uid( 0x10282E52 )

    44 #define KGfxConfirmationNoteControlUid TUid::Uid( 0x10282E53 )

    45 #define KGfxWaitNoteControlUid TUid::Uid( 0x10282E54 )

    46 #define KGfxQueryControlUid TUid::Uid( 0x10282E56 )

    47 #define KGfxPopupDefaultControlUid TUid::Uid( 0x10282E57 )

    48 #define KGfxSystemNotificationControlUid TUid::Uid( 0x2000B472 )

    49 #define KGfxSystemNotifBatteryControlUid TUid::Uid( 0x2000B473 )

    50 #define KGfxDiscreetPopupControlUid TUid::Uid( 0x2000B478 )

    51 #define KGfxPreviewPopupControlUid TUid::Uid( 0x2000B479 )

    52 

    53 #define KGfxSequenceFirstControlUid TUid::Uid( 0x2000B474 )

    54 #define KGfxSequenceMiddleControlUid TUid::Uid( 0x2000B475 )

    55 #define KGfxSequenceLastControlUid TUid::Uid( 0x2000B476 )

    56 

    57 // Enumerations for notifying tfx server (used via 

    58 // GfxTransEffect::NotifyExternalState)

    59 enum TGfxTransNotification 

    60     {

    61     ENotifyGlobalAbort,

    62     ENotifySetExtent

    63     ,ECaptureComponentsBegin

    64     ,ECaptureComponentsEnd

    65     ,EBeginPopupSequence

    66     ,ELastPopupInSequence

    67     ,EEndPopupSequence

    68     ,EInternalHandleSequence

    69     // Get the type of the current transition.  Must be called during

    70     // a transition, ie. between Begin() and End().

    71     ,EGetRegistrationType

    72     ,ECaptureComponentsAbort

    73     ,EAddIgnoreWOChildComponent

    74     ,ERemoveIgnoreWOChildComponent

    75     };

    76 

    77 // Enumeration for data that should be accessible globally. (cross-class)

    78 // For local data, use this pointer or key > EUserDefinedKey

    79 enum TAknTransitionUtilsDataKey

    80 	{

    81 	EDontAnimateBitmaps,

    82 	EUserDefinedKey = 0xFFFF,

    83 	};

    84 

    85 // Constants for unique ID's to store values with SetData().

    86 // These must not collide with pointers to controls, which are used as keys

    87 // in some places, so starting from 1 is safe.

    88 const TInt KScreensaverCallStateChange = 1;

    89 

    90 const TUid KAknTransitionUtilsUid = { 0x10282E4B };

    91 

    92 class CAknPsObserver;

    93 

    94 NONSHARABLE_CLASS( MAknPsObserver )

    95     {

    96 public:

    97     virtual void PsValueUpdated( const TUid aCategory, const TUint aKey,

    98                                  const TInt aVal ) = 0;

    99     };

   100 

   101 /**

   102  * Transition callback interface.

   103  */

   104 class MAknTransitionUtilsObserver

   105     {

   106 public:

   107     virtual TInt AknTransitionCallback(TInt aEvent, TInt aState = 0, 

   108                                        const TDesC8* aParams = NULL) = 0;

   109 	};

   110 

   111 /**

   112  * Utility class for transition effects.

   113  *

   114  * There are three different kinds of utilities here:

   115  * 1. Callbacks for different transition related events.

   116  * 2. Temporary storage of arbitrary data, associated with a key.

   117  * 3. General transition related functions.

   118  *

   119  * The data storage functionality is useful when you need to pass data

   120  * between different parts of the code, and there is no natural way to

   121  * do it, eg. when doing control transitions with integration in 

   122  * components that aren't explicitly connected.  In this case a fitting

   123  * key would be a pointer to the CCoeControl.

   124  */

   125 NONSHARABLE_CLASS( CAknTransitionUtils ) : public CCoeStatic, 

   126                                            public MGfxTransEffectObserver,

   127                                            public MAknPsObserver

   128     {

   129     public:

   130 

   131     /**

   132      * Types of events for which callbacks can be registered.

   133      */

   134     enum TEvents

   135         { 

   136         ENone = 0x0,

   137         

   138         /**

   139          * Changes in screen redirection.

   140          */

   141         EEventWsBufferRedirection = 0x1,

   142         

   143         /**

   144          * Component effect completion.

   145          */

   146         EEventControlTransitionFinished = 0x2

   147 		};

   148 

   149     /**

   150      * Control type specification for CAknTransitionUtils::GetDemarcation().

   151      */

   152     enum TGfxControlType

   153         {

   154         EOptionsMenu,

   155         EPopup

   156         };

   157 

   158     enum TMakeVisibleSubComponentsInfo

   159         {

   160         EForceInvisible,

   161         EForceVisible,

   162         EDisappearInvisible,

   163         EAppearInvisible,

   164         EAppearVisible,

   165         EClearIgnored

   166         };

   167 

   168     ~CAknTransitionUtils();

   169 

   170     /**

   171      * Add an observer for transition events.  If the observer has already

   172      * been added, the events for which it is listening will be updated to

   173      * the new set of events passed in.

   174      *

   175      * @param aObserver The observer object.

   176      * @param aEvent The event(s) to listen to.  To register an observer

   177      *        for multiple events, the event flags should be OR-ed together.

   178      * @param aParams Extra parameters.  Not used with

   179      *        EEventWsBufferRedirection.  With EEventControlTransitionFinished,

   180      *        a pointer to the CCoeControl of the transition should be passed

   181      *        in, as this will be passed back to the observer in the callback.

   182      *        Send this pointer directly as the argument, cast to a 

   183      *        const TDesC8*.

   184      *

   185      * @return KErrNone on success, otherwise one of the other system-wide 

   186      *         error codes.

   187      */

   188     IMPORT_C static TInt AddObserver( MAknTransitionUtilsObserver* aObserver,

   189                                       TInt aEvents,

   190                                       const TDesC8* aParams = NULL );

   191                                       

   192     /**

   193      * Remove an observer for transition events.  The events specified are

   194      * significant: only the specified events will be removed.  If there are

   195      * no remaining events, the observer will be removed and the

   196      * actual observer object can be safely deleted.

   197      *

   198      * @param aObserver The observer to remove.

   199      * @param aEvent The event(s) that should be removed.

   200      *

   201      * @return KErrNone on success, otherwise one of the other system-wide

   202      *         error codes.

   203      */

   204     IMPORT_C static TInt RemoveObserver( MAknTransitionUtilsObserver* aObserver,

   205                                          TInt aEvents );

   206 

   207     /**

   208      * Get the state of the observed event.  This currently only applies to

   209      * window redirection, not to component transition completion.

   210      *

   211      * @param aEvent The event to check the state of.  Currently

   212      *        EEventWsBufferRedirection is the only valid alternative.

   213      * @param aState On return, the state is set.  For window redirection,

   214      *        this is 0 (false) if it's not redirected, and non-zero (true)

   215      *        if it is.

   216      * @param aParams Additional parameters.  Not currently used.

   217      *

   218      * @return KErrNone on success, otherwise one of the other system-wide

   219      *         error codes.

   220      */

   221     IMPORT_C static TInt GetState( TInt aEvent, TInt* aState, 

   222                                    TDes8* aParams = NULL);

   223 

   224     /**

   225      * Store arbitrary data, associated with a key.  Only one data pointer

   226      * can be stored per key, so if data has already been stored using aKey,

   227      * aData will be stored instead of the old data.

   228      *

   229      * @param aKey The key, which can be used to retrieve the data.

   230      * @param aData The data to store.

   231      *

   232      * @return KErrNone on success, otherwise one of the other

   233      *         system-wide error codes.

   234      */

   235     IMPORT_C static TInt SetData( const TInt aKey, TAny* aData );

   236 

   237     /**

   238      * Retrieve stored data, using its associated key.

   239      * 

   240      * @param aKey The key to which the data is associated.

   241      *

   242      * @return The data, or NULL on error.

   243      */

   244     IMPORT_C static TAny* GetData( const TInt aKey );

   245 

   246     /**

   247      * Remove stored data.  This does not free the stored data, just removes

   248      * it from storage, so that it can no longer be retrieved.  This should

   249      * be done when the data no longer needs to be retrieved, to free up

   250      * data internal to this class.

   251      *

   252      * @param aKey The key to which the data is associated.

   253      */

   254     IMPORT_C static void RemoveData( const TInt aKey );

   255 

   256     /**

   257      * Recursively sets all parents to the control tree.  Used by control

   258      * transition integration points to ensure that all controls will be

   259      * included in the transition.

   260      *

   261      * @param aControl The base (key) control of a control transition.

   262      */

   263     IMPORT_C static void SetAllParents( const CCoeControl* aControl );

   264     

   265     /**

   266      * Check if transition effects are enabled.

   267      *

   268      * @param aEffectCategory Specify which category of effects to inquire

   269      *        about.  The categories are specified in akntranseffect.h,

   270      *        (EFullScreenTransitionsOff etc.).

   271      *

   272      * @return ETrue if effects in the specified category are enabled, 

   273      *         EFalse if not.

   274      */

   275     IMPORT_C static TBool TransitionsEnabled( TInt aEffectCategory );

   276 

   277     /**

   278      * Set the visibility for all the subcomponents of a control.  NB: does

   279      * NOT set the visibility for the control itself (aControl).

   280      *

   281      * @param aControl The main control, whose subcomponents will have their

   282      *        visibility set.

   283      * @param aInfo EForceInvisible = Makes all window owning sub controls

   284      *                  invisible

   285      *             EForceVisible: Makes all window owning sub controls visible

   286      *             EDisappearInvisible: Makes all window owning sub controls

   287      *                  invisible

   288      *             EAppearInvisible: Makes all visible subcontrols invisible

   289      *                  (must be followed by a call using EAppearVisible or

   290      *                  EClearIgnored)

   291      *             EAppearVisible: Makes all controls visible that was made

   292      *                  invisible using argument EAppearInvisible

   293      *             EClearIgnored: Reset the list of controls that was added

   294      *                  to ignore list

   295      *

   296      * @return KErrNone on success, otherwise one of the system-wide error 

   297      *         codes.

   298      */

   299     IMPORT_C static TInt MakeVisibleSubComponents( CCoeControl* aControl, 

   300                                         TMakeVisibleSubComponentsInfo aInfo );

   301 

   302     /**

   303      * Get the demarcation rect for a specified component.  The demarcation

   304      * rect is the area where an appear transition should start, and a

   305      * disappear transition should end.  For example, for the options menu,

   306      * this would probably be the left softkey.  With the proper KML, this

   307      * could be used to give the impression that the options menu grows 

   308      * out from the left softkey.

   309      *

   310      * This function handles portrait and landscape mode transparently, so

   311      * the integration code should always get the appropriate demarcation

   312      * rect.

   313      *

   314      * @param aControlType The control type to get the demarcation for.

   315      * @param aRect On return, contains the resulting rect.

   316      *

   317      * @return KErrNone on success, otherwise one of the system-wide error

   318      *         codes.

   319      */

   320     IMPORT_C static TInt GetDemarcation( TGfxControlType aControlType, 

   321                                          TRect& aRect );

   322 

   323     private:

   324     CAknTransitionUtils();

   325 

   326     /**

   327      * Returns the AknTransitionUtils singleton.

   328      *

   329      * The AknTransitionUtils singleton, or NULL or error.

   330      */    

   331     static CAknTransitionUtils* Static();

   332     

   333     // From MGfxTransEffectObserver

   334     void TransitionFinished( const CCoeControl* aControl, 

   335                                       TUint aAction );

   336 

   337     // From MAknPsObserver

   338     void PsValueUpdated( const TUid aCategory, const TUint aKey,

   339                          const TInt aVal );

   340     

   341     void RemoveControlTransitionObserver( const TInt aKey );

   342 

   343     TInt MakeVisibleSubComponentsR( CCoeControl* aControl, 

   344                                     TMakeVisibleSubComponentsInfo aInfo );

   345 

   346 private:

   347     struct TDataEntry;

   348     struct TTransitionObserver;

   349   

   350     RPointerArray<TDataEntry> iUserData;

   351 

   352     RPointerArray<TTransitionObserver> iObservers;

   353     TInt iNumControlTransitionObservers;

   354     

   355     CAknPsObserver* iPsObserver;

   356     TInt iNumPsObservers;

   357     TBool iScreenRedirected;

   358     

   359     CRepository* iRepository;

   360     RPointerArray<const CCoeControl> iIgnoredChildControls;

   361     };

   362 

   363 #endif // __AKN_TRANSITION_UTILS_H__