Collapse all Symbian^3 Application Developer Library

CThumbnailManager Class Reference

class CThumbnailManager : public CBase

Thumbnail engine.

This is the main interface class to thumbnail engine. Thumbnail engine can be used to request thumbnails for different kinds of media objects.

The client using thumbnail engine must implement the MThumbnailManagerObserver . The observer interface is used to provide thumbnail data when it is available.

Typical use of thumbnail engine consists of 4 parts:

creating an engine instance using NewL
setting thumbnail parameters using SetThumbnailSizeL() , SetFlags(), and so on
creating an object source ( CThumbnailObjectSource ) and using it to request thumbnails
handling MThumbnailManagerObserver callbacks when the thumbnail request is complete

Here is an example of how thumbnail engine could be used by a typical application:

        #include <thumbnailmanagerobserver.h>
  #include <thumbnailmanager.h>

  class CMyThumbnailControl: public CCoeControl,
                             public MThumbnailManagerObserver
      {
  public:
      CMyThumbnailControl();
      ~CMyThumbnailControl();
      ...

      // Callbacks from MThumbnailManagerObserver for getting thumbnails
      void ThumbnailPreviewReady(
          MThumbnailData& aThumbnail,
          TThumbnailRequestId aId );
      void ThumbnailReady(
          TInt aError, 
          MThumbnailData& aThumbnail, 
          TThumbnailRequestId aId );

  private:
      void ConstructL();
      CThumbnailManager* iManager;
      CFbsBitmap* iBitmap;
      }

  _LIT( KTestFilePath, "e:\\TestImage.jpg" );
  _LIT( KTestFileType, "image/jpeg" );

  void CMyThumbnailControl::ConstructL()
      {
      // Create Thumbnail Manager instance. This object is the observer.
      iManager = CThumbnailManager::NewL( *this ); 

      // Set flags: If the aspect ratio of the media object does not match
      // 4:3 then we would like it to be cropped. We don t mind getting
      // smaller images than requested.
      iManager->SetFlagsL( CThumbnailManager::ECropToAspectRatio |
                           CThumbnailManager::EAllowAnySize );

      // Preferred size is 160x120 (or less)
      iManager->SetSizeL( TSize( 160, 120 ) );

      // Get a preview thumbnail first, if available.
      // The preview thumbnail is delivered via a ThumbnailPreviewReady()
      // callback.
      iManager->SetQualityPreferenceL(
          CThumbnailManager::EOptimizeForQualityWithPreview );

      // Create an object source representing a path to a file on local
      // file system.
      CThumbnailObjectSource* source = CThumbnailObjectSource::NewLC(
          KTestFilePath,   // File path
          KTestFileType ); // Let Thumbnail Manager know it s a JPEG, so
                           // it doesn t need to recognize the file format

      // Issue the request using default priority
      iManager->GetThumbnailL( *source );

      // If GetThumbnailL() did not leave, the ThumbnailReady() callback is
      // now guaranteed to be called, unless the request is cancelled or
      // CThumbnailManager instance is deleted.

      // The source can be deleted immediately after issuing the request
      CleanupStack::PopAndDestroy( source );
      }

  CMyThumbnailControl::~CMyThumbnailControl()
      {
      // Bitmap should be destroyed before Thumbnail Manager
      delete iBitmap;
      delete iManager;
      }

  void CMyThumbnailControl::ThumbnailReady(
      TInt aError,
      MThumbnailData& aThumbnail,
      TThumbnailRequestId aId )
      {
      // This function must not leave.

      delete iBitmap; iBitmap = NULL;
      if ( !aError )
          {
          // Claim ownership of the bitmap instance for later use
          iBitmap = aThumbnail.DetachBitmap();

          // We can now use iBitmap in our Draw() method
          DrawDeferred();
          }
      else
          {
          // An error occurred while getting the thumbnail.
          // Perhaps we should show a broken image icon to the user.
          }
      }

thumbnailmanager.lib

Since: S60 v5.0

Inherits from

CThumbnailManager
- CBase

Public Member Functions
	~CThumbnailManager ()
