kio Library API Documentation

KFileMetaInfo Class Reference

This is the class for objects that hold meta information about a file. Meta Information about a file. More...

#include <kfilemetainfo.h>

List of all members.

Public Types

enum  What {
  Fastest = 0x1, DontCare = 0x2, TechnicalInfo = 0x4, ContentInfo = 0x8,
  ExtenedAttr = 0x10, Thumbnail = 0x20, Preferred = 0x40, Everything = 0xffff
}

Public Methods

 KFileMetaInfo (const QString &path, const QString &mimeType=QString::null, uint what=Fastest)
 KFileMetaInfo (const KURL &url, const QString &mimeType=QString::null, uint what=Fastest)
 KFileMetaInfo ()
 KFileMetaInfo (const KFileMetaInfo &original)
const KFileMetaInfo & operator= (const KFileMetaInfo &info)
QStringList groups () const
QStringList supportedGroups () const
QStringList preferredGroups () const
QStringList preferredKeys () const
QStringList supportedKeys () const
QStringList editableGroups () const
KFileMetaInfoItem item (const QString &key) const
KFileMetaInfoItem item (const KFileMetaInfoItem::Hint hint) const
KFileMetaInfoItem saveItem (const QString &key, const QString &preferredGroup=QString::null, bool createGroup=true)
KFileMetaInfoGroup group (const QString &key) const
KFileMetaInfoGroup operator[] (const QString &key) const
bool addGroup (const QString &name)
bool removeGroup (const QString &name)
QStringList removedGroups ()
bool applyChanges ()
bool contains (const QString &key) const
bool containsGroup (const QString &key) const
bool isValid () const
bool isEmpty () const
QString mimeType () const
QString path () const
KURL url () const

Protected Methods

KFilePlugin *const plugin () const


Detailed Description

This is the class for objects that hold meta information about a file. Meta Information about a file.

The information is kept in form of a system of key/value pairs. See also KFileMetaInfoItem. This information is retrieved from the file through a plugin system, and this class is the main interface to it. If you want to write your own plugin, have a look at KFilePlugin. There are basically two different kinds of meta information: Fixed ones that the plugin knows about (e.g. an mp3 id3v1 tag has a well defined fixed list of fields), and variable keys that exist in mimetypes that support their own key/value system (comments in png files are of this type). Almost every file has fixed keys, but some also have variable keys.

The groups and the What enum are not yet supported, but already added to the interface so that adding support doesn't break compatibility.

Definition at line 888 of file kfilemetainfo.h.


Member Enumeration Documentation

enum KFileMetaInfo::What
 

This is used to specify what a KFileMetaInfo object should read, so you can specify if you want to read "expensive" items or not.

Enumeration values:
Fastest  do the fastest possible read and omit all items that might need a significantly longer time than the others
DontCare  let the plugin decide what to read
TechnicalInfo  extract technical details about the file, like e.g

play time, resolution or a compressioni type

ContentInfo  read information about the content of the file, like comments or id3 tags
ExtenedAttr  read filesystem based extended attributes if they are supported for the filesystem
Thumbnail  only read the file's thumbnail, if it contains one
Preferred  get at least the preferred items
Everything  read everything, even if it might take a while

Definition at line 900 of file kfilemetainfo.h.


Constructor & Destructor Documentation

KFileMetaInfo::KFileMetaInfo const QString   path,
const QString   mimeType = QString::null,
uint    what = Fastest
 

The constructor.

creating a KFileMetaInfo item through this will autoload the plugin belonging to the mimetype and try to get meta information about the specified file.

If no info is available, you'll get an empty (not invalid) object. You can test for it with the isEmpty() method.

Parameters:
path  The file name. This must be the path to a local file.
mimeType  The name of the file's mimetype. If ommited, the mimetype is autodetected
what  one or more of the What enum values. It gives some hint to the plugin what information is desired. The plugin may still return more items.
Note:
This version will only work for local (file:/) files.

Definition at line 294 of file kfilemetainfo.cpp.

References KURL::setPath().

KFileMetaInfo::KFileMetaInfo const KURL   url,
const QString   mimeType = QString::null,
uint    what = Fastest
 

Another constructor.

Similar to the above, but takes a URL so that meta-data may be retrieved over other protocols (ftp, etc.)

Definition at line 303 of file kfilemetainfo.cpp.

KFileMetaInfo::KFileMetaInfo  
 

