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:  Definition of helper utility for Common UI

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef C_CMPXCOMMONUIHELPER_H

    21 #define C_CMPXCOMMONUIHELPER_H

    22 

    23 #ifdef __ENABLE_MSK

    24 #include <eikbtgpc.h>

    25 #endif // __ENABLE_MSK

    26 #include <mpxcollectionuihelperobserver.h>

    27 #include <mpxcollectionuihelper.h>

    28 #include <mpxcommonui.rsg>

    29 

    30 #include <mpxcollectionutility.h>  

    31 

    32 // FORWARD DECLARATIONS

    33 class CMPXMedia;

    34 class CMPXDrmUiHelper;

    35 class MProgressDialogCallback;

    36 class CAknWaitDialog;

    37 class MMPXCollectionUtility;

    38 class CEikButtonGroupContainer;

    39 

    40 // CONSTANTS

    41 

    42 // CLASS DECLARATION

    43 

    44 /**

    45  * Common UI helper utility class.

    46  *

    47  * @lib mpxcommonui.lib

    48  * @since S60 3.2.3

    49  */

    50 NONSHARABLE_CLASS( CMPXCommonUiHelper ) : public CBase,

    51                                           public MMPXCHelperObserver

    52     {

    53 public:

    54 

    55     /**  Duration display mode */

    56     enum TMPXDuratDisplayMode

    57         {

    58         EMPXDuratAuto = 0,

    59         EMPXDuratHMS

    60         };

    61 

    62     /**

    63     * Two-phased constructor.

    64     *

    65     * @since S60 3.2.3

    66     * @aCollectionUtility Collection utility to use for this helper

    67     * @return Pointer to newly created object.

    68     */

    69     IMPORT_C static CMPXCommonUiHelper* NewL(MMPXCollectionUtility* aCollectionUtility = NULL);

    70 

    71     /**

    72     * Destructor.

    73     */

    74     virtual ~CMPXCommonUiHelper();

    75 

    76     /**

    77     * Check if the host application is messaging or browser

    78     * @since S60 3.2.3

    79     * @return ETrue if host is messaging or browser, EFalse otherwise

    80     */

    81     IMPORT_C TBool IsHostMessagingBrowserL();

    82 

    83     /**

    84     * Check if the host application is the Podcasting Application

    85     * @since S60 3.2.3

    86     * @return ETrue if host is Podcasting Application, EFalse otherwise

    87     */

    88     IMPORT_C TBool IsHostPodcastingAppL();

    89 

    90     /**

    91     * Check if the host application is messaging

    92     * @since S60 3.2.3

    93     * @return ETrue if host is messaging, EFalse otherwise

    94     */

    95     IMPORT_C TBool IsHostMessagingL();

    96 

    97     /**

    98     * Check if the host application is browser

    99     * @since S60 3.2.3

   100     * @return ETrue if host is browser, EFalse otherwise

   101     */

   102     IMPORT_C TBool IsHostBrowserL();

   103 

   104     /**

   105     * Convert to displayable duration

   106     *

   107     * @since S60 3.2.3

   108     * @param aduration Duration in seconds

   109     * @param aMode time display mode

   110     * @return A heap descriptor that contains displayable duration

   111     *         (ownership transferred). Caller must destroy this object

   112     *         after use.

   113     */

   114     IMPORT_C HBufC* DisplayableDurationL(

   115         TInt64 aDuration,

   116         TMPXDuratDisplayMode aMode = EMPXDuratAuto );

   117 

   118     /**

   119     * Convert to displayable duration in text format

   120     *

   121     * @since S60 3.2.3

   122     * @param aduration Duration in seconds

   123     * @return A heap descriptor that contains displayable duration

   124     *         (ownership transferred). Caller must destroy this object

   125     *         after use.

   126     */

   127     IMPORT_C HBufC* DisplayableDurationInTextL(

   128         TInt64 aDuration );

   129 

   130     /**

   131     * Set current file as ringing tone.

   132     *

   133 	* @since S60 3.2.3

   134     * @param aMedia Media properties of the current track. the media must

   135     *               contain the following attributes:

   136     *               TMPXAttribute( KMPXMediaIdGeneral, EMPXMediaGeneralUri )

   137     *               TMPXAttribute( KMPXMediaIdGeneral, EMPXMediaGeneralTitle )

   138     *               TMPXAttribute( KMPXMediaIdDrm, EMPXMediaDrmProtected )

   139     *               TMPXAttribute( KMPXMediaIdDrm, EMPXMediaDrmRightsStatus )

   140     *               TMPXAttribute( KMPXMediaIdDrm, EMPXMediaDrmCanSetAutomated )

   141     * @param aSetToAllProfiles ETrue if set ringtone to all profiles.

   142     *                          EFalse if set ringtone to active profile.

   143     * @param aShowQuery If ETrue, a confirmation query is shown before

   144     *                   setting ringtone. This setting will only apply if

   145     *                   aSetToAllProfiles is set to ETrue. No effect if

   146     *                   aSetToAllProfiles is set to EFalse.

   147     */

   148     IMPORT_C void DoSetAsRingingToneL(

   149         const CMPXMedia& aMedia,

   150         TBool aSetToAllProfiles,

   151         TBool aShowQuery = EFalse );

   152 

   153     /**

   154     * Check if current profile mode is offline mode.

   155     *

   156     * @since S60 3.2.3

   157     * @return ETrue if in Offline mode. Otherwise, EFalse.

   158     */

   159     IMPORT_C TBool IsProfileOfflineModeL();

   160 

   161     /*

   162     * Returns path of the default drive used to store playlist, attachments,

   163     * downloads and ringtones.

   164     * @return a path of the default drive

   165     * @since S60 3.2.3

   166     */

   167     IMPORT_C HBufC* DefaultDriveLC();

   168 

   169     /*

   170     * Returns a path of the next available drive used for saving playlists, ringtones,

   171     * downloads and attachments. The order of priority is internal mass store,

   172     * MMC, then phone memory.

   173     *

   174     * @since S60 3.2.3

   175     * @param aSize

   176     */

   177     IMPORT_C HBufC* AvailableDriveLC( TInt aSize );

   178 

   179     /**

   180     * Display information note

   181     *

   182     * @since S60 3.2.3

   183     * @param aResourceId Resource id of the text string

   184     */

   185     IMPORT_C void DisplayInfoNoteL( TInt aResourceId );

   186 

   187     /**

   188     * Display information note

   189     *

   190     * @since S60 3.2.3

   191     * @param aText Text to be shown on the note

   192     */

   193     IMPORT_C void DisplayInfoNoteL( const TDesC& aText );

   194 

   195     /**

   196     * Display confirmation note

   197     *

   198     * @since S60 3.2.3

   199     * @param aResourceId Resource id of the text string

   200     */

   201     IMPORT_C void DisplayConfirmNoteL( TInt aResourceId );

   202 

   203     /**

   204     * Display confirmation note

   205     *

   206     * @since S60 3.2.3

   207     * @param aText Text to be shown on the note

   208     */

   209     IMPORT_C void DisplayConfirmNoteL( const TDesC& aText );

   210 

   211 // Cover UI start

   212 //#ifdef __COVER_DISPLAY

   213     void DisplayConfirmNoteL( const TDesC& aText, TInt aResourceId );

   214 //#endif // __COVER_DISPLAY

   215 // Cover UI end

   216 

   217     /**

   218     * Convert a value from bytes to kB/MB/GB.

   219     *

   220     * @since S60 3.2.3

   221     * @param aByte Number of bytes

   222     * @param ETrue to append " free" at the end of the string

   223     */

   224     IMPORT_C HBufC* UnitConversionL( TInt64 aByte, TBool aFree = EFalse );

   225 

   226     /**

   227     * Finds all user playlists in the given collection

   228     *

   229     * @since S60 3.2.3

   230     */

   231     IMPORT_C CMPXMedia* FindPlaylistsL();

   232 

   233     /**

   234     * Add to saved playlist

   235     *

   236     * @since S60 3.2.3

   237     * @param aPlaylists media containing a media array

   238     *         each entry in the array must contain the following attributes

   239     *         TMPXAttribute( KMPXMediaIdGeneral, EMPXMediaGeneralTitle )

   240     *         TMPXAttribute( KMPXMediaIdGeneral, EMPXMediaGeneralId )

   241     *         TMPXAttribute( KMPXMediaIdGeneral, EMPXMediaGeneralDrive )

   242     * @param aTracks Tracks to be add to the playlist

   243     *          media containing a media array

   244     *          must contain at least 1 element

   245     *          each entry in the arry must contain the following attributes

   246     *          TMPXAttribute( KMPXMediaIdGeneral, EMPXMediaGeneralType )

   247     *          TMPXAttribute( KMPXMediaIdGeneral, EMPXMediaGeneralCategory )

   248     *          TMPXAttribute( KMPXMediaIdGeneral, EMPXMediaGeneralId )

   249     *          TMPXAttribute( KMPXMediaIdGeneral, EMPXMediaGeneralTitle )

   250     * @param aObserver pointer to callback

   251     * @param aCallback call back for wait dialog

   252     *

   253     * @return ETrue if the user accepts the save dialog, EFalse otherwise

   254     */

   255     IMPORT_C TBool AddToSavedPlaylistL(

   256         const CMPXMedia& aPlaylists, const CMPXMedia& aTracks,

   257         MMPXCHelperObserver* aObserver,

   258         MProgressDialogCallback* aCallback );

   259 

   260     /**

   261     * Create new playlist

   262     *

   263     * @since S60 3.2.3

   264     * @param aTracks Tracks to be add to the playlist

   265     *          media containing a media array

   266     *          can be a valid array with 0 length

   267     *          each entry in the arry must contain the following attributes

   268     *          TMPXAttribute( KMPXMediaIdGeneral, EMPXMediaGeneralType )

   269     *          TMPXAttribute( KMPXMediaIdGeneral, EMPXMediaGeneralCategory )

   270     *          TMPXAttribute( KMPXMediaIdGeneral, EMPXMediaGeneralId )

   271     *          TMPXAttribute( KMPXMediaIdGeneral, EMPXMediaGeneralTitle )

   272     * @param aObserver pointer to callback

   273     * @param aCallback call back for wait dialog

   274     *

   275     * @return ETrue if user accepts the query, EFalse otherwise

   276     */

   277     IMPORT_C TBool CreatePlaylistL( const CMPXMedia& aTracks,

   278         MMPXCHelperObserver* aObserver,

   279         MProgressDialogCallback* aCallback );

   280 

   281     /**

   282 	* Launches rename dialog

   283 	*

   284 	* @since S60 3.2.3

   285 	* @param aOldName original name, with the extension (e.g. a.mp3)

   286 	* @param aNewName on return, this will be populated with the new name

   287 	*                 inputed by the user

   288 	* @param aPath    the path to the file, without the file name (e.g. c:\\data\\)

   289 	* @return generic return code from AknDialog

   290 	*/

   291 	IMPORT_C TInt LaunchRenameDialogL(

   292         const TDesC& aOldName,

   293 		TDes& aNewName,

   294 		const TDesC& aPath );

   295 

   296     /**

   297     * Shows wait note

   298     *

   299     * @since S60 3.2.3

   300     * @param aText text to display

   301     * @param aCBAId button group ID

   302     * @param aVisibilityDelayOff If set ETrue the dialog will be visible

   303     *                            immediality. Use only when the length of

   304     *                            the process is ALWAYS over 1.5 seconds.

   305     * @param aCallback call back

   306     * @param aResId resource Id for the WaitNote, default is R_MPX_GENERIC_WAIT_NOTE

   307     */

   308     IMPORT_C void ShowWaitNoteL( TDesC& aText, TInt aCBAId,

   309         TBool aVisibilityDelayOff, MProgressDialogCallback* aCallback, TInt aResId = R_MPX_GENERIC_WAIT_NOTE );

   310 

   311     /**

   312      * Dismiss wait note

   313      */

   314     IMPORT_C void DismissWaitNoteL();

   315 

   316     /**

   317     * Handles displaying the error message for given error code

   318     * according to the media object provided

   319     *

   320     * @since S60 3.2.3

   321     * @param aError Error code

   322     * @param aMedia MPXMedia object

   323     * @param aFile Handle to file

   324     * @return KErrNone if no error, or else if a dialog is displayed will

   325     *         return the Button ID used to dismiss dialog.

   326     */

   327     IMPORT_C TInt HandleErrorL( TInt aError,

   328                                 const CMPXMedia* aMedia=NULL,

   329                                 RFile* aFile=NULL );

   330 

   331     /**

   332     * Adds given resource text as MSK to CBA.

   333     *

   334     * @since S60 3.2.3

   335     * @param aCba a button group container

   336     * @param aResourceId middle softkey label.

   337     * @param aCommandId command that should be performed when MSK

   338     *        is pressed.

   339     */

   340     IMPORT_C void SetMiddleSoftKeyLabelL(

   341         CEikButtonGroupContainer& aCba,

   342         TInt aResourceId,

   343         TInt aCommandId );

   344 

   345     /**

   346     * Removes current MSK label

   347     *

   348     * @since S60 3.2.3

   349     * @param aCba a button group container

   350     */

   351     IMPORT_C void RemoveMiddleSoftKeyLabel(

   352         CEikButtonGroupContainer& aCba );

   353 

   354     /**

   355     * Adds given resource icon as MSK to CBA.

   356     *

   357     * @since S60 3.2.3

   358     * @param aCba a button group container

   359     * @param aBitmap a bitmap

   360     * @param aMask a bitmap mask

   361     */

   362     IMPORT_C void SetMiddleSoftKeyIconL(

   363         CEikButtonGroupContainer& aCba,

   364         CFbsBitmap* aBitmap,

   365         CFbsBitmap* aMask );

   366 

   367     /**

   368     * Generate the next available title from the given title for the category.

   369     * The generated title is unique within the category regardless of the

   370     * media type within the category and its location.

   371     * e.g. c:\data\playlists\Playlist.m3u exists in the collection, the next

   372     * available title for the playlist category will be Playlist(01) regardless

   373     * if the title is going to be used for a playlist located in e:\data\playlists

   374     * or if it's a xml playlist file.

   375     *

   376     * @since S60 3.2.3

   377     * @param aCategory specifies the category for the title

   378     * @param aBaseTitle specifies the base title for new title generation

   379     * @return the next available title in the category in "BaseTitle(number)"

   380     *         format where number is the lowest available number.

   381     */

   382     IMPORT_C HBufC* GenerateTitleL(

   383         TMPXGeneralCategory aCategory,

   384         const TDesC& aBaseTitle );

   385 

   386     /**

   387     * Checks if Exit option should be hidden

   388     *

   389     * @since S60 3.2.3

   390     * @return ETrue if exit option should be hidden, EFalse otherwise

   391     */

   392     IMPORT_C TBool ExitOptionHiddenL();

   393 

   394     /**

   395     * Sets standalone mode process ID

   396     *

   397     * @since S60 3.2.3

   398     * @param aPId Process ID for standalone mode, 0 to reset

   399     * @return ETrue if successful, EFalse otherwise

   400     */

   401     IMPORT_C static TBool SetStandAloneModePId( TInt64 aPId );

   402 

   403     /**

   404     * Gets stand alone mode's process id

   405     *

   406     * @since S60 3.2.3

   407     * @return Stand alone mode's process ID, or 0 if not found

   408     */

   409     IMPORT_C static TInt64 StandAloneModePId();

   410 

   411 

   412     /**

   413     * Checks if the application with the provided group id is in foreground

   414     * This method is required because AppUi()->IsForeground() does not work

   415     * properly when the screen saver is active

   416     *

   417     * @since S60 3.2.3

   418     * @param aWindowGroupId application group identifier

   419     * @return ETrue if the application is in foreground, EFalse otherwise

   420     */

   421     IMPORT_C TBool IsForegroundApplication(TInt aWindowGroupId);

   422 

   423     /**

   424     * Get the Drive Number for the MMC card

   425     *

   426     * @since S60 3.2.3

   427     * @return Drive Number as defined in TDriveNumber or error code

   428     */

   429     IMPORT_C static TInt MMCDriveNumber();

   430 

   431 

   432     /**

   433      * Cancel all subsequent operations scheduled by CollectionUiHelper

   434      * Currently, this method is only used to cancel adding songs incrementally

   435      * to the playlist (user clicks on Cancel on the wait note)

   436      */

   437     IMPORT_C void CancelCollectionOperation();

   438     

   439                             

   440 private:

   441 

   442     /**

   443     * C++ default constructor.

   444     *

   445     * @since S60 3.2.3

   446     * @param aCollectionUtility Collection utility to use for this helper

   447     */

   448     CMPXCommonUiHelper(MMPXCollectionUtility* aCollectionUtility);

   449 

   450     /**

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

   452     */

   453     void ConstructL();

   454 

   455     /**

   456     * Check if memory card is present and writable.

   457     *

   458     * @since S60 3.2.3

   459     * @param aDrive If return is ETrue, aDrive contains the drive letter

   460     * @return ETrue if memory card is present and writable.

   461     */

   462     TBool IsMemoryCardWritable( TChar& aDrive );

   463 

   464     /**

   465     * Show playlist creation queries: memory selection and name query.

   466     *

   467     * @since S60 3.2.3

   468     * @param aPath Descriptor to receive the full path and

   469     *              name of the playlist file

   470     */

   471     TBool PlaylistCreationQueriesL( TDes& aPath );

   472 

   473     /**

   474     * Get next available playlist full pathname based on the information passed.

   475     *

   476     * @since S60 3.2.3

   477     * @param aBuf Buffer contains the file path and initial playlist name (optional).

   478     *             This buffer must be big enough to hold all texts.

   479     * @return KErrNone if everything ok.

   480     */

   481     TInt GetNextPlaylistNameL( TDes& aBuf );

   482 

   483     /**

   484     * Finds all medias in the specified category. Matching medias should

   485     * return the specified attributes

   486     *

   487     * @since S60 3.2.3

   488     * @param aAttrs attributes to return for the matching media(s)

   489     * @return matching media(s)

   490     */

   491     CMPXMedia* FindAllL(TMPXGeneralCategory aCategory, const TArray<TMPXAttribute>& aAttrs);

   492 

   493     /**

   494     * From MMPXCHelperObserver

   495     * Handles the completion of any collection helper event.

   496     *

   497     * @since S60 3.2.3

   498     * @param aOperation, operation completed

   499     * @param aErr. the error code

   500     * @param aArgument Argument returned from the operation

   501     */

   502     void HandleOperationCompleteL( TCHelperOperation aOperation,

   503                                    TInt aErr,

   504                                    void* aArgument );

   505 

   506     TBool PlaylistCreateNameExistL( TDes& aName, const TParseBase& aParse );

   507 private:    // Data

   508 

   509     TInt                        iResourceOffset;   // must be freed

   510     CMPXDrmUiHelper*            iMpxDrmHelper; // owned

   511     MMPXCollectionUiHelper*     iCollectionUiHelper;

   512     MMPXCHelperObserver*        iAddObserver;

   513     CAknWaitDialog*             iWaitDialog;

   514     MMPXCollectionUtility*      iCollectionUtility; // not owned

   515     TInt                        iAppUiResourceOffset;

   516 

   517 // Cover UI start

   518 //#ifdef __COVER_DISPLAY

   519     TBool iCoverDisplay;

   520 //#endif

   521 // Cover UI end

   522 

   523     };

   524 

   525 #endif  // C_CMPXCOMMONUIHELPER_H

   526 

   527 // End of File