diff options
Diffstat (limited to 'tdeio/tdeio/tdefileitem.h')
| -rw-r--r-- | tdeio/tdeio/tdefileitem.h | 671 |
1 files changed, 671 insertions, 0 deletions
diff --git a/tdeio/tdeio/tdefileitem.h b/tdeio/tdeio/tdefileitem.h new file mode 100644 index 000000000..7097d7bc5 --- /dev/null +++ b/tdeio/tdeio/tdefileitem.h @@ -0,0 +1,671 @@ +/* This file is part of the KDE project + Copyright (C) 1999 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 __tdefileitem_h__ +#define __tdefileitem_h__ + +#include <tqstringlist.h> +#include <sys/stat.h> + +#include <tqptrlist.h> +#include <tdeio/global.h> +#include <kurl.h> +#include <kacl.h> +#include <kmimetype.h> +#include <tdefilemetainfo.h> + +#define KFILEITEM_HAS_ISWRITABLE // only used in libkonq/konq_iconviewwidget.cc, will be removed for 3.4 + +/** + * A KFileItem is a generic class to handle a file, local or remote. + * In particular, it makes it easier to handle the result of TDEIO::listDir + * (UDSEntry isn't very friendly to use). + * It includes many file attributes such as mimetype, icon, text, mode, link... + */ +class TDEIO_EXPORT KFileItem +{ +public: + enum { Unknown = (mode_t) - 1 }; + + /** + * Creates an item representing a file, from a UDSEntry. + * This is the preferred constructor when using TDEIO::listDir(). + * + * @param _entry the KIO entry used to get the file, contains info about it + * @param _url the file url + * @param _determineMimeTypeOnDemand 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. + */ + KFileItem( const TDEIO::UDSEntry& _entry, const KURL& _url, + bool _determineMimeTypeOnDemand = 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 _determineMimeTypeOnDemand 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 _determineMimeTypeOnDemand = 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 TQString &mimeType, mode_t mode ); + + /** + * Copy constructor. Note that extra-data set via setExtraData() is not + * deeply copied -- just the pointers are copied. + */ + KFileItem( const KFileItem &item ); + + /** + * Destructs the KFileItem. Extra data set via setExtraData() + * is not deleted. + */ + virtual ~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 + */ + const KURL & url() const { return m_url; } + + /** + * 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 TQString &name ); + + /** + * Returns the permissions of the file (stat.st_mode containing only permissions). + * @return the permissions of the file + */ + mode_t permissions() const { return m_permissions; } + + /** + * Returns the access permissions for the file as a string. + * @return the access persmission as string + */ + TQString 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 + * @since 3.5 + */ + bool hasExtendedACL() const; + + /** + * Returns the access control list for the file. + * @return the access control list as a KACL + * @since 3.5 + */ + KACL ACL() const; + + /** + * Returns the default access control list for the directory. + * @return the default access control list as a KACL + * @since 3.5 + */ + KACL defaultACL() const; + + /** + * Returns the file type (stat.st_mode containing only S_IFDIR, S_IFLNK, ...). + * @return the file type + */ + mode_t mode() const { return m_fileMode; } + + /** + * Returns the owner of the file. + * @return the file's owner + */ + TQString user() const; + + /** + * Returns the group of the file. + * @return the file's group + */ + TQString 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 { return m_bLink; } + + /** + * 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 { return !isDir(); } + + /** + * 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 + * @since 3.4 + */ + bool isWritable() const; + + /** + * Checks whether the file is hidden. + * @return true if the file is hidden. + */ + bool isHidden() const; + + /** + * Returns the link destination if isLink() == true. + * @return the link destination. TQString::null if the item is not a link + */ + TQString linkDest() const; + + /** + * Returns the local path if isLocalFile() == true or the KIO item has + * a UDS_LOCAL_PATH atom. + * @return the item local path, or TQString::null if not known + * @since 3.4 + */ + TQString localPath() const; + + //FIXME KDE4 deprecate this in favor of size(bool &hasSize) + /** + * Returns the size of the file, if known. + * @return the file size, or 0 if not known + */ + TDEIO::filesize_t size() const; + + /** + * Returns the size of the file, if known, and sets @p hasSize to false if not known + * @param @hasSize This is set to true if the size is known, and false if not known + * @return the file size, or 0 if not known + */ + TDEIO::filesize_t size(bool &hasSize) const; + + //FIXME KDE4 deprecate this in favor of time(unsigned int which, bool &hasSize) + /** + * Requests the modification, access or creation time, depending on @p which. + * @param which UDS_MODIFICATION_TIME, UDS_ACCESS_TIME or UDS_CREATION_TIME + * @return the time asked for, (time_t)0 if not available + * @see timeString() + */ + time_t time( unsigned int which ) const; + + /** + * Requests the modification, access or creation time, depending on @p which. + * @param which UDS_MODIFICATION_TIME, UDS_ACCESS_TIME or UDS_CREATION_TIME + * @param hasTime This is set to true is the time is known, and false if not known + * @return the time asked for, (time_t)0 if not known/available + * @see timeString() + */ + time_t time( unsigned int which, bool &hasTime ) const; + + /** + * Requests the modification, access or creation time as a string, depending + * on @p which. + * @param which UDS_MODIFICATION_TIME, UDS_ACCESS_TIME or UDS_CREATION_TIME + * @returns a formatted string of the requested time, TQString::null if time is not known + * @see time + */ + TQString timeString( unsigned int which = TDEIO::UDS_MODIFICATION_TIME ) const; + + /** + * Returns true if the file is a local file. + * @return true if the file is local, false otherwise + */ + bool isLocalFile() const { return m_bIsLocalURL; } + + /** + * 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 + */ + const TQString& text() const { return m_strText; } + + /** + * 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 + */ + const TQString& name( bool lowerCase = false ) const { + if ( !lowerCase ) + return m_strName; + else + if ( m_strLowerCaseName.isNull() ) + m_strLowerCaseName = m_strName.lower(); + return m_strLowerCaseName; + } + + /** + * Returns the mimetype of the file item. + * If @p _determineMimeTypeOnDemand was used in the constructor, this will determine + * the mimetype first. Equivalent to determineMimeType()->name() + * @return the mime type of the file + */ + TQString mimetype() const; + + /** + * Returns the mimetype of the file item. + * If _determineMimeTypeOnDemand was used in the constructor, this will determine + * the mimetype first. + * @return the mime type + */ + KMimeType::Ptr determineMimeType(); + + /** + * 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 m_pMimeType; } + + bool isMimeTypeKnown() const; + /** + * Returns the descriptive comment for this mime type, or + * the mime type itself if none is present. + * @return the mime type description, or the mime type itself + */ + TQString mimeComment(); + + /** + * Returns the full path name to the icon that represents + * this mime type. + * @return iconName the name of the file's icon + */ + TQString iconName(); + + /** + * 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: KIcon::DefaultState, + * KIcon::ActiveState or KIcon::DisabledState. + * @return the pixmap + */ + TQPixmap pixmap( int _size, int _state=0 ) const; + + /** + * Returns the overlays (bitfield of KIcon::*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 + */ + int overlays() const; + + /** + * Returns the string to be displayed in the statusbar, + * e.g. when the mouse is over this item + * @return the status bar information + */ + TQString getStatusBarInfo(); + + /** + * 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 + */ + TQString getToolTipText(int maxcount = 6); + + /** + * 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 + */ + bool acceptsDrops( ); + + /** + * Let's "KRun" this file ! + * (e.g. when file is clicked or double-clicked or return is pressed) + */ + void run(); + + /** + * Returns the UDS entry. Used by the tree view to access all details + * by position. + * @return the UDS entry + */ + const TDEIO::UDSEntry & entry() const { return m_entry; } + + /** + * Used when updating a directory. marked == seen when refreshing. + * @return true if the file item is marked + */ + bool isMarked() const { return m_bMarked; } + /** + * Marks the item. + * @see isMarked() + */ + void mark() { m_bMarked = true; } + /** + * Unmarks the item. + * @see isMarked() + */ + void unmark() { m_bMarked = false; } + + /** + * Somewhat like a comparison operator, but more explicit. + * @param item the item to compare + * @return true if all values are equal + */ + bool cmp( const KFileItem & item ); + + /** + * 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 TQIconView) does + * + * \code + * tdefileItem->setExtraData( this, iconViewItem ); + * \endcode + * + * and can later access the iconViewItem by doing + * + * \code + * KFileIconViewItem *iconViewItem = static_cast<KFileIconViewItem*>( tdefileItem->extraData( this )); + * \endcode + * + * This is usually more efficient then having every view associate data to + * items by using a separate TQDict or TQMap. + * + * 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 + */ + virtual void setExtraData( const void *key, void *value ); + + /** + * 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 + */ + virtual const void * extraData( const void *key ) const; + + /** + * 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 + */ + virtual void * extraData( const void *key ); + + /** + * Removes the extra data associated with an item via @p key. + * @param key the key of the extra data to remove + */ + virtual void removeExtraData( const void *key ); + + /** + * Sets the metainfo of this item to @p info. + * @param info the new meta info + */ + void setMetaInfo( const KFileMetaInfo & info ); + + /** + * Sets the file type (stat.st_mode containing only S_IFDIR, S_IFLNK, ...). + * @param m the new file type + * @since 3.5.0 + * @todo Actually explain what this does -- does setting S_IFDIR + * mean the file type is set to Directory? + */ + void setFileMode( mode_t m ); + + /** + * Sets new mimetype for item + * @param mimetype the new mimetype + * @since 3.5.0 + */ + void setMimeType( const TQString& mimetype ); + + /** + * Returns the metainfo of this item. + * @param autoget if true, the metainfo will automatically be created + * @param what ignored + */ + const KFileMetaInfo & metaInfo(bool autoget = true, + int what = KFileMetaInfo::Fastest) const; + + /** + * Somewhat like an assignment operator, but more explicit. + * Note: extra-data set with setExtraData() is not copied, so be careful + * what you do! + * + * @param item the item to copy + */ + void assign( const KFileItem & item ); + + /** + * 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 determineMimeTypeOnDemand 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. + * @since 3.4.1 + */ + void setUDSEntry( const TDEIO::UDSEntry& entry, const KURL& url, + bool determineMimeTypeOnDemand = false, + bool urlIsDirectory = false ); + + /** + * Assignment operator, calls assign() + */ + KFileItem& operator=( const KFileItem& ); + + /** + * 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; + + ///////////// + +protected: + /** + * Computes the text, mode, and mimetype from the UDSEntry + * Called by constructor, but can be called again later + */ + void init( bool _determineMimeTypeOnDemand ); + + /** + * Extracts the data from the UDSEntry member and updates the KFileItem + * accordingly. + * @since 3.4.1 + */ + void readUDSEntry( bool _urlIsDirectory ); + + /** + * Parses the given permission set and provides it for access() + */ + TQString parsePermissions( mode_t perm ) const; + +private: + /** + * We keep a copy of the UDSEntry since we need it for getStatusBarInfo + */ + TDEIO::UDSEntry m_entry; + /** + * The url of the file + */ + KURL m_url; + + /** + * The text for this item, i.e. the file name without path, + */ + TQString m_strName; + + /** + * The text for this item, i.e. the file name without path, decoded + * ('%%' becomes '%', '%2F' becomes '/') + */ + TQString m_strText; + + /** + * the user and group assigned to the file. + */ + mutable TQString m_user, m_group; + + /** + * The filename in lower case (to speed up sorting) + */ + mutable TQString m_strLowerCaseName; + + /** + * The mimetype of the file + */ + KMimeType::Ptr m_pMimeType; + + /** + * The file mode + */ + mode_t m_fileMode; + /** + * The permissions + */ + mode_t m_permissions; + + /** + * Marked : see mark() + */ + bool m_bMarked:1; + /** + * Whether the file is a link + */ + bool m_bLink:1; + /** + * True if local file + */ + bool m_bIsLocalURL:1; + + bool m_bMimeTypeKnown:1; + + // Auto: check leading dot. + enum { Auto, Hidden, Shown } m_hidden:3; + + // For special case like link to dirs over FTP + TQString m_guessedMimeType; + mutable TQString m_access; + TQMap<const void*, void*> m_extra; + mutable KFileMetaInfo m_metaInfo; + + enum { Modification = 0, Access = 1, Creation = 2, NumFlags = 3 }; + mutable time_t m_time[3]; + mutable TDEIO::filesize_t m_size; + +protected: + virtual void virtual_hook( int id, void* data ); +private: + class KFileItemPrivate; + KFileItemPrivate * d; + TDEIO_EXPORT friend TQDataStream & operator<< ( TQDataStream & s, const KFileItem & a ); + TDEIO_EXPORT friend TQDataStream & operator>> ( TQDataStream & s, KFileItem & a ); +}; + +/** + * List of KFileItems + */ +typedef TQPtrList<KFileItem> KFileItemList; + +/** + * Iterator for KFileItemList + */ +typedef TQPtrListIterator<KFileItem> KFileItemListIterator; + +TDEIO_EXPORT TQDataStream & operator<< ( TQDataStream & s, const KFileItem & a ); +TDEIO_EXPORT TQDataStream & operator>> ( TQDataStream & s, KFileItem & a ); + + +#endif |