tdefilemetainfo.h

/*
 *  This file is part of the KDE libraries
 *  Copyright (C) 2001-2002 Rolf Magnus <ramagnus@kde.org>
 *  Copyright (C) 2001-2002 Carsten Pfeiffer <pfeiffer@kde.org>
 *
 *  This library is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Library General Public
 *  License as published by the Free Software Foundation version 2.0.
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Library General Public License for more details.
 *
 *  You should have received a copy of the GNU Library General Public License
 *  along with this library; see the file COPYING.LIB.  If not, write to
 *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 *  Boston, MA 02110-1301, USA.
 */
#ifndef TDEFILEMETAINFO_H
#define TDEFILEMETAINFO_H
 
#include <tqdict.h>
#include <tqvariant.h>
#include <tqobject.h>
#include <tqstring.h>
#include <kurl.h>
 
class TQValidator;
class KFilePlugin;
class KFileMetaInfoGroup;
 
class TDEIO_EXPORT KFileMimeTypeInfo
{
    // the plugin needs to be a friend because it puts the data into the object,
    // and it should be the only one allowed to do this.
    friend class KFilePlugin;
    friend class KFileMetaInfoProvider;
 
public:
    KFileMimeTypeInfo() {}
 
    enum Attributes
    {
        Addable     =  1, 
        Removable   =  2, 
        Modifiable  =  4, 
        Cumulative =  8,  
        Cummulative = Cumulative, 
        Averaged    = 16, 
        MultiLine   = 32, 
        SqueezeText = 64  
    };
 
    enum Hint {
        NoHint      = 0, 
        Name        = 1, 
        Author      = 2, 
        Description = 3, 
        Width       = 4, 
        Height      = 5, 
        Size        = 6, 
        Bitrate     = 7, 
        Length      = 8, 
        Hidden      = 9, 
        Thumbnail   = 10 
 
    };
 
    enum Unit {
        NoUnit          = 0,  
        Seconds         = 1,  
        MilliSeconds    = 2,  
        BitsPerSecond   = 3,  
        Pixels          = 4,  
        Inches          = 5,  
        Centimeters     = 6,  
        Bytes           = 7,  
        FramesPerSecond = 8,  
        DotsPerInch     = 9,  
        BitsPerPixel    = 10, 
        Hertz           = 11, 
        KiloBytes       = 12, 
        Millimeters     = 13  
    };
 
 
    class ItemInfo;
 
    class TDEIO_EXPORT GroupInfo
    {
 
    friend class KFilePlugin;
    friend class KFileMimeTypeInfo;
    public:
        TQStringList supportedKeys() const
        {
            return m_supportedKeys;
        }
 
        const TQString& name() const
        {
            return m_name;
        }
 
        const TQString& translatedName() const
        {
            return m_translatedName;
        }
 
        const ItemInfo * itemInfo( const TQString& key ) const;
 
        uint attributes() const
        {
            return m_attr;
        }
 
        bool supportsVariableKeys() const
        {
            return m_variableItemInfo;
        }
 
        const ItemInfo* variableItemInfo( ) const
        {
            return m_variableItemInfo;
        }
 
        ~GroupInfo();
    private:
        GroupInfo( const TQString& name, const TQString& translatedName);
 
        KFileMimeTypeInfo::ItemInfo* addItemInfo( const TQString& key,
                                                  const TQString& translatedKey,
                                                  TQVariant::Type type);
 
        void addVariableInfo( TQVariant::Type type, uint attr );
 
        TQString         m_name;
        TQString         m_translatedName;
        TQStringList     m_supportedKeys;
        uint            m_attr;
        ItemInfo*       m_variableItemInfo;
        TQDict<ItemInfo> m_itemDict;
 
    };
 
    class TDEIO_EXPORT ItemInfo
    {
    friend class KFilePlugin;
    friend class GroupInfo;
    public:
        ItemInfo() {}     // ### should be private?
 
        const TQString& prefix() const
        {
            return m_prefix;
        }
 
        const TQString& suffix() const
        {
            return m_suffix;
        }
 
        TQVariant::Type type() const
        {
            return m_type;
        }
 
        const TQString& key() const
        {
            return m_key;
        }
 
