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.61 2003/10/01 07:17:39 staikos Exp $
00021  */
00022 #ifndef KILEMETAINFO_H
00023 #define KILEMETAINFO_H
00024 
00025 /* Hack for HPUX: Namespace pollution
00026    m_unit is a define in <sys/sysmacros.h> */
00027 #define m_unit outouftheway_m_unit
00028 
00029 #include <qdict.h>
00030 #include <qvariant.h>
00031 #include <qobject.h>
00032 #include <qstring.h>
00033 #include <kurl.h>
00034 
00035 #undef m_unit
00036 
00037 class QValidator;
00038 class KFilePlugin;
00039 class KFileMetaInfoGroup;
00040 
00051 class KFileMimeTypeInfo
00052 {
00053     // the plugin needs to be a friend because it puts the data into the object,
00054     // and it should be the only one allowed to do this.
00055     friend class KFilePlugin;
00056     friend class KFileMetaInfoProvider;
00057 
00058 public:
00059     KFileMimeTypeInfo() {}
00060 
00065     enum Attributes
00066     {
00067         Addable     =  1, 
00068         Removable   =  2, 
00069         Modifiable  =  4, 
00070         Cummulative =  8, 
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     };
00126 
00127 
00128     class ItemInfo;
00129 
00136     class GroupInfo
00137     {
00138 
00139     friend class KFilePlugin;
00140     friend class KFileMimeTypeInfo;
00141     public:
00152         QStringList supportedKeys() const
00153         {
00154             return m_supportedKeys;
00155         }
00156 
00163         const QString& name() const
00164         {
00165             return m_name;
00166         }
00167 
00175         const QString& translatedName() const
00176         {
00177             return m_translatedName;
00178         }
00179 
00187         const ItemInfo * itemInfo( const QString& key ) const;
00188 
00194         uint attributes() const
00195         {
00196             return m_attr;
00197         }
00198 
00203         bool supportsVariableKeys() const
00204         {
00205             return m_variableItemInfo;
00206         }
00207 
00215         const ItemInfo* variableItemInfo( ) const
00216         {
00217             return m_variableItemInfo;
00218         }
00219 
00220     private:
00222         GroupInfo( const QString& name, const QString& translatedName);
00223 
00225         KFileMimeTypeInfo::ItemInfo* addItemInfo( const QString& key,
00226                                                   const QString& translatedKey,
00227                                                   QVariant::Type type);
00228 
00230         void addVariableInfo( QVariant::Type type, uint attr );
00231 
00232         QString         m_name;
00233         QString         m_translatedName;
00234         QStringList     m_supportedKeys;
00235         uint            m_attr;
00236         ItemInfo*       m_variableItemInfo;
00237         QDict<ItemInfo> m_itemDict;
00238 
00239     };
00240 
00246     class ItemInfo
00247     {
00248     friend class KFilePlugin;
00249     friend class GroupInfo;
00250     public:
00252         ItemInfo() {}     // ### should be private?
00253 
00261         const QString& prefix() const
00262         {
00263             return m_prefix;
00264         }
00265 
00272         const QString& suffix() const
00273         {
00274             return m_suffix;
00275         }
00276 
00283         QVariant::Type type() const
00284         {
00285             return m_type;
00286         }
00287 
00292         const QString& key() const
00293         {
00294             return m_key;
00295         }
00296 
00308         QString string( const QVariant& value, bool mangle = true ) const;
00309 
00315         bool isVariableItem() const
00316         {
00317             // every valid item is supposed to have a non-null key
00318             return key().isNull();
00319         }
00320 
00327         const QString& translatedKey() const
00328         {
00329             return m_translatedKey;
00330         }
00331 
00337         uint attributes() const
00338         {
00339             return m_attr;
00340         }
00341 
00347         uint hint() const
00348         {
00349             return m_hint;
00350         }
00351 
00357         uint unit() const
00358         {
00359             return m_unit;
00360         }
00361 
00362     private:
00364         ItemInfo(const QString& key, const QString& translatedKey,
00365                  QVariant::Type type)
00366             : m_key(key), m_translatedKey(translatedKey),
00367               m_type(type),
00368               m_attr(0), m_unit(NoUnit), m_hint(NoHint),
00369               m_prefix(QString::null), m_suffix(QString::null)
00370         {}
00371 
00372         QString           m_key;
00373         QString           m_translatedKey;
00374         QVariant::Type    m_type;
00375         uint              m_attr;
00376         uint              m_unit;
00377         uint              m_hint;
00378         QString           m_prefix;
00379         QString           m_suffix;
00380     };
00381 
00382     // ### could it be made private? Would this be BC?
00383     ~KFileMimeTypeInfo();
00384 
00395     QValidator * createValidator(const QString& group, const QString& key,
00396                                  QObject *parent = 0, const char *name = 0) const;
00397 
00404     QStringList supportedGroups() const;
00405 
00412     QStringList translatedGroups() const;
00413 
00420     QStringList preferredGroups() const
00421     {
00422         return m_preferredGroups;
00423     }
00424 
00429     QString mimeType()  const {return m_mimeType;}
00430 
00438     const GroupInfo * groupInfo( const QString& group ) const;
00439 
00440     // always returning stringlists which the user has to iterate and use them
00441     // to look up the real items sounds strange to me. I think we should add
00442     // our own iterators some time (somewhere in the future ;)
00443 
00450     QStringList supportedKeys() const;
00451 
00457     QStringList preferredKeys() const
00458     {
00459         return m_preferredKeys;
00460     }
00461 
00462     // ### shouldn't this be private? BC?
00463     GroupInfo * addGroupInfo( const QString& name,
00464                               const QString& translatedName);
00465 
00466     QString         m_translatedName;
00467     QStringList     m_supportedKeys;
00468     uint            m_attr;
00469     //        bool            m_supportsVariableKeys : 1;
00470     QDict<ItemInfo> m_itemDict;
00471 
00472 // ### this should be made private instead, but this would be BIC
00473 protected:
00475     KFileMimeTypeInfo( const QString& mimeType );
00476 
00477     QDict<GroupInfo> m_groups;
00478     QString     m_mimeType;
00479     QStringList m_preferredKeys;   // same as KFileMetaInfoProvider::preferredKeys()
00480     QStringList m_preferredGroups; // same as KFileMetaInfoProvider::preferredKeys()
00481 };
00482 
00483 
00489 class KFileMetaInfoItem
00490 {
00491 public:
00492     class Data;
00493     typedef KFileMimeTypeInfo::Hint Hint;
00494     typedef KFileMimeTypeInfo::Unit Unit;
00495     typedef KFileMimeTypeInfo::Attributes Attributes;
00496 
00502     // ### hmm, then it should be private
00503     KFileMetaInfoItem( const KFileMimeTypeInfo::ItemInfo* mti,
00504                        const QString& key, const QVariant& value);
00505 
00509     KFileMetaInfoItem( const KFileMetaInfoItem & item );
00510 
00520     const KFileMetaInfoItem& operator= (const KFileMetaInfoItem & item );
00521 
00525     KFileMetaInfoItem();
00526 
00527     ~KFileMetaInfoItem();
00528 
00533     QString key() const;
00534 
00540     QString translatedKey() const;
00541 
00546     const QVariant& value() const;
00547 
00555     QString string( bool mangle = true ) const;
00556 
00562     bool setValue( const QVariant& value );
00563 
00568     QVariant::Type type() const;
00569 
00578     bool isEditable() const;
00579 
00588     bool isRemoved() const;
00589 
00598     bool isModified() const;
00599 
00606     QString prefix() const;
00607 
00614     QString suffix() const;
00615 
00620     uint hint() const;
00621 
00627     uint unit() const;
00628 
00634     uint attributes() const;
00635 
00643     bool isValid() const;
00644 
00645     friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoItem& );
00646     friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
00647     friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfoItem& );
00648     friend class KFileMetaInfoGroup;
00649 
00650 protected:
00651     void setAdded();
00652     void setRemoved();
00653 
00654     void ref();
00655     void deref();
00656 
00657     Data *d;
00658 };
00659 
00665 class KFileMetaInfoGroup
00666 {
00667   friend class KFilePlugin;
00668   friend class KFileMetaInfo;
00669   friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
00670   friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfoGroup& );
00671 
00672 public:
00673     class Data;
00679     // ### hmm, then it should be private
00680     KFileMetaInfoGroup( const QString& name, const KFileMimeTypeInfo* info );
00681 
00685     KFileMetaInfoGroup( const KFileMetaInfoGroup& original );
00686 
00696     const KFileMetaInfoGroup& operator= (const KFileMetaInfoGroup& info );
00697 
00702      KFileMetaInfoGroup();
00703 
00704     ~KFileMetaInfoGroup();
00705 
00713     bool isValid() const;
00714 
00720     bool isEmpty() const;
00721 
00728     bool isModified() const;
00729 
00734     KFileMetaInfoItem operator[]( const QString& key ) const
00735     { return item( key ); }
00736 
00743     KFileMetaInfoItem item( const QString& key ) const;
00744 
00750     KFileMetaInfoItem item( uint hint ) const;
00751 
00758     const QVariant value( const QString& key ) const
00759     {
00760         const KFileMetaInfoItem &i = item( key );
00761         return i.value();
00762     }
00763 
00774     QStringList supportedKeys() const;
00775 
00781     bool supportsVariableKeys() const;
00782 
00787     bool contains( const QString& key ) const;
00788 
00793     QStringList keys() const;
00794 
00799     QStringList preferredKeys() const;
00800 
00807     // ### do we really want to support that?
00808     // let's not waste time on thinking about it. Let's just kick it for now
00809     // and add it in 4.0 if needed ;)
00810 //    const QMemArray<QVariant::Type>& types( const QString& key ) const;
00811 
00819     KFileMetaInfoItem addItem( const QString& key );
00820 
00829     bool removeItem(const QString& key);
00830 
00835     QStringList removedItems();
00836 
00841     QString name() const;
00842 
00848     QString translatedName() const;
00849 
00854     uint attributes() const;
00855 
00856 protected:
00857       void setAdded();
00858       KFileMetaInfoItem appendItem( const QString& key, const QVariant& value);
00859 
00860       Data* d;
00861       void ref();
00862       void deref();
00863 
00864 };
00865 
00866 
00869 
00870 
00888 class KFileMetaInfo
00889 {
00890 public:
00891     typedef KFileMimeTypeInfo::Hint Hint;
00892     typedef KFileMimeTypeInfo::Unit Unit;
00893     typedef KFileMimeTypeInfo::Attributes Attributes;
00894     class Data;
00895 
00900     enum What
00901     {
00902       Fastest       = 0x1,  
00905       DontCare      = 0x2,  
00906 
00907       TechnicalInfo = 0x4,  
00910       ContentInfo   = 0x8,  
00912       ExtenedAttr   = 0x10, 
00914       Thumbnail     = 0x20, 
00916       Preferred     = 0x40,  
00917       Everything    = 0xffff 
00918 
00919     };
00920 
00941     KFileMetaInfo( const QString& path,
00942                    const QString& mimeType = QString::null,
00943                    uint what = Fastest);
00944 
00952     KFileMetaInfo( const KURL& url,
00953                    const QString& mimeType = QString::null,
00954                    uint what = Fastest);
00955 
00960     KFileMetaInfo();
00961 
00968     KFileMetaInfo( const KFileMetaInfo& original);
00969 
00970     ~KFileMetaInfo();
00971 
00982     const KFileMetaInfo& operator= (const KFileMetaInfo& info );
00983 
00984 
00989     QStringList groups() const;
00990 
00995     QStringList supportedGroups() const;
00996 
01001     QStringList preferredGroups() const;
01002 
01007     QStringList preferredKeys() const;
01008 
01013     QStringList supportedKeys() const;
01014 
01019     QStringList editableGroups() const;
01020 
01021     // I'd like to keep those for lookup without group, at least the hint
01022     // version
01028     KFileMetaInfoItem item(const QString& key) const;
01034     KFileMetaInfoItem item(const KFileMetaInfoItem::Hint hint) const;
01035 
01043     KFileMetaInfoItem saveItem( const QString& key,
01044                                 const QString& preferredGroup = QString::null,
01045                                 bool createGroup = true );
01046 
01052     KFileMetaInfoGroup group(const QString& key) const;
01053 
01059     KFileMetaInfoGroup operator[] (const QString& key) const
01060     {
01061         return group(key);
01062     }
01063 
01072     bool addGroup( const QString& name );
01073 
01082     bool removeGroup( const QString& name );
01083 
01088     QStringList removedGroups();
01089 
01096     bool applyChanges();
01097 
01103     bool contains( const QString& key ) const;
01104 
01110     bool containsGroup( const QString& key ) const;
01111 
01112     /*
01113      * Returns the value with the given @p key.
01114      * @param key the key to retrieve
01115      * @return the value. Invalid if it does not exist
01116      */
01117     const QVariant value( const QString& key ) const
01118     {
01119         return item(key).value();
01120     }
01121 
01122 
01128     bool isValid() const;
01129 
01135     bool isEmpty() const;
01136 
01141     QString mimeType() const;
01142 
01147     QString path() const;
01148 
01153     KURL url() const;
01154 
01155     friend QDataStream& operator >>(QDataStream& s, KFileMetaInfo& );
01156     friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfo& );
01157     friend class KFilePlugin;
01158 
01159 protected:
01160     KFileMetaInfoGroup appendGroup(const QString& name);
01161 
01166     KFilePlugin * const plugin() const;
01167 
01168     void ref();
01169     void deref();
01170 
01171     Data* d;
01172 
01173 private:
01174     KFileMetaInfoItem findEditableItem( KFileMetaInfoGroup& group,
01175                                         const QString& key );
01176 
01177     void init( const KURL& url,
01178                const QString& mimeType = QString::null,
01179                uint what = Fastest);
01180 };
01181 
01184 
01185 
01203 class KFilePlugin : public QObject
01204 {
01205     Q_OBJECT
01206 
01207 public:
01214     KFilePlugin( QObject *parent, const char *name,
01215                  const QStringList& args );
01216 
01217     virtual ~KFilePlugin();
01218 
01227     virtual bool readInfo( KFileMetaInfo& info,
01228                            uint what = KFileMetaInfo::Fastest ) = 0;
01229 
01236     virtual bool writeInfo( const KFileMetaInfo& info ) const
01237     {
01238         Q_UNUSED(info);
01239         return true;
01240     }
01241 
01255     virtual QValidator* createValidator( const QString& mimeType,
01256                                          const QString& group,
01257                                          const QString& key,
01258                                          QObject* parent,
01259                                          const char* name) const
01260     {
01261         Q_UNUSED(mimeType); Q_UNUSED(group);Q_UNUSED(key);
01262         Q_UNUSED(parent);Q_UNUSED(name);
01263         return 0;
01264     }
01265 
01266 protected:
01267 
01268     KFileMimeTypeInfo::GroupInfo*  addGroupInfo(KFileMimeTypeInfo* info,
01269                       const QString& key, const QString& translatedKey) const;
01270     void setAttributes(KFileMimeTypeInfo::GroupInfo* gi, uint attr) const;
01271     void addVariableInfo(KFileMimeTypeInfo::GroupInfo* gi, QVariant::Type type,
01272                          uint attr) const;
01273     KFileMimeTypeInfo::ItemInfo* addItemInfo(KFileMimeTypeInfo::GroupInfo* gi,
01274                                              const QString& key,
01275                                              const QString& translatedKey,
01276                                              QVariant::Type type);
01277     void setAttributes(KFileMimeTypeInfo::ItemInfo* item, uint attr);
01278     void setHint(KFileMimeTypeInfo::ItemInfo* item, uint hint);
01279     void setUnit(KFileMimeTypeInfo::ItemInfo* item, uint unit);
01280     void setPrefix(KFileMimeTypeInfo::ItemInfo* item, const QString& prefix);
01281     void setSuffix(KFileMimeTypeInfo::ItemInfo* item, const QString& suffix);
01282     KFileMetaInfoGroup appendGroup(KFileMetaInfo& info, const QString& key);
01283     void appendItem(KFileMetaInfoGroup& group, const QString& key, QVariant value);
01284 
01288     // ### do we need this, if it only calls the provider?
01289     // IMHO the Plugin shouldn't call its provider.
01290     KFileMimeTypeInfo * addMimeTypeInfo( const QString& mimeType );
01291 
01292     QStringList m_preferredKeys;
01293     QStringList m_preferredGroups;
01294 
01295 protected:
01296     virtual void virtual_hook( int id, void* data );
01297 private:
01298     class KFilePluginPrivate;
01299     KFilePluginPrivate *d;
01300 };
01301 
01304 
01305 
01312 class KFileMetaInfoProvider: private QObject
01313 {
01314     friend class KFilePlugin;
01315 
01316   Q_OBJECT
01317 public:
01318     virtual ~KFileMetaInfoProvider();
01319 
01320     static KFileMetaInfoProvider * self();
01321 
01326     KFilePlugin * plugin( const QString& mimeType );
01327 
01328     const KFileMimeTypeInfo * mimeTypeInfo( const QString& mimeType );
01329 
01330     QStringList preferredKeys( const QString& mimeType ) const;
01331     QStringList preferredGroups( const QString& mimeType ) const;
01332 
01334     QStringList supportedMimeTypes() const;
01335 
01336 protected:
01337     KFileMetaInfoProvider();
01338 
01339     QDict<KFilePlugin> m_plugins;
01340     QDict<KFileMimeTypeInfo> m_mimeTypeDict;
01341 
01342 private:
01343     static KFileMetaInfoProvider * s_self;
01344 
01345     KFileMimeTypeInfo * addMimeTypeInfo( const QString& mimeType );
01346 
01347     class KFileMetaInfoProviderPrivate;
01348     KFileMetaInfoProviderPrivate *d;
01349 
01350 };
01351 
01352 QDataStream& operator <<(QDataStream& s, const KFileMetaInfoItem& );
01353 QDataStream& operator >>(QDataStream& s, KFileMetaInfoItem& );
01354 
01355 QDataStream& operator <<(QDataStream& s, const KFileMetaInfoGroup& );
01356 QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
01357 
01358 QDataStream& operator <<(QDataStream& s, const KFileMetaInfo& );
01359 QDataStream& operator >>(QDataStream& s, KFileMetaInfo& );
01360 
01361 
01362 #endif // KILEMETAINFO_H
KDE Logo
This file is part of the documentation for kio Library Version 3.2.1.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Thu Mar 4 22:44:23 2004 by doxygen 1.3.6-20040222 written by Dimitri van Heesch, © 1997-2003