/*

* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: Qt interface class to Thumbnail Manager

*

*/

#ifndef THUMBNAILMANAGER_QT_H

#define THUMBNAILMANAGER_QT_H

#include <QtGlobal>

class QString;

class QSize;

class ThumbnailManagerPrivate;

class TestThumbnailManager;

#ifdef TNMQT_DLL

#  define TNM_EXPORT Q_DECL_EXPORT

#else

#  define TNM_EXPORT Q_DECL_IMPORT

#endif  

/** default priority value */

const int tnmWrapperPriorityIdle = -100;

class ThumbnailManager : public QObject

    {

    Q_OBJECT

public:

    /** Thumbnail size. */

    enum ThumbnailSize

    {

        /**

         * Small thumbnail

         */

        ThumbnailSmall = 0, 

        /**

         * Medium thumbnail

         */

        ThumbnailMedium, 

        /**

         * Large thumbnail

         */

        ThumbnailLarge

    };

    /** Mode of thumbnail creation. */

    enum ThumbnailMode

        {

        /**

         * Default mode. 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.

         */

        Default = 0, 

        /**

         * Allow thumbnails which are smaller than requested are. Thumbnail

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

         */

        AllowAnySize = 1, 

        /**

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

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

         * not exist null pixmap will be returned.

         */

        DoNotCreate = 2, 

        /**

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

         * this mode is set, the size of the resulting thumbnail always

         * matches the requested size.

         */

        CropToAspectRatio = 4

    };

    /**  Quality versus speed preference setting */

    enum QualityPreference

    {

        /**

         * Prefer thumbnails in the highest quality possible disregarding

         * any negative impact on performance.

         */

        OptimizeForQuality, 

        /**

         * Get thumbnails as fast as possible, even if

         * it means lower quality.

         */

        OptimizeForPerformance

    };

    /**

     * Constructor

     * 

     * @param parentPtr parent

     */    

    TNM_EXPORT ThumbnailManager( QObject* parentPtr = NULL );

    /**

     * Destructor

     */

    TNM_EXPORT ~ThumbnailManager();

    /**

     * Get quality versus performance preference.

     *

     * @return quality versus performance preference

     */

    TNM_EXPORT QualityPreference qualityPreference() const;

    /**

     * Set quality versus performance preference.

     *

     * @param qualityPreference New quality versus performance preference

     *                           value.

     * @return true on success

     */

    TNM_EXPORT bool setQualityPreference( QualityPreference qualityPreference );

    /**

     * Get the current desired size for thumbnail bitmaps.

     *

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

     */

    TNM_EXPORT QSize thumbnailSize() const;

    /**

     * Set desired size for thumbnail bitmaps.

     *

     * @param thumbnailSize New desired thumbnail size.

     * @return true on success

     */

    TNM_EXPORT bool setThumbnailSize( const QSize& thumbnailSize );

    /**

     * Set desired size for thumbnail bitmaps.

     *

     * @param thumbnailSize New desired thumbnail size.

     * @return true on success

     */

    TNM_EXPORT bool setThumbnailSize( ThumbnailSize thumbnailSize );

    /**

     * Get current mode for thumbnail generation.

     *

     * @return Current mode.

     */

    TNM_EXPORT ThumbnailMode mode() const;

    /**

     * Set mode for thumbnail generation.

     *

     * @param mode New flags.

     * @return true on success 

     */

    TNM_EXPORT bool setMode( ThumbnailMode mode );

    /**

     * 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. If thumbnail loadinf fails thumbnailReady signal is emited 

     * with null pixmap and error code.

     *

     * @param fileName      Source object or file

     * @param clientData    Pointer to arbitrary client data.

     *                      This pointer is not used by the API for

     *                      anything other than returning it in the

     *                      ThumbnailReady signal.

     * @param priority      Priority for this operation

     * @return              Thumbnail request ID or -1 if request failed. This can be used to

     *                      cancel the request or change priority.

     *                      The ID is specific to this tnm

     *                      instance and may not be shared with other

     *                      instances.

     */

    TNM_EXPORT int getThumbnail( const QString& fileName, void * clientData = NULL, 

            int priority = tnmWrapperPriorityIdle );

    /**

     * 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. If thumbnail loading fails thumbnailReady signal is emited 

     * with null pixmap and error code.

     *

     * @param thumbnailId   Thumbnail ID

     * @param clientData    Pointer to arbitrary client data.

     *                      This pointer is not used by the API for

     *                      anything other than returning it in the

     *                      ThumbnailReady signal.

     * @param priority      Priority for this operation

     * @return              Thumbnail request ID or -1 if request failed. This can be used to

     *                      cancel the request or change priority.

     *                      The ID is specific to this tnm

     *                      instance and may not be shared with other

     *                      instances.

     */    

    TNM_EXPORT int getThumbnail( unsigned long int thumbnailId, void * clientData = NULL, 

            int priority = tnmWrapperPriorityIdle );

    /**

     * Set a thumbnail for an object file generated from pixmap delivered.

     * thumbnailReady() signal will be emited when the operation is complete. 

     * 

     * @param source             Pixmap from which the thumbnail will be created

     * @param fileName           file name

     * @param clientData         Pointer to arbitrary client data.

     *                           This pointer is not used by the API for

     *                           anything other than returning it in the

     *                           ThumbnailReady callback.

     * @param priority           Priority for this operation

     * @return                   Thumbnail request ID or -1 if request failed. This can be used to

     *                           cancel the request or change priority. 

     *                           

     */    

    TNM_EXPORT int setThumbnail( const QPixmap& source, const QString& fileName,

            void * clientData = NULL, int priority = tnmWrapperPriorityIdle );

    /**

     * Set a thumbnail for an object file generated from pixmap delivered.

     * thumbnailReady() signal will be emited when the operation is complete. 

     * 

     * @param source             QImage from which the thumbnail will be created

     * @param fileName           file name

     * @param clientData         Pointer to arbitrary client data.

     *                           This pointer is not used by the API for

     *                           anything other than returning it in the

     *                           ThumbnailReady callback.

     * @param priority           Priority for this operation

     * @return                   Thumbnail request ID or -1 if request failed. This can be used to

     *                           cancel the request or change priority. 

     *                           

     */    

    TNM_EXPORT int setThumbnail( const QImage& source, const QString& fileName,

            void * clientData = NULL, int priority = tnmWrapperPriorityIdle );

    /**

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

     * operation, which always returns immediately.

     *

     * @param fileName      Source file

     */

    TNM_EXPORT void deleteThumbnails( const QString& fileName );

    /**

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

     * operation, which always returns immediately.

     *

     * @param thumbnailId      thumbnail id

     */

    TNM_EXPORT void deleteThumbnails( unsigned long int thumbnailId );

    /**

     * Cancel a thumbnail operation.

     *

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

     * @return         true if cancelling was successful.

     */

    TNM_EXPORT bool cancelRequest( int id );

    /**

     * Change the priority of a queued thumbnail operation.

     *

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

     *                      priority.

     * @param newPriority  New priority value

     * @return              true if change was successful.

     */

    TNM_EXPORT bool changePriority( int id, int newPriority );

signals:  

    /**

     * Final thumbnail bitmap generation or loading is complete.

     *

     * @param pixmap     An object representing the resulting thumbnail.

     * @param clientData Client data

     * @param id         Request ID for the operation

     * @param errorCode  error code

     */

    TNM_EXPORT void thumbnailReady( QPixmap , void * , int , int );    

    /**

     * Final thumbnail bitmap generation or loading is complete.

     *

     * @param image      An object representing the resulting thumbnail.

     * @param clientData Client data

     * @param id         Request ID for the operation

     * @param errorCode  error code

     */

    TNM_EXPORT void thumbnailReady( QImage , void * , int , int );    

protected:

    void connectNotify(const char *signal);

    void disconnectNotify(const char *signal);

private:

    ThumbnailManagerPrivate* d;

    friend class ThumbnailManagerPrivate;

    friend class TestThumbnailManager;

};

#endif // THUMBNAILMANAGER_QT