        TQString string( const TQVariant& value, bool mangle = true ) const;
 
        bool isVariableItem() const
        {
            // every valid item is supposed to have a non-null key
            return key().isNull();
        }
 
        const TQString& translatedKey() const
        {
            return m_translatedKey;
        }
 
        uint attributes() const
        {
            return m_attr;
        }
 
        uint hint() const
        {
            return m_hint;
        }
 
        uint unit() const
        {
            return m_unit;
        }
 
    private:
        ItemInfo(const TQString& key, const TQString& translatedKey,
                 TQVariant::Type type)
            : m_key(key), m_translatedKey(translatedKey),
              m_type(type),
              m_attr(0), m_unit(NoUnit), m_hint(NoHint),
              m_prefix(TQString::null), m_suffix(TQString::null)
        {}
 
        TQString           m_key;
        TQString           m_translatedKey;
        TQVariant::Type    m_type;
        uint              m_attr;
        uint              m_unit;
        uint              m_hint;
        TQString           m_prefix;
        TQString           m_suffix;
    };
 
    // ### could it be made private? Would this be BC?
    ~KFileMimeTypeInfo();
 
    TQValidator * createValidator(const TQString& group, const TQString& key,
                                 TQObject *parent = 0, const char *name = 0) const;
 
    TQStringList supportedGroups() const;
 
    TQStringList translatedGroups() const;
 
    TQStringList preferredGroups() const
    {
        return m_preferredGroups;
    }
 
    TQString mimeType()  const {return m_mimeType;}
 
    const GroupInfo * groupInfo( const TQString& group ) const;
 
    // always returning stringlists which the user has to iterate and use them
    // to look up the real items sounds strange to me. I think we should add
    // our own iterators some time (somewhere in the future ;)
 
    TQStringList supportedKeys() const;
 
    TQStringList preferredKeys() const
    {
        return m_preferredKeys;
    }
 
    // ### shouldn't this be private? BC?
    GroupInfo * addGroupInfo( const TQString& name,
                              const TQString& translatedName);
 
    TQString         m_translatedName;
    TQStringList     m_supportedKeys;
    uint            m_attr;
    //        bool            m_supportsVariableKeys : 1;
    TQDict<ItemInfo> m_itemDict;
 
// ### this should be made private instead, but this would be BIC
protected:
    KFileMimeTypeInfo( const TQString& mimeType );
 
    TQDict<GroupInfo> m_groups;
    TQString     m_mimeType;
    TQStringList m_preferredKeys;   // same as KFileMetaInfoProvider::preferredKeys()
    TQStringList m_preferredGroups; // same as KFileMetaInfoProvider::preferredKeys()
};
 
 
class TDEIO_EXPORT KFileMetaInfoItem
{
public:
    class Data;
    typedef KFileMimeTypeInfo::Hint Hint;
    typedef KFileMimeTypeInfo::Unit Unit;
    typedef KFileMimeTypeInfo::Attributes Attributes;
 
    // ### hmm, then it should be private
    KFileMetaInfoItem( const KFileMimeTypeInfo::ItemInfo* mti,
                       const TQString& key, const TQVariant& value);
 
    KFileMetaInfoItem( const KFileMetaInfoItem & item );
 
    const KFileMetaInfoItem& operator= (const KFileMetaInfoItem & item );
 
    KFileMetaInfoItem();
 
    ~KFileMetaInfoItem();
 
    TQString key() const;
 
    TQString translatedKey() const;
 
    const TQVariant& value() const;
 
    TQString string( bool mangle = true ) const;
 
    bool setValue( const TQVariant& value );
 
    TQVariant::Type type() const;
 
    bool isEditable() const;
 
    bool isRemoved() const;
 
    bool isModified() const;
 
    TQString prefix() const;
 
    TQString suffix() const;
 
    uint hint() const;
 
    uint unit() const;
 
    uint attributes() const;
 
    bool isValid() const;
 
