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.65 2004/05/03 06:00:00 pletourn 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         Cumulative =  8,  
00073         Cummulative = Cumulative, 
00074         Averaged    = 16, 
00076         MultiLine   = 32, 
00080         SqueezeText = 64  
00084     };
00085 
00090     enum Hint {
00091         NoHint      = 0, 
00092         Name        = 1, 
00093         Author      = 2, 
00094         Description = 3, 
00095         Width       = 4, 
00096         Height      = 5, 
00097         Size        = 6, 
00098         Bitrate     = 7, 
00099         Length      = 8, 
00100         Hidden      = 9, 
00101         Thumbnail   = 10 
00102 
00103     };
00104 
00112     enum Unit {
00113         NoUnit          = 0,  
00114         Seconds         = 1,  
00115         MilliSeconds    = 2,  
00116         BitsPerSecond   = 3,  
00117         Pixels          = 4,  
00118         Inches          = 5,  
00119         Centimeters     = 6,  
00120         Bytes           = 7,  
00121         FramesPerSecond = 8,  
00122         DotsPerInch     = 9,  
00123         BitsPerPixel    = 10, 
00124         Hertz           = 11, 
00125         KiloBytes       = 12, 
00126         Millimeters     = 13  
00127     };
00128 
00129 
00130     class ItemInfo;
00131 
00138     class 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 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 
00397     QValidator * createValidator(const QString& group, const QString& key,
00398                                  QObject *parent = 0, const char *name = 0) const;
00399 
00406     QStringList supportedGroups() const;
00407 
00414     QStringList translatedGroups() const;
00415 
00422     QStringList preferredGroups() const
00423     {
00424         return m_preferredGroups;
00425     }
00426 
00431     QString mimeType()  const {return m_mimeType;}
00432 
00440     const GroupInfo * groupInfo( const QString& group ) const;
00441 
00442     // always returning stringlists which the user has to iterate and use them
00443     // to look up the real items sounds strange to me. I think we should add
00444     // our own iterators some time (somewhere in the future ;)
00445 
00452     QStringList supportedKeys() const;
00453 
00459     QStringList preferredKeys() const
00460     {
00461         return m_preferredKeys;
00462     }
00463 
00464     // ### shouldn't this be private? BC?
00465     GroupInfo * addGroupInfo( const QString& name,
00466                               const QString& translatedName);
00467 
00468     QString         m_translatedName;
00469     QStringList     m_supportedKeys;
00470     uint            m_attr;
00471     //        bool            m_supportsVariableKeys : 1;
00472     QDict<ItemInfo> m_itemDict;
00473 
00474 // ### this should be made private instead, but this would be BIC
00475 protected:
00477     KFileMimeTypeInfo( const QString& mimeType );
00478 
00479     QDict<GroupInfo> m_groups;
00480     QString     m_mimeType;
00481     QStringList m_preferredKeys;   // same as KFileMetaInfoProvider::preferredKeys()
00482     QStringList m_preferredGroups; // same as KFileMetaInfoProvider::preferredKeys()
00483 };
00484 
00485 
00491 class KFileMetaInfoItem
00492 {
00493 public:
00494     class Data;
00495     typedef KFileMimeTypeInfo::Hint Hint;
00496     typedef KFileMimeTypeInfo::Unit Unit;
00497     typedef KFileMimeTypeInfo::Attributes Attributes;
00498 
00504     // ### hmm, then it should be private
00505     KFileMetaInfoItem( const KFileMimeTypeInfo::ItemInfo* mti,
00506                        const QString& key, const QVariant& value);
00507 
00511     KFileMetaInfoItem( const KFileMetaInfoItem & item );
00512 
00522     const KFileMetaInfoItem& operator= (const KFileMetaInfoItem & item );
00523 
00527     KFileMetaInfoItem();
00528 
00529     ~KFileMetaInfoItem();
00530 
00535     QString key() const;
00536 
00542     QString translatedKey() const;
00543 
00548     const QVariant& value() const;
00549 
00557     QString string( bool mangle = true ) const;
00558 
00564     bool setValue( const QVariant& value );
00565 
00570     QVariant::Type type() const;
00571 
00580     bool isEditable() const;
00581 
00590     bool isRemoved() const;
00591 
00600     bool isModified() const;
00601 
00608     QString prefix() const;
00609 
00616     QString suffix() const;
00617 
00622     uint hint() const;
00623 
00629     uint unit() const;
00630 
00636     uint attributes() const;
00637 
00645     bool isValid() const;
00646 
00647     friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoItem& );
00648     friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
00649     friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfoItem& );
00650     friend class KFileMetaInfoGroup;
00651 
00652 protected:
00653     void setAdded();
00654     void setRemoved();
00655 
00656     void ref();
00657     void deref();
00658 
00659     Data *d;
00660 };
00661 
00667 class KFileMetaInfoGroup
00668 {
00669   friend class KFilePlugin;
00670   friend class KFileMetaInfo;
00671   friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
00672   friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfoGroup& );
00673 
00674 public:
00675     class Data;
00681     // ### hmm, then it should be private
00682     KFileMetaInfoGroup( const QString& name, const KFileMimeTypeInfo* info );
00683 
00687     KFileMetaInfoGroup( const KFileMetaInfoGroup& original );
00688 
00698     const KFileMetaInfoGroup& operator= (const KFileMetaInfoGroup& info );
00699 
00704      KFileMetaInfoGroup();
00705 
00706     ~KFileMetaInfoGroup();
00707 
00715     bool isValid() const;
00716 
00722     bool isEmpty() const;
00723 
00730     bool isModified() const;
00731 
00736     KFileMetaInfoItem operator[]( const QString& key ) const
00737     { return item( key ); }
00738 
00745     KFileMetaInfoItem item( const QString& key ) const;
00746 
00752     KFileMetaInfoItem item( uint hint ) const;
00753 
00760     const QVariant value( const QString& key ) const
00761     {
00762         const KFileMetaInfoItem &i = item( key );
00763         return i.value();
00764     }
00765 
00776     QStringList supportedKeys() const;
00777 
00783     bool supportsVariableKeys() const;
00784 
00789     bool contains( const QString& key ) const;
00790 
00795     QStringList keys() const;
00796 
00801     QStringList preferredKeys() const;
00802 
00809     // ### do we really want to support that?
00810     // let's not waste time on thinking about it. Let's just kick it for now
00811     // and add it in 4.0 if needed ;)
00812 //    const QMemArray<QVariant::Type>& types( const QString& key ) const;
00813 
00821     KFileMetaInfoItem addItem( const QString& key );
00822 
00831     bool removeItem(const QString& key);
00832 
00837     QStringList removedItems();
00838 
00843     QString name() const;
00844 
00850     QString translatedName() const;
00851 
00856     uint attributes() const;
00857 
00858 protected:
00859       void setAdded();
00860       KFileMetaInfoItem appendItem( const QString& key, const QVariant& value);
00861 
00862       Data* d;
00863       void ref();
00864       void deref();
00865 
00866 };
00867 
00868 
00871 
00872 
00890 class KFileMetaInfo
00891 {
00892 public:
00893     typedef KFileMimeTypeInfo::Hint Hint;
00894     typedef KFileMimeTypeInfo::Unit Unit;
00895     typedef KFileMimeTypeInfo::Attributes Attributes;
00896     class Data;
00897 
00902     enum What
00903     {
00904       Fastest       = 0x1,  
00907       DontCare      = 0x2,  
00908 
00909       TechnicalInfo = 0x4,  
00912       ContentInfo   = 0x8,  
00914       ExtenedAttr   = 0x10, 
00916       Thumbnail     = 0x20, 
00918       Preferred     = 0x40,  
00919       Everything    = 0xffff 
00920 
00921     };
00922 
00943     KFileMetaInfo( const QString& path,
00944                    const QString& mimeType = QString::null,
00945                    uint what = Fastest);
00946 
00954     KFileMetaInfo( const KURL& url,
00955                    const QString& mimeType = QString::null,
00956                    uint what = Fastest);
00957 
00962     KFileMetaInfo();
00963 
00970     KFileMetaInfo( const KFileMetaInfo& original);
00971 
00972     ~KFileMetaInfo();
00973 
00984     const KFileMetaInfo& operator= (const KFileMetaInfo& info );
00985 
00986 
00991     QStringList groups() const;
00992 
00997     QStringList supportedGroups() const;
00998 
01003     QStringList preferredGroups() const;
01004 
01009     QStringList preferredKeys() const;
01010 
01015     QStringList supportedKeys() const;
01016 
01021     QStringList editableGroups() const;
01022 
01023     // I'd like to keep those for lookup without group, at least the hint
01024     // version
01030     KFileMetaInfoItem item(const QString& key) const;
01036     KFileMetaInfoItem item(const KFileMetaInfoItem::Hint hint) const;
01037 
01045     KFileMetaInfoItem saveItem( const QString& key,
01046                                 const QString& preferredGroup = QString::null,
01047                                 bool createGroup = true );
01048 
01054     KFileMetaInfoGroup group(const QString& key) const;
01055 
01061     KFileMetaInfoGroup operator[] (const QString& key) const
01062     {
01063         return group(key);
01064     }
01065 
01074     bool addGroup( const QString& name );
01075 
01084     bool removeGroup( const QString& name );
01085 
01090     QStringList removedGroups();
01091 
01098     bool applyChanges();
01099 
01105     bool contains( const QString& key ) const;
01106 
01112     bool containsGroup( const QString& key ) const;
01113 
01114     /*
01115      * Returns the value with the given @p key.
01116      * @param key the key to retrieve
01117      * @return the value. Invalid if it does not exist
01118      */
01119     const QVariant value( const QString& key ) const
01120     {
01121         return item(key).value();
01122     }
01123 
01124 
01130     bool isValid() const;
01131 
01137     bool isEmpty() const;
01138 
01143     QString mimeType() const;
01144 
01149     QString path() const;
01150 
01155     KURL url() const;
01156 
01157     friend QDataStream& operator >>(QDataStream& s, KFileMetaInfo& );
01158     friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfo& );
01159     friend class KFilePlugin;
01160 
01161 protected:
01162     KFileMetaInfoGroup appendGroup(const QString& name);
01163 
01168     KFilePlugin * const plugin() const;
01169 
01170     void ref();
01171     void deref();
01172 
01173     Data* d;
01174 
01175 private:
01176     KFileMetaInfoItem findEditableItem( KFileMetaInfoGroup& group,
01177                                         const QString& key );
01178 
01179     void init( const KURL& url,
01180                const QString& mimeType = QString::null,
01181                uint what = Fastest);
01182 };
01183 
01186 
01187 
01205 class KFilePlugin : public QObject
01206 {
01207     Q_OBJECT
01208 
01209 public:
01216     KFilePlugin( QObject *parent, const char *name,
01217                  const QStringList& args );
01218 
01219     virtual ~KFilePlugin();
01220 
01229     virtual bool readInfo( KFileMetaInfo& info,
01230                            uint what = KFileMetaInfo::Fastest ) = 0;
01231 
01238     virtual bool writeInfo( const KFileMetaInfo& info ) const
01239     {
01240         Q_UNUSED(info);
01241         return true;
01242     }
01243 
01257     virtual QValidator* createValidator( const QString& mimeType,
01258                                          const QString& group,
01259                                          const QString& key,
01260                                          QObject* parent,
01261                                          const char* name) const
01262     {
01263         Q_UNUSED(mimeType); Q_UNUSED(group);Q_UNUSED(key);
01264         Q_UNUSED(parent);Q_UNUSED(name);
01265         return 0;
01266     }
01267 
01268 protected:
01269 
01270     KFileMimeTypeInfo::GroupInfo*  addGroupInfo(KFileMimeTypeInfo* info,
01271                       const QString& key, const QString& translatedKey) const;
01272     void setAttributes(KFileMimeTypeInfo::GroupInfo* gi, uint attr) const;
01273     void addVariableInfo(KFileMimeTypeInfo::GroupInfo* gi, QVariant::Type type,
01274                          uint attr) const;
01275     KFileMimeTypeInfo::ItemInfo* addItemInfo(KFileMimeTypeInfo::GroupInfo* gi,
01276                                              const QString& key,
01277                                              const QString& translatedKey,
01278                                              QVariant::Type type);
01279     void setAttributes(KFileMimeTypeInfo::ItemInfo* item, uint attr);
01280     void setHint(KFileMimeTypeInfo::ItemInfo* item, uint hint);
01281     void setUnit(KFileMimeTypeInfo::ItemInfo* item, uint unit);
01282     void setPrefix(KFileMimeTypeInfo::ItemInfo* item, const QString& prefix);
01283     void setSuffix(KFileMimeTypeInfo::ItemInfo* item, const QString& suffix);
01284     KFileMetaInfoGroup appendGroup(KFileMetaInfo& info, const QString& key);
01285     void appendItem(KFileMetaInfoGroup& group, const QString& key, QVariant value);
01286 
01290     // ### do we need this, if it only calls the provider?
01291     // IMHO the Plugin shouldn't call its provider.
01292     KFileMimeTypeInfo * addMimeTypeInfo( const QString& mimeType );
01293 
01294     QStringList m_preferredKeys;
01295     QStringList m_preferredGroups;
01296 
01297 protected:
01298     virtual void virtual_hook( int id, void* data );
01299 private:
01300     class KFilePluginPrivate;
01301     KFilePluginPrivate *d;
01302 };
01303 
01306 
01307 
01314 class KFileMetaInfoProvider: private QObject
01315 {
01316     friend class KFilePlugin;
01317 
01318   Q_OBJECT
01319 public:
01320     virtual ~KFileMetaInfoProvider();
01321 
01322     static KFileMetaInfoProvider * self();
01323 
01328     KFilePlugin * plugin( const QString& mimeType );
01329 
01330     const KFileMimeTypeInfo * mimeTypeInfo( const QString& mimeType );
01331 
01332     QStringList preferredKeys( const QString& mimeType ) const;
01333     QStringList preferredGroups( const QString& mimeType ) const;
01334 
01336     QStringList supportedMimeTypes() const;
01337 
01338 protected:
01339     KFileMetaInfoProvider();
01340 
01341     QDict<KFilePlugin> m_plugins;
01342     QDict<KFileMimeTypeInfo> m_mimeTypeDict;
01343 
01344 private:
01345     static KFileMetaInfoProvider * s_self;
01346 
01347     KFileMimeTypeInfo * addMimeTypeInfo( const QString& mimeType );
01348 
01349     class KFileMetaInfoProviderPrivate;
01350     KFileMetaInfoProviderPrivate *d;
01351 
01352 };
01353 
01354 QDataStream& operator <<(QDataStream& s, const KFileMetaInfoItem& );
01355 QDataStream& operator >>(QDataStream& s, KFileMetaInfoItem& );
01356 
01357 QDataStream& operator <<(QDataStream& s, const KFileMetaInfoGroup& );
01358 QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& );
01359 
01360 QDataStream& operator <<(QDataStream& s, const KFileMetaInfo& );
01361 QDataStream& operator >>(QDataStream& s, KFileMetaInfo& );
01362 
01363 
01364 #endif // KILEMETAINFO_H
KDE Logo
This file is part of the documentation for kio Library Version 3.3.1.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Fri Feb 18 15:10:42 2005 by doxygen 1.3.9.1 written by Dimitri van Heesch, © 1997-2003