TInt	CancelRequest ( TThumbnailRequestId )
TInt	ChangePriority ( TThumbnailRequestId , TInt )
TThumbnailRequestId	CreateThumbnails ( CThumbnailObjectSource &, TInt )
void	DeleteThumbnails ( CThumbnailObjectSource &)
void	DeleteThumbnails (const TThumbnailId )
TDisplayMode	DisplayMode ()
TThumbnailFlags	Flags ()
const CDesCArray &	GetSupportedMimeTypesL ()
TThumbnailRequestId	GetThumbnailL ( CThumbnailObjectSource &, TAny *, TInt )
TThumbnailRequestId	GetThumbnailL (const TThumbnailId , TAny *, TInt )
TThumbnailRequestId	ImportThumbnailL ( CThumbnailObjectSource &, const TDesC &, TAny *, TInt )
IMPORT_C CThumbnailManager *	NewL ( MThumbnailManagerObserver &)
IMPORT_C CThumbnailManager *	NewLC ( MThumbnailManagerObserver &)
TThumbnailQualityPreference	QualityPreference ()
void	RemoveRequestObserver ()
TThumbnailRequestId	RenameThumbnailsL (const TDesC &, const TDesC &, TInt )
void	SetDisplayModeL ( TDisplayMode )
void	SetFlagsL ( TThumbnailFlags )
void	SetQualityPreferenceL ( TThumbnailQualityPreference )
void	SetRequestObserver ( MThumbnailManagerRequestObserver &)
TThumbnailRequestId	SetThumbnailL ( CThumbnailObjectSource &, TAny *, TInt )
void	SetThumbnailSizeL (const TSize &)
void	SetThumbnailSizeL (const TThumbnailSize )
const TSize &	ThumbnailSize ()
void	UpdateThumbnailsL (const TThumbnailId , const TDesC &, const TInt , const TInt64 , const TInt )

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Public Member Enumerations
enum	TThumbnailFlags { EDefaultFlags = 0, EAllowAnySize = 1, EDoNotCreate = 2, ECropToAspectRatio = 4 }
enum	TThumbnailQualityPreference { EOptimizeForQuality , EOptimizeForPerformance , EOptimizeForQualityWithPreview }

Constructor & Destructor Documentation

~CThumbnailManager()

~CThumbnailManager

(

)

[virtual]

Destructor

Since: S60 v5.0

Member Functions Documentation

CancelRequest(TThumbnailRequestId)

TInt

CancelRequest

(

TThumbnailRequestId

aId

)

[pure virtual]

Cancel a thumbnail operation.

Since: S60 v5.0

Parameters

TThumbnailRequestId aId

Request ID for the operation to be cancelled.

ChangePriority(TThumbnailRequestId, TInt)

TInt	ChangePriority	(	TThumbnailRequestId	aId,
			TInt	aNewPriority
		)	[pure virtual]

Change the priority of a queued thumbnail operation.

Since: S60 v5.0

Parameters

TThumbnailRequestId aId	Request ID for the request which to assign a new priority.
TInt aNewPriority	New priority value

CreateThumbnails(CThumbnailObjectSource &, TInt)

TThumbnailRequestId	CreateThumbnails	(	CThumbnailObjectSource &	aObjectSource,
			TInt	aPriority = CActive::EPriorityIdle
		)	[pure virtual]

Create thumbnail for a given object. This is an asynchronous operation, which always returns immediately. No callbacks are emitted.

Since: S60 v5.0

Parameters

CThumbnailObjectSource & aObjectSource	Source object or file
TInt aPriority = CActive::EPriorityIdle	Priority for this operation

DeleteThumbnails(CThumbnailObjectSource &)

void

DeleteThumbnails

(

CThumbnailObjectSource &

aObjectSource

)

[pure virtual]

Delete all thumbnails for a given object. This is an asynchronous operation, which always returns immediately.

Since: S60 v5.0

Parameters

CThumbnailObjectSource & aObjectSource

Source object or file

DeleteThumbnails(const TThumbnailId)

void

DeleteThumbnails

(

const TThumbnailId

aItemId

)

[pure virtual]

Delete thumbnails by TThumbnailId. This is an asynchronous operation, which always returns immediately.

Since: S60 v5.0

Parameters

const TThumbnailId aItemId

TThumbnailId

DisplayMode()

TDisplayMode

DisplayMode

(

)

const [pure virtual]

Get the current display mode for thumbnail bitmaps.

Since: S60 v5.0

Flags()

TThumbnailFlags

Flags

(

)

const [pure virtual]

Get current flags for thumbnail generation.

Since: S60 v5.0

GetSupportedMimeTypesL()

const CDesCArray &

GetSupportedMimeTypesL

(

)

[pure virtual]

Get a list of supported file formats for object files.

The return value is a reference to a list that contains each supported MIME type. There may also be wildcards, such as "image/*".

The returned reference is valid until CThumbnailManager is destroyed or GetSupportedMimeTypesL() is called again.

Since: S60 v5.0

GetThumbnailL(CThumbnailObjectSource &, TAny *, TInt)

TThumbnailRequestId	GetThumbnailL	(	CThumbnailObjectSource &	aObjectSource,
			TAny *	aClientData = NULL,
			TInt	aPriority = CActive::EPriorityStandard
		)	[pure virtual]

