File indexing completed on 2023-10-01 04:06:16

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      * @since 4.5
0122      */
0123     Q_PROPERTY(bool jobTransfersVisible READ jobTransfersVisible WRITE setJobTransfersVisible)
0124 
0125 public:
0126     /**
0127      * This enum defines the additional information that can be displayed below item
0128      * labels in icon views.
0129      *
0130      * The information will only be shown for indexes for which the model provides
0131      * a valid value for KDirModel::FileItemRole, and only when there's sufficient vertical
0132      * space to display at least one line of the information, along with the display label.
0133      *
0134      * For the number of items to be shown for folders, the model must provide a valid
0135      * value for KDirMode::ChildCountRole, in addition to KDirModel::FileItemRole.
0136      *
0137      * Note that KFileItemDelegate will not call KFileItem::determineMimeType() if
0138      * KFileItem::isMimeTypeKnown() returns false, so if you want to display MIME types
0139      * you should use a KMimeTypeResolver with the model and the view, to ensure that MIME
0140      * types are resolved. If the MIME type isn't known, "Unknown" will be displayed until
0141      * the MIME type has been successfully resolved.
0142      *
0143      * @see setShowInformation()
0144      * @see showInformation()
0145      * @see information
0146      */
0147     enum Information {
0148         NoInformation, ///< No additional information will be shown for items.
0149         Size, ///< The file size for files, and the number of items for folders.
0150         Permissions, ///< A UNIX permissions string, e.g.\ -rwxr-xr-x.
0151         OctalPermissions, ///< The permissions as an octal value, e.g.\ 0644.
0152         Owner, ///< The user name of the file owner, e.g.\ root
0153         OwnerAndGroup, ///< The user and group that owns the file, e.g.\ root:root
0154         CreationTime, ///< The date and time the file/folder was created.
0155         ModificationTime, ///< The date and time the file/folder was last modified.
0156         AccessTime, ///< The date and time the file/folder was last accessed.
0157         MimeType, ///< The MIME type for the item, e.g.\ text/html.
0158         FriendlyMimeType, ///< The descriptive name for the MIME type, e.g.\ HTML Document.
0159         LinkDest, ///< The destination of a symbolic link. @since 4.5
0160         LocalPathOrUrl, ///< The local path to the file or the URL in case it is not a local file. @since 4.5
0161         Comment, ///< A simple comment that can be displayed to the user as is. @since 4.6
0162     };
0163     Q_ENUM(Information)
0164 
0165     typedef QList<Information> InformationList;
0166 
0167     /**
0168      * Constructs a new KFileItemDelegate.
0169      *
0170      * @param parent The parent object for the delegate.
0171      */
0172     explicit KFileItemDelegate(QObject *parent = nullptr);
0173 
0174     /**
0175      * Destroys the item delegate.
0176      */
0177     ~KFileItemDelegate() override;
0178 
0179     /**
0180      * Returns the nominal size for the item referred to by @p index, given the
0181      * provided options.
0182      *
0183      * If the model provides a valid Qt::FontRole and/or Qt::TextAlignmentRole for the item,
0184      * those will be used instead of the ones specified in the style options.
0185      *
0186      * This function is reimplemented from @ref QAbstractItemDelegate.
0187      *
0188      * @param option  The style options that should be used when painting the item.
0189      * @param index   The index to the item for which to return the size hint.
0190      */
0191     QSize sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const override;
0192 
0193     /**
0194      * Paints the item indicated by @p index, using @p painter.
0195      *
0196      * The item will be drawn in the rectangle specified by option.rect.
0197      * The correct size for that rectangle can be obtained by calling
0198      * @ref sizeHint().
0199      *
0200      * This function will use the following data values if the model provides
0201      * them for the item, in place of the values in @p option:
0202      *
0203      * @li Qt::FontRole           The font that should be used for the display role.
0204      * @li Qt::TextAlignmentRole  The alignment of the display role.
0205      * @li Qt::ForegroundRole     The text color for the display role.
0206      * @li Qt::BackgroundRole     The background color for the item.
0207      *
0208      * This function is reimplemented from @ref QAbstractItemDelegate.
0209      *
0210      * @param painter The painter with which to draw the item.
0211      * @param option  The style options that should be used when painting the item.
0212      * @param index   The index to the item that should be painted.
0213      */
0214     void paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override;
0215 
0216     /**
0217      * Reimplemented from @ref QAbstractItemDelegate.
0218      */
0219     QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const override;
0220 
0221     /**
0222      * Reimplemented from @ref QAbstractItemDelegate.
0223      */
0224     bool editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index) override;
0225 
0226     /**
0227      * Reimplemented from @ref QAbstractItemDelegate.
0228      */
0229     void setEditorData(QWidget *editor, const QModelIndex &index) const override;
0230 
0231     /**
0232      * Reimplemented from @ref QAbstractItemDelegate.
0233      */
0234     void setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const override;
0235 
0236     /**
0237      * Reimplemented from @ref QAbstractItemDelegate.
0238      */
0239     void updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const override;
0240 
0241     /**
0242      * Sets the list of information lines that are shown below the icon label in list views.
0243      *
0244      * You will typically construct the list like this:
0245      * @code
0246      * KFileItemDelegate::InformationList list;
0247      * list << KFileItemDelegate::FriendlyMimeType << KFileItemDelegate::Size;
0248      * delegate->setShowInformation(list);
0249      * @endcode
0250      *
0251      * The information lines will be displayed in the list order.
0252      * The delegate will first draw the item label, and then as many information
0253      * lines as will fit in the available space.
0254      *
0255      * @param list A list of information items that should be shown
0256      */
0257     void setShowInformation(const InformationList &list);
0258 
0259     /**
0260      * Sets a single information line that is shown below the icon label in list views.
0261      *
0262      * This is a convenience function for when you only want to show a single line
0263      * of information.
0264      *
0265      * @param information The information that should be shown
0266      */
0267     void setShowInformation(Information information);
0268 
0269     /**
0270      * Returns the file item information that should be shown below item labels in list views.
0271      */
0272     InformationList showInformation() const;
0273 
0274     /**
0275      * Sets the color used for drawing the text shadow.
0276      *
0277      * To enable text shadows, set the shadow color to a non-transparent color.
0278      * To disable text shadows, set the color to Qt::transparent.
0279      *
0280      * @see shadowColor()
0281      */
0282     void setShadowColor(const QColor &color);
0283 
0284     /**
0285      * Returns the color used for the text shadow.
0286      *
0287      * @see setShadowColor()
0288      */
0289     QColor shadowColor() const;
0290 
0291     /**
0292      * Sets the horizontal and vertical offset for the text shadow.
0293      *
0294      * @see shadowOffset()
0295      */
0296     void setShadowOffset(const QPointF &offset);
0297 
0298     /**
0299      * Returns the offset used for the text shadow.
0300      *
0301      * @see setShadowOffset()
0302      */
0303     QPointF shadowOffset() const;
0304 
0305     /**
0306      * Sets the blur radius for the text shadow.
0307      *
0308      * @see shadowBlur()
0309      */
0310     void setShadowBlur(qreal radius);
0311 
0312     /**
0313      * Returns the blur radius for the text shadow.
0314      *
0315      * @see setShadowBlur()
0316      */
0317     qreal shadowBlur() const;
0318 
0319     /**
0320      * Sets the maximum size for KFileItemDelegate::sizeHint().
0321      *
0322      * @see maximumSize()
0323      * @since 4.1
0324      */
0325     void setMaximumSize(const QSize &size);
0326 
0327     /**
0328      * Returns the maximum size for KFileItemDelegate::sizeHint().
0329      *
0330      * @see setMaximumSize()
0331      * @since 4.1
0332      */
0333     QSize maximumSize() const;
0334 
0335     /**
0336      * Sets whether a tooltip should be shown if the display role is
0337      * elided containing the full display role information.
0338      *
0339      * @note The tooltip will only be shown if the Qt::ToolTipRole differs
0340      *       from Qt::DisplayRole, or if they match, showToolTipWhenElided
0341      *       flag is set and the display role information is elided.
0342      * @see showToolTipWhenElided()
0343      * @since 4.2
0344      */
0345     void setShowToolTipWhenElided(bool showToolTip);
0346 
0347     /**
0348      * Returns whether a tooltip should be shown if the display role
0349      * is elided containing the full display role information.
0350      *
0351      * @note The tooltip will only be shown if the Qt::ToolTipRole differs
0352      *       from Qt::DisplayRole, or if they match, showToolTipWhenElided
0353      *       flag is set and the display role information is elided.
0354      * @see setShowToolTipWhenElided()
0355      * @since 4.2
0356      */
0357     bool showToolTipWhenElided() const;
0358 
0359     /**
0360      * Returns the rectangle of the icon that is aligned inside the decoration
0361      * rectangle.
0362      * @since 4.4
0363      */
0364     QRect iconRect(const QStyleOptionViewItem &option, const QModelIndex &index) const;
0365 
0366     /**
0367      * When the contents text needs to be wrapped, @p wrapMode strategy
0368      * will be followed.
0369      *
0370      * @since 4.4
0371      */
0372     void setWrapMode(QTextOption::WrapMode wrapMode);
0373 
0374     /**
0375      * Returns the wrapping strategy followed to show text when it needs
0376      * wrapping.
0377      *
0378      * @since 4.4
0379      */
0380     QTextOption::WrapMode wrapMode() const;
0381 
0382     /**
0383      * Enable/Disable the displaying of an animated overlay that is shown for any destination
0384      * urls (in the view). When enabled, the animations (if any) will be drawn automatically.
0385      *
0386      * Only the files/folders that are visible and have jobs associated with them
0387      * will display the animation.
0388      * You would likely not want this enabled if you perform some kind of custom painting
0389      * that takes up a whole item, and will just make this(and what you paint) look funky.
0390      *
0391      * Default is disabled.
0392      *
0393      * Note: The model (KDirModel) needs to have it's method called with the same
0394      * value, when you make the call to this method.
0395      *
0396      * @since 4.5
0397      */
0398     void setJobTransfersVisible(bool jobTransfersVisible);
0399 
0400     /**
0401      * Returns whether or not the displaying of job transfers is enabled.
0402      * @see setJobTransfersVisible()
0403      * @since 4.5
0404      */
0405     bool jobTransfersVisible() const;
0406 
0407     /**
0408      * Reimplemented from @ref QAbstractItemDelegate.
0409      */
0410     bool eventFilter(QObject *object, QEvent *event) override;
0411 
0412 public Q_SLOTS:
0413     /**
0414      * Reimplemented from @ref QAbstractItemDelegate.
0415      */
0416     bool helpEvent(QHelpEvent *event, QAbstractItemView *view, const QStyleOptionViewItem &option, const QModelIndex &index) override;
0417 
0418     /**
0419      * Returns the shape of the item as a region.
0420      * The returned region can be used for precise hit testing of the item.
0421      */
0422     QRegion shape(const QStyleOptionViewItem &option, const QModelIndex &index);
0423 
0424 private:
0425     class Private;
0426     std::unique_ptr<Private> const d; /// @internal
0427     Q_DISABLE_COPY(KFileItemDelegate)
0428 };
0429 
0430 #endif // KFILEITEMDELEGATE_H