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 #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 00048 class KIO_EXPORT KFileMimeTypeInfo 00049 { 00050 // the plugin needs to be a friend because it puts the data into the object, 00051 // and it should be the only one allowed to do this. 00052 friend class KFilePlugin; 00053 friend class KFileMetaInfoProvider; 00054 00055 public: 00056 KFileMimeTypeInfo() {} 00057 00062 enum Attributes 00063 { 00064 Addable = 1, 00065 Removable = 2, 00066 Modifiable = 4, 00067 Cumulative = 8, 00070 Cummulative = Cumulative, 00071 Averaged = 16, 00073 MultiLine = 32, 00077 SqueezeText = 64 00081 }; 00082 00087 enum Hint { 00088 NoHint = 0, 00089 Name = 1, 00090 Author = 2, 00091 Description = 3, 00092 Width = 4, 00093 Height = 5, 00094 Size = 6, 00095 Bitrate = 7, 00096 Length = 8, 00097 Hidden = 9, 00098 Thumbnail = 10 00099 00100 }; 00101 00109 enum Unit { 00110 NoUnit = 0, 00111 Seconds = 1, 00112 MilliSeconds = 2, 00113 BitsPerSecond = 3, 00114 Pixels = 4, 00115 Inches = 5, 00116 Centimeters = 6, 00117 Bytes = 7, 00118 FramesPerSecond = 8, 00119 DotsPerInch = 9, 00120 BitsPerPixel = 10, 00121 Hertz = 11, 00122 KiloBytes = 12, 00123 Millimeters = 13 00124 }; 00125 00126 00127 class ItemInfo; 00128 00135 class KIO_EXPORT GroupInfo 00136 { 00137 00138 friend class KFilePlugin; 00139 friend class KFileMimeTypeInfo; 00140 public: 00151 QStringList supportedKeys() const 00152 { 00153 return m_supportedKeys; 00154 } 00155 00162 const QString& name() const 00163 { 00164 return m_name; 00165 } 00166 00174 const QString& translatedName() const 00175 { 00176 return m_translatedName; 00177 } 00178 00186 const ItemInfo * itemInfo( const QString& key ) const; 00187 00193 uint attributes() const 00194 { 00195 return m_attr; 00196 } 00197 00202 bool supportsVariableKeys() const 00203 { 00204 return m_variableItemInfo; 00205 } 00206 00214 const ItemInfo* variableItemInfo( ) const 00215 { 00216 return m_variableItemInfo; 00217 } 00218 00219 private: 00221 GroupInfo( const QString& name, const QString& translatedName); 00222 00224 KFileMimeTypeInfo::ItemInfo* addItemInfo( const QString& key, 00225 const QString& translatedKey, 00226 QVariant::Type type); 00227 00229 void addVariableInfo( QVariant::Type type, uint attr ); 00230 00231 QString m_name; 00232 QString m_translatedName; 00233 QStringList m_supportedKeys; 00234 uint m_attr; 00235 ItemInfo* m_variableItemInfo; 00236 QDict<ItemInfo> m_itemDict; 00237 00238 }; 00239 00245 class KIO_EXPORT ItemInfo 00246 { 00247 friend class KFilePlugin; 00248 friend class GroupInfo; 00249 public: 00251 ItemInfo() {} // ### should be private? 00252 00260 const QString& prefix() const 00261 { 00262 return m_prefix; 00263 } 00264 00271 const QString& suffix() const 00272 { 00273 return m_suffix; 00274 } 00275 00282 QVariant::Type type() const 00283 { 00284 return m_type; 00285 } 00286 00291 const QString& key() const 00292 { 00293 return m_key; 00294 } 00295 00307 QString string( const QVariant& value, bool mangle = true ) const; 00308 00314 bool isVariableItem() const 00315 { 00316 // every valid item is supposed to have a non-null key 00317 return key().isNull(); 00318 } 00319 00326 const QString& translatedKey() const 00327 { 00328 return m_translatedKey; 00329 } 00330 00336 uint attributes() const 00337 { 00338 return m_attr; 00339 } 00340 00346 uint hint() const 00347 { 00348 return m_hint; 00349 } 00350 00356 uint unit() const 00357 { 00358 return m_unit; 00359 } 00360 00361 private: 00363 ItemInfo(const QString& key, const QString& translatedKey, 00364 QVariant::Type type) 00365 : m_key(key), m_translatedKey(translatedKey), 00366 m_type(type), 00367 m_attr(0), m_unit(NoUnit), m_hint(NoHint), 00368 m_prefix(QString::null), m_suffix(QString::null) 00369 {} 00370 00371 QString m_key; 00372 QString m_translatedKey; 00373 QVariant::Type m_type; 00374 uint m_attr; 00375 uint m_unit; 00376 uint m_hint; 00377 QString m_prefix; 00378 QString m_suffix; 00379 }; 00380 00381 // ### could it be made private? Would this be BC? 00382 ~KFileMimeTypeInfo(); 00383 00394 QValidator * createValidator(const QString& group, const QString& key, 00395 QObject *parent = 0, const char *name = 0) const; 00396 00403 QStringList supportedGroups() const; 00404 00411 QStringList translatedGroups() const; 00412 00419 QStringList preferredGroups() const 00420 { 00421 return m_preferredGroups; 00422 } 00423 00428 QString mimeType() const {return m_mimeType;} 00429 00437 const GroupInfo * groupInfo( const QString& group ) const; 00438 00439 // always returning stringlists which the user has to iterate and use them 00440 // to look up the real items sounds strange to me. I think we should add 00441 // our own iterators some time (somewhere in the future ;) 00442 00449 QStringList supportedKeys() const; 00450 00456 QStringList preferredKeys() const 00457 { 00458 return m_preferredKeys; 00459 } 00460 00461 // ### shouldn't this be private? BC? 00462 GroupInfo * addGroupInfo( const QString& name, 00463 const QString& translatedName); 00464 00465 QString m_translatedName; 00466 QStringList m_supportedKeys; 00467 uint m_attr; 00468 // bool m_supportsVariableKeys : 1; 00469 QDict<ItemInfo> m_itemDict; 00470 00471 // ### this should be made private instead, but this would be BIC 00472 protected: 00474 KFileMimeTypeInfo( const QString& mimeType ); 00475 00476 QDict<GroupInfo> m_groups; 00477 QString m_mimeType; 00478 QStringList m_preferredKeys; // same as KFileMetaInfoProvider::preferredKeys() 00479 QStringList m_preferredGroups; // same as KFileMetaInfoProvider::preferredKeys() 00480 }; 00481 00482 00488 class KIO_EXPORT KFileMetaInfoItem 00489 { 00490 public: 00491 class Data; 00492 typedef KFileMimeTypeInfo::Hint Hint; 00493 typedef KFileMimeTypeInfo::Unit Unit; 00494 typedef KFileMimeTypeInfo::Attributes Attributes; 00495 00501 // ### hmm, then it should be private 00502 KFileMetaInfoItem( const KFileMimeTypeInfo::ItemInfo* mti, 00503 const QString& key, const QVariant& value); 00504 00508 KFileMetaInfoItem( const KFileMetaInfoItem & item ); 00509 00519 const KFileMetaInfoItem& operator= (const KFileMetaInfoItem & item ); 00520 00524 KFileMetaInfoItem(); 00525 00526 ~KFileMetaInfoItem(); 00527 00532 QString key() const; 00533 00539 QString translatedKey() const; 00540 00545 const QVariant& value() const; 00546 00554 QString string( bool mangle = true ) const; 00555 00561 bool setValue( const QVariant& value ); 00562 00567 QVariant::Type type() const; 00568 00577 bool isEditable() const; 00578 00587 bool isRemoved() const; 00588 00597 bool isModified() const; 00598 00605 QString prefix() const; 00606 00613 QString suffix() const; 00614 00619 uint hint() const; 00620 00626 uint unit() const; 00627 00633 uint attributes() const; 00634 00642 bool isValid() const; 00643 00644 KIO_EXPORT friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoItem& ); 00645 KIO_EXPORT friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& ); 00646 KIO_EXPORT friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfoItem& ); 00647 friend class KFileMetaInfoGroup; 00648 00649 protected: 00650 void setAdded(); 00651 void setRemoved(); 00652 00653 void ref(); 00654 void deref(); 00655 00656 Data *d; 00657 }; 00658 00664 class KIO_EXPORT KFileMetaInfoGroup 00665 { 00666 friend class KFilePlugin; 00667 friend class KFileMetaInfo; 00668 KIO_EXPORT friend QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& ); 00669 KIO_EXPORT friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfoGroup& ); 00670 00671 public: 00672 class Data; 00678 // ### hmm, then it should be private 00679 KFileMetaInfoGroup( const QString& name, const KFileMimeTypeInfo* info ); 00680 00684 KFileMetaInfoGroup( const KFileMetaInfoGroup& original ); 00685 00695 const KFileMetaInfoGroup& operator= (const KFileMetaInfoGroup& info ); 00696 00701 KFileMetaInfoGroup(); 00702 00703 ~KFileMetaInfoGroup(); 00704 00712 bool isValid() const; 00713 00719 bool isEmpty() const; 00720 00727 bool isModified() const; 00728 00733 KFileMetaInfoItem operator[]( const QString& key ) const 00734 { return item( key ); } 00735 00742 KFileMetaInfoItem item( const QString& key ) const; 00743 00749 KFileMetaInfoItem item( uint hint ) const; 00750 00757 const QVariant value( const QString& key ) const 00758 { 00759 const KFileMetaInfoItem &i = item( key ); 00760 return i.value(); 00761 } 00762 00773 QStringList supportedKeys() const; 00774 00780 bool supportsVariableKeys() const; 00781 00786 bool contains( const QString& key ) const; 00787 00792 QStringList keys() const; 00793 00798 QStringList preferredKeys() const; 00799 00806 // ### do we really want to support that? 00807 // let's not waste time on thinking about it. Let's just kick it for now 00808 // and add it in 4.0 if needed ;) 00809 // const QMemArray<QVariant::Type>& types( const QString& key ) const; 00810 00818 KFileMetaInfoItem addItem( const QString& key ); 00819 00828 bool removeItem(const QString& key); 00829 00834 QStringList removedItems(); 00835 00840 QString name() const; 00841 00847 QString translatedName() const; 00848 00853 uint attributes() const; 00854 00855 protected: 00856 void setAdded(); 00857 KFileMetaInfoItem appendItem( const QString& key, const QVariant& value); 00858 00859 Data* d; 00860 void ref(); 00861 void deref(); 00862 00863 }; 00864 00865 00868 00869 00887 class KIO_EXPORT KFileMetaInfo 00888 { 00889 public: 00890 typedef KFileMimeTypeInfo::Hint Hint; 00891 typedef KFileMimeTypeInfo::Unit Unit; 00892 typedef KFileMimeTypeInfo::Attributes Attributes; 00893 class Data; 00894 00899 enum What 00900 { 00901 Fastest = 0x1, 00904 DontCare = 0x2, 00905 00906 TechnicalInfo = 0x4, 00909 ContentInfo = 0x8, 00911 ExtenedAttr = 0x10, 00913 Thumbnail = 0x20, 00915 Preferred = 0x40, 00916 Everything = 0xffff 00917 00918 }; 00919 00940 KFileMetaInfo( const QString& path, 00941 const QString& mimeType = QString::null, 00942 uint what = Fastest); 00943 00951 KFileMetaInfo( const KURL& url, 00952 const QString& mimeType = QString::null, 00953 uint what = Fastest); 00954 00959 KFileMetaInfo(); 00960 00967 KFileMetaInfo( const KFileMetaInfo& original); 00968 00969 ~KFileMetaInfo(); 00970 00981 const KFileMetaInfo& operator= (const KFileMetaInfo& info ); 00982 00983 00988 QStringList groups() const; 00989 00994 QStringList supportedGroups() const; 00995 01000 QStringList preferredGroups() const; 01001 01006 QStringList preferredKeys() const; 01007 01012 QStringList supportedKeys() const; 01013 01018 QStringList editableGroups() const; 01019 01020 // I'd like to keep those for lookup without group, at least the hint 01021 // version 01027 KFileMetaInfoItem item(const QString& key) const; 01033 KFileMetaInfoItem item(const KFileMetaInfoItem::Hint hint) const; 01034 01042 KFileMetaInfoItem saveItem( const QString& key, 01043 const QString& preferredGroup = QString::null, 01044 bool createGroup = true ); 01045 01051 KFileMetaInfoGroup group(const QString& key) const; 01052 01058 KFileMetaInfoGroup operator[] (const QString& key) const 01059 { 01060 return group(key); 01061 } 01062 01071 bool addGroup( const QString& name ); 01072 01081 bool removeGroup( const QString& name ); 01082 01087 QStringList removedGroups(); 01088 01095 bool applyChanges(); 01096 01102 bool contains( const QString& key ) const; 01103 01109 bool containsGroup( const QString& key ) const; 01110 01111 /* 01112 * Returns the value with the given @p key. 01113 * @param key the key to retrieve 01114 * @return the value. Invalid if it does not exist 01115 */ 01116 const QVariant value( const QString& key ) const 01117 { 01118 return item(key).value(); 01119 } 01120 01121 01127 bool isValid() const; 01128 01134 bool isEmpty() const; 01135 01140 QString mimeType() const; 01141 01146 QString path() const; 01147 01152 KURL url() const; 01153 01154 KIO_EXPORT friend QDataStream& operator >>(QDataStream& s, KFileMetaInfo& ); 01155 KIO_EXPORT friend QDataStream& operator <<(QDataStream& s, const KFileMetaInfo& ); 01156 friend class KFilePlugin; 01157 01158 protected: 01159 KFileMetaInfoGroup appendGroup(const QString& name); 01160 01165 KFilePlugin * const plugin() const; 01166 01167 void ref(); 01168 void deref(); 01169 01170 Data* d; 01171 01172 private: 01173 KFileMetaInfoItem findEditableItem( KFileMetaInfoGroup& group, 01174 const QString& key ); 01175 01176 void init( const KURL& url, 01177 const QString& mimeType = QString::null, 01178 uint what = Fastest); 01179 }; 01180 01183 01184 01202 class KIO_EXPORT KFilePlugin : public QObject 01203 { 01204 Q_OBJECT 01205 01206 public: 01213 KFilePlugin( QObject *parent, const char *name, 01214 const QStringList& args ); 01215 01216 virtual ~KFilePlugin(); 01217 01226 virtual bool readInfo( KFileMetaInfo& info, 01227 uint what = KFileMetaInfo::Fastest ) = 0; 01228 01235 virtual bool writeInfo( const KFileMetaInfo& info ) const 01236 { 01237 Q_UNUSED(info); 01238 return true; 01239 } 01240 01254 virtual QValidator* createValidator( const QString& mimeType, 01255 const QString& group, 01256 const QString& key, 01257 QObject* parent, 01258 const char* name) const 01259 { 01260 Q_UNUSED(mimeType); Q_UNUSED(group);Q_UNUSED(key); 01261 Q_UNUSED(parent);Q_UNUSED(name); 01262 return 0; 01263 } 01264 01265 protected: 01266 01267 KFileMimeTypeInfo::GroupInfo* addGroupInfo(KFileMimeTypeInfo* info, 01268 const QString& key, const QString& translatedKey) const; 01269 void setAttributes(KFileMimeTypeInfo::GroupInfo* gi, uint attr) const; 01270 void addVariableInfo(KFileMimeTypeInfo::GroupInfo* gi, QVariant::Type type, 01271 uint attr) const; 01272 KFileMimeTypeInfo::ItemInfo* addItemInfo(KFileMimeTypeInfo::GroupInfo* gi, 01273 const QString& key, 01274 const QString& translatedKey, 01275 QVariant::Type type); 01276 void setAttributes(KFileMimeTypeInfo::ItemInfo* item, uint attr); 01277 void setHint(KFileMimeTypeInfo::ItemInfo* item, uint hint); 01278 void setUnit(KFileMimeTypeInfo::ItemInfo* item, uint unit); 01279 void setPrefix(KFileMimeTypeInfo::ItemInfo* item, const QString& prefix); 01280 void setSuffix(KFileMimeTypeInfo::ItemInfo* item, const QString& suffix); 01281 KFileMetaInfoGroup appendGroup(KFileMetaInfo& info, const QString& key); 01282 void appendItem(KFileMetaInfoGroup& group, const QString& key, QVariant value); 01283 01287 // ### do we need this, if it only calls the provider? 01288 // IMHO the Plugin shouldn't call its provider. 01289 // DF: yes we need this. A plugin can create more than one mimetypeinfo. 01290 // What sucks though, is to let plugins do that in their ctor. 01291 // Would be much simpler to have a virtual init method for that, 01292 // so that the provider can set up stuff with the plugin pointer first! 01293 KFileMimeTypeInfo * addMimeTypeInfo( const QString& mimeType ); 01294 01295 QStringList m_preferredKeys; 01296 QStringList m_preferredGroups; 01297 01298 protected: 01299 virtual void virtual_hook( int id, void* data ); 01300 private: 01301 class KFilePluginPrivate; 01302 KFilePluginPrivate *d; 01303 }; 01304 01307 01308 01315 class KIO_EXPORT KFileMetaInfoProvider: private QObject 01316 { 01317 friend class KFilePlugin; 01318 01319 Q_OBJECT 01320 public: 01321 virtual ~KFileMetaInfoProvider(); 01322 01323 static KFileMetaInfoProvider * self(); 01324 01329 KFilePlugin * plugin( const QString& mimeType ); // KDE4: merge with method below 01330 01336 KFilePlugin * plugin( const QString& mimeType, const QString& protocol ); 01337 01338 const KFileMimeTypeInfo * mimeTypeInfo( const QString& mimeType ); // KDE4: merge with below 01339 const KFileMimeTypeInfo * mimeTypeInfo( const QString& mimeType, const QString& protocol ); 01340 01341 QStringList preferredKeys( const QString& mimeType ) const; 01342 QStringList preferredGroups( const QString& mimeType ) const; 01343 01345 QStringList supportedMimeTypes() const; 01346 01347 protected: // ## should be private, right? 01348 KFileMetaInfoProvider(); 01349 01350 private: 01351 01352 // Data structure: 01353 // Mimetype or Protocol -> { Plugin and MimeTypeInfo } 01354 // The {} struct is CachedPluginInfo 01355 struct CachedPluginInfo 01356 { 01357 CachedPluginInfo() : plugin( 0 ), mimeTypeInfo( 0 ), ownsPlugin( false ) {} 01358 CachedPluginInfo( KFilePlugin* p, KFileMimeTypeInfo* i, bool owns ) 01359 : plugin( p ), mimeTypeInfo( i ), ownsPlugin( owns ) {} 01360 // auto-delete behavior 01361 ~CachedPluginInfo() { 01362 if ( ownsPlugin ) delete plugin; 01363 delete mimeTypeInfo; 01364 } 01365 01366 // If plugin and mimeTypeInfo are 0, means that no plugin is available. 01367 KFilePlugin* plugin; 01368 KFileMimeTypeInfo* mimeTypeInfo; 01369 // The problem here is that plugin can be shared in multiple instances, 01370 // so the memory management isn't easy. KDE4 solution: use KSharedPtr? 01371 // For now we flag one copy of the KFilePlugin pointer as being "owned". 01372 bool ownsPlugin; 01373 }; 01374 01375 // The key is either a mimetype or a protocol. Those things don't look the same 01376 // so there's no need for two QDicts. 01377 QDict<CachedPluginInfo> m_plugins; 01378 01379 // This data is aggregated during the creation of a plugin, 01380 // before being moved to the appropriate CachedPluginInfo(s) 01381 // At any other time than during the loading of a plugin, this dict is EMPTY. 01382 // Same key as in m_plugins: mimetype or protocol 01383 QDict<KFileMimeTypeInfo> m_pendingMimetypeInfos; 01384 01385 private: 01386 static KFileMetaInfoProvider * s_self; 01387 01388 KFilePlugin* loadPlugin( const QString& mimeType, const QString& protocol ); 01389 KFilePlugin* loadAndRegisterPlugin( const QString& mimeType, const QString& protocol ); 01390 KFileMimeTypeInfo * addMimeTypeInfo( const QString& mimeType ); 01391 01392 class KFileMetaInfoProviderPrivate; 01393 KFileMetaInfoProviderPrivate *d; 01394 01395 }; 01396 01397 KIO_EXPORT QDataStream& operator <<(QDataStream& s, const KFileMetaInfoItem& ); 01398 KIO_EXPORT QDataStream& operator >>(QDataStream& s, KFileMetaInfoItem& ); 01399 01400 KIO_EXPORT QDataStream& operator <<(QDataStream& s, const KFileMetaInfoGroup& ); 01401 KIO_EXPORT QDataStream& operator >>(QDataStream& s, KFileMetaInfoGroup& ); 01402 01403 KIO_EXPORT QDataStream& operator <<(QDataStream& s, const KFileMetaInfo& ); 01404 KIO_EXPORT QDataStream& operator >>(QDataStream& s, KFileMetaInfo& ); 01405 01406 01407 #endif // KILEMETAINFO_H
KDE Logo
This file is part of the documentation for kio Library Version 3.4.0.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Thu Apr 14 00:20:24 2005 by doxygen 1.3.7 written by Dimitri van Heesch, © 1997-2003