Get a thumbnail for an object file. If a thumbnail already exists, it is loaded and if a thumbnail does not exist, it is created transparently. ThumbnailReady() callback will be called when the operation is complete. In addition, ThumbnailPreviewReady() callback may be called if EOptimizeForQualityWithPreview mode was defined.

Current values for display mode, thumbnail size, flags and performance preference are used.

Since: S60 v5.0

Parameters

CThumbnailObjectSource & aObjectSource	Source object or file
TAny * aClientData = NULL	Pointer to arbitrary client data. This pointer is not used by the API for anything other than returning it in the ThumbnailReady callback.
TInt aPriority = CActive::EPriorityStandard	Priority for this operation

GetThumbnailL(const TThumbnailId, TAny *, TInt)

TThumbnailRequestId	GetThumbnailL	(	const TThumbnailId	aThumbnailId,
			TAny *	aClientData = NULL,
			TInt	aPriority = CActive::EPriorityStandard
		)	[pure virtual]

Get a persistent thumbnail for an object file. If a thumbnail already exists, it is loaded and if a thumbnail does not exist, it is created transparently. ThumbnailReady() callback will be called when the operation is complete. In addition, ThumbnailPreviewReady() callback may be called if EOptimizeForQualityWithPreview mode was defined.

Current values for display mode, thumbnail size, flags and performance preference are used.

Since: S60 v5.0

Parameters

const TThumbnailId aThumbnailId	Thumbnail ID
TAny * aClientData = NULL	Pointer to arbitrary client data. This pointer is not used by the API for anything other than returning it in the ThumbnailReady callback.
TInt aPriority = CActive::EPriorityStandard	Priority for this operation

ImportThumbnailL(CThumbnailObjectSource &, const TDesC &, TAny *, TInt)

TThumbnailRequestId	ImportThumbnailL	(	CThumbnailObjectSource &	aObjectSource,
			const TDesC &	aTargetUri,
			TAny *	aClientData = NULL,
			TInt	aPriority = CActive::EPriorityIdle
		)	[pure virtual]

Import an image to be used as thumbnail for an object. If a thumbnail already exists, it is loaded and if a thumbnail does not exist, it is created transparently. ThumbnailReady() callback will be called when the operation is complete. In addition, ThumbnailPreviewReady() callback may be called if EOptimizeForQualityWithPreview mode was defined.

Current values for display mode, thumbnail size, flags and performance preference are used.

Since: S60 v5.0

Parameters

CThumbnailObjectSource & aObjectSource	Source object or file
const TDesC & aTargetUri	Target URI to which the imported thumbnail is linked.
TAny * aClientData = NULL	Pointer to arbitrary client data. This pointer is not used by the API for anything other than returning it in the ThumbnailReady callback.
TInt aPriority = CActive::EPriorityIdle	Priority for this operation

NewL(MThumbnailManagerObserver &)

IMPORT_C CThumbnailManager *

NewL

(

MThumbnailManagerObserver &

aObserver

)

[static]

Two-phased constructor.

Since: S60 v5.0

Parameters

MThumbnailManagerObserver & aObserver

Observer to receive notifications about completed operations.

NewLC(MThumbnailManagerObserver &)

IMPORT_C CThumbnailManager *

NewLC

(

MThumbnailManagerObserver &

aObserver

)

[static]

Two-phased constructor.

Since: S60 v5.0

Parameters

MThumbnailManagerObserver & aObserver

Observer to receive notifications about completed operations.

QualityPreference()

TThumbnailQualityPreference

QualityPreference

(

)

const [pure virtual]

Get the current quality versus performance preference.

Since: S60 v5.0

RemoveRequestObserver()

void

RemoveRequestObserver

(

)

[pure virtual]

Remove optional request observer.

Since: Symbian^3

RenameThumbnailsL(const TDesC &, const TDesC &, TInt)

TThumbnailRequestId	RenameThumbnailsL	(	const TDesC &	aCurrentPath,
			const TDesC &	aNewPath,
			TInt	aPriority = CActive::EPriorityIdle
		)	[pure virtual]

Rename Thumbnails. This is an asynchronous operation, which always returns immediately.

Since: S60 v5.0

Parameters

const TDesC & aCurrentPath	Current path of the Thumbnail
const TDesC & aNewPath	New path for the Thumbnail
TInt aPriority = CActive::EPriorityIdle	Priority for this operation

SetDisplayModeL(TDisplayMode)

void

SetDisplayModeL

(

TDisplayMode

aDisplayMode

)

[pure virtual]

Set the current display mode for thumbnail bitmaps.

Since: S60 v5.0

Parameters

TDisplayMode aDisplayMode

New display mode value for the thumbnail bitmaps.

SetFlagsL(TThumbnailFlags)

void

SetFlagsL

(

TThumbnailFlags

aFlags

)

[pure virtual]

Set flags for thumbnail generation. Several flags may be enabled by combining the values using bitwise or.