Default constructor.

This will create an invalid object (see isValid().

Definition at line 345 of file kfilemetainfo.cpp.

KFileMetaInfo::KFileMetaInfo const KFileMetaInfo &    original
 

Copy constructor.

This creates a copy of the original object, but that copy will point to the same data, so if you change the original, the copy will be changed, too. After all, they are referring to the same file.

Definition at line 338 of file kfilemetainfo.cpp.


Member Function Documentation

const KFileMetaInfo & KFileMetaInfo::operator= const KFileMetaInfo &    info
 

The assignment operator, so you can do e.g.:

    KFileMetaInfo info;
    if (something) info = KFileMetaInfo("/the/file");
.

This will create a shared copy of the object. The actual data is automatically deleted if all copies go out of scope.

Definition at line 490 of file kfilemetainfo.cpp.

References d.

QStringList KFileMetaInfo::groups  
 

Returns a list of all groups.

Returns:
the keys of the groups that the file has.

Definition at line 365 of file kfilemetainfo.cpp.

Referenced by contains(), containsGroup(), item(), preferredGroups(), and saveItem().

QStringList KFileMetaInfo::supportedGroups  
 

Returns a list of all supported groups.

Returns:
the supported keys of the groups that the file has.

Definition at line 355 of file kfilemetainfo.cpp.

Referenced by editableGroups().

QStringList KFileMetaInfo::preferredGroups  
 

Returns a list of the preferred groups.

Returns:
the keys of the preferred groups that the file has.

Definition at line 390 of file kfilemetainfo.cpp.

References group(), and groups().

Referenced by item(), preferredKeys(), and saveItem().

QStringList KFileMetaInfo::preferredKeys  
 

Returns a list of all preferred keys.

Returns:
a list of all preferred keys.

Definition at line 415 of file kfilemetainfo.cpp.

References preferredGroups().

Referenced by KFileItem::getToolTipText().

QStringList KFileMetaInfo::supportedKeys  
 

Returns a list of supported keys.

Returns:
a list of supported keys

Definition at line 360 of file kfilemetainfo.cpp.

QStringList KFileMetaInfo::editableGroups  
 

Returns the list of groups that you can add or remove from the file.

Returns:
the groups can be added or removed

Definition at line 375 of file kfilemetainfo.cpp.

References KFileMimeTypeInfo::Addable, KFileMimeTypeInfo::GroupInfo::attributes(), KFileMimeTypeInfo::Removable, and supportedGroups().

KFileMetaInfoItem KFileMetaInfo::item const QString   key const
 

Returns the KFileMetaInfoItem with the given key.

Parameters:
key  the key of the item
Returns:
the item. Invalid if there is no item with the given key.

Definition at line 586 of file kfilemetainfo.cpp.

References groups(), KFileMetaInfoItem::isValid(), KStdAccel::key(), and preferredGroups().

Referenced by KFileItem::getToolTipText(), and saveItem().

KFileMetaInfoItem KFileMetaInfo::item const KFileMetaInfoItem::Hint    hint const
 

Returns the KFileMetaInfoItem with the given hint.

Parameters:
hint  the hint of the item
Returns:
the item. Invalid if there is no item with the given hint.

Definition at line 597 of file kfilemetainfo.cpp.

References groups(), KFileMetaInfoItem::isValid(), and preferredGroups().

KFileMetaInfoItem KFileMetaInfo::saveItem const QString   key,
const QString   preferredGroup = QString::null,
bool    createGroup = true
 

Saves the item with the given key.

Parameters:
key  the key of the item
preferredGroup  the preferred group, or QString::null
createGroup  true to create the group if necessary
Returns:
the saved item

Definition at line 609 of file kfilemetainfo.cpp.

References addGroup(), KFileMetaInfoGroup::addItem(), QMapIterator::data(), group(), groups(), QString::isEmpty(), KFileMetaInfoItem::isValid(), item(), KStdAccel::key(), preferredGroups(), and KFileMimeTypeInfo::GroupInfo::supportedKeys().

KFileMetaInfoGroup KFileMetaInfo::group const QString   key const
 

Returns the KFileMetaInfoGroup with the given key.

Parameters:
key  the key of the item
Returns:
the group. Invalid if there is no group with the given key.

Definition at line 428 of file kfilemetainfo.cpp.

References QMapIterator::data(), and KStdAccel::key().

Referenced by addGroup(), operator[](), preferredGroups(), and saveItem().

KFileMetaInfoGroup KFileMetaInfo::operator[] const QString   key const [inline]
 

Returns the KFileMetaInfoGroup with the given key.

Parameters:
key  the key of the item
Returns:
the group. Invalid if there is no group with the given key.

Definition at line 1059 of file kfilemetainfo.h.

References group(), and KStdAccel::key().

bool KFileMetaInfo::addGroup const QString   name
 

Try to add the specified group.

This will only succeed if it is in the list of editableGroups().

Note:
that all non-variable items that belong to this group are automatically added as empty item.
Parameters:
name  the name of the group to add
Returns:
true if successful, false if not

Definition at line 437 of file kfilemetainfo.cpp.

References KFileMimeTypeInfo::Addable, KFileMetaInfoGroup::appendItem(), KFileMimeTypeInfo::ItemInfo::attributes(), group(), KFileMimeTypeInfo::GroupInfo::itemInfo(), KFileMimeTypeInfo::ItemInfo::key(), KFileMimeTypeInfo::Modifiable, KFileMetaInfoGroup::setAdded(), and KFileMimeTypeInfo::GroupInfo::supportedKeys().

Referenced by saveItem().

bool KFileMetaInfo::removeGroup const QString   name
 

Remove the specified group.

This will only succeed if it is in the list of editableGroups(). Beware that this also removes all the items in that group, so always ask the user before removing it!

Parameters:
name  the name of the group to remove
Returns:
true if successful, false if not

Definition at line 473 of file kfilemetainfo.cpp.

References KFileMimeTypeInfo::Removable.

QStringList KFileMetaInfo::removedGroups  
 

Returns a list of removed groups.

Returns:
a list of removed groups.

Definition at line 485 of file kfilemetainfo.cpp.

bool KFileMetaInfo::applyChanges  
 

This method writes all pending changes of the meta info back to the file.

If any items are marked as removed, they are really removed from the list. The info object as well as all items are updated.

Returns:
true if successful, false if not

Definition at line 518 of file kfilemetainfo.cpp.

References QMapConstIterator::data(), plugin(), and KFilePlugin::writeInfo().

bool KFileMetaInfo::contains const QString   key const
 

Checks whether an item with the given key exists.

Parameters:
key  the key to check
Returns:
whether an item for this key exists.

Definition at line 570 of file kfilemetainfo.cpp.

References KFileMetaInfoGroup::contains(), groups(), and KStdAccel::key().

bool KFileMetaInfo::containsGroup const QString   key const
 

Checks whether a group with the given key exists.

Parameters:
key  the key to check
Returns:
whether a group with this name exists.

Definition at line 581 of file kfilemetainfo.cpp.

References groups(), and KStdAccel::key().

bool KFileMetaInfo::isValid  
 

Returns true if the item is valid, i.e.

if actually represents the info about a file, false if the object is uninitialized.

Returns:
true if valid, false otherwise

Definition at line 503 of file kfilemetainfo.cpp.

Referenced by KFileItem::getToolTipText(), and KFileItem::metaInfo().

bool KFileMetaInfo::isEmpty  
 

Returns false if the object contains data, true if it's empty.

You'll get an empty object if no plugin for the file could be found.

Returns:
true if empty, false otherwise

Definition at line 509 of file kfilemetainfo.cpp.

Referenced by KFileItem::getToolTipText().

QString KFileMetaInfo::mimeType  
 

Returns the mime type of file.

Returns:
the file's mime type

Definition at line 565 of file kfilemetainfo.cpp.

QString KFileMetaInfo::path  
 

Returns the path of file - or QString::null if file is non-local.

Returns:
the file's path - or QString::null if file is non-local

Definition at line 703 of file kfilemetainfo.cpp.

KURL KFileMetaInfo::url  
 

Returns the url of file.

Returns:
the file's url

Definition at line 708 of file kfilemetainfo.cpp.

KFilePlugin *const KFileMetaInfo::plugin   [protected]
 

Returns:
a pointer to the plugin that belogs to this object's mimetype. It will be auto-loaded if it's currently not loaded

Definition at line 559 of file kfilemetainfo.cpp.

Referenced by applyChanges().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kio Library Version 3.2.0.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Wed Feb 4 12:35:12 2004 by doxygen 1.2.18 written by Dimitri van Heesch, © 1997-2003