kio Library API Documentation

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., 59 Temple Place - Suite 330,
00018  *  Boston, MA 02111-1307, USA.
00019  *
00020  *  $Id: kfilemetainfo.h,v 1.47.2.2 2002/12/14 04:20:39 pfeiffer Exp $
00021  */
00022 #ifndef KILEMETAINFO_H
00023 #define KILEMETAINFO_H
00024 
00025 #include <qdict.h>
00026 #include <qvariant.h>
00027 #include <qobject.h>
00028 #include <qstring.h>
00029 
00030 class QValidator;
00031 class KFilePlugin;
00032 class KFileMetaInfoGroup;
00033 
00041 class KFileMimeTypeInfo
00042 {
00043     // the plugin needs to be a friend because it puts the data into the object,
00044     // and it should be the only one allowed to do this.
00045     friend class KFilePlugin;
00046     friend class KFileMetaInfoProvider;
00047 
00048 public:
00049     KFileMimeTypeInfo() {}
00050 
00071     enum Attributes
00072     {
00073         Addable     =  1,
00074         Removable   =  2,
00075         Modifiable  =  4,
00076         Cummulative =  8,
00077         Averaged    = 16,
00078         MultiLine   = 32, 
00079         SqueezeText = 64  
00080     };
00081 
00098     enum Hint {
00099         NoHint      = 0,
00100         Name        = 1,
00101         Author      = 2,
00102         Description = 3,
00103         Width       = 4,
00104         Height      = 5,
00105         Size        = 6,
00106         Bitrate     = 7,
00107         Length      = 8,
00108         Hidden      = 9,
00109         Thumbnail   = 10
00110     };
00111 
00133     enum Unit {
00134         NoUnit          = 0,
00135         Seconds         = 1,
00136         MilliSeconds    = 2,
00137         BitsPerSecond   = 3,
00138         Pixels          = 4,
00139         Inches          = 5,
00140         Centimeters     = 6,
00141         Bytes           = 7,
00142         FramesPerSecond = 8,  
00143         DotsPerInch     = 9,  
00144         BitsPerPixel    = 10, 
00145         Hertz           = 11, 
00146         KiloBytes       = 12  
00147     };
00148 
00149 
00150     class ItemInfo;
00151 
00157     class GroupInfo
00158     {
00159 
00160     friend class KFilePlugin;
00161     friend class KFileMimeTypeInfo;
00162     public:
00173         QStringList supportedKeys() const
00174         {
00175             return m_supportedKeys;
00176         }
00177 
00184         const QString& name() const
00185         {
00186             return m_name;
00187         }
00188 
00196         const QString& translatedName() const
00197         {
00198             return m_translatedName;
00199         }
00200 
00208         const ItemInfo * itemInfo( const QString& key ) const;
00209 
00215         uint attributes() const
00216         {
00217             return m_attr;
00218         }
00219 
00224         bool supportsVariableKeys() const
00225         {
00226             return m_variableItemInfo;
00227         }
00228 
00236         const ItemInfo* variableItemInfo( ) const
00237         {
00238             return m_variableItemInfo;
00239         }
00240 
00241     private:
00243         GroupInfo( const QString& name, const QString& translatedName);
00244 
00246         KFileMimeTypeInfo::ItemInfo* addItemInfo( const QString& key,
00247                                                   const QString& translatedKey,
00248                                                   QVariant::Type type);
00249 
00251         void addVariableInfo( QVariant::Type type, uint attr );
00252 
00253         QString         m_name;
00254         QString         m_translatedName;
00255         QStringList     m_supportedKeys;
00256         uint            m_attr;
00257         ItemInfo*       m_variableItemInfo;
00258         QDict<ItemInfo> m_itemDict;
00259 
00260     };
00261 
00267     class ItemInfo
00268     {
00269     friend class KFilePlugin;
00270     friend class GroupInfo;
00271     public:
00273         ItemInfo() {}     // ### should be private?
00274 
00282         const QString& prefix() const
00283         {
00284             return m_prefix;
00285         }
00286 
00293         const QString& suffix() const
00294         {
00295             return m_suffix;
00296         }
00297 
00304         QVariant::Type type() const
00305         {
00306             return m_type;
00307         }
00308 
00312         const QString& key() const
00313         {
00314             return m_key;
00315         }
00316 
00326         QString string( const QVariant& value, bool mangle = true ) const;
00327 
00333         bool isVariableItem() const
00334         {
00335             // every valid item is supposed to have a non-null key
00336             return key().isNull();
00337         }
00338 
00344         const QString& translatedKey() const
00345         {
00346             return m_translatedKey;
00347         }
00348 
00353         uint attributes() const
00354         {
00355             return m_attr;
00356         }
00357 
00362         uint hint() const
00363         {
00364             return m_hint;
00365         }
00366 
00371         uint unit() const
00372         {
00373             return m_unit;
00374         }
00375 
00376     private:
00378         ItemInfo(const QString& key, const QString& translatedKey,
00379                  QVariant::Type type)
00380             : m_key(key), m_translatedKey(translatedKey),
00381               m_type(type),
00382               m_attr(0), m_unit(NoUnit), m_hint(NoHint),
00383               m_prefix(QString::null), m_suffix(QString::null)
00384         {}
00385 
00386         QString           m_key;
00387         QString           m_translatedKey;
00388         QVariant::Type    m_type;
00389         uint              m_attr;
00390         uint              m_unit;
00391         uint              m_hint;
00392         QString           m_prefix;
00393         QString           m_suffix;
00394     };
00395 
00396     // ### could it be made private? Would this be BC?
00397     ~KFileMimeTypeInfo();
00398 
00403     QValidator * createValidator(const QString& group, const QString& key,
00404                                  QObject *parent = 0, const char *name = 0) const;
00405 
00412     QStringList supportedGroups() const;
00413 
00420     QStringList translatedGroups() const;
00421 
00428     QStringList preferredGroups() const
00429     {
00430         return m_preferredGroups;
00431     }
00432 
00436     QString mimeType()  const {return m_mimeType;}
00437 
00443     const GroupInfo * groupInfo( const QString& group ) const;
00444 
00445     // always returning stringlists which the user has to iterate and use them
00446     // to look up the real items sounds strange to me. I think we should add
00447     // our own iterators some time (somewhere in the future ;)
00448 
00455     QStringList supportedKeys() const;
00456 
00462     QStringList preferredKeys() const
00463     {
00464         return m_preferredKeys;
00465     }
00466 
00467     // ### shouldn't this be private? BC?
00468     GroupInfo * addGroupInfo( const QString& name,
00469                               const QString& translatedName);
00470 
00471     QString         m_translatedName;
00472     QStringList     m_supportedKeys;
00473     uint            m_attr;
00474     //        bool            m_supportsVariableKeys : 1;
00475     QDict<ItemInfo> m_itemDict;
00476 
00477 // ### this should be made private instead, but this would be BIC
00478 protected:
00480     KFileMimeTypeInfo( const QString& mimeType );
00481 
00482     QDict<GroupInfo> m_groups;
00483     QString     m_mimeType;
00484     QStringList m_preferredKeys;   // same as KFileMetaInfoProvider::preferredKeys()
00485     QStringList m_preferredGroups; // same as KFileMetaInfoProvider::preferredKeys()
00486 };
00487 
00488 
00493 class KFileMetaInfoItem
00494 {
00495 public:
00496     class Data;
00497     typedef KFileMimeTypeInfo::Hint Hint;
00498     typedef KFileMimeTypeInfo::Unit Unit;
00499     typedef KFileMimeTypeInfo::Attributes Attributes;
00500 
00506     // ### hmm, then it should be private
00507     KFileMetaInfoItem( const KFileMimeTypeInfo::ItemInfo* mti,
00508                        const QString& key, const QVariant& value);
00509 
00513     KFileMetaInfoItem( const KFileMetaInfoItem & item );
00514 
00524     const KFileMetaInfoItem& operator= (const KFileMetaInfoItem & item );
00525 
00529     KFileMetaInfoItem();
00530 
00531     ~KFileMetaInfoItem();
00532 
00536     QString key() const;
00537 
00542     QString translatedKey() const;
00543 
00547     const QVariant& value() const;
00548 
00555     QString string( bool mangle = true ) const;
00556 
00560     bool setValue( const QVariant& value );
00561 
00566     QVariant::Type type() const;
00567 
00575     bool isEditable() const;
00576 
00585     bool isRemoved() const;
00586 
00595     bool isModified() const;
00596 
00603     QString prefix() const;
00604 
00611     QString suffix() const;
00612 
00616     uint hint() const;
00617 
00621     uint unit() const;
00622 
00627     uint attributes() const;
00628 
00635     bool isValid() const;
00636 
00637     friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoItem& );
00638     friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
00639     friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfoItem& );
00640     friend class KFileMetaInfoGroup;
00641 
00642 protected:
00643     void setAdded();
00644     void setRemoved();
00645 
00646     void ref();
00647     void deref();
00648 
00649     Data *d;
00650 };
00651 
00656 class KFileMetaInfoGroup
00657 {
00658   friend class KFilePlugin;
00659   friend class KFileMetaInfo;
00660   friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
00661   friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfoGroup& );
00662 
00663 public:
00664     class Data;
00670     // ### hmm, then it should be private
00671     KFileMetaInfoGroup( const QString& name, const KFileMimeTypeInfo* info );
00672 
00676     KFileMetaInfoGroup( const KFileMetaInfoGroup& original );
00677 
00687     const KFileMetaInfoGroup& operator= (const KFileMetaInfoGroup& info );
00688 
00693      KFileMetaInfoGroup();
00694 
00695     ~KFileMetaInfoGroup();
00696 
00703     bool isValid() const;
00704 
00709     bool isEmpty() const;
00710 
00717     bool isModified() const;
00718     
00723     KFileMetaInfoItem operator[]( const QString& key ) const
00724     { return item( key ); }
00725 
00731     KFileMetaInfoItem item( const QString& key ) const;
00732 
00736     KFileMetaInfoItem item( uint hint ) const;
00737 
00742     const QVariant value( const QString& key ) const
00743     {
00744         const KFileMetaInfoItem &i = item( key );
00745         return i.value();
00746     }
00747 
00748 
00759     QStringList supportedKeys() const;
00760 
00765     bool supportsVariableKeys() const;
00766 
00770     bool contains( const QString& key ) const;
00771 
00775     QStringList keys() const;
00776 
00780     QStringList preferredKeys() const;
00781 
00788     // ### do we really want to support that?
00789     // let's not waste time on thinking about it. Let's just kick it for now
00790     // and add it in 4.0 if needed ;)
00791 //    const QMemArray<QVariant::Type>& types( const QString& key ) const;
00792 
00798     KFileMetaInfoItem addItem( const QString& key );
00799 
00806     bool removeItem(const QString& key);
00807 
00808     QStringList removedItems();
00809 
00810     QString name() const;
00811 
00812     uint attributes() const;
00813 
00814 protected:
00815       void setAdded();
00816       KFileMetaInfoItem appendItem( const QString& key, const QVariant& value);
00817 
00818       Data* d;
00819       void ref();
00820       void deref();
00821 
00822 };
00823 
00824 
00827 
00828 
00847 class KFileMetaInfo
00848 {
00849 public:
00850     typedef KFileMimeTypeInfo::Hint Hint;
00851     typedef KFileMimeTypeInfo::Unit Unit;
00852     typedef KFileMimeTypeInfo::Attributes Attributes;
00853     class Data;
00854 
00874     enum What
00875     {
00876       Fastest       = 0x1,
00877       DontCare      = 0x2,
00878       TechnicalInfo = 0x4,
00879       ContentInfo   = 0x8,
00880       ExtenedAttr   = 0x10,
00881       Thumbnail     = 0x20,
00882       Preferred     = 0x40,
00883       Everything    = 0xffff // all bits 1 (this also makes sure the enum is
00884                              // at least 16bit, so there is more space for
00885                              // new values)
00886 
00887     };
00888 
00907     KFileMetaInfo( const QString& path,
00908                    const QString& mimeType = QString::null,
00909                    uint what = Fastest);
00910 
00915     KFileMetaInfo();
00916 
00920     KFileMetaInfo( const KFileMetaInfo& original);
00921 
00922     ~KFileMetaInfo();
00923 
00934     const KFileMetaInfo& operator= (const KFileMetaInfo& info );
00935 
00936 
00940     QStringList groups() const;
00941 
00942     QStringList supportedGroups() const;
00943 
00944     QStringList preferredGroups() const;
00945 
00946     QStringList preferredKeys() const;
00947 
00948     QStringList supportedKeys() const;
00949 
00953     QStringList editableGroups() const;
00954 
00955     // I'd like to keep those for lookup without group, at least the hint
00956     // version
00957     KFileMetaInfoItem item(const QString& key) const;
00958     KFileMetaInfoItem item(const KFileMetaInfoItem::Hint hint) const;
00959     KFileMetaInfoItem saveItem( const QString& key,
00960                                 const QString& preferredGroup = QString::null,
00961                                 bool createGroup = true );
00962 
00963     KFileMetaInfoGroup group(const QString& key) const;
00964 
00965     KFileMetaInfoGroup operator[] (const QString& key) const
00966     {
00967         return group(key);
00968     }
00969 
00976     bool addGroup( const QString& name );
00977 
00984     bool removeGroup( const QString& name );
00985 
00986     QStringList removedGroups();
00987 
00994     bool applyChanges();
00995 
00999     bool contains( const QString& key ) const;
01000 
01004     bool containsGroup( const QString& key ) const;
01005 
01006     const QVariant value( const QString& key ) const
01007     {
01008         return item(key).value();
01009     }
01010 
01011 
01016     bool isValid() const;
01017 
01022     bool isEmpty() const;
01023 
01024     QString mimeType() const;
01025 
01026     QString path() const;
01027 
01028     friend QDataStream& operator >>(QDataStream& s, KFileMetaInfo& );
01029     friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfo& );
01030     friend class KFilePlugin;
01031 
01032 protected:
01033     KFileMetaInfoGroup appendGroup(const QString& name);
01034 
01039     KFilePlugin * const plugin() const;
01040 
01041     void ref();
01042     void deref();
01043 
01044     Data* d;
01045 
01046 private:
01047     KFileMetaInfoItem findEditableItem( KFileMetaInfoGroup& group,
01048                                         const QString& key );
01049 };
01050 
01053 
01054 
01072 class KFilePlugin : public QObject
01073 {
01074     Q_OBJECT
01075 
01076 public:
01077     KFilePlugin( QObject *parent, const char *name,
01078                  const QStringList& args );
01079 
01080     virtual ~KFilePlugin();
01081 
01087     virtual bool readInfo( KFileMetaInfo& info,
01088                            uint what = KFileMetaInfo::Fastest ) = 0;
01089 
01094     virtual bool writeInfo( const KFileMetaInfo& /*info*/ ) const
01095     {
01096         return true;
01097     }
01098 
01107     virtual QValidator* createValidator( const QString& /* mimeType */,
01108                                          const QString& /* group */,
01109                                          const QString& /* key */,
01110                                          QObject* /*parent*/,
01111                                          const char* /*name*/) const
01112     {
01113         return 0;
01114     }
01115 
01116 protected:
01117 
01118     KFileMimeTypeInfo::GroupInfo*  addGroupInfo(KFileMimeTypeInfo* info,
01119                       const QString& key, const QString& translatedKey) const;
01120     void setAttributes(KFileMimeTypeInfo::GroupInfo* gi, uint attr) const;
01121     void addVariableInfo(KFileMimeTypeInfo::GroupInfo* gi, QVariant::Type type,
01122                          uint attr) const;
01123     KFileMimeTypeInfo::ItemInfo* addItemInfo(KFileMimeTypeInfo::GroupInfo* gi,
01124                                              const QString& key,
01125                                              const QString& translatedKey,
01126                                              QVariant::Type type);
01127     void setAttributes(KFileMimeTypeInfo::ItemInfo* item, uint attr);
01128     void setHint(KFileMimeTypeInfo::ItemInfo* item, uint hint);
01129     void setUnit(KFileMimeTypeInfo::ItemInfo* item, uint unit);
01130     void setPrefix(KFileMimeTypeInfo::ItemInfo* item, const QString& prefix);
01131     void setSuffix(KFileMimeTypeInfo::ItemInfo* item, const QString& suffix);
01132     KFileMetaInfoGroup appendGroup(KFileMetaInfo& info, const QString& key);
01133     void appendItem(KFileMetaInfoGroup& group, const QString& key, QVariant value);
01134 
01138     // ### do we need this, if it only calls the provider?
01139     // IMHO the Plugin shouldn't call its provider.
01140     KFileMimeTypeInfo * addMimeTypeInfo( const QString& mimeType );
01141 
01142     QStringList m_preferredKeys;
01143     QStringList m_preferredGroups;
01144 
01145 protected:
01146     virtual void virtual_hook( int id, void* data );
01147 private:
01148     class KFilePluginPrivate;
01149     KFilePluginPrivate *d;
01150 };
01151 
01154 
01155 
01162 class KFileMetaInfoProvider: QObject
01163 {
01164     friend class KFilePlugin;
01165 
01166   Q_OBJECT
01167 public:
01168     virtual ~KFileMetaInfoProvider();
01169 
01170     static KFileMetaInfoProvider * self();
01171 
01176     KFilePlugin * plugin( const QString& mimeType );
01177 
01178     const KFileMimeTypeInfo * mimeTypeInfo( const QString& mimeType );
01179 
01180     QStringList preferredKeys( const QString& mimeType ) const;
01181     QStringList preferredGroups( const QString& mimeType ) const;
01182 
01184     QStringList supportedMimeTypes() const;
01185 
01186 protected:
01187     KFileMetaInfoProvider();
01188 
01189     QDict<KFilePlugin> m_plugins;
01190     QDict<KFileMimeTypeInfo> m_mimeTypeDict;
01191 
01192 private:
01193     static KFileMetaInfoProvider * s_self;
01194 
01195     KFileMimeTypeInfo * addMimeTypeInfo( const QString& mimeType );
01196 
01197     class KFileMetaInfoProviderPrivate;
01198     KFileMetaInfoProviderPrivate *d;
01199 
01200 };
01201 
01202 QDataStream& operator <<(QDataStream& s, const KFileMetaInfoItem& );
01203 QDataStream& operator >>(QDataStream& s, KFileMetaInfoItem& );
01204 
01205 QDataStream& operator <<(QDataStream& s, const KFileMetaInfoGroup& );
01206 QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
01207 
01208 QDataStream& operator <<(QDataStream& s, const KFileMetaInfo& );
01209 QDataStream& operator >>(QDataStream& s, KFileMetaInfo& );
01210 
01211 
01212 #endif // KILEMETAINFO_H
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.0.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Oct 8 12:21:29 2003 by doxygen 1.2.18 written by Dimitri van Heesch, © 1997-2001