/* This file is part of the KDE project Copyright (C) 1999 David Faure 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 #include #include #include #include #include #include #include #define TDEFILEITEM_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 TDEIO 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 ); /** * Returns the lister url of the file. * @return the lister url of the file * @internal */ const KURL & listerURL() const { return m_listerURL; } /** * Sets the item's lister URL. Do not call unless you know what you are doing! * @param url the item's lister URL * @internal */ void setListerURL( 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 TDEIO 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: TDEIcon::DefaultState, * TDEIcon::ActiveState or TDEIcon::DisabledState. * @return the pixmap */ TQPixmap pixmap( int _size, int _state=0 ) const; /** * Returns the overlays (bitfield of TDEIcon::*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( 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 lister url of the file */ KURL m_listerURL; /** * 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 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 KFileItemList; /** * Iterator for KFileItemList */ typedef TQPtrListIterator KFileItemListIterator; TDEIO_EXPORT TQDataStream & operator<< ( TQDataStream & s, const KFileItem & a ); TDEIO_EXPORT TQDataStream & operator>> ( TQDataStream & s, KFileItem & a ); #endif