    TDEIO_EXPORT friend TQDataStream& operator >>(TQDataStream& s, KFileMetaInfoItem& );
    TDEIO_EXPORT friend TQDataStream& operator >>(TQDataStream& s, KFileMetaInfoGroup& );
    TDEIO_EXPORT friend TQDataStream& operator <<(TQDataStream& s, const KFileMetaInfoItem& );
    friend class KFileMetaInfoGroup;
 
protected:
    void setAdded();
    void setRemoved();
 
    void ref();
    void deref();
 
    Data *d;
};
 
class TDEIO_EXPORT KFileMetaInfoGroup
{
  friend class KFilePlugin;
  friend class KFileMetaInfo;
  TDEIO_EXPORT friend TQDataStream& operator >>(TQDataStream& s, KFileMetaInfoGroup& );
  TDEIO_EXPORT friend TQDataStream& operator <<(TQDataStream& s, const KFileMetaInfoGroup& );
 
public:
    class Data;
    // ### hmm, then it should be private
    KFileMetaInfoGroup( const TQString& name, const KFileMimeTypeInfo* info );
 
    KFileMetaInfoGroup( const KFileMetaInfoGroup& original );
 
    const KFileMetaInfoGroup& operator= (const KFileMetaInfoGroup& info );
 
     KFileMetaInfoGroup();
 
    ~KFileMetaInfoGroup();
 
    bool isValid() const;
 
    bool isEmpty() const;
 
    bool isModified() const;
 
    KFileMetaInfoItem operator[]( const TQString& key ) const
    { return item( key ); }
 
    KFileMetaInfoItem item( const TQString& key ) const;
 
    KFileMetaInfoItem item( uint hint ) const;
 
    const TQVariant value( const TQString& key ) const
    {
        const KFileMetaInfoItem &i = item( key );
        return i.value();
    }
 
    TQStringList supportedKeys() const;
 
    bool supportsVariableKeys() const;
 
    bool contains( const TQString& key ) const;
 
    TQStringList keys() const;
 
    TQStringList preferredKeys() const;
 
    // ### do we really want to support that?
    // let's not waste time on thinking about it. Let's just kick it for now
    // and add it in 4.0 if needed ;)
//    const TQMemArray<TQVariant::Type>& types( const TQString& key ) const;
 
    KFileMetaInfoItem addItem( const TQString& key );
 
    bool removeItem(const TQString& key);
 
    TQStringList removedItems();
 
    TQString name() const;
 
    TQString translatedName() const;
 
    uint attributes() const;
 
protected:
      void setAdded();
      KFileMetaInfoItem appendItem( const TQString& key, const TQVariant& value);
 
      Data* d;
      void ref();
      void deref();
 
};
 
 
 
 
class TDEIO_EXPORT KFileMetaInfo
{
public:
    typedef KFileMimeTypeInfo::Hint Hint;
    typedef KFileMimeTypeInfo::Unit Unit;
    typedef KFileMimeTypeInfo::Attributes Attributes;
    class Data;
 
    enum What
    {
      Fastest       = 0x1,  
      DontCare      = 0x2,  
 
      TechnicalInfo = 0x4,  
      ContentInfo   = 0x8,  
      ExtenedAttr   = 0x10, 
      Thumbnail     = 0x20, 
      Preferred     = 0x40,  
      Everything    = 0xffff 
 
    };
 
    KFileMetaInfo( const TQString& path,
                   const TQString& mimeType = TQString::null,
                   uint what = Fastest);
 
    KFileMetaInfo( const KURL& url,
                   const TQString& mimeType = TQString::null,
                   uint what = Fastest);
 
    KFileMetaInfo();
 
    KFileMetaInfo( const KFileMetaInfo& original);
 
    ~KFileMetaInfo();
 
    const KFileMetaInfo& operator= (const KFileMetaInfo& info );
 
 
    TQStringList groups() const;
 
    TQStringList supportedGroups() const;
 
    TQStringList preferredGroups() const;
 
    TQStringList preferredKeys() const;
 
    TQStringList supportedKeys() const;
 
    TQStringList editableGroups() const;
 
    // I'd like to keep those for lookup without group, at least the hint
    // version
    KFileMetaInfoItem item(const TQString& key) const;
    KFileMetaInfoItem item(const KFileMetaInfoItem::Hint hint) const;
 
