File indexing completed on 2025-02-16 13:07:48
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