kfilemetainfo.h

00001 /*
00002  *  This file is part of the KDE libraries
00003  *  Copyright (C) 2001-2002 Rolf Magnus <ramagnus@kde.org>
00004  *  Copyright (C) 2001-2002 Carsten Pfeiffer <pfeiffer@kde.org>
00005  *
00006  *  This library is free software; you can redistribute it and/or
00007  *  modify it under the terms of the GNU Library General Public
00008  *  License as published by the Free Software Foundation version 2.0.
00009  *
00010  *  This library is distributed in the hope that it will be useful,
00011  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00012  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00013  *  Library General Public License for more details.
00014  *
00015  *  You should have received a copy of the GNU Library General Public License
00016  *  along with this library; see the file COPYING.LIB.  If not, write to
00017  *  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
00018  *  Boston, MA 02110-1301, USA.
00019  */
00020 #ifndef KILEMETAINFO_H
00021 #define KILEMETAINFO_H
00022 
00023 /* Hack for HPUX: Namespace pollution
00024    m_unit is a define in <sys/sysmacros.h> */
00025 #define m_unit outouftheway_m_unit
00026 
00027 #include <qdict.h>
00028 #include <qvariant.h>
00029 #include <qobject.h>
00030 #include <qstring.h>
00031 #include <kurl.h>
00032 
00033 #undef m_unit
00034 
00035 class QValidator;
00036 class KFilePlugin;
00037 class KFileMetaInfoGroup;
00038 
00050 class KIO_EXPORT KFileMimeTypeInfo
00051 {
00052     // the plugin needs to be a friend because it puts the data into the object,
00053     // and it should be the only one allowed to do this.
00054     friend class KFilePlugin;
00055     friend class KFileMetaInfoProvider;
00056 
00057 public:
00058     KFileMimeTypeInfo() {}
00059 
00064     enum Attributes
00065     {
00066         Addable     =  1, 
00067         Removable   =  2, 
00068         Modifiable  =  4, 
00069         Cumulative =  8,  
00072         Cummulative = Cumulative, 
00073         Averaged    = 16, 
00075         MultiLine   = 32, 
00079         SqueezeText = 64  
00083     };
00084 
00089     enum Hint {
00090         NoHint      = 0, 
00091         Name        = 1, 
00092         Author      = 2, 
00093         Description = 3, 
00094         Width       = 4, 
00095         Height      = 5, 
00096         Size        = 6, 
00097         Bitrate     = 7, 
00098         Length      = 8, 
00099         Hidden      = 9, 
00100         Thumbnail   = 10 
00101 
00102     };
00103 
00111     enum Unit {
00112         NoUnit          = 0,  
00113         Seconds         = 1,  
00114         MilliSeconds    = 2,  
00115         BitsPerSecond   = 3,  
00116         Pixels          = 4,  
00117         Inches          = 5,  
00118         Centimeters     = 6,  
00119         Bytes           = 7,  
00120         FramesPerSecond = 8,  
00121         DotsPerInch     = 9,  
00122         BitsPerPixel    = 10, 
00123         Hertz           = 11, 
00124         KiloBytes       = 12, 
00125         Millimeters     = 13  
00126     };
00127 
00128 
00129     class ItemInfo;
00130 
00138     class KIO_EXPORT GroupInfo
00139     {
00140 
00141     friend class KFilePlugin;
00142     friend class KFileMimeTypeInfo;
00143     public:
00154         QStringList supportedKeys() const
00155         {
00156             return m_supportedKeys;
00157         }
00158 
00165         const QString& name() const
00166         {
00167             return m_name;
00168         }
00169 
00177         const QString& translatedName() const
00178         {
00179             return m_translatedName;
00180         }
00181 
00189         const ItemInfo * itemInfo( const QString& key ) const;
00190 
00196         uint attributes() const
00197         {
00198             return m_attr;
00199         }
00200 
00205         bool supportsVariableKeys() const
00206         {
00207             return m_variableItemInfo;
00208         }
00209 
00217         const ItemInfo* variableItemInfo( ) const
00218         {
00219             return m_variableItemInfo;
00220         }
00221 
00222     private:
00224         GroupInfo( const QString& name, const QString& translatedName);
00225 
00227         KFileMimeTypeInfo::ItemInfo* addItemInfo( const QString& key,
00228                                                   const QString& translatedKey,
00229                                                   QVariant::Type type);
00230 
00232         void addVariableInfo( QVariant::Type type, uint attr );
00233 
00234         QString         m_name;
00235         QString         m_translatedName;
00236         QStringList     m_supportedKeys;
00237         uint            m_attr;
00238         ItemInfo*       m_variableItemInfo;
00239         QDict<ItemInfo> m_itemDict;
00240 
00241     };
00242 
00248     class KIO_EXPORT ItemInfo
00249     {
00250     friend class KFilePlugin;
00251     friend class GroupInfo;
00252     public:
00254         ItemInfo() {}     // ### should be private?
00255 
00263         const QString& prefix() const
00264         {
00265             return m_prefix;
00266         }
00267 
00274         const QString& suffix() const
00275         {
00276             return m_suffix;
00277         }
00278 
00285         QVariant::Type type() const
00286         {
00287             return m_type;
00288         }
00289 
00294         const QString& key() const
00295         {
00296             return m_key;
00297         }
00298 
00310         QString string( const QVariant& value, bool mangle = true ) const;
00311 
00317         bool isVariableItem() const
00318         {
00319             // every valid item is supposed to have a non-null key
00320             return key().isNull();
00321         }
00322 
00329         const QString& translatedKey() const
00330         {
00331             return m_translatedKey;
00332         }
00333 
00339         uint attributes() const
00340         {
00341             return m_attr;
00342         }
00343 
00349         uint hint() const
00350         {
00351             return m_hint;
00352         }
00353 
00359         uint unit() const
00360         {
00361             return m_unit;
00362         }
00363 
00364     private:
00366         ItemInfo(const QString& key, const QString& translatedKey,
00367                  QVariant::Type type)
00368             : m_key(key), m_translatedKey(translatedKey),
00369               m_type(type),
00370               m_attr(0), m_unit(NoUnit), m_hint(NoHint),
00371               m_prefix(QString::null), m_suffix(QString::null)
00372         {}
00373 
00374         QString           m_key;
00375         QString           m_translatedKey;
00376         QVariant::Type    m_type;
00377         uint              m_attr;
00378         uint              m_unit;
00379         uint              m_hint;
00380         QString           m_prefix;
00381         QString           m_suffix;
00382     };
00383 
00384     // ### could it be made private? Would this be BC?
00385     ~KFileMimeTypeInfo();
00386 
00398     QValidator * createValidator(const QString& group, const QString& key,
00399                                  QObject *parent = 0, const char *name = 0) const;
00400 
00407     QStringList supportedGroups() const;
00408 
00415     QStringList translatedGroups() const;
00416 
00423     QStringList preferredGroups() const
00424     {
00425         return m_preferredGroups;
00426     }
00427 
00433     QString mimeType()  const {return m_mimeType;}
00434 
00442     const GroupInfo * groupInfo( const QString& group ) const;
00443 
00444     // always returning stringlists which the user has to iterate and use them
00445     // to look up the real items sounds strange to me. I think we should add
00446     // our own iterators some time (somewhere in the future ;)
00447 
00454     QStringList supportedKeys() const;
00455 
00461     QStringList preferredKeys() const
00462     {
00463         return m_preferredKeys;
00464     }
00465 
00466     // ### shouldn't this be private? BC?
00467     GroupInfo * addGroupInfo( const QString& name,
00468                               const QString& translatedName);
00469 
00470     QString         m_translatedName;
00471     QStringList     m_supportedKeys;
00472     uint            m_attr;
00473     //        bool            m_supportsVariableKeys : 1;
00474     QDict<ItemInfo> m_itemDict;
00475 
00476 // ### this should be made private instead, but this would be BIC
00477 protected:
00479     KFileMimeTypeInfo( const QString& mimeType );
00480 
00481     QDict<GroupInfo> m_groups;
00482     QString     m_mimeType;
00483     QStringList m_preferredKeys;   // same as KFileMetaInfoProvider::preferredKeys()
00484     QStringList m_preferredGroups; // same as KFileMetaInfoProvider::preferredKeys()
00485 };
00486 
00487 
00494 class KIO_EXPORT KFileMetaInfoItem
00495 {
00496 public:
00497     class Data;
00498     typedef KFileMimeTypeInfo::Hint Hint;
00499     typedef KFileMimeTypeInfo::Unit Unit;
00500     typedef KFileMimeTypeInfo::Attributes Attributes;
00501 
00507     // ### hmm, then it should be private
00508     KFileMetaInfoItem( const KFileMimeTypeInfo::ItemInfo* mti,
00509                        const QString& key, const QVariant& value);
00510 
00514     KFileMetaInfoItem( const KFileMetaInfoItem & item );
00515 
00525     const KFileMetaInfoItem& operator= (const KFileMetaInfoItem & item );
00526 
00530     KFileMetaInfoItem();
00531 
00532     ~KFileMetaInfoItem();
00533 
00539     QString key() const;
00540 
00547     QString translatedKey() const;
00548 
00554     const QVariant& value() const;
00555 
00564     QString string( bool mangle = true ) const;
00565 
00572     bool setValue( const QVariant& value );
00573 
00579     QVariant::Type type() const;
00580 
00590     bool isEditable() const;
00591 
00600     bool isRemoved() const;
00601 
00610     bool isModified() const;
00611 
00618     QString prefix() const;
00619 
00626     QString suffix() const;
00627 
00633     uint hint() const;
00634 
00641     uint unit() const;
00642 
00649     uint attributes() const;
00650 
00659     bool isValid() const;
00660 
00661     KIO_EXPORT friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoItem& );
00662     KIO_EXPORT friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
00663     KIO_EXPORT friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfoItem& );
00664     friend class KFileMetaInfoGroup;
00665 
00666 protected:
00667     void setAdded();
00668     void setRemoved();
00669 
00670     void ref();
00671     void deref();
00672 
00673     Data *d;
00674 };
00675 
00682 class KIO_EXPORT KFileMetaInfoGroup
00683 {
00684   friend class KFilePlugin;
00685   friend class KFileMetaInfo;
00686   KIO_EXPORT friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
00687   KIO_EXPORT friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfoGroup& );
00688 
00689 public:
00690     class Data;
00696     // ### hmm, then it should be private
00697     KFileMetaInfoGroup( const QString& name, const KFileMimeTypeInfo* info );
00698 
00702     KFileMetaInfoGroup( const KFileMetaInfoGroup& original );
00703 
00713     const KFileMetaInfoGroup& operator= (const KFileMetaInfoGroup& info );
00714 
00720      KFileMetaInfoGroup();
00721 
00722     ~KFileMetaInfoGroup();
00723 
00732     bool isValid() const;
00733 
00740     bool isEmpty() const;
00741 
00750     bool isModified() const;
00751 
00756     KFileMetaInfoItem operator[]( const QString& key ) const
00757     { return item( key ); }
00758 
00765     KFileMetaInfoItem item( const QString& key ) const;
00766 
00773     KFileMetaInfoItem item( uint hint ) const;
00774 
00782     const QVariant value( const QString& key ) const
00783     {
00784         const KFileMetaInfoItem &i = item( key );
00785         return i.value();
00786     }
00787 
00798     QStringList supportedKeys() const;
00799 
00806     bool supportsVariableKeys() const;
00807 
00813     bool contains( const QString& key ) const;
00814 
00820     QStringList keys() const;
00821 
00827     QStringList preferredKeys() const;
00828 
00835     // ### do we really want to support that?
00836     // let's not waste time on thinking about it. Let's just kick it for now
00837     // and add it in 4.0 if needed ;)
00838 //    const QMemArray<QVariant::Type>& types( const QString& key ) const;
00839 
00848     KFileMetaInfoItem addItem( const QString& key );
00849 
00859     bool removeItem(const QString& key);
00860 
00866     QStringList removedItems();
00867 
00873     QString name() const;
00874 
00882     QString translatedName() const;
00883 
00889     uint attributes() const;
00890 
00891 protected:
00892       void setAdded();
00893       KFileMetaInfoItem appendItem( const QString& key, const QVariant& value);
00894 
00895       Data* d;
00896       void ref();
00897       void deref();
00898 
00899 };
00900 
00901 
00904 
00905 
00924 class KIO_EXPORT KFileMetaInfo
00925 {
00926 public:
00927     typedef KFileMimeTypeInfo::Hint Hint;
00928     typedef KFileMimeTypeInfo::Unit Unit;
00929     typedef KFileMimeTypeInfo::Attributes Attributes;
00930     class Data;
00931 
00936     enum What
00937     {
00938       Fastest       = 0x1,  
00941       DontCare      = 0x2,  
00942 
00943       TechnicalInfo = 0x4,  
00946       ContentInfo   = 0x8,  
00948       ExtenedAttr   = 0x10, 
00950       Thumbnail     = 0x20, 
00952       Preferred     = 0x40,  
00953       Everything    = 0xffff 
00954 
00955     };
00956 
00977     KFileMetaInfo( const QString& path,
00978                    const QString& mimeType = QString::null,
00979                    uint what = Fastest);
00980 
00988     KFileMetaInfo( const KURL& url,
00989                    const QString& mimeType = QString::null,
00990                    uint what = Fastest);
00991 
00996     KFileMetaInfo();
00997 
01004     KFileMetaInfo( const KFileMetaInfo& original);
01005 
01006     ~KFileMetaInfo();
01007 
01018     const KFileMetaInfo& operator= (const KFileMetaInfo& info );
01019 
01020 
01026     QStringList groups() const;
01027 
01033     QStringList supportedGroups() const;
01034 
01040     QStringList preferredGroups() const;
01041 
01047     QStringList preferredKeys() const;
01048 
01054     QStringList supportedKeys() const;
01055 
01061     QStringList editableGroups() const;
01062 
01063     // I'd like to keep those for lookup without group, at least the hint
01064     // version
01071     KFileMetaInfoItem item(const QString& key) const;
01078     KFileMetaInfoItem item(const KFileMetaInfoItem::Hint hint) const;
01079 
01088     KFileMetaInfoItem saveItem( const QString& key,
01089                                 const QString& preferredGroup = QString::null,
01090                                 bool createGroup = true );
01091 
01098     KFileMetaInfoGroup group(const QString& key) const;
01099 
01106     KFileMetaInfoGroup operator[] (const QString& key) const
01107     {
01108         return group(key);
01109     }
01110 
01121     bool addGroup( const QString& name );
01122 
01132     bool removeGroup( const QString& name );
01133 
01139     QStringList removedGroups();
01140 
01148     bool applyChanges();
01149 
01156     bool contains( const QString& key ) const;
01157 
01164     bool containsGroup( const QString& key ) const;
01165 
01172     const QVariant value( const QString& key ) const
01173     {
01174         return item(key).value();
01175     }
01176 
01177 
01184     bool isValid() const;
01185 
01192     bool isEmpty() const;
01193 
01199     QString mimeType() const;
01200 
01206     QString path() const;
01207 
01213     KURL url() const;
01214 
01215     KIO_EXPORT friend QDataStream& operator >>(QDataStream& s, KFileMetaInfo& );
01216     KIO_EXPORT friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfo& );
01217     friend class KFilePlugin;
01218 
01219 protected:
01220     KFileMetaInfoGroup appendGroup(const QString& name);
01221 
01226     KFilePlugin * const plugin() const;
01227 
01228     void ref();
01229     void deref();
01230 
01231     Data* d;
01232 
01233 private:
01234     KFileMetaInfoItem findEditableItem( KFileMetaInfoGroup& group,
01235                                         const QString& key );
01236 
01237     void init( const KURL& url,
01238                const QString& mimeType = QString::null,
01239                uint what = Fastest);
01240 };
01241 
01244 
01245 
01383 class KIO_EXPORT KFilePlugin : public QObject
01384 {
01385     Q_OBJECT
01386 
01387 public:
01401     KFilePlugin( QObject *parent, const char *name,
01402                  const QStringList& args );
01403 
01407     virtual ~KFilePlugin();
01408 
01421     virtual bool readInfo( KFileMetaInfo& info,
01422                            uint what = KFileMetaInfo::Fastest ) = 0;
01423 
01431     virtual bool writeInfo( const KFileMetaInfo& info ) const
01432     {
01433         Q_UNUSED(info);
01434         return true;
01435     }
01436 
01451     virtual QValidator* createValidator( const QString& mimeType,
01452                                          const QString& group,
01453                                          const QString& key,
01454                                          QObject* parent,
01455                                          const char* name) const
01456     {
01457         Q_UNUSED(mimeType); Q_UNUSED(group);Q_UNUSED(key);
01458         Q_UNUSED(parent);Q_UNUSED(name);
01459         return 0;
01460     }
01461 
01462 protected:
01463 
01471     KFileMimeTypeInfo * addMimeTypeInfo( const QString& mimeType );
01472     // ### do we need this, if it only calls the provider?
01473     // IMHO the Plugin shouldn't call its provider.
01474     // DF: yes we need this. A plugin can create more than one mimetypeinfo.
01475     // What sucks though, is to let plugins do that in their ctor.
01476     // Would be much simpler to have a virtual init method for that,
01477     // so that the provider can set up stuff with the plugin pointer first!
01478 
01495     KFileMimeTypeInfo::GroupInfo*  addGroupInfo(KFileMimeTypeInfo* info,
01496                       const QString& key, const QString& translatedKey) const;
01497 
01505     void setAttributes(KFileMimeTypeInfo::GroupInfo* gi, uint attr) const;
01506 
01507     void addVariableInfo(KFileMimeTypeInfo::GroupInfo* gi, QVariant::Type type,
01508                          uint attr) const;
01509 
01524     KFileMimeTypeInfo::ItemInfo* addItemInfo(KFileMimeTypeInfo::GroupInfo* gi,
01525                                              const QString& key,
01526                                              const QString& translatedKey,
01527                                              QVariant::Type type);
01528 
01538     void setAttributes(KFileMimeTypeInfo::ItemInfo* item, uint attr);
01539 
01549     void setHint(KFileMimeTypeInfo::ItemInfo* item, uint hint);
01550 
01561     void setUnit(KFileMimeTypeInfo::ItemInfo* item, uint unit);
01562 
01571     void setPrefix(KFileMimeTypeInfo::ItemInfo* item, const QString& prefix);
01572 
01581     void setSuffix(KFileMimeTypeInfo::ItemInfo* item, const QString& suffix);
01582 
01594     KFileMetaInfoGroup appendGroup(KFileMetaInfo& info, const QString& key);
01595 
01604     void appendItem(KFileMetaInfoGroup& group, const QString& key, QVariant value);
01605 
01606     QStringList m_preferredKeys;
01607     QStringList m_preferredGroups;
01608 
01609 protected:
01617     virtual void virtual_hook( int id, void* data );
01618 private:
01619     class KFilePluginPrivate;
01620     KFilePluginPrivate *d;
01621 };
01622 
01625 
01626 
01635 class KIO_EXPORT KFileMetaInfoProvider: private QObject
01636 {
01637     friend class KFilePlugin;
01638 
01639   Q_OBJECT
01640 public:
01641     virtual ~KFileMetaInfoProvider();
01642 
01643     static KFileMetaInfoProvider * self();
01644 
01649     KFilePlugin * plugin( const QString& mimeType ); // KDE4: merge with method below
01650 
01656     KFilePlugin * plugin( const QString& mimeType, const QString& protocol );
01657 
01658     const KFileMimeTypeInfo * mimeTypeInfo( const QString& mimeType ); // KDE4: merge with below
01659     const KFileMimeTypeInfo * mimeTypeInfo( const QString& mimeType, const QString& protocol );
01660 
01661     QStringList preferredKeys( const QString& mimeType ) const;
01662     QStringList preferredGroups( const QString& mimeType ) const;
01663 
01665     QStringList supportedMimeTypes() const;
01666 
01667 protected: // ## should be private, right?
01668     KFileMetaInfoProvider();
01669 
01670 private:
01671 
01672     // Data structure:
01673     // Mimetype or Protocol -> { Plugin and MimeTypeInfo }
01674     // The {} struct is CachedPluginInfo
01675     struct CachedPluginInfo
01676     {
01677         CachedPluginInfo() : plugin( 0 ), mimeTypeInfo( 0 ), ownsPlugin( false ) {}
01678         CachedPluginInfo( KFilePlugin* p, KFileMimeTypeInfo* i, bool owns )
01679             : plugin( p ), mimeTypeInfo( i ), ownsPlugin( owns ) {}
01680         // auto-delete behavior
01681         ~CachedPluginInfo() {
01682             if ( ownsPlugin ) delete plugin;
01683             delete mimeTypeInfo;
01684         }
01685 
01686         // If plugin and mimeTypeInfo are 0, means that no plugin is available.
01687         KFilePlugin* plugin;
01688         KFileMimeTypeInfo* mimeTypeInfo;
01689         // The problem here is that plugin can be shared in multiple instances,
01690         // so the memory management isn't easy. KDE4 solution: use KSharedPtr?
01691         // For now we flag one copy of the KFilePlugin pointer as being "owned".
01692         bool ownsPlugin;
01693     };
01694 
01695     // The key is either a mimetype or a protocol. Those things don't look the same
01696     // so there's no need for two QDicts.
01697     QDict<CachedPluginInfo> m_plugins;
01698 
01699     // This data is aggregated during the creation of a plugin,
01700     // before being moved to the appropriate CachedPluginInfo(s)
01701     // At any other time than during the loading of a plugin, this dict is EMPTY.
01702     // Same key as in m_plugins: mimetype or protocol
01703     QDict<KFileMimeTypeInfo> m_pendingMimetypeInfos;
01704 
01705 private:
01706     static KFileMetaInfoProvider * s_self;
01707 
01708     KFilePlugin* loadPlugin( const QString& mimeType, const QString& protocol );
01709     KFilePlugin* loadAndRegisterPlugin( const QString& mimeType, const QString& protocol );
01710     KFileMimeTypeInfo * addMimeTypeInfo( const QString& mimeType );
01711 
01712     class KFileMetaInfoProviderPrivate;
01713     KFileMetaInfoProviderPrivate *d;
01714 
01715 };
01716 
01717 KIO_EXPORT QDataStream& operator <<(QDataStream& s, const KFileMetaInfoItem& );
01718 KIO_EXPORT QDataStream& operator >>(QDataStream& s, KFileMetaInfoItem& );
01719 
01720 KIO_EXPORT QDataStream& operator <<(QDataStream& s, const KFileMetaInfoGroup& );
01721 KIO_EXPORT QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
01722 
01723 KIO_EXPORT QDataStream& operator <<(QDataStream& s, const KFileMetaInfo& );
01724 KIO_EXPORT QDataStream& operator >>(QDataStream& s, KFileMetaInfo& );
01725 
01726 
01727 #endif // KILEMETAINFO_H
KDE Home | KDE Accessibility Home | Description of Access Keys