1 /*

     2 * Copyright (c) 2006 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:  MPX view utility implementation

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef CMPXVIEWUTILITYIMP_H

    21 #define CMPXVIEWUTILITYIMP_H

    22 

    23 

    24 // INCLUDES

    25 #include <mpxcustomcommandobserver.h>

    26 #include <mpxpluginhandlerobserver.h>

    27 #include "mpxviewutility.h"

    28 

    29 // FORWARD DECLARATIONS

    30 class CMPXViewPluginHandler;

    31 class CRepository;

    32 class CMPXViewPlugin;

    33 class CMPXViewHistory;

    34 

    35 // CLASS DECLARATION

    36 

    37 /**

    38  *  MPX view utility implementation.

    39  *

    40  *  @lib mpxviewutility.lib

    41  *  @since S60 v3.1

    42  */

    43 NONSHARABLE_CLASS( CMPXViewUtilityImp ) : public CBase,

    44                                           public MMPXViewUtility,

    45                                           public MMPXCustomCommandObserver,

    46                                           public MMPXPluginHandlerObserver

    47     {

    48 public:

    49 

    50     /**

    51      * Retrieves view utility from TLS. Creates if it's not there.

    52      *

    53      * @since 3.1

    54      * @return Pointer to a view utility object.

    55      */

    56     static MMPXViewUtility* UtilityL();

    57 

    58 private:

    59 

    60     /**

    61      * C++ default constructor.

    62      */

    63     CMPXViewUtilityImp();

    64 

    65     /**

    66      * Destructor.

    67      */

    68     virtual ~CMPXViewUtilityImp();

    69 

    70     /**

    71      * By default Symbian 2nd phase constructor is private.

    72      */

    73     void ConstructL();

    74 

    75     /**

    76      * Two-phased constructor.

    77      * Intentionally make this API private as this class is a singleton.

    78      * To get a view utility instance, UtilityL() should be called.

    79      *

    80      * @return Pointer to newly created object.

    81      */

    82     static CMPXViewUtilityImp* NewL();

    83 

    84     /**

    85      * Store view utility to TLS.

    86      *

    87      * @param aUtility View utility object. Ownership not transferred.

    88      */

    89     static void StoreViewUtility( MMPXViewUtility* aUtility );

    90 

    91 // from base class MMPXViewUtility

    92 

    93     /**

    94      * From MMPXViewUtility

    95      * This method must be called when the client no longer needs the utility

    96      * instance. This object will be destroyed when no one is using it.

    97      *

    98      * @since 3.1

    99      */

   100     void Close();

   101 

   102     /**

   103      * From MMPXViewUtility

   104      * Activate view by resolving passed uid.

   105      *

   106      * @since 3.1

   107      * @param aUid Uid to be resolved. This uid can be plugin implementation

   108      *             uid, plugin type uid or specific view plugin uid.

   109      * @param aParam Parameter passed to the view on activation

   110      * @leave KErrNotFound if a matching plugin cannot be found

   111      */

   112     void ActivateViewL(

   113         const TUid& aUid,

   114         const TDesC* aParam = NULL );

   115 

   116     /**

   117      * From MMPXViewUtility

   118      * Activate view by resolving passed uids.

   119      *

   120      * @since 3.1

   121      * @param aUids List of Uids to be resolved, this uid can be plugin uid,

   122      *              plugin type uid or specific view plugin uid.

   123      * @param aParam Parameter passed to the view on activation

   124      * @leave KErrNotFound if a matching plugin cannot be found

   125      */

   126     void ActivateViewL(

   127         const RArray<TUid>& aUids,

   128         const TDesC* aParam = NULL );

   129 

   130     /**

   131      * From MMPXViewUtility

   132      * Set view as default view, not bring to foreground. This is only valid

   133      * if there are no views previously activated

   134      *

   135      * @since 3.1

   136      * @param aUid Uid of item to be activated. This uid can be plugin implementation

   137      *             uid, plugin type uid or specific view plugin uid.

   138      * @leave Error code KErrAlreadyExist when there are views already

   139      *        activated

   140      * @leave Error code KErrNotSupported for views that doesn't support

   141      *        default view (such as dialogs)

   142      */

   143     void SetAsDefaultViewL( const TUid& aUid );

   144 

   145     /**

   146      * From MMPXViewUtility

   147      * Set view as default view, not bring to foreground. This is only valid

   148      * if there are no views previously activated

   149      *

   150      * @since 3.1

   151      * @param aUid Uids of item to be activated. This uid can be plugin implementation

   152      *             uid, plugin type uid or specific view plugin uid.

   153      * @leave Error code KErrAlreadyExist when there are views already

   154      *        activated

   155      * @leave Error code KErrNotSupported for views that doesn't support

   156      *        default view (such as dialogs)

   157      */

   158     void SetAsDefaultViewL( const RArray<TUid>& aUids );

   159 

   160     /**

   161      * From MMPXViewUtility

   162      * Activate previous view.

   163      *

   164      * @since 3.1

   165      *

   166      * @leave Error code KErrNotFound if there's no history.

   167      */

   168     void ActivatePreviousViewL();

   169 

   170     /**

   171      * From MMPXViewUtility

   172      * Pre-load view plug-ins that have KMPXVpFeaturePreLoaded flag set.

   173      *

   174      * @since 3.1

   175      */

   176     void PreLoadViewsL();

   177 

   178     /**

   179      * From MMPXViewUtility

   180      * Pre-load view plug-ins that have KMPXVpFeaturePreLoaded flag set and also by resolving aUid.

   181      *

   182      * @param aUid Uid of specific applicaiton to be resolved

   183      */

   184     void PreLoadViewsL(const TUid& aUid);

   185 	

   186     /**

   187      * From MMPXViewUtility

   188      * Pre-load view plug-in by resolving passed uid.

   189      *

   190      * @since 3.1

   191      * @param aUid Uid to be resolved. This uid can be plugin uid, plugin type

   192      *             uid or specific view plugin uid.

   193      * @leave if no match is found.

   194      */

   195     void PreLoadViewL( const TUid& aUid );

   196 

   197     /**

   198      * From MMPXViewUtility

   199      * Get a reference to view plugin manager.

   200      *

   201      * @since 3.1

   202      * @return Reference to view plugin manager.

   203      */

   204     MMPXViewPluginManager& ViewPluginManager();

   205 

   206     /**

   207      * From MMPXViewUtility

   208      * Constructs default view history

   209      *

   210      * @since 3.1

   211      * @return if defined, the default view UID.  KNullUid if not defined

   212      */

   213     TUid ConstructDefaultViewHistoryL();

   214 

   215     /**

   216      * From MMPXViewUtility

   217      *

   218      * Push default history to view history.  The current browse history

   219      * is erased and the default browsing path is loaded as the current history

   220      *

   221      * @since 3.1

   222      */

   223     void PushDefaultHistoryL();

   224 

   225     /**

   226      * From MMPXViewUtility

   227      * Gets default view's UID

   228      *

   229      * @return if defined, the default view UID.  KNullUid if not defined

   230      *

   231      * @since 3.1

   232      */

   233     TUid DefaultViewUid();

   234 

   235     /**

   236      * From MMPXViewUtility

   237      * Returns the current history depth

   238      * if depth is greater than 1, the client should call ActivatePreviousViewL

   239      * on a back command

   240      *

   241      * if depth is 1, the client should exit the app on a back command instead

   242      * of calling ActivatePreviousViewL

   243      *

   244      * @since 3.1

   245      *

   246      * @return The current browsing history depth.

   247      */

   248     TInt ViewHistoryDepth();

   249 

   250     /**

   251      * From MMPXViewUtility

   252      * Returns the last activated view type

   253      *

   254      * @return previous view type if defined.  KNullUid if not.

   255      *

   256      * @since 3.1

   257      */

   258     TUid PreviousViewType();

   259 

   260     /**

   261      * From MMPXViewUtility

   262      * Returns the view type of the active view.

   263      *

   264      * @return current view type if defined.  KNullUid if not.

   265      *

   266      * @since 3.1

   267      */

   268     TUid ActiveViewType();

   269 

   270     /**

   271      * From MMPXViewUtility

   272      * Returns the implementation uid of the active view.

   273      *

   274      * @return current view implementation id if defined.  KNullUid if not.

   275      *

   276      * @since 3.1

   277      */

   278     TUid ActiveViewImplementationUid();

   279 

   280     /**

   281      * From MMPXViewUtility

   282      * Add view activation observer.

   283      *

   284      * @since 3.1

   285      * @param aObserver Pointer to an observer object

   286      */

   287     void AddObserverL(

   288         MMPXViewActivationObserver* aObserver );

   289 

   290     /**

   291      * From MMPXViewUtility

   292      * Remove view activation observer.

   293      *

   294      * @since 3.1

   295      * @param aObserver Pointer to an observer object

   296      */

   297     void RemoveObserver(

   298         MMPXViewActivationObserver* aObserver );

   299 

   300     /**

   301      * From MMPXCustomCommandObserver

   302      * Handle custom commands.

   303      *

   304      * @since 3.1

   305      * @param aUid Command category Uid. Different command set will have

   306      *             different Uid to avoid clash.

   307      * @param aCommand Command to be handled.

   308      * @param aData data for the specific command

   309      */

   310     void HandleCustomCommand(

   311         const TUid& aUid,

   312         const TInt aCommand,

   313         const TDesC8& aData = KNullDesC8 );

   314 

   315     /*

   316     * From MMPXPluginHandlerObserver

   317     * @see MMPXPluginHandlerObserver

   318     */

   319     void HandlePluginHandlerEvent(TPluginHandlerEvents aEvent, const TUid& aPluginUid,

   320         TInt aLoaded, TInt aData);

   321 

   322 private:

   323 

   324     /**

   325      * Activate view by resolving passed uids.

   326      *

   327      * @since 3.1

   328      * @param aUids List of Uids to be resolved, this uid can be plugin uid,

   329      *              plugin type uid or specific view plugin uid.

   330      * @param aIsActivatingPreviousView ETrue if activating previous view

   331      * @param aUpdatedPreviousView ETrue iPreviousView has been updated or no need

   332      *                             EFalse will update iPreviousView

   333      * @param aParam Parameter passed to the view on activation

   334      */

   335     void ActivateViewL(

   336         const RArray<TUid>& aUids,

   337         TBool aIsActivatingPreviousView,

   338         TBool aUpdatedPreviousView,

   339         const TDesC* aParam = NULL );

   340 

   341     /**

   342      * Marks the view closed.  This does not actually close the view.

   343      * When a dialog is closed, it should call this method to indicate it has been closed.

   344      *

   345      * @since 3.1

   346      * @param aPlugin a pointer to the current dialog

   347      */

   348     void MarkViewAsClosedL( CMPXViewPlugin* aPlugin );

   349 

   350     /**

   351      * Notify observers on view activation.

   352      *

   353      * @param aCurrentViewType Current view type Uid

   354      * @param aPreviousViewType Previous view type Uid

   355      */

   356     void NotifyObservers(

   357         const TUid& aCurrentViewType,

   358         const TUid& aPreviousViewType );

   359 

   360     /**

   361      * Notify observers on view update events (addition/update/removal).

   362      *

   363      * @param aViewUid Identifies the view.

   364      * @param aUpdateEvent Identifies the event (addition/update/removal).

   365      * @param aLoaded ETrue if the view is currently loaded

   366      * @param aVersion View version (new for addition and update and old for removal)

   367      */

   368     void NotifyViewUpdate(

   369         const TUid& aViewUid,

   370         MMPXViewActivationObserver::TViewUpdateEvent aUpdateEvent,

   371         TBool aLoaded,

   372         TInt aVersion = 0);

   373 

   374     /**

   375      * Insert/Append to default view history array

   376      *

   377      * @param aData data to append/insert

   378      * @param aLoc location to insert (default append)

   379      *

   380      * @return if successful, returns the plulgin type uid

   381      */

   382     TInt AddToDefaultViewHistoryL( const TDesC& aData, TInt aLoc = -1 );

   383 

   384     /**

   385      * Updates previous view info

   386      *

   387      * @param aIndex index in current view history to store

   388      */

   389     void UpdatePreviousViewInfoL( TInt aIndex );

   390 

   391     /**

   392      * Find if the view exist in current history

   393      *

   394      * @param aType type to search for

   395      * @return index of the plugin in history if found, KErrNotFound otherwise

   396      */

   397     TInt FindCurrentHistoryEntryByTypeL( const TUid aType );

   398 

   399 private:    // data

   400 

   401     /**

   402      * View plugin handler.

   403      * Own.

   404      */

   405     CMPXViewPluginHandler* iPluginManager;

   406 

   407     /**

   408      * Reference count.

   409      */

   410     TInt iRefCount;

   411 

   412     /**

   413      * History paths

   414      */

   415     RPointerArray<CMPXViewHistory> iDefaultHistoryPath;

   416     RPointerArray<CMPXViewHistory> iCurrentHistoryPath;

   417 

   418     /**

   419      * List of observers

   420      * Owned.

   421      */

   422     RPointerArray<MMPXViewActivationObserver> iObservers;

   423 

   424     CMPXViewHistory* iPreviousView;

   425     CMPXViewHistory* iCurrentView;

   426     CMPXViewHistory* iDefaultView;

   427     };

   428 

   429 #endif  // CMPXVIEWUTILITYIMP_H

   430 

   431 // End of File