Your IP : 216.73.216.48
/* This file is part of the KDE project
Copyright (C) 1999-2006 David Faure <faure@kde.org>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.
*/
#ifndef KFILEITEM_H
#define KFILEITEM_H
#include <sys/stat.h>
#include <kio/global.h>
#include <kio/udsentry.h>
#include <kurl.h>
#include <kacl.h>
#include <kmimetype.h>
#include <kfilemetainfo.h>
#include <kdatetime.h>
#include <QtCore/QList>
class KFileItemPrivate;
/**
* A KFileItem is a generic class to handle a file, local or remote.
* In particular, it makes it easier to handle the result of KIO::listDir
* (UDSEntry isn't very friendly to use).
* It includes many file attributes such as mimetype, icon, text, mode, link...
*
* KFileItem is implicitly shared, i.e. it can be used as a value and copied around at almost no cost.
*/
class KIO_EXPORT KFileItem
{
public:
enum { Unknown = static_cast<mode_t>(-1) };
/**
* The timestamps associated with a file.
* - ModificationTime: the time the file's contents were last modified
* - AccessTime: the time the file was last accessed (last read or written to)
* - CreationTime: the time the file was created
*/
enum FileTimes {
// warning: don't change without looking at the Private class
ModificationTime = 0,
AccessTime = 1,
CreationTime = 2
//ChangeTime
};
/**
* Null KFileItem. Doesn't represent any file, only exists for convenience.
*
* NOTE KDE 4.0 when porting from KFileItem* to KFileItem&:
* '(KFileItem*)a==0' becomes '(KFileItem)a.isNull()'
*/
KFileItem();
/**
* Creates an item representing a file, from a UDSEntry.
* This is the preferred constructor when using KIO::listDir().
*
* @param entry the KIO entry used to get the file, contains info about it
* @param itemOrDirUrl the URL of the item or of the directory containing this item (see urlIsDirectory).
* @param delayedMimeTypes specifies if the mimetype of the given
* URL should be determined immediately or on demand.
* See the bool delayedMimeTypes in the KDirLister constructor.
* @param urlIsDirectory specifies if the url is just the directory of the
* fileitem and the filename from the UDSEntry should be used.
*
* When creating KFileItems out of the UDSEntry emitted by a KIO list job,
* use KFileItem(entry, listjob->url(), delayedMimeTypes, true);
*/
KFileItem( const KIO::UDSEntry& entry, const KUrl& itemOrDirUrl,
bool delayedMimeTypes = false,
bool urlIsDirectory = false );
/**
* Creates an item representing a file, from all the necessary info for it.
* @param mode the file mode (according to stat() (e.g. S_IFDIR...)
* Set to KFileItem::Unknown if unknown. For local files, KFileItem will use stat().
* @param permissions the access permissions
* If you set both the mode and the permissions, you save a ::stat() for
* local files.
* Set to KFileItem::Unknown if you don't know the mode or the permission.
* @param url the file url
*
* @param delayedMimeTypes specify if the mimetype of the given URL
* should be determined immediately or on demand
*/
KFileItem( mode_t mode, mode_t permissions, const KUrl& url,
bool delayedMimeTypes = false );
/**
* Creates an item representing a file, for which the mimetype is already known.
* @param url the file url
* @param mimeType the name of the file's mimetype
* @param mode the mode (S_IFDIR...)
*/
KFileItem( const KUrl &url, const QString &mimeType, mode_t mode );
/**
* Copy constructor
*/
KFileItem(const KFileItem& other);
/**
* Assignment operator
*/
KFileItem& operator=(const KFileItem& other);
/**
* Destructs the KFileItem. Extra data set via setExtraData()
* is not deleted.
*/
~KFileItem();
/**
* Throw away and re-read (for local files) all information about the file.
* This is called when the _file_ changes.
*/
void refresh();
/**
* Re-reads mimetype information.
* This is called when the mimetype database changes.
*/
void refreshMimeType();
/**
* Returns the url of the file.
* @return the url of the file
*/
KUrl url() const;
/**
* Sets the item's URL. Do not call unless you know what you are doing!
* (used for example when an item got renamed).
* @param url the item's URL
*/
void setUrl( const KUrl &url );
/**
* Sets the item's name (i.e. the filename).
* This is automatically done by setUrl, to set the name from the URL's fileName().
* This method is provided for some special cases like relative paths as names (KFindPart)
* @param name the item's name
*/
void setName( const QString &name );
/**
* Returns the permissions of the file (stat.st_mode containing only permissions).
* @return the permissions of the file
*/
mode_t permissions() const;
/**
* Returns the access permissions for the file as a string.
* @return the access persmission as string
*/
QString permissionsString() const;
/**
* Tells if the file has extended access level information ( Posix ACL )
* @return true if the file has extend ACL information or false if it hasn't
*/
bool hasExtendedACL() const;
/**
* Returns the access control list for the file.
* @return the access control list as a KACL
*/
KACL ACL() const;
/**
* Returns the default access control list for the directory.
* @return the default access control list as a KACL
*/
KACL defaultACL() const;
/**
* Returns the file type (stat.st_mode containing only S_IFDIR, S_IFLNK, ...).
* @return the file type
*/
mode_t mode() const;
/**
* Returns the owner of the file.
* @return the file's owner
*/
QString user() const;
/**
* Returns the group of the file.
* @return the file's group
*/
QString group() const;
/**
* Returns true if this item represents a link in the UNIX sense of
* a link.
* @return true if the file is a link
*/
bool isLink() const;
/**
* Returns true if this item represents a directory.
* @return true if the item is a directory
*/
bool isDir() const;
/**
* Returns true if this item represents a file (and not a a directory)
* @return true if the item is a file
*/
bool isFile() const;
/**
* Checks whether the file or directory is readable. In some cases
* (remote files), we may return true even though it can't be read.
* @return true if the file can be read - more precisely,
* false if we know for sure it can't
*/
bool isReadable() const;
/**
* Checks whether the file or directory is writable. In some cases
* (remote files), we may return true even though it can't be written to.
* @return true if the file or directory can be written to - more precisely,
* false if we know for sure it can't
*/
bool isWritable() const;
/**
* Checks whether the file is hidden.
* @return true if the file is hidden.
*/
bool isHidden() const;
/**
* @return true if the file is a remote URL, or a local file on a network mount.
* It will return false only for really-local file systems.
* @since 4.7.4
*/
bool isSlow() const;
/**
* Checks whether the file is a readable local .desktop file,
* i.e. a file whose path can be given to KDesktopFile
* @return true if the file is a desktop file.
* @since 4.1
*/
bool isDesktopFile() const;
/**
* Returns the link destination if isLink() == true.
* @return the link destination. QString() if the item is not a link
*/
QString linkDest() const;
/**
* Returns the target url of the file, which is the same as url()
* in cases where the slave doesn't specify UDS_TARGET_URL
* @return the target url.
* @since 4.1
*/
KUrl targetUrl() const;
/**
* Returns the resource URI to be used for Nepomuk annotations. In case
* the slave does not specify UDS_NEPOMUK_URI an invalid url is
* returned.
* For local files this is the same as url().
* @return The Nepomuk resource URI.
* @since 4.4
*/
KUrl nepomukUri() const;
/**
* Returns the local path if isLocalFile() == true or the KIO item has
* a UDS_LOCAL_PATH atom.
* @return the item local path, or QString() if not known
*/
QString localPath() const;
/**
* Returns the size of the file, if known.
* @return the file size, or 0 if not known
*/
KIO::filesize_t size() const;
/**
* Requests the modification, access or creation time, depending on @p which.
* @param which the timestamp
* @return the time asked for, (time_t)0 if not available
* @see timeString()
*/
KDateTime time( FileTimes which ) const;
#ifndef KDE_NO_DEPRECATED
KDE_DEPRECATED time_t time( unsigned int which ) const;
#endif
/**
* Requests the modification, access or creation time as a string, depending
* on @p which.
* @param which the timestamp
* @returns a formatted string of the requested time.
* @see time
*/
QString timeString( FileTimes which = ModificationTime ) const;
#ifndef KDE_NO_DEPRECATED
KDE_DEPRECATED QString timeString( unsigned int which) const;
#endif
/**
* Returns true if the file is a local file.
* @return true if the file is local, false otherwise
*/
bool isLocalFile() const;
/**
* Returns the text of the file item.
* It's not exactly the filename since some decoding happens ('%2F'->'/').
* @return the text of the file item
*/
QString text() const;
/**
* Return the name of the file item (without a path).
* Similar to text(), but unencoded, i.e. the original name.
* @param lowerCase if true, the name will be returned in lower case,
* which is useful to speed up sorting by name, case insensitively.
* @return the file's name
*/
QString name( bool lowerCase = false ) const;
/**
* Returns the mimetype of the file item.
* If @p delayedMimeTypes was used in the constructor, this will determine
* the mimetype first. Equivalent to determineMimeType()->name()
* @return the mime type of the file
*/
QString mimetype() const;
/**
* Returns the mimetype of the file item.
* If delayedMimeTypes was used in the constructor, this will determine
* the mimetype first.
* @return the mime type
*/
KMimeType::Ptr determineMimeType() const;
/**
* Returns the currently known mimetype of the file item.
* This will not try to determine the mimetype if unknown.
* @return the known mime type
*/
KMimeType::Ptr mimeTypePtr() const;
/**
* @return true if we have determined the final icon of this file already.
* @since 4.10.2
*/
bool isFinalIconKnown() const;
/**
* @return true if we have determined the mimetype of this file already,
* i.e. if determineMimeType() will be fast. Otherwise it will have to
* find what the mimetype is, which is a possibly slow operation; usually
* this is delayed until necessary.
*/
bool isMimeTypeKnown() const;
/**
* Returns the user-readable string representing the type of this file,
* like "OpenDocument Text File".
* @return the type of this KFileItem
*/
QString mimeComment() const;
/**
* Returns the full path name to the icon that represents
* this mime type.
* @return iconName the name of the file's icon
*/
QString iconName() const;
/**
* Returns a pixmap representing the file.
* @param _size Size for the pixmap in pixels. Zero will return the
* globally configured default size.
* @param _state The state of the icon: KIconLoader::DefaultState,
* KIconLoader::ActiveState or KIconLoader::DisabledState.
* @return the pixmap
*/
QPixmap pixmap( int _size, int _state=0 ) const;
/**
* Returns the overlays (bitfield of KIconLoader::*Overlay flags) that are used
* for this item's pixmap. Overlays are used to show for example, whether
* a file can be modified.
* @return the overlays of the pixmap
*/
QStringList overlays() const;
/**
* A comment which can contain anything - even rich text. It will
* simply be displayed to the user as is.
*
* @since 4.6
*/
QString comment() const;
/**
* Returns the string to be displayed in the statusbar,
* e.g. when the mouse is over this item
* @return the status bar information
*/
QString getStatusBarInfo() const;
/**
* Returns the string to be displayed in the tool tip when the mouse
* is over this item. This may load a plugin to determine additional
* information specific to the mimetype of the file.
*
* @param maxcount the maximum number of entries shown
* @return the tool tip string
*
* @deprecated File Managers implement more complete tooltips.
*/
#ifndef KDE_NO_DEPRECATED
KDE_DEPRECATED QString getToolTipText(int maxcount = 6) const;
#endif
/**
* Returns true if files can be dropped over this item.
* Contrary to popular belief, not only dirs will return true :)
* Executables, .desktop files, will do so as well.
* @return true if you can drop files over the item
*
* @deprecated This logic is application-dependent, the behavior described above
* mostly makes sense for file managers only.
* KDirModel has setDropsAllowed for similar (but configurable) logic.
*/
#ifndef KDE_NO_DEPRECATED
KDE_DEPRECATED bool acceptsDrops() const;
#endif
/**
* Let's "KRun" this file !
* (e.g. when file is clicked or double-clicked or return is pressed)
*/
void run( QWidget* parentWidget = 0 ) const;
/**
* Returns the UDS entry. Used by the tree view to access all details
* by position.
* @return the UDS entry
*/
KIO::UDSEntry entry() const;
/**
* Used when updating a directory. marked == seen when refreshing.
* @return true if the file item is marked
*/
bool isMarked() const;
/**
* Marks the item.
* @see isMarked()
*/
void mark();
/**
* Unmarks the item.
* @see isMarked()
*/
void unmark();
/**
* Return true if this item is a regular file,
* false otherwise (directory, link, character/block device, fifo, socket)
* @since 4.3
*/
bool isRegularFile() const;
/**
* Somewhat like a comparison operator, but more explicit,
* and it can detect that two fileitems differ if any property of the file item
* has changed (file size, modification date, etc.). Two items are equal if
* all properties are equal. In contrast, operator== only compares URLs.
* @param item the item to compare
* @return true if all values are equal
*/
bool cmp( const KFileItem & item ) const;
/**
* Returns true if both items share the same URL.
*/
bool operator==(const KFileItem& other) const;
/**
* Returns true if both items do not share the same URL.
*/
bool operator!=(const KFileItem& other) const;
/**
* Converts this KFileItem to a QVariant, this allows to use KFileItem
* in QVariant() constructor
*/
operator QVariant() const;
/**
* This allows to associate some "extra" data to a KFileItem. As one
* KFileItem can be used by several objects (often views) which all need
* to add some data, you have to use a key to reference your extra data
* within the KFileItem.
*
* That way a KFileItem can hold and provide access to all those views
* separately.
*
* I.e. a KFileIconView that associates a KFileIconViewItem (an item suitable
* for use with QIconView) does
*
* \code
* kfileItem->setExtraData( this, iconViewItem );
* \endcode
*
* and can later access the iconViewItem by doing
*
* \code
* KFileIconViewItem *iconViewItem = static_cast<KFileIconViewItem*>( kfileItem->extraData( this ));
* \endcode
*
* This is usually more efficient then having every view associate data to
* items by using a separate QDict or QMap.
*
* Note: you have to remove and destroy the data you associated yourself
* when you don't need it anymore!
*
* @param key the key of the extra data
* @param value the value of the extra data
* @see extraData
* @see removeExtraData
*
* @deprecated use model/view (KDirModel) and you won't need this anymore
*/
#ifndef KDE_NO_DEPRECATED
KDE_DEPRECATED void setExtraData( const void *key, void *value );
#endif
/**
* Retrieves the extra data with the given @p key.
* @param key the key of the extra data
* @return the extra data associated to an item with @p key via
* setExtraData. 0L if nothing was associated with @p key.
* @see extraData
*
* @deprecated use model/view (KDirModel) and you won't need this anymore
*/
#ifndef KDE_NO_DEPRECATED
KDE_DEPRECATED const void * extraData( const void *key ) const;
#endif
/**
* Removes the extra data associated with an item via @p key.
* @param key the key of the extra data to remove
*
* @deprecated use model/view (KDirModel) and you won't need this anymore
*/
#ifndef KDE_NO_DEPRECATED
KDE_DEPRECATED void removeExtraData( const void *key );
#endif
/**
* Sets the metainfo of this item to @p info.
*
* Made const to avoid deep copy.
* @param info the new meta info
*/
void setMetaInfo( const KFileMetaInfo & info ) const;
/**
* Returns the metainfo of this item.
*
* (since 4.4.3) By default it uses the KFileMetaInfo::ContentInfo | KFileMetaInfo::TechnicalInfo.
* If you need more information, create your own KFileMetaInfo object and set it using setMetaInfo()
* @param autoget if true, the metainfo will automatically be created
* @param what how much metainfo you need to retrieve from the file (KFileMetaInfo::WhatFlag)
*/
KFileMetaInfo metaInfo(bool autoget = true,
int what = KFileMetaInfo::ContentInfo | KFileMetaInfo::TechnicalInfo) const;
/**
* @deprecated simply use '='
*/
#ifndef KDE_NO_DEPRECATED
KDE_DEPRECATED void assign( const KFileItem & item );
#endif
/**
* Reinitialize KFileItem with a new UDSEntry.
*
* Note: extra-data set with setExtraData() is not changed or deleted, so
* be careful what you do!
*
* KDirListerCache uses it to save new/delete calls by updating existing
* items that are otherwise not needed anymore.
*
* @param entry the UDSEntry to assign to this KFileItem
* @param url the file url
* @param delayedMimeTypes specifies if the mimetype of the given
* URL should be determined immediately or on demand
* @param urlIsDirectory specifies if the url is just the directory of the
* fileitem and the filename from the UDSEntry should be used.
*
* @deprecated why not just create another KFileItem and use operator=,
* now that it's a value class?
*/
#ifndef KDE_NO_DEPRECATED
KDE_DEPRECATED void setUDSEntry( const KIO::UDSEntry& entry, const KUrl& url,
bool delayedMimeTypes = false,
bool urlIsDirectory = false );
#endif
/**
* Tries to give a local URL for this file item if possible.
* The given boolean indicates if the returned url is local or not.
*/
KUrl mostLocalUrl(bool &local) const; // KDE4 TODO: bool* local = 0
/**
* Tries to give a local URL for this file item if possible.
*
* \since 4.6
*/
KUrl mostLocalUrl() const; // KDE5: merge with above version
/**
* Return true if default-constructed
*/
bool isNull() const;
private:
QSharedDataPointer<KFileItemPrivate> d;
private:
KIO_EXPORT friend QDataStream & operator<< ( QDataStream & s, const KFileItem & a );
KIO_EXPORT friend QDataStream & operator>> ( QDataStream & s, KFileItem & a );
friend class KFileItemTest;
};
Q_DECLARE_METATYPE(KFileItem)
Q_CORE_EXPORT uint qHash(const QString &key);
inline uint qHash(const KFileItem& item){ return qHash(item.url().url()); }
/**
* List of KFileItems, which adds a few helper
* methods to QList<KFileItem>.
*/
class KIO_EXPORT KFileItemList : public QList<KFileItem>
{
public:
/// Creates an empty list of file items.
KFileItemList();
/// Creates a new KFileItemList from a QList of file @p items.
KFileItemList( const QList<KFileItem> &items );
/**
* Find a KFileItem by name and return it.
* @return the item with the given name, or a null-item if none was found
* (see KFileItem::isNull())
*/
KFileItem findByName( const QString& fileName ) const;
/**
* Find a KFileItem by URL and return it.
* @return the item with the given URL, or a null-item if none was found
* (see KFileItem::isNull())
*/
KFileItem findByUrl( const KUrl& url ) const;
/// @return the list of URLs that those items represent
KUrl::List urlList() const;
/// @return the list of target URLs that those items represent
/// @since 4.2
KUrl::List targetUrlList() const;
// TODO KDE-5 add d pointer here so that we can merge KFileItemListProperties into KFileItemList
};
KIO_EXPORT QDataStream & operator<< ( QDataStream & s, const KFileItem & a );
KIO_EXPORT QDataStream & operator>> ( QDataStream & s, KFileItem & a );
/**
* Support for qDebug() << aFileItem
* \since 4.4
*/
KIO_EXPORT QDebug operator<<(QDebug stream, const KFileItem& item);
#endif