Since: S60 v5.0

Parameters

TThumbnailFlags aFlags

New flags.

SetQualityPreferenceL(TThumbnailQualityPreference)

void

SetQualityPreferenceL

(

TThumbnailQualityPreference

aQualityPreference

)

[pure virtual]

Set quality versus performance preference.

Since: S60 v5.0

Parameters

TThumbnailQualityPreference aQualityPreference

New quality versus performance preference value.

SetRequestObserver(MThumbnailManagerRequestObserver &)

void

SetRequestObserver

(

MThumbnailManagerRequestObserver &

aObserver

)

[pure virtual]

Set optional request observer for getting information about completed requests that don't include a thumbnail.

Since: Symbian^3

Parameters

MThumbnailManagerRequestObserver & aObserver

Observer to receive notifications.

SetThumbnailL(CThumbnailObjectSource &, TAny *, TInt)

TThumbnailRequestId	SetThumbnailL	(	CThumbnailObjectSource &	aObjectSource,
			TAny *	= NULL,
			TInt	aPriority = CActive::EPriorityIdle
		)	[pure virtual]

Set a thumbnail for an object file generated from buffer delivered in source object. ThumbnailReady() callback will be called when the operation is complete. In addition, ThumbnailPreviewReady() callback may be called if EOptimizeForQualityWithPreview mode was defined.

Current values for display mode, thumbnail size, flags and performance preference are used.

Since: S60 v5.0

Parameters

CThumbnailObjectSource & aObjectSource
TAny * = NULL
TInt aPriority = CActive::EPriorityIdle	Priority for this operation

SetThumbnailSizeL(const TSize &)

void

SetThumbnailSizeL

(

const TSize &

aThumbnailSize

)

[pure virtual]

Set desired size for thumbnail bitmaps.

Since: S60 v5.0

Parameters

const TSize & aThumbnailSize

New quality for the desired thumbnail size.

SetThumbnailSizeL(const TThumbnailSize)

void

SetThumbnailSizeL

(

const TThumbnailSize

aThumbnailSize

)

[pure virtual]

Set desired size for thumbnail bitmaps.

Since: S60 v5.0

Parameters

const TThumbnailSize aThumbnailSize

Desired thumbnail size.

ThumbnailSize()

const TSize &

ThumbnailSize

(

)

const [pure virtual]

Get the current desired size for thumbnail bitmaps.

Since: S60 v5.0

UpdateThumbnailsL(const TThumbnailId, const TDesC &, const TInt, const TInt64, const TInt)

void	UpdateThumbnailsL	(	const TThumbnailId	aItemId,
			const TDesC &	aPath,
			const TInt	aOrientation,
			const TInt64	aModified,
			const TInt	aPriority
		)	[pure virtual]

Update Thumbnails by TThumbnailId. This is an asynchronous operation, which always returns immediately.

Since: S60 v5.0

Parameters

const TThumbnailId aItemId	TThumbnailId
const TDesC & aPath	(New) path for the Thumbnail
const TInt aOrientation	Thumbnail orientation
const TInt64 aModified	Last modified
const TInt aPriority

Member Enumerations Documentation

Enum TThumbnailFlags

Flags for thumbnail creation. These can be combined using bitwise or.

Enumerators

EDefaultFlags = 0	Default flags. This means that: Thumbnail must be as large as requested (unless the actual object is smaller). Smaller thumbnails may be up scaled to desired resolution. Aspect ratio is maintained and thumbnails are not cropped. The resulting thumbnail may smaller in either width or height if the aspect ratio of the object does not match the aspect ratio of the requested size.
EAllowAnySize = 1	Allow thumbnails which are smaller than requested are. Thumbnail bitmaps are never up scaled if this flag is set.
EDoNotCreate = 2	New thumbnail images are not created if this flag is set. Only existing thumbnails may be returned. If a requested thumbnail does not exist, KErrNotFound error is returned in ThumbnailReady() callback.
ECropToAspectRatio = 4	Thumbnail images are cropped to match requested aspect ratio. If this flag is set, the size of the resulting thumbnail always matches the requested size.

Enum TThumbnailQualityPreference

Quality versus speed preference setting

Enumerators

EOptimizeForQuality	Prefer thumbnails in the highest quality possible disregarding any negative impact on performance.
EOptimizeForPerformance	Get thumbnails as fast as possible, even if it means lower quality.
EOptimizeForQualityWithPreview	Get lower quality preview thumbnail as fast as possible first and then a higher quality thumbnail later. The preview thumbnail is provided in the ThumbnailPreviewReady() callback and the high quality thumbnail in ThumbnailReady(). ThumbnailPreviewReady() is not get called at all if a suitable existing thumbnail is not found or if a high quality version is already available.