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:  Thumbnail Manager observer.

    15  *

    16 */

    17 

    18 

    19 #ifndef THUMBNAILMANAGEROBSERVER_H

    20 #define THUMBNAILMANAGEROBSERVER_H

    21 

    22 #include "thumbnailobjectsource.h"

    23 

    24 class MThumbnailData;

    25 

    26 /**

    27  *  Thumbnail observer.

    28  *

    29  *  Callback interface for getting information about completed thumbnail

    30  *  operations. This should be implemented by the client using the API.

    31  *

    32  *  Example of how the client may implement the ThumbnailReady()

    33  *  method:

    34  *  @code

    35  *  void CMyThumbnailControl::ThumbnailReady(

    36  *      TInt aError,

    37  *      MThumbnailData& aThumbnail,

    38  *      TThumbnailRequestId aId )

    39  *      {

    40  *      // This function must not leave.

    41  *      delete iBitmap;

    42  *      iBitmap = NULL;

    43  *

    44  *      if ( !aError )

    45  *          {

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

    47  *          iBitmap = aThumbnail.DetachBitmap();

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

    49  *          DrawDeferred();

    50  *          }

    51  *      else

    52  *          {

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

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

    55  *          }

    56  *      }

    57  *  @endcode

    58  *  @since S60 v5.0

    59  */

    60 class MThumbnailManagerObserver

    61     {

    62 public:

    63 

    64     /**

    65      * Preview thumbnail generation or loading is complete.

    66      *

    67      * This callback is not called unless EOptimizeForQualityWithPreview flag

    68      * was specified.

    69      *

    70      * This callback is not called if any of the following is true:

    71      * - an error occurred while processing the preview thumbnail

    72      * - a suitable existing thumbnail was not found

    73      * - a high quality thumbnail is already available

    74      *

    75      * The MThumbnailData instance is only valid for the duration of

    76      * this call. It may not be stored for later use. If the client should

    77      * want to use the bitmap data later, it can claim ownership of the

    78      * CFbsBitmap object by calling DetachBitmap().

    79      *

    80      * @since S60 v5.0

    81      * @param aThumbnail     An object representing the resulting thumbnail.

    82      * @param aId            Request ID for the operation

    83      */

    84     virtual void ThumbnailPreviewReady( MThumbnailData& aThumbnail,

    85         TThumbnailRequestId aId ) = 0;

    86 

    87     /**

    88      * Final thumbnail bitmap generation or loading is complete.

    89      *

    90      * The MThumbnailData instance is only valid for the duration of

    91      * this call. It may not be stored for later use. If the client should

    92      * want to use the bitmap data later, it can claim ownership of the

    93      * CFbsBitmap object by calling DetachBitmap().

    94      *

    95      * @since S60 v5.0

    96      * @param aError         Error code.

    97      * @param aThumbnail     An object representing the resulting thumbnail.

    98      * @param aId            Request ID for the operation.

    99      */

   100     virtual void ThumbnailReady( TInt aError, MThumbnailData& aThumbnail,

   101         TThumbnailRequestId aId ) = 0;

   102 };

   103 

   104 /**  Thumbnail request types */

   105 enum TThumbnailRequestType

   106     {

   107     ERequestDeleteThumbnails = 0

   108     };

   109 

   110 /**

   111  *  Optional callback interface for getting information about other completed 

   112  *  requests that don't include a thumbnail. 

   113  *  

   114  *  Request types:

   115  *  - ERequestDeleteThumbnails

   116  *  

   117  *  Can be added using SetRequestObserver(MThumbnailManagerRequestObserver& aObserver)

   118  *  and removed using RemoveRequestObserver().

   119  *

   120  *  @since Symbian^3

   121  */

   122 class MThumbnailManagerRequestObserver

   123     {

   124 public:

   125     /**

   126      * A request is complete.

   127      *

   128      * @since Symbian^3

   129      * @param aError         Error code.

   130      * @param aRequestType   Type of the completed request.

   131      * @param aId            Request ID for the operation.

   132      */

   133     virtual void ThumbnailRequestReady( TInt aError, TThumbnailRequestType aRequestType,

   134         TThumbnailRequestId aId ) = 0;

   135 };

   136 

   137 #endif // THUMBNAILMANAGEROBSERVER_H