File indexing completed on 2024-06-16 06:56:54

0001 /*
0002     This file is part of the KDE project
0003     SPDX-FileCopyrightText: 2006-2007, 2008 Fredrik Höglund <fredrik@kde.org>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef KFILEITEMDELEGATE_H
0009 #define KFILEITEMDELEGATE_H
0010 
0011 #include "kiowidgets_export.h"
0012 #include <QAbstractItemDelegate>
0013 #include <QTextOption>
0014 
0015 #include <memory>
0016 
0017 class QAbstractItemModel;
0018 class QAbstractItemView;
0019 class QHelpEvent;
0020 class QModelIndex;
0021 class QPainter;
0022 
0023 /**
0024  * @class KFileItemDelegate kfileitemdelegate.h <KFileItemDelegate>
0025  *
0026  * KFileItemDelegate is intended to be used to provide a KDE file system
0027  * view, when using one of the standard item views in Qt with KDirModel.
0028  *
0029  * While primarily intended to be used with KDirModel, it uses
0030  * Qt::DecorationRole and Qt::DisplayRole for the icons and text labels,
0031  * just like QItemDelegate, and can thus be used with any standard model.
0032  *
0033  * When used with KDirModel however, KFileItemDelegate can change the way
0034  * the display and/or decoration roles are drawn, based on properties
0035  * of the file items. For example, if the file item is a symbolic link,
0036  * it will use an italic font to draw the file name.
0037  *
0038  * KFileItemDelegate also supports showing additional information about
0039  * the file items below the icon labels.
0040  *
0041  * Which information should be shown, if any, is controlled by the
0042  * @ref information property, which is a list that can be set by calling
0043  * setShowInformation(), and read by calling showInformation().
0044  * By default this list is empty.
0045  *
0046  * To use KFileItemDelegate, instantiate an object from the delegate,
0047  * and call setItemDelegate() in one of the standard item views in Qt:
0048  *
0049  * @code
0050  * QListView *listview = new QListView(this);
0051  * KFileItemDelegate *delegate = new KFileItemDelegate(this);
0052  * listview->setItemDelegate(delegate);
0053  * @endcode
0054  */
0055 class KIOWIDGETS_EXPORT KFileItemDelegate : public QAbstractItemDelegate
0056 {
0057     Q_OBJECT
0058 
0059     /**
0060      * This property holds which additional information (if any) should be shown below
0061      * items in icon views.
0062      *
0063      * Access functions:
0064      * @li void setShownformation(InformationList information)
0065      * @li InformationList showInformation() const
0066      */
0067     Q_PROPERTY(InformationList information READ showInformation WRITE setShowInformation)
0068 
0069     /**
0070      * This property holds the color used for the text shadow.
0071      *
0072      * The alpha value in the color determines the opacity of the shadow.
0073      * Shadows are only rendered when the alpha value is non-zero.
0074      * The default value for this property is Qt::transparent.
0075      *
0076      * Access functions:
0077      * @li void setShadowColor(const QColor &color)
0078      * @li QColor shadowColor() const
0079      */
0080     Q_PROPERTY(QColor shadowColor READ shadowColor WRITE setShadowColor)
0081 
0082     /**
0083      * This property holds the horizontal and vertical offset for the text shadow.
0084      * The default value for this property is (1, 1).
0085      *
0086      * Access functions:
0087      * @li void setShadowOffset(const QPointF &offset)
0088      * @li QPointF shadowOffset() const
0089      */
0090     Q_PROPERTY(QPointF shadowOffset READ shadowOffset WRITE setShadowOffset)
0091 
0092     /**
0093      * This property holds the blur radius for the text shadow.
0094      * The default value for this property is 2.
0095      *
0096      * Access functions:
0097      * @li void setShadowBlur(qreal radius)
0098      * @li qreal shadowBlur() const
0099      */
0100     Q_PROPERTY(qreal shadowBlur READ shadowBlur WRITE setShadowBlur)
0101 
0102     /**
0103      * This property holds the maximum size that can be returned
0104      * by KFileItemDelegate::sizeHint(). If the maximum size is empty,
0105      * it will be ignored.
0106      */
0107     Q_PROPERTY(QSize maximumSize READ maximumSize WRITE setMaximumSize)
0108 
0109     /**
0110      * This property determines whether a tooltip will be shown by the delegate
0111      * if the display role is elided. This tooltip will contain the full display
0112      * role information. The tooltip will only be shown if the Qt::ToolTipRole differs
0113      * from Qt::DisplayRole, or if they match, showToolTipWhenElided flag is set and
0114      * the display role information is elided.
0115      */
0116     Q_PROPERTY(bool showToolTipWhenElided READ showToolTipWhenElided WRITE setShowToolTipWhenElided)
0117 
0118     /**
0119      * This property determines if there are KIO jobs on a destination URL visible, then
0120      * they will have a small animation overlay displayed on them.
0121      */
0122     Q_PROPERTY(bool jobTransfersVisible READ jobTransfersVisible WRITE setJobTransfersVisible)
0123 
0124 public:
0125     /**
0126      * This enum defines the additional information that can be displayed below item
0127      * labels in icon views.
0128      *
0129      * The information will only be shown for indexes for which the model provides
0130      * a valid value for KDirModel::FileItemRole, and only when there's sufficient vertical
0131      * space to display at least one line of the information, along with the display label.
0132      *
0133      * For the number of items to be shown for folders, the model must provide a valid
0134      * value for KDirMode::ChildCountRole, in addition to KDirModel::FileItemRole.
0135      *
0136      * Note that KFileItemDelegate will not call KFileItem::determineMimeType() if
0137      * KFileItem::isMimeTypeKnown() returns false, so if you want to display MIME types
0138      * you should use a KMimeTypeResolver with the model and the view, to ensure that MIME
0139      * types are resolved. If the MIME type isn't known, "Unknown" will be displayed until
0140      * the MIME type has been successfully resolved.
0141      *
0142      * @see setShowInformation()
0143      * @see showInformation()
0144      * @see information
0145      */
0146     enum Information {
0147         NoInformation, ///< No additional information will be shown for items.
0148         Size, ///< The file size for files, and the number of items for folders.
0149         Permissions, ///< A UNIX permissions string, e.g.\ -rwxr-xr-x.
0150         OctalPermissions, ///< The permissions as an octal value, e.g.\ 0644.
0151         Owner, ///< The user name of the file owner, e.g.\ root
0152         OwnerAndGroup, ///< The user and group that owns the file, e.g.\ root:root
0153         CreationTime, ///< The date and time the file/folder was created.
0154         ModificationTime, ///< The date and time the file/folder was last modified.
0155         AccessTime, ///< The date and time the file/folder was last accessed.
0156         MimeType, ///< The MIME type for the item, e.g.\ text/html.
0157         FriendlyMimeType, ///< The descriptive name for the MIME type, e.g.\ HTML Document.
0158         LinkDest, ///< The destination of a symbolic link. @since 4.5
0159         LocalPathOrUrl, ///< The local path to the file or the URL in case it is not a local file. @since 4.5
0160         Comment, ///< A simple comment that can be displayed to the user as is. @since 4.6
0161     };
0162     Q_ENUM(Information)
0163 
0164     typedef QList<Information> InformationList;
0165 
0166     /**
0167      * Constructs a new KFileItemDelegate.
0168      *
0169      * @param parent The parent object for the delegate.
0170      */
0171     explicit KFileItemDelegate(QObject *parent = nullptr);
0172 
0173     /**
0174      * Destroys the item delegate.
0175      */
0176     ~KFileItemDelegate() override;
0177 
0178     /**
0179      * Returns the nominal size for the item referred to by @p index, given the
0180      * provided options.
0181      *
0182      * If the model provides a valid Qt::FontRole and/or Qt::TextAlignmentRole for the item,
0183      * those will be used instead of the ones specified in the style options.
0184      *
0185      * This function is reimplemented from @ref QAbstractItemDelegate.
0186      *
0187      * @param option  The style options that should be used when painting the item.
0188      * @param index   The index to the item for which to return the size hint.
0189      */
0190     QSize sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const override;
0191 
0192     /**
0193      * Paints the item indicated by @p index, using @p painter.
0194      *
0195      * The item will be drawn in the rectangle specified by option.rect.
0196      * The correct size for that rectangle can be obtained by calling
0197      * @ref sizeHint().
0198      *
0199      * This function will use the following data values if the model provides
0200      * them for the item, in place of the values in @p option:
0201      *
0202      * @li Qt::FontRole           The font that should be used for the display role.
0203      * @li Qt::TextAlignmentRole  The alignment of the display role.
0204      * @li Qt::ForegroundRole     The text color for the display role.
0205      * @li Qt::BackgroundRole     The background color for the item.
0206      *
0207      * This function is reimplemented from @ref QAbstractItemDelegate.
0208      *
0209      * @param painter The painter with which to draw the item.
0210      * @param option  The style options that should be used when painting the item.
0211      * @param index   The index to the item that should be painted.
0212      */
0213     void paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override;
0214 
0215     /**
0216      * Reimplemented from @ref QAbstractItemDelegate.
0217      */
0218     QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const override;
0219 
0220     /**
0221      * Reimplemented from @ref QAbstractItemDelegate.
0222      */
0223     bool editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index) override;
0224 
0225     /**
0226      * Reimplemented from @ref QAbstractItemDelegate.
0227      */
0228     void setEditorData(QWidget *editor, const QModelIndex &index) const override;
0229 
0230     /**
0231      * Reimplemented from @ref QAbstractItemDelegate.
0232      */
0233     void setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const override;
0234 
0235     /**
0236      * Reimplemented from @ref QAbstractItemDelegate.
0237      */
0238     void updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const override;
0239 
0240     /**
0241      * Sets the list of information lines that are shown below the icon label in list views.
0242      *
0243      * You will typically construct the list like this:
0244      * @code
0245      * KFileItemDelegate::InformationList list;
0246      * list << KFileItemDelegate::FriendlyMimeType << KFileItemDelegate::Size;
0247      * delegate->setShowInformation(list);
0248      * @endcode
0249      *
0250      * The information lines will be displayed in the list order.
0251      * The delegate will first draw the item label, and then as many information
0252      * lines as will fit in the available space.
0253      *
0254      * @param list A list of information items that should be shown
0255      */
0256     void setShowInformation(const InformationList &list);
0257 
0258     /**
0259      * Sets a single information line that is shown below the icon label in list views.
0260      *
0261      * This is a convenience function for when you only want to show a single line
0262      * of information.
0263      *
0264      * @param information The information that should be shown
0265      */
0266     void setShowInformation(Information information);
0267 
0268     /**
0269      * Returns the file item information that should be shown below item labels in list views.
0270      */
0271     InformationList showInformation() const;
0272 
0273     /**
0274      * Sets the color used for drawing the text shadow.
0275      *
0276      * To enable text shadows, set the shadow color to a non-transparent color.
0277      * To disable text shadows, set the color to Qt::transparent.
0278      *
0279      * @see shadowColor()
0280      */
0281     void setShadowColor(const QColor &color);
0282 
0283     /**
0284      * Returns the color used for the text shadow.
0285      *
0286      * @see setShadowColor()
0287      */
0288     QColor shadowColor() const;
0289 
0290     /**
0291      * Sets the horizontal and vertical offset for the text shadow.
0292      *
0293      * @see shadowOffset()
0294      */
0295     void setShadowOffset(const QPointF &offset);
0296 
0297     /**
0298      * Returns the offset used for the text shadow.
0299      *
0300      * @see setShadowOffset()
0301      */
0302     QPointF shadowOffset() const;
0303 
0304     /**
0305      * Sets the blur radius for the text shadow.
0306      *
0307      * @see shadowBlur()
0308      */
0309     void setShadowBlur(qreal radius);
0310 
0311     /**
0312      * Returns the blur radius for the text shadow.
0313      *
0314      * @see setShadowBlur()
0315      */
0316     qreal shadowBlur() const;
0317 
0318     /**
0319      * Sets the maximum size for KFileItemDelegate::sizeHint().
0320      *
0321      * @see maximumSize()
0322      */
0323     void setMaximumSize(const QSize &size);
0324 
0325     /**
0326      * Returns the maximum size for KFileItemDelegate::sizeHint().
0327      *
0328      * @see setMaximumSize()
0329      */
0330     QSize maximumSize() const;
0331 
0332     /**
0333      * Sets whether a tooltip should be shown if the display role is
0334      * elided containing the full display role information.
0335      *
0336      * @note The tooltip will only be shown if the Qt::ToolTipRole differs
0337      *       from Qt::DisplayRole, or if they match, showToolTipWhenElided
0338      *       flag is set and the display role information is elided.
0339      * @see showToolTipWhenElided()
0340      */
0341     void setShowToolTipWhenElided(bool showToolTip);
0342 
0343     /**
0344      * Returns whether a tooltip should be shown if the display role
0345      * is elided containing the full display role information.
0346      *
0347      * @note The tooltip will only be shown if the Qt::ToolTipRole differs
0348      *       from Qt::DisplayRole, or if they match, showToolTipWhenElided
0349      *       flag is set and the display role information is elided.
0350      * @see setShowToolTipWhenElided()
0351      */
0352     bool showToolTipWhenElided() const;
0353 
0354     /**
0355      * Returns the rectangle of the icon that is aligned inside the decoration
0356      * rectangle.
0357      */
0358     QRect iconRect(const QStyleOptionViewItem &option, const QModelIndex &index) const;
0359 
0360     /**
0361      * When the contents text needs to be wrapped, @p wrapMode strategy
0362      * will be followed.
0363      *
0364      */
0365     void setWrapMode(QTextOption::WrapMode wrapMode);
0366 
0367     /**
0368      * Returns the wrapping strategy followed to show text when it needs
0369      * wrapping.
0370      *
0371      */
0372     QTextOption::WrapMode wrapMode() const;
0373 
0374     /**
0375      * Enable/Disable the displaying of an animated overlay that is shown for any destination
0376      * urls (in the view). When enabled, the animations (if any) will be drawn automatically.
0377      *
0378      * Only the files/folders that are visible and have jobs associated with them
0379      * will display the animation.
0380      * You would likely not want this enabled if you perform some kind of custom painting
0381      * that takes up a whole item, and will just make this(and what you paint) look funky.
0382      *
0383      * Default is disabled.
0384      *
0385      * Note: The model (KDirModel) needs to have it's method called with the same
0386      * value, when you make the call to this method.
0387      */
0388     void setJobTransfersVisible(bool jobTransfersVisible);
0389 
0390     /**
0391      * Returns whether or not the displaying of job transfers is enabled.
0392      * @see setJobTransfersVisible()
0393      */
0394     bool jobTransfersVisible() const;
0395 
0396     /**
0397      * Reimplemented from @ref QAbstractItemDelegate.
0398      */
0399     bool eventFilter(QObject *object, QEvent *event) override;
0400 
0401 public Q_SLOTS:
0402     /**
0403      * Reimplemented from @ref QAbstractItemDelegate.
0404      */
0405     bool helpEvent(QHelpEvent *event, QAbstractItemView *view, const QStyleOptionViewItem &option, const QModelIndex &index) override;
0406 
0407     /**
0408      * Returns the shape of the item as a region.
0409      * The returned region can be used for precise hit testing of the item.
0410      */
0411     QRegion shape(const QStyleOptionViewItem &option, const QModelIndex &index);
0412 
0413 private:
0414     class Private;
0415     std::unique_ptr<Private> const d; /// @internal
0416     Q_DISABLE_COPY(KFileItemDelegate)
0417 };
0418 
0419 #endif // KFILEITEMDELEGATE_H