home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / kfileitem.h < prev    next >
Encoding:
C/C++ Source or Header  |  2005-10-10  |  19.7 KB  |  672 lines
  1. /* This file is part of the KDE project
  2.    Copyright (C) 1999 David Faure <faure@kde.org>
  3.  
  4.    This library is free software; you can redistribute it and/or
  5.    modify it under the terms of the GNU Library General Public
  6.    License as published by the Free Software Foundation; either
  7.    version 2 of the License, or (at your option) any later version.
  8.  
  9.    This library is distributed in the hope that it will be useful,
  10.    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11.    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12.    Library General Public License for more details.
  13.  
  14.    You should have received a copy of the GNU Library General Public License
  15.    along with this library; see the file COPYING.LIB.  If not, write to
  16.    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  17.    Boston, MA 02110-1301, USA.
  18. */
  19.  
  20. #ifndef __kfileitem_h__
  21. #define __kfileitem_h__
  22.  
  23. #include <qstringlist.h>
  24. #include <sys/stat.h>
  25.  
  26. #include <qptrlist.h>
  27. #include <kio/global.h>
  28. #include <kurl.h>
  29. #include <kacl.h>
  30. #include <kmimetype.h>
  31. #include <kfilemetainfo.h>
  32.  
  33. #define KFILEITEM_HAS_ISWRITABLE // only used in libkonq/konq_iconviewwidget.cc, will be removed for 3.4
  34.  
  35. /**
  36.  * A KFileItem is a generic class to handle a file, local or remote.
  37.  * In particular, it makes it easier to handle the result of KIO::listDir
  38.  * (UDSEntry isn't very friendly to use).
  39.  * It includes many file attributes such as mimetype, icon, text, mode, link...
  40.  */
  41. class KIO_EXPORT KFileItem
  42. {
  43. public:
  44.   enum { Unknown = (mode_t) - 1 };
  45.  
  46.   /**
  47.    * Creates an item representing a file, from a UDSEntry.
  48.    * This is the preferred constructor when using KIO::listDir().
  49.    *
  50.    * @param _entry the KIO entry used to get the file, contains info about it
  51.    * @param _url the file url
  52.    * @param _determineMimeTypeOnDemand specifies if the mimetype of the given
  53.    *       URL should be determined immediately or on demand
  54.    * @param _urlIsDirectory specifies if the url is just the directory of the
  55.    *       fileitem and the filename from the UDSEntry should be used.
  56.    */
  57.   KFileItem( const KIO::UDSEntry& _entry, const KURL& _url,
  58.              bool _determineMimeTypeOnDemand = false,
  59.              bool _urlIsDirectory = false );
  60.  
  61.   /**
  62.    * Creates an item representing a file, from all the necessary info for it.
  63.    * @param _mode the file mode (according to stat() (e.g. S_IFDIR...)
  64.    * Set to KFileItem::Unknown if unknown. For local files, KFileItem will use stat().
  65.    * @param _permissions the access permissions
  66.    * If you set both the mode and the permissions, you save a ::stat() for
  67.    * local files.
  68.    * Set to KFileItem::Unknown if you don't know the mode or the permission.
  69.    * @param _url the file url
  70.    *
  71.    * @param _determineMimeTypeOnDemand specify if the mimetype of the given URL
  72.    *       should be determined immediately or on demand
  73.    */
  74.   KFileItem( mode_t _mode, mode_t _permissions, const KURL& _url,
  75.              bool _determineMimeTypeOnDemand = false );
  76.  
  77.   /**
  78.    * Creates an item representing a file, for which the mimetype is already known.
  79.    * @param url the file url
  80.    * @param mimeType the name of the file's mimetype
  81.    * @param mode the mode (S_IFDIR...)
  82.    */
  83.   KFileItem( const KURL &url, const QString &mimeType, mode_t mode );
  84.  
  85.   /**
  86.    * Copy constructor. Note that extra-data set via setExtraData() is not
  87.    * deeply copied -- just the pointers are copied.
  88.    */
  89.   KFileItem( const KFileItem &item );
  90.  
  91.   /**
  92.    * Destructs the KFileItem. Extra data set via setExtraData()
  93.    * is not deleted.
  94.    */
  95.   virtual ~KFileItem();
  96.  
  97.   /**
  98.    * Throw away and re-read (for local files) all information about the file.
  99.    * This is called when the _file_ changes.
  100.    */
  101.   void refresh();
  102.  
  103.   /**
  104.    * Re-reads mimetype information.
  105.    * This is called when the mimetype database changes.
  106.    */
  107.   void refreshMimeType();
  108.  
  109.   /**
  110.    * Returns the url of the file.
  111.    * @return the url of the file
  112.    */
  113.   const KURL & url() const { return m_url; }
  114.  
  115.   /**
  116.    * Sets the item's URL. Do not call unless you know what you are doing!
  117.    * (used for example when an item got renamed).
  118.    * @param url the item's URL
  119.    */
  120.   void setURL( const KURL &url );
  121.  
  122.   /**
  123.    * Sets the item's name (i.e. the filename).
  124.    * This is automatically done by setURL, to set the name from the URL's fileName().
  125.    * This method is provided for some special cases like relative paths as names (KFindPart)
  126.    * @param name the item's name
  127.    */
  128.   void setName( const QString &name );
  129.  
  130.   /**
  131.    * Returns the permissions of the file (stat.st_mode containing only permissions).
  132.    * @return the permissions of the file
  133.    */
  134.   mode_t permissions() const { return m_permissions; }
  135.  
  136.   /**
  137.    * Returns the access permissions for the file as a string.
  138.    * @return the access persmission as string
  139.    */
  140.   QString permissionsString() const;
  141.  
  142.   /**
  143.    * Tells if the file has extended access level information ( Posix ACL )
  144.    * @return true if the file has extend ACL information or false if it hasn't
  145.    * @since 3.5
  146.   */
  147.   bool hasExtendedACL() const;
  148.  
  149.   /**
  150.    * Returns the access control list for the file.
  151.    * @return the access control list as a KACL
  152.    * @since 3.5
  153.    */
  154.   KACL ACL() const;
  155.  
  156.   /**
  157.    * Returns the default access control list for the directory.
  158.    * @return the default access control list as a KACL
  159.    * @since 3.5
  160.    */
  161.   KACL defaultACL() const;
  162.  
  163.   /**
  164.    * Returns the file type (stat.st_mode containing only S_IFDIR, S_IFLNK, ...).
  165.    * @return the file type
  166.    */
  167.   mode_t mode() const { return m_fileMode; }
  168.  
  169.   /**
  170.    * Returns the owner of the file.
  171.    * @return the file's owner
  172.    */
  173.   QString user() const;
  174.  
  175.   /**
  176.    * Returns the group of the file.
  177.    * @return the file's group
  178.    */
  179.   QString group() const;
  180.  
  181.   /**
  182.    * Returns true if this item represents a link in the UNIX sense of
  183.    * a link.
  184.    * @return true if the file is a link
  185.    */
  186.   bool isLink() const { return m_bLink; }
  187.  
  188.   /**
  189.    * Returns true if this item represents a directory.
  190.    * @return true if the item is a directory
  191.    */
  192.   bool isDir() const;
  193.  
  194.   /**
  195.    * Returns true if this item represents a file (and not a a directory)
  196.    * @return true if the item is a file
  197.    */
  198.   bool isFile() const { return !isDir(); }
  199.  
  200.   /**
  201.    * Checks whether the file or directory is readable. In some cases
  202.    * (remote files), we may return true even though it can't be read.
  203.    * @return true if the file can be read - more precisely,
  204.    *         false if we know for sure it can't
  205.    */
  206.   bool isReadable() const;
  207.  
  208.   /**
  209.    * Checks whether the file or directory is writable. In some cases
  210.    * (remote files), we may return true even though it can't be written to.
  211.    * @return true if the file or directory can be written to - more precisely,
  212.    *         false if we know for sure it can't
  213.    * @since 3.4
  214.    */
  215.   bool isWritable() const;
  216.  
  217.     /**
  218.    * Checks whether the file is hidden.
  219.    * @return true if the file is hidden.
  220.    */
  221.   bool isHidden() const;
  222.  
  223.   /**
  224.    * Returns the link destination if isLink() == true.
  225.    * @return the link destination. QString::null if the item is not a link
  226.    */
  227.   QString linkDest() const;
  228.  
  229.   /**
  230.    * Returns the local path if isLocalFile() == true or the KIO item has
  231.    * a UDS_LOCAL_PATH atom.
  232.    * @return the item local path, or QString::null if not known
  233.    * @since 3.4
  234.    */
  235.   QString localPath() const;
  236.  
  237.   //FIXME KDE4 deprecate this in favor of size(bool &hasSize)
  238.   /**
  239.    * Returns the size of the file, if known.
  240.    * @return the file size, or 0 if not known
  241.    */
  242.   KIO::filesize_t size() const;
  243.  
  244.   /**
  245.    * Returns the size of the file, if known, and sets @p hasSize to false if not known
  246.    * @param @hasSize This is set to true if the size is known, and false if not known
  247.    * @return the file size, or 0 if not known
  248.    */ 
  249.   KIO::filesize_t size(bool &hasSize) const;
  250.   
  251.   //FIXME KDE4 deprecate this in favor of time(unsigned int which, bool &hasSize)
  252.   /**
  253.    * Requests the modification, access or creation time, depending on @p which.
  254.    * @param which UDS_MODIFICATION_TIME, UDS_ACCESS_TIME or UDS_CREATION_TIME
  255.    * @return the time asked for, (time_t)0 if not available
  256.    * @see timeString()
  257.    */
  258.   time_t time( unsigned int which ) const;
  259.  
  260.   /**
  261.    * Requests the modification, access or creation time, depending on @p which.
  262.    * @param which UDS_MODIFICATION_TIME, UDS_ACCESS_TIME or UDS_CREATION_TIME
  263.    * @param hasTime This is set to true is the time is known, and false if not known
  264.    * @return the time asked for, (time_t)0 if not known/available
  265.    * @see timeString()
  266.    */
  267.   time_t time( unsigned int which, bool &hasTime ) const;
  268.  
  269.   /**
  270.    * Requests the modification, access or creation time as a string, depending
  271.    * on @p which.
  272.    * @param which UDS_MODIFICATION_TIME, UDS_ACCESS_TIME or UDS_CREATION_TIME
  273.    * @returns a formatted string of the requested time, QString::null if time is not known
  274.    * @see time
  275.    */
  276.   QString timeString( unsigned int which = KIO::UDS_MODIFICATION_TIME ) const;
  277.  
  278.   /**
  279.    * Returns true if the file is a local file.
  280.    * @return true if the file is local, false otherwise
  281.    */
  282.   bool isLocalFile() const { return m_bIsLocalURL; }
  283.  
  284.   /**
  285.    * Returns the text of the file item.
  286.    * It's not exactly the filename since some decoding happens ('%2F'->'/').
  287.    * @return the text of the file item
  288.    */
  289.   const QString& text() const { return m_strText; }
  290.  
  291.   /**
  292.    * Return the name of the file item (without a path).
  293.    * Similar to text(), but unencoded, i.e. the original name.
  294.    * @param lowerCase if true, the name will be returned in lower case,
  295.    * which is useful to speed up sorting by name, case insensitively.
  296.    * @return the file's name
  297.    */
  298.   const QString& name( bool lowerCase = false ) const {
  299.       if ( !lowerCase )
  300.           return m_strName;
  301.       else
  302.           if ( m_strLowerCaseName.isNull() )
  303.               m_strLowerCaseName = m_strName.lower();
  304.       return m_strLowerCaseName;
  305.   }
  306.  
  307.   /**
  308.    * Returns the mimetype of the file item.
  309.    * If @p _determineMimeTypeOnDemand was used in the constructor, this will determine
  310.    * the mimetype first. Equivalent to determineMimeType()->name()
  311.    * @return the mime type of the file
  312.    */
  313.   QString mimetype() const;
  314.  
  315.   /**
  316.    * Returns the mimetype of the file item.
  317.    * If _determineMimeTypeOnDemand was used in the constructor, this will determine
  318.    * the mimetype first.
  319.    * @return the mime type
  320.    */
  321.   KMimeType::Ptr determineMimeType();
  322.  
  323.   /**
  324.    * Returns the currently known mimetype of the file item.
  325.    * This will not try to determine the mimetype if unknown.
  326.    * @return the known mime type
  327.    */
  328.   KMimeType::Ptr mimeTypePtr() const { return m_pMimeType; }
  329.  
  330.   bool isMimeTypeKnown() const;
  331.   /**
  332.    * Returns the descriptive comment for this mime type, or
  333.    * the mime type itself if none is present.
  334.    * @return the mime type description, or the mime type itself
  335.    */
  336.   QString mimeComment();
  337.  
  338.   /**
  339.    * Returns the full path name to the icon that represents
  340.    * this mime type.
  341.    * @return iconName the name of the file's icon
  342.    */
  343.   QString iconName();
  344.  
  345.   /**
  346.    * Returns a pixmap representing the file.
  347.    * @param _size Size for the pixmap in pixels. Zero will return the
  348.    * globally configured default size.
  349.    * @param _state The state of the icon: KIcon::DefaultState,
  350.    * KIcon::ActiveState or KIcon::DisabledState.
  351.    * @return the pixmap
  352.    */
  353.   QPixmap pixmap( int _size, int _state=0 ) const;
  354.  
  355.   /**
  356.    * Returns the overlays (bitfield of KIcon::*Overlay flags) that are used
  357.    * for this item's pixmap. Overlays are used to show for example, whether
  358.    * a file can be modified.
  359.    * @return the overlays of the pixmap
  360.    */
  361.   int overlays() const;
  362.  
  363.   /**
  364.    * Returns the string to be displayed in the statusbar,
  365.    * e.g. when the mouse is over this item
  366.    * @return the status bar information
  367.    */
  368.   QString getStatusBarInfo();
  369.  
  370.   /**
  371.    * Returns the string to be displayed in the tool tip when the mouse
  372.    * is over this item. This may load a plugin to determine additional
  373.    * information specific to the mimetype of the file.
  374.    *
  375.    * @param maxcount the maximum number of entries shown
  376.    * @return the tool tip string
  377.    */
  378.   QString getToolTipText(int maxcount = 6);
  379.  
  380.   /**
  381.    * Returns true if files can be dropped over this item.
  382.    * Contrary to popular belief, not only dirs will return true :)
  383.    * Executables, .desktop files, will do so as well.
  384.    * @return true if you can drop files over the item
  385.    */
  386.   bool acceptsDrops( );
  387.  
  388.   /**
  389.    * Let's "KRun" this file !
  390.    * (e.g. when file is clicked or double-clicked or return is pressed)
  391.    */
  392.   void run();
  393.  
  394.   /**
  395.    * Returns the UDS entry. Used by the tree view to access all details
  396.    * by position.
  397.    * @return the UDS entry
  398.    */
  399.   const KIO::UDSEntry & entry() const { return m_entry; }
  400.  
  401.   /**
  402.    * Used when updating a directory. marked == seen when refreshing.
  403.    * @return true if the file item is marked
  404.    */
  405.   bool isMarked() const { return m_bMarked; }
  406.   /**
  407.    * Marks the item.
  408.    * @see isMarked()
  409.    */
  410.   void mark() { m_bMarked = true; }
  411.   /**
  412.    * Unmarks the item.
  413.    * @see isMarked()
  414.    */
  415.   void unmark() { m_bMarked = false; }
  416.  
  417.   /**
  418.    * Somewhat like a comparison operator, but more explicit.
  419.    * @param item the item to compare
  420.    * @return true if all values are equal
  421.    */
  422.   bool cmp( const KFileItem & item );
  423.  
  424.   /**
  425.    * This allows to associate some "extra" data to a KFileItem. As one
  426.    * KFileItem can be used by several objects (often views) which all need
  427.    * to add some data, you have to use a key to reference your extra data
  428.    * within the KFileItem.
  429.    *
  430.    * That way a KFileItem can hold and provide access to all those views
  431.    * separately.
  432.    *
  433.    * I.e. a KFileIconView that associates a KFileIconViewItem (an item suitable
  434.    * for use with QIconView) does
  435.    *
  436.    * \code
  437.    * kfileItem->setExtraData( this, iconViewItem );
  438.    * \endcode
  439.    *
  440.    * and can later access the iconViewItem by doing
  441.    *
  442.    * \code
  443.    * KFileIconViewItem *iconViewItem = static_cast<KFileIconViewItem*>( kfileItem->extraData( this ));
  444.    * \endcode
  445.    *
  446.    * This is usually more efficient then having every view associate data to
  447.    * items by using a separate QDict or QMap.
  448.    *
  449.    * Note: you have to remove and destroy the data you associated yourself
  450.    * when you don't need it anymore!
  451.    *
  452.    * @param key the key of the extra data
  453.    * @param value the value of the extra data
  454.    * @see extraData
  455.    * @see removeExtraData
  456.    */
  457.   virtual void setExtraData( const void *key, void *value );
  458.  
  459.   /**
  460.    * Retrieves the extra data with the given @p key.
  461.    * @param key the key of the extra data
  462.    * @return the extra data associated to an item with @p key via
  463.    * setExtraData. 0L if nothing was associated with @p key.
  464.    * @see extraData
  465.    */
  466.   virtual const void * extraData( const void *key ) const;
  467.  
  468.   /**
  469.    * Retrieves the extra data with the given @p key.
  470.    * @param key the key of the extra data
  471.    * @return the extra data associated to an item with @p key via
  472.    * setExtraData. 0L if nothing was associated with @p key.
  473.    * @see extraData
  474.    */
  475.   virtual void * extraData( const void *key );
  476.  
  477.   /**
  478.    * Removes the extra data associated with an item via @p key.
  479.    * @param key the key of the extra data to remove
  480.    */
  481.   virtual void removeExtraData( const void *key );
  482.  
  483.   /**
  484.    * Sets the metainfo of this item to @p info.
  485.    * @param info the new meta info
  486.    */
  487.   void setMetaInfo( const KFileMetaInfo & info );
  488.  
  489.   /**
  490.    * Sets the file type (stat.st_mode containing only S_IFDIR, S_IFLNK, ...).
  491.    * @param m the new file type
  492.    * @since 3.5.0
  493.    * @todo Actually explain what this does -- does setting S_IFDIR
  494.    *       mean the file type is set to Directory?
  495.    */
  496.    void setFileMode( mode_t m );
  497.  
  498.   /**
  499.    * Sets new mimetype for item
  500.    * @param mimetype the new mimetype
  501.    * @since 3.5.0
  502.    */
  503.    void setMimeType( const QString& mimetype );
  504.  
  505.   /**
  506.    * Returns the metainfo of this item.
  507.    * @param autoget if true, the metainfo will automatically be created
  508.    * @param what ignored
  509.    */
  510.   const KFileMetaInfo & metaInfo(bool autoget = true,
  511.                                  int what = KFileMetaInfo::Fastest) const;
  512.  
  513.   /**
  514.    * Somewhat like an assignment operator, but more explicit.
  515.    * Note: extra-data set with setExtraData() is not copied, so be careful
  516.    * what you do!
  517.    *
  518.    * @param item the item to copy
  519.    */
  520.   void assign( const KFileItem & item );
  521.  
  522.   /**
  523.    * Reinitialize KFileItem with a new UDSEntry.
  524.    *
  525.    * Note: extra-data set with setExtraData() is not changed or deleted, so
  526.    * be careful what you do!
  527.    *
  528.    * KDirListerCache uses it to save new/delete calls by updating existing
  529.    * items that are otherwise not needed anymore.
  530.    *
  531.    * @param entry the UDSEntry to assign to this KFileItem
  532.    * @param url the file url
  533.    * @param determineMimeTypeOnDemand specifies if the mimetype of the given
  534.    *        URL should be determined immediately or on demand
  535.    * @param urlIsDirectory specifies if the url is just the directory of the
  536.    *        fileitem and the filename from the UDSEntry should be used.
  537.    * @since 3.4.1
  538.    */
  539.   void setUDSEntry( const KIO::UDSEntry& entry, const KURL& url,
  540.                     bool determineMimeTypeOnDemand = false,
  541.                     bool urlIsDirectory = false );
  542.  
  543.   /**
  544.    * Assignment operator, calls assign()
  545.    */
  546.   KFileItem& operator=( const KFileItem& );
  547.  
  548.   /**
  549.    * Tries to give a local URL for this file item if possible.
  550.    * The given boolean indicates if the returned url is local or not.
  551.    */
  552.   KURL mostLocalURL(bool &local) const;
  553.  
  554.   /////////////
  555.  
  556. protected:
  557.   /**
  558.    * Computes the text, mode, and mimetype from the UDSEntry
  559.    * Called by constructor, but can be called again later
  560.    */
  561.   void init( bool _determineMimeTypeOnDemand );
  562.  
  563.   /**
  564.    * Extracts the data from the UDSEntry member and updates the KFileItem
  565.    * accordingly.
  566.    * @since 3.4.1
  567.    */
  568.   void readUDSEntry( bool _urlIsDirectory );
  569.  
  570.   /**
  571.    * Parses the given permission set and provides it for access()
  572.    */
  573.   QString parsePermissions( mode_t perm ) const;
  574.  
  575. private:
  576.   /**
  577.    * We keep a copy of the UDSEntry since we need it for getStatusBarInfo
  578.    */
  579.   KIO::UDSEntry m_entry;
  580.   /**
  581.    * The url of the file
  582.    */
  583.   KURL m_url;
  584.  
  585.   /**
  586.    * The text for this item, i.e. the file name without path,
  587.    */
  588.   QString m_strName;
  589.  
  590.   /**
  591.    * The text for this item, i.e. the file name without path, decoded
  592.    * ('%%' becomes '%', '%2F' becomes '/')
  593.    */
  594.   QString m_strText;
  595.  
  596.   /**
  597.    * the user and group assigned to the file.
  598.    */
  599.   mutable QString m_user, m_group;
  600.  
  601.   /**
  602.    * The filename in lower case (to speed up sorting)
  603.    */
  604.   mutable QString m_strLowerCaseName;
  605.  
  606.   /**
  607.    * The mimetype of the file
  608.    */
  609.   KMimeType::Ptr m_pMimeType;
  610.  
  611.   /**
  612.    * The file mode
  613.    */
  614.   mode_t m_fileMode;
  615.   /**
  616.    * The permissions
  617.    */
  618.   mode_t m_permissions;
  619.  
  620.   /**
  621.    * Marked : see mark()
  622.    */
  623.   bool m_bMarked:1;
  624.   /**
  625.    * Whether the file is a link
  626.    */
  627.   bool m_bLink:1;
  628.   /**
  629.    * True if local file
  630.    */
  631.   bool m_bIsLocalURL:1;
  632.  
  633.   bool m_bMimeTypeKnown:1;
  634.  
  635.   // Auto: check leading dot.
  636.   enum { Auto, Hidden, Shown } m_hidden:3;
  637.  
  638.    // For special case like link to dirs over FTP
  639.   QString m_guessedMimeType;
  640.   mutable QString m_access;
  641.   QMap<const void*, void*> m_extra;
  642.   mutable KFileMetaInfo m_metaInfo;
  643.  
  644.   enum { Modification = 0, Access = 1, Creation = 2, NumFlags = 3 };
  645.   mutable time_t m_time[3];
  646.   mutable KIO::filesize_t m_size;
  647.  
  648. protected:
  649.   virtual void virtual_hook( int id, void* data );
  650. private:
  651.   class KFileItemPrivate;
  652.   KFileItemPrivate * d;
  653.   KIO_EXPORT friend QDataStream & operator<< ( QDataStream & s, const KFileItem & a );
  654.   KIO_EXPORT friend QDataStream & operator>> ( QDataStream & s, KFileItem & a );
  655. };
  656.  
  657. /**
  658.  * List of KFileItems
  659.  */
  660. typedef QPtrList<KFileItem> KFileItemList;
  661.  
  662. /**
  663.  * Iterator for KFileItemList
  664.  */
  665. typedef QPtrListIterator<KFileItem> KFileItemListIterator;
  666.  
  667. KIO_EXPORT QDataStream & operator<< ( QDataStream & s, const KFileItem & a );
  668. KIO_EXPORT QDataStream & operator>> ( QDataStream & s, KFileItem & a );
  669.  
  670.  
  671. #endif
  672.