    KFileMetaInfoItem saveItem( const TQString& key,
                                const TQString& preferredGroup = TQString::null,
                                bool createGroup = true );
 
    KFileMetaInfoGroup group(const TQString& key) const;
 
    KFileMetaInfoGroup operator[] (const TQString& key) const
    {
        return group(key);
    }
 
    bool addGroup( const TQString& name );
 
    bool removeGroup( const TQString& name );
 
    TQStringList removedGroups();
 
    bool applyChanges();
 
    bool applyChanges(const TQString& path);
 
    bool contains( const TQString& key ) const;
 
    bool containsGroup( const TQString& key ) const;
 
    const TQVariant value( const TQString& key ) const
    {
        return item(key).value();
    }
 
 
    bool isValid() const;
 
    bool isEmpty() const;
 
    TQString mimeType() const;
 
    TQString path() const;
 
    KURL url() const;
 
    TDEIO_EXPORT friend TQDataStream& operator >>(TQDataStream& s, KFileMetaInfo& );
    TDEIO_EXPORT friend TQDataStream& operator <<(TQDataStream& s, const KFileMetaInfo& );
    friend class KFilePlugin;
 
protected:
    KFileMetaInfoGroup appendGroup(const TQString& name);
 
    KFilePlugin * plugin() const;
 
    void ref();
    void deref();
 
    Data* d;
 
private:
    KFileMetaInfoItem findEditableItem( KFileMetaInfoGroup& group,
                                        const TQString& key );
 
    void init( const KURL& url,
               const TQString& mimeType = TQString::null,
               uint what = Fastest);
};
 
 
 
class TDEIO_EXPORT KFilePlugin : public TQObject
{
    TQ_OBJECT
 
public:
    KFilePlugin( TQObject *parent, const char *name,
                 const TQStringList& args );
 
    virtual ~KFilePlugin();
 
    virtual bool readInfo( KFileMetaInfo& info,
                           uint what = KFileMetaInfo::Fastest ) = 0;
 
    virtual bool writeInfo( const KFileMetaInfo& info ) const
    {
        Q_UNUSED(info);
        return true;
    }
 
    virtual TQValidator* createValidator( const TQString& mimeType,
                                         const TQString& group,
                                         const TQString& key,
                                         TQObject* parent,
                                         const char* name) const
    {
        Q_UNUSED(mimeType); Q_UNUSED(group);Q_UNUSED(key);
        Q_UNUSED(parent);Q_UNUSED(name);
        return 0;
    }
 
protected:
 
    KFileMimeTypeInfo * addMimeTypeInfo( const TQString& mimeType );
    // ### do we need this, if it only calls the provider?
    // IMHO the Plugin shouldn't call its provider.
    // DF: yes we need this. A plugin can create more than one mimetypeinfo.
    // What sucks though, is to let plugins do that in their ctor.
    // Would be much simpler to have a virtual init method for that,
    // so that the provider can set up stuff with the plugin pointer first!
 
    KFileMimeTypeInfo::GroupInfo*  addGroupInfo(KFileMimeTypeInfo* info,
                      const TQString& key, const TQString& translatedKey) const;
 
    void setAttributes(KFileMimeTypeInfo::GroupInfo* gi, uint attr) const;
 
    void addVariableInfo(KFileMimeTypeInfo::GroupInfo* gi, TQVariant::Type type,
                         uint attr) const;
 
    KFileMimeTypeInfo::ItemInfo* addItemInfo(KFileMimeTypeInfo::GroupInfo* gi,
                                             const TQString& key,
                                             const TQString& translatedKey,
                                             TQVariant::Type type);
 
    void setAttributes(KFileMimeTypeInfo::ItemInfo* item, uint attr);
 
    void setHint(KFileMimeTypeInfo::ItemInfo* item, uint hint);
 
    void setUnit(KFileMimeTypeInfo::ItemInfo* item, uint unit);
 
    void setPrefix(KFileMimeTypeInfo::ItemInfo* item, const TQString& prefix);
 
    void setSuffix(KFileMimeTypeInfo::ItemInfo* item, const TQString& suffix);
 
    KFileMetaInfoGroup appendGroup(KFileMetaInfo& info, const TQString& key);
 
    void appendItem(KFileMetaInfoGroup& group, const TQString& key, TQVariant value);
 
    TQStringList m_preferredKeys;
    TQStringList m_preferredGroups;
 
protected:
    virtual void virtual_hook( int id, void* data );
private:
    class KFilePluginPrivate;
    KFilePluginPrivate *d;
};
 
 
 
class TDEIO_EXPORT KFileMetaInfoProvider: private TQObject
{
    friend class KFilePlugin;
 
  TQ_OBJECT
public:
    virtual ~KFileMetaInfoProvider();
 
    static KFileMetaInfoProvider * self();
 
    KFilePlugin * plugin( const TQString& mimeType ); // KDE4: merge with method below
 
    KFilePlugin * plugin( const TQString& mimeType, const TQString& protocol );
 
    const KFileMimeTypeInfo * mimeTypeInfo( const TQString& mimeType ); // KDE4: merge with below
    const KFileMimeTypeInfo * mimeTypeInfo( const TQString& mimeType, const TQString& protocol );
 
    TQStringList preferredKeys( const TQString& mimeType ) const;
    TQStringList preferredGroups( const TQString& mimeType ) const;
 
    TQStringList supportedMimeTypes() const;
 
protected: // ## should be private, right?
    KFileMetaInfoProvider();
 
private:
 
    // Data structure:
    // Mimetype or Protocol -> { Plugin and MimeTypeInfo }
    // The {} struct is CachedPluginInfo
    struct CachedPluginInfo
    {
        CachedPluginInfo() : plugin( 0 ), mimeTypeInfo( 0 ), ownsPlugin( false ) {}
        CachedPluginInfo( KFilePlugin* p, KFileMimeTypeInfo* i, bool owns )
            : plugin( p ), mimeTypeInfo( i ), ownsPlugin( owns ) {}
        // auto-delete behavior
        ~CachedPluginInfo() {
            if ( ownsPlugin ) delete plugin;
            delete mimeTypeInfo;
        }
 
        // If plugin and mimeTypeInfo are 0, means that no plugin is available.
        KFilePlugin* plugin;
        KFileMimeTypeInfo* mimeTypeInfo;
        // The problem here is that plugin can be shared in multiple instances,
        // so the memory management isn't easy. KDE4 solution: use TDESharedPtr?
        // For now we flag one copy of the KFilePlugin pointer as being "owned".
        bool ownsPlugin;
    };
 
    // The key is either a mimetype or a protocol. Those things don't look the same
    // so there's no need for two QDicts.
    TQDict<CachedPluginInfo> m_plugins;
 
    // This data is aggregated during the creation of a plugin,
    // before being moved to the appropriate CachedPluginInfo(s)
    // At any other time than during the loading of a plugin, this dict is EMPTY.
    // Same key as in m_plugins: mimetype or protocol
    TQDict<KFileMimeTypeInfo> m_pendingMimetypeInfos;
 
private:
    static KFileMetaInfoProvider * s_self;
 
    KFilePlugin* loadPlugin( const TQString& mimeType, const TQString& protocol );
    KFilePlugin* loadAndRegisterPlugin( const TQString& mimeType, const TQString& protocol );
    KFileMimeTypeInfo * addMimeTypeInfo( const TQString& mimeType );
 
    class KFileMetaInfoProviderPrivate;
    KFileMetaInfoProviderPrivate *d;
 
};
 
TDEIO_EXPORT TQDataStream& operator <<(TQDataStream& s, const KFileMetaInfoItem& );
TDEIO_EXPORT TQDataStream& operator >>(TQDataStream& s, KFileMetaInfoItem& );
 
TDEIO_EXPORT TQDataStream& operator <<(TQDataStream& s, const KFileMetaInfoGroup& );
TDEIO_EXPORT TQDataStream& operator >>(TQDataStream& s, KFileMetaInfoGroup& );
 
TDEIO_EXPORT TQDataStream& operator <<(TQDataStream& s, const KFileMetaInfo& );
TDEIO_EXPORT TQDataStream& operator >>(TQDataStream& s, KFileMetaInfo& );
 
 
#endif // TDEFILEMETAINFO_H