1 /*

     2 * Copyright (c) 2006-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:  Main interface class to Thumbnail Manager

    15  *

    16 */

    17 

    18 

    19 #ifndef THUMBNAILMANAGER_H

    20 #define THUMBNAILMANAGER_H

    21 

    22 #include <e32base.h>

    23 #include <gdi.h>

    24 #include <badesca.h>

    25 

    26 #include <thumbnailobjectsource.h>

    27 

    28 class MThumbnailManagerObserver;

    29 

    30 typedef TInt TThumbnailRequestId;

    31 

    32 typedef TUint32 TThumbnailId;

    33 typedef enum 

    34 {

    35 EUnknownThumbnailSize,

    36 ECustomThumbnailSize,

    37 EImageGridThumbnailSize,

    38 EImageListThumbnailSize,

    39 EImageFullScreenThumbnailSize,

    40 EVideoGridThumbnailSize,

    41 EVideoListThumbnailSize,

    42 EVideoFullScreenThumbnailSize,      

    43 EAudioGridThumbnailSize,

    44 EAudioListThumbnailSize,

    45 EAudioFullScreenThumbnailSize,

    46 EGridThumbnailSize,

    47 EListThumbnailSize,

    48 EFullScreenThumbnailSize

    49 } TThumbnailSize;

    50 /**

    51  *  Thumbnail engine.

    52  *

    53  *  This is the main interface class to thumbnail engine. Thumbnail engine

    54  *  can be used to request thumbnails for different kinds of media objects.

    55  *

    56  *  The client using thumbnail engine must implement the

    57  *  MThumbnailManagerObserver. The observer interface is used to provide

    58  *  thumbnail data when it is available.

    59  *

    60  *  Typical use of thumbnail engine consists of 4 parts:

    61  *  - creating an engine instance using NewL

    62  *  - setting thumbnail parameters using SetThumbnailSizeL(), SetFlags(),

    63  *    and so on

    64  *  - creating an object source (CThumbnailObjectSource) and using it to

    65  *    request thumbnails

    66  *  - handling MThumbnailManagerObserver callbacks when the thumbnail request

    67  *    is complete

    68  *

    69  *  Here is an example of how thumbnail engine could be used by a typical

    70  *  application:

    71  *

    72  *  @code

    73  *

    74  *  #include <thumbnailmanagerobserver.h>

    75  *  #include <thumbnailmanager.h>

    76  *

    77  *  class CMyThumbnailControl: public CCoeControl,

    78  *                             public MThumbnailManagerObserver

    79  *      {

    80  *  public:

    81  *      CMyThumbnailControl();

    82  *      ~CMyThumbnailControl();

    83  *      ...

    84  *

    85  *      // Callbacks from MThumbnailManagerObserver for getting thumbnails

    86  *      void ThumbnailPreviewReady(

    87  *          MThumbnailData& aThumbnail,

    88  *          TThumbnailRequestId aId );

    89  *      void ThumbnailReady(

    90  *          TInt aError, 

    91  *          MThumbnailData& aThumbnail, 

    92  *          TThumbnailRequestId aId );

    93  *

    94  *  private:

    95  *      void ConstructL();

    96  *      CThumbnailManager* iManager;

    97  *      CFbsBitmap* iBitmap;

    98  *      }

    99  *

   100  *  _LIT( KTestFilePath, "e:\\TestImage.jpg" );

   101  *  _LIT( KTestFileType, "image/jpeg" );

   102  *

   103  *  void CMyThumbnailControl::ConstructL()

   104  *      {

   105  *      // Create Thumbnail Manager instance. This object is the observer.

   106  *      iManager = CThumbnailManager::NewL( *this ); 

   107  *

   108  *      // Set flags: If the aspect ratio of the media object does not match

   109  *      // 4:3 then we would like it to be cropped. We don’t mind getting

   110  *      // smaller images than requested.

   111  *      iManager->SetFlagsL( CThumbnailManager::ECropToAspectRatio |

   112  *                           CThumbnailManager::EAllowAnySize );

   113  *

   114  *      // Preferred size is 160x120 (or less)

   115  *      iManager->SetSizeL( TSize( 160, 120 ) );

   116  *

   117  *      // Get a preview thumbnail first, if available.

   118  *      // The preview thumbnail is delivered via a ThumbnailPreviewReady()

   119  *      // callback.

   120  *      iManager->SetQualityPreferenceL(

   121  *          CThumbnailManager::EOptimizeForQualityWithPreview );

   122  *

   123  *      // Create an object source representing a path to a file on local

   124  *      // file system.

   125  *      CThumbnailObjectSource* source = CThumbnailObjectSource::NewLC(

   126  *          KTestFilePath,   // File path

   127  *          KTestFileType ); // Let Thumbnail Manager know it’s a JPEG, so

   128  *                           // it doesn’t need to recognize the file format

   129  *

   130  *      // Issue the request using default priority

   131  *      iManager->GetThumbnailL( *source );

   132  *

   133  *      // If GetThumbnailL() did not leave, the ThumbnailReady() callback is

   134  *      // now guaranteed to be called, unless the request is cancelled or

   135  *      // CThumbnailManager instance is deleted.

   136  *

   137  *      // The source can be deleted immediately after issuing the request

   138  *      CleanupStack::PopAndDestroy( source );

   139  *      }

   140  *

   141  *  CMyThumbnailControl::~CMyThumbnailControl()

   142  *      {

   143  *      // Bitmap should be destroyed before Thumbnail Manager

   144  *      delete iBitmap;

   145  *      delete iManager;

   146  *      }

   147  *

   148  *  void CMyThumbnailControl::ThumbnailReady(

   149  *      TInt aError,

   150  *      MThumbnailData& aThumbnail,

   151  *      TThumbnailRequestId aId )

   152  *      {

   153  *      // This function must not leave.

   154  *

   155  *      delete iBitmap; iBitmap = NULL;

   156  *      if ( !aError )

   157  *          {

   158  *          // Claim ownership of the bitmap instance for later use

   159  *          iBitmap = aThumbnail.DetachBitmap();

   160  *

   161  *          // We can now use iBitmap in our Draw() method

   162  *          DrawDeferred();

   163  *          }

   164  *      else

   165  *          {

   166  *          // An error occurred while getting the thumbnail.

   167  *          // Perhaps we should show a broken image icon to the user.

   168  *          }

   169  *      }

   170  *

   171  *  @endcode

   172  *

   173  *  @lib thumbnailmanager.lib

   174  *  @since S60 v5.0

   175  */

   176 NONSHARABLE_CLASS( CThumbnailManager ): public CBase

   177     {

   178 public:

   179     /**

   180      * Flags for thumbnail creation.

   181      * These can be combined using bitwise or.

   182      */

   183     enum TThumbnailFlags

   184         {

   185         /**

   186          * Default flags. This means that:

   187          * - Thumbnail must be as large as requested (unless the actual

   188          *   object is smaller).

   189          * - Smaller thumbnails may be up scaled to desired resolution.

   190          * - Aspect ratio is maintained and thumbnails are not cropped. The

   191          *   resulting thumbnail may smaller in either width or height if

   192          *   the aspect ratio of the object does not match the aspect ratio

   193          *   of the requested size.

   194          */

   195         EDefaultFlags = 0, 

   196 

   197         /**

   198          * Allow thumbnails which are smaller than requested are. Thumbnail

   199          * bitmaps are never up scaled if this flag is set.

   200          */

   201         EAllowAnySize = 1, 

   202 

   203         /**

   204          * New thumbnail images are not created if this flag is set. Only

   205          * existing thumbnails may be returned. If a requested thumbnail does

   206          * not exist, KErrNotFound error is returned in ThumbnailReady()

   207          * callback.

   208          */

   209         EDoNotCreate = 2, 

   210 

   211         /**

   212          * Thumbnail images are cropped to match requested aspect ratio. If

   213          * this flag is set, the size of the resulting thumbnail always

   214          * matches the requested size.

   215          */

   216         ECropToAspectRatio = 4

   217     };

   218 

   219     /**  Quality versus speed preference setting */

   220     enum TThumbnailQualityPreference

   221         {

   222         /**

   223          * Prefer thumbnails in the highest quality possible disregarding

   224          * any negative impact on performance.

   225          */

   226         EOptimizeForQuality, 

   227 

   228         /**

   229          * Get thumbnails as fast as possible, even if

   230          * it means lower quality.

   231          */

   232         EOptimizeForPerformance, 

   233 

   234         /**

   235          * Get lower quality preview thumbnail as fast as possible first and

   236          * then a higher quality thumbnail later. The preview thumbnail is

   237          * provided in the ThumbnailPreviewReady() callback and the high

   238          * quality thumbnail in ThumbnailReady(). ThumbnailPreviewReady()

   239          * is not get called at all if a suitable existing thumbnail is not

   240          * found or if a high quality version is already available.

   241          */

   242         EOptimizeForQualityWithPreview

   243         };

   244 

   245     /**

   246      * Two-phased constructor.

   247      *

   248      * @since S60 v5.0

   249      * @param  aObserver Observer to receive notifications about completed

   250      *                   operations.

   251      * @return           New CThumbnailManager instance.

   252      */

   253     IMPORT_C static CThumbnailManager* NewL( MThumbnailManagerObserver&

   254         aObserver );

   255 

   256     /**

   257      * Two-phased constructor.

   258      *

   259      * @since S60 v5.0

   260      * @param  aObserver Observer to receive notifications about completed

   261      *                   operations.

   262      * @return           New CThumbnailManager instance (on cleanup stack).

   263      */

   264     IMPORT_C static CThumbnailManager* NewLC( MThumbnailManagerObserver&

   265         aObserver );

   266 

   267     /**

   268      * Destructor

   269      *

   270      * @since S60 v5.0

   271      */

   272     virtual ~CThumbnailManager();

   273 

   274     /**

   275      * Get the current display mode for thumbnail bitmaps.

   276      *

   277      * @since S60 v5.0

   278      * @return Current display mode for the thumbnail bitmaps.

   279      */

   280     virtual TDisplayMode DisplayMode()const = 0;

   281 

   282     /**

   283      * Set the current display mode for thumbnail bitmaps.

   284      *

   285      * @since S60 v5.0

   286      * @param aDisplayMode New display mode value for the thumbnail bitmaps.

   287      */

   288     virtual void SetDisplayModeL( TDisplayMode aDisplayMode ) = 0;

   289 

   290     /**

   291      * Get the current quality versus performance preference.

   292      *

   293      * @since S60 v5.0

   294      * @return Current quality versus performance preference.

   295      */

   296     virtual TThumbnailQualityPreference QualityPreference()const = 0;

   297 

   298     /**

   299      * Set quality versus performance preference.

   300      *

   301      * @since S60 v5.0

   302      * @param aQualityPreference New quality versus performance preference

   303      *                           value.

   304      */

   305     virtual void SetQualityPreferenceL( TThumbnailQualityPreference

   306         aQualityPreference ) = 0;

   307 

   308     /**

   309      * Get the current desired size for thumbnail bitmaps.

   310      *

   311      * @since S60 v5.0

   312      * @return Current desired size for thumbnail bitmaps (in pixels).

   313      */

   314     virtual const TSize& ThumbnailSize()const = 0;

   315 

   316     /**

   317      * Set desired size for thumbnail bitmaps.

   318      *

   319      * @since S60 v5.0

   320      * @param aThumbnailSize New quality for the desired thumbnail size.

   321      */

   322     virtual void SetThumbnailSizeL( const TSize& aThumbnailSize ) = 0;

   323 

   324     

   325     /**

   326      * Get current flags for thumbnail generation.

   327      *

   328      * @since S60 v5.0

   329      * @return Current flags.

   330      */

   331     virtual TThumbnailFlags Flags()const = 0;

   332 

   333     /**

   334      * Set flags for thumbnail generation. Several flags may be enabled

   335      * by combining the values using bitwise or.

   336      *

   337      * @since S60 v5.0

   338      * @param aFlags New flags.

   339      */

   340     virtual void SetFlagsL( TThumbnailFlags aFlags ) = 0;

   341 

   342     /**

   343      * Get a thumbnail for an object file. If a thumbnail already exists, it

   344      * is loaded and if a thumbnail does not exist, it is created

   345      * transparently. ThumbnailReady() callback will be called when the

   346      * operation is complete. In addition, ThumbnailPreviewReady()

   347      * callback may be called if EOptimizeForQualityWithPreview mode was

   348      * defined.

   349      *

   350      * Current values for display mode, thumbnail size, flags and performance

   351      * preference are used.

   352      *

   353      * @since S60 v5.0

   354      * @param aObjectSource      Source object or file

   355      * @param aClientData        Pointer to arbitrary client data.

   356      *                           This pointer is not used by the API for

   357      *                           anything other than returning it in the

   358      *                           ThumbnailReady callback.

   359      * @param aPriority          Priority for this operation

   360      * @return                   Thumbnail request ID. This can be used to

   361      *                           cancel the request or change priority.

   362      *                           The ID is specific to this CThumbnailManager

   363      *                           instance and may not be shared with other

   364      *                           instances.

   365      */

   366     virtual TThumbnailRequestId GetThumbnailL( CThumbnailObjectSource&

   367         aObjectSource, TAny* aClientData = NULL, TInt aPriority = CActive

   368         ::EPriorityStandard ) = 0;

   369 

   370     /**

   371      * Delete all thumbnails for a given object. This is an asynchronous

   372      * operation, which always returns immediately.

   373      *

   374      * @since S60 v5.0

   375      * @param aObjectSource      Source object or file

   376      */

   377     virtual void DeleteThumbnails( CThumbnailObjectSource& aObjectSource ) = 0;

   378 

   379     /**

   380      * Create thumbnail for a given object. This is an asynchronous

   381      * operation, which always returns immediately. No callbacks are

   382      * emitted.

   383      *

   384      * @since S60 v5.0

   385      * @param aObjectSource      Source object or file

   386      * @param aPriority          Priority for this operation

   387      * @return                   Thumbnail request ID. This can be used to

   388      *                           cancel the request or change priority.

   389      *                           The ID is specific to this CThumbnailManager

   390      *                           instance and may not be shared with other

   391      *                           instances.

   392      */

   393     virtual TThumbnailRequestId CreateThumbnails( CThumbnailObjectSource&

   394         aObjectSource, TInt aPriority = CActive::EPriorityIdle ) = 0;

   395 

   396     /**

   397      * Cancel a thumbnail operation.

   398      *

   399      * @since S60 v5.0

   400      * @param aId      Request ID for the operation to be cancelled.

   401      * @return         Symbian OS error code or KErrNone if cancelling was

   402      *                 successful.

   403      */

   404     virtual TInt CancelRequest( TThumbnailRequestId aId ) = 0;

   405 

   406     /**

   407      * Change the priority of a queued thumbnail operation.

   408      *

   409      * @since S60 v5.0

   410      * @param aId           Request ID for the request which to assign a new

   411      *                      priority.

   412      * @param aNewPriority  New priority value

   413      * @return              Symbian OS error code or KErrNone if change was

   414      *                      successful.

   415      */

   416     virtual TInt ChangePriority( TThumbnailRequestId aId, TInt aNewPriority ) =

   417         0;

   418 

   419     /**

   420      * Get a list of supported file formats for object files.

   421      * 

   422      * The return value is a reference to a list that contains each

   423      * supported MIME type. There may also be wildcards, such as "image/*".

   424      * 

   425      * The returned reference is valid until CThumbnailManager is

   426      * destroyed or GetSupportedMimeTypesL() is called again.

   427      *

   428      * @since S60 v5.0

   429      * @return A list of supported MIME types. May contain wildcards.

   430      *         Ownership not transferred.

   431      */

   432     virtual const CDesCArray& GetSupportedMimeTypesL() = 0;

   433 

   434     /**

   435      * Delete thumbnails by TThumbnailId. This is an asynchronous

   436      * operation, which always returns immediately.

   437      *

   438      * @since S60 v5.0

   439      * @param aItemId     TThumbnailId

   440      */

   441     virtual void DeleteThumbnails( const TThumbnailId aItemId ) = 0;    

   442 

   443 /**

   444      * Set desired size for thumbnail bitmaps.

   445      *

   446      * @since S60 v5.0

   447      * @param aThumbnailSize Desired thumbnail size.

   448      */    

   449     virtual void SetThumbnailSizeL( const TThumbnailSize aThumbnailSize ) = 0;

   450 

   451     /**

   452      * Get a persistent thumbnail for an object file. If a thumbnail already

   453      *  exists, it is loaded and if a thumbnail does not exist, it is created

   454      * transparently. ThumbnailReady() callback will be called when the

   455      * operation is complete. In addition, ThumbnailPreviewReady()

   456      * callback may be called if EOptimizeForQualityWithPreview mode was

   457      * defined.

   458      *

   459      * Current values for display mode, thumbnail size, flags and performance

   460      * preference are used.

   461      *

   462      * @since S60 v5.0

   463      * @param aThumbnailId       Thumbnail ID

   464      * @param aThumbnailSizeType Thumbnail size enumeration

   465      * @param aClientData        Pointer to arbitrary client data.

   466      *                           This pointer is not used by the API for

   467      *                           anything other than returning it in the

   468      *                           ThumbnailReady callback.

   469      * @param aPriority          Priority for this operation

   470      * @return                   Thumbnail request ID. This can be used to

   471      *                           cancel the request or change priority.

   472      *                           The ID is specific to this CThumbnailManager

   473      *                           instance and may not be shared with other

   474      *                           instances.

   475      */    

   476     virtual TThumbnailRequestId GetThumbnailL( const TThumbnailId aThumbnailId,

   477         TAny* aClientData = NULL, 

   478         TInt aPriority = CActive::EPriorityStandard ) = 0;

   479     

   480     

   481     /**

   482      * Set a thumbnail for an object file generated from buffer delivered in source 

   483      * object. ThumbnailReady() callback will be called when the

   484      * operation is complete. In addition, ThumbnailPreviewReady()

   485      * callback may be called if EOptimizeForQualityWithPreview mode was

   486      * defined.

   487      *

   488      * Current values for display mode, thumbnail size, flags and performance

   489      * preference are used.

   490      *

   491      * @since S60 v5.0

   492      * @param aThumbnailId       Thumbnail ID

   493      * @param aThumbnailSizeType Thumbnail size enumeration

   494      * @param aClientData        Pointer to arbitrary client data.

   495      *                           This pointer is not used by the API for

   496      *                           anything other than returning it in the

   497      *                           ThumbnailReady callback.

   498      * @param aPriority          Priority for this operation

   499      * @return                   Thumbnail request ID. This can be used to

   500      *                           cancel the request or change priority.

   501      *                           The ID is specific to this CThumbnailManager

   502      *                           instance and may not be shared with other

   503      *                           instances.

   504      */    

   505     virtual TThumbnailRequestId SetThumbnailL( CThumbnailObjectSource& aObjectSource,

   506         TAny* = NULL, 

   507         TInt aPriority = CActive::EPriorityIdle ) = 0;

   508     

   509     

   510     /**

   511      * Import an image to be used as thumbnail for an object. If a

   512      * thumbnail already exists, it is loaded and if a thumbnail does not

   513      * exist, it is created transparently. ThumbnailReady() callback will be

   514      * called when the operation is complete. In addition, ThumbnailPreviewReady()

   515      * callback may be called if EOptimizeForQualityWithPreview mode was

   516      * defined.

   517      * 

   518      * Current values for display mode, thumbnail size, flags and performance

   519      * preference are used.

   520      *

   521      * @since S60 v5.0

   522      * @param aObjectSource      Source object or file

   523      * @param aTargetUri         Target URI to which the imported thumbnail is linked.

   524      * @param aClientData        Pointer to arbitrary client data.

   525      *                           This pointer is not used by the API for

   526      *                           anything other than returning it in the

   527      *                           ThumbnailReady callback.

   528      * @param aPriority          Priority for this operation

   529      * @return                   Thumbnail request ID. This can be used to

   530      *                           cancel the request or change priority.

   531      *                           The ID is specific to this CThumbnailManager

   532      *                           instance and may not be shared with other

   533      *                           instances.

   534      */

   535      virtual TThumbnailRequestId ImportThumbnailL( CThumbnailObjectSource& aObjectSource,

   536         const TDesC& aTargetUri, TAny* aClientData = NULL,

   537         TInt aPriority = CActive::EPriorityIdle ) = 0;

   538 

   539      /**

   540       * Update Thumbnails by TThumbnailId. This is an asynchronous

   541       * operation, which always returns immediately.

   542       *

   543       * @since S60 v5.0

   544       * @param aItemId       TThumbnailId

   545       * @param aPath         (New) path for the Thumbnail

   546       * @param aOrientation  Thumbnail orientation

   547       * @param aModified     Last modified

   548       */

   549       virtual void UpdateThumbnailsL( const TThumbnailId aItemId, const TDesC& aPath,

   550                                       const TInt aOrientation, const TInt64 aModified, const TInt aPriority  ) = 0;

   551 

   552 };

   553 

   554 #endif // THUMBNAILMANAGER_H