interface.h

Go to the documentation of this file.

#ifndef KIPI_INTERFACE_H
#define KIPI_INTERFACE_H

// Qt includes

#include <QtCore/QFlags>
#include <QtCore/QObject>
#include <QtCore/QVariant>
#include <QtCore/QList>

// KDE includes

#include <kurl.h>

// Local includes

#include "libkipi_export.h"

class QPixmap;
class QWidget;
class QAbstractItemModel;

class KFileItem;

namespace KIPI
{

class ImageCollection;
class ImageCollectionSelector;
class ImageInfo;
class ImageInfoShared;
class UploadWidget;

enum Features
{
    CollectionsHaveComments     = 1 << 0,  
    ImagesHasComments           = 1 << 1,  
    ImagesHasTime               = 1 << 2,  
    HostSupportsDateRanges      = 1 << 3,  
    HostAcceptNewImages         = 1 << 4,  
    ImagesHasTitlesWritable     = 1 << 5,  
    CollectionsHaveCategory     = 1 << 6,  
    CollectionsHaveCreationDate = 1 << 7,  
    HostSupportsProgressBar     = 1 << 8,  
    HostSupportsTags            = 1 << 9,  
    HostSupportsRating          = 1 << 10, 
    HostSupportsThumbnails      = 1 << 11, 
    HostSupportsReadWriteLock   = 1 << 12, 
    HostSupportsPickLabel       = 1 << 13, 
    HostSupportsColorLabel      = 1 << 14, 
    HostSupportsItemReservation = 1 << 15  
};

// NOTE: When a new item is add to Features, please don't forget to patch Interface::hasFeature().

enum EditHint
{
    UndefinedEditHint   = 0,
    HintPixelContentChanged = 1 << 0,
    HintMetadataChanged     = 1 << 1,
    HintChangeReflectedByAttributes
                            = 1 << 2,
    HintEditAborted         = 1 << 3,

    HintMetadataOnlyChange  = HintMetadataChanged | HintChangeReflectedByAttributes
};
Q_DECLARE_FLAGS(EditHints, EditHint)

// ---------------------------------------------------------------------------------------------------------------

class LIBKIPI_EXPORT FileReadWriteLock
{
public:

    virtual ~FileReadWriteLock() {}
    virtual void lockForRead() = 0;
    virtual void lockForWrite() = 0;
    virtual bool tryLockForRead() = 0;
    virtual bool tryLockForRead(int timeout) = 0;
    virtual bool tryLockForWrite() = 0;
    virtual bool tryLockForWrite(int timeout) = 0;
    virtual void unlock() = 0;
};

// ---------------------------------------------------------------------------------------------------------------

class LIBKIPI_EXPORT Interface : public QObject
{
    Q_OBJECT

public:

    explicit Interface(QObject* const parent, const char* name=0);
    virtual ~Interface();

    bool hasFeature(Features feature) const;

    virtual ImageCollection currentAlbum() = 0;

    virtual ImageCollection currentSelection() = 0;

    virtual QList<ImageCollection> allAlbums() = 0;

    virtual ImageInfo info(const KUrl&) = 0;

    virtual bool addImage(const KUrl&, QString& err);

    virtual void delImage(const KUrl&);

    virtual void refreshImages(const KUrl::List&);

    virtual void thumbnail(const KUrl& url, int size);

    virtual void thumbnails(const KUrl::List& list, int size);

    virtual QString progressScheduled(const QString& title, bool canBeCanceled, bool hasThumb) const;

    virtual void progressValueChanged(const QString& id, float percent);
    virtual void progressStatusChanged(const QString& id, const QString& status);
    virtual void progressThumbnailChanged(const QString& id, const QPixmap& thumb);
    virtual void progressCompleted(const QString& id);

    virtual QVariant hostSetting(const QString& settingName);

    virtual ImageCollectionSelector* imageCollectionSelector(QWidget* parent)=0;
    virtual UploadWidget*            uploadWidget(QWidget* parent)=0;
    virtual QAbstractItemModel*      getTagTree() const;

    virtual bool reserveForAction(const KUrl& url, QObject* const reservingObject,
                                  const QString& descriptionOfAction) const;
    virtual void clearReservation(const KUrl& url, QObject* const reservingObject);

    virtual bool itemIsReserved(const KUrl& url, QString* const descriptionOfAction = 0) const;

    virtual FileReadWriteLock* createReadWriteLock(const KUrl& url) const;

    virtual void aboutToEdit(const KUrl& url, EditHints hints);
    virtual void editingFinished(const KUrl& url, EditHints hints);

    static QString version();

Q_SIGNALS:

    void selectionChanged(bool hasSelection);

    void currentAlbumChanged(bool hasSelection);

    void gotThumbnail(const KUrl&, const QPixmap&);

    void progressCanceled(const QString& id);

    void reservedForAction(const KUrl& url, const QString& descriptionOfAction);
    void reservationCleared(const KUrl& url);

protected:

    virtual int features() const = 0;

private Q_SLOTS:

    void gotKDEPreview(const KFileItem& item, const QPixmap& pix);
    void failedKDEPreview(const KFileItem&);

private:

    bool hasFeature(const QString& feature) const;

private:

    friend class PluginLoader;
};

// ---------------------------------------------------------------------------------------------------------------

class LIBKIPI_EXPORT FileReadLocker
{
public:

    FileReadLocker(Interface* const iface, const KUrl& url);
    FileReadLocker(ImageInfoShared* const info);
    ~FileReadLocker();

    FileReadWriteLock* fileReadWriteLock() const;
    void unlock();
    void relock();

private:

    FileReadWriteLock* const d;
};

// ---------------------------------------------------------------------------------------------------------------

class LIBKIPI_EXPORT FileWriteLocker
{
public:

    FileWriteLocker(Interface* const iface, const KUrl& url);
    FileWriteLocker(ImageInfoShared* const info);
    ~FileWriteLocker();

    FileReadWriteLock* fileReadWriteLock() const;
    void unlock();
    void relock();

private:

    FileReadWriteLock* const d;
};

// ---------------------------------------------------------------------------------------------------------------

class LIBKIPI_EXPORT EditHintScope
{
public:

    EditHintScope(Interface* const iface, const KUrl& url, EditHints hints);
    ~EditHintScope();

    void changeAborted();

private:

    Interface* const iface;
    KUrl const       url;
    EditHints        hints;
};

}  // namespace KIPI

Q_DECLARE_OPERATORS_FOR_FLAGS(KIPI::EditHints)

#endif /* KIPI_INTERFACE_H */