1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 2006-2007, 2008 Fredrik Höglund <fredrik@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KFILEITEMDELEGATE_H
9#define KFILEITEMDELEGATE_H
10
11#include "kiowidgets_export.h"
12#include <QAbstractItemDelegate>
13#include <QTextOption>
14
15#include <memory>
16
17class QAbstractItemModel;
18class QAbstractItemView;
19class QHelpEvent;
20class QModelIndex;
21class QPainter;
22
23/**
24 * @class KFileItemDelegate kfileitemdelegate.h <KFileItemDelegate>
25 *
26 * KFileItemDelegate is intended to be used to provide a KDE file system
27 * view, when using one of the standard item views in Qt with KDirModel.
28 *
29 * While primarily intended to be used with KDirModel, it uses
30 * Qt::DecorationRole and Qt::DisplayRole for the icons and text labels,
31 * just like QItemDelegate, and can thus be used with any standard model.
32 *
33 * When used with KDirModel however, KFileItemDelegate can change the way
34 * the display and/or decoration roles are drawn, based on properties
35 * of the file items. For example, if the file item is a symbolic link,
36 * it will use an italic font to draw the file name.
37 *
38 * KFileItemDelegate also supports showing additional information about
39 * the file items below the icon labels.
40 *
41 * Which information should be shown, if any, is controlled by the
42 * @ref information property, which is a list that can be set by calling
43 * setShowInformation(), and read by calling showInformation().
44 * By default this list is empty.
45 *
46 * To use KFileItemDelegate, instantiate an object from the delegate,
47 * and call setItemDelegate() in one of the standard item views in Qt:
48 *
49 * @code
50 * QListView *listview = new QListView(this);
51 * KFileItemDelegate *delegate = new KFileItemDelegate(this);
52 * listview->setItemDelegate(delegate);
53 * @endcode
54 */
55class KIOWIDGETS_EXPORT KFileItemDelegate : public QAbstractItemDelegate
56{
57 Q_OBJECT
58
59 /**
60 * This property holds which additional information (if any) should be shown below
61 * items in icon views.
62 *
63 * Access functions:
64 * @li void setShownformation(InformationList information)
65 * @li InformationList showInformation() const
66 */
67 Q_PROPERTY(InformationList information READ showInformation WRITE setShowInformation)
68
69 /**
70 * This property holds the color used for the text shadow.
71 *
72 * The alpha value in the color determines the opacity of the shadow.
73 * Shadows are only rendered when the alpha value is non-zero.
74 * The default value for this property is Qt::transparent.
75 *
76 * Access functions:
77 * @li void setShadowColor(const QColor &color)
78 * @li QColor shadowColor() const
79 */
80 Q_PROPERTY(QColor shadowColor READ shadowColor WRITE setShadowColor)
81
82 /**
83 * This property holds the horizontal and vertical offset for the text shadow.
84 * The default value for this property is (1, 1).
85 *
86 * Access functions:
87 * @li void setShadowOffset(const QPointF &offset)
88 * @li QPointF shadowOffset() const
89 */
90 Q_PROPERTY(QPointF shadowOffset READ shadowOffset WRITE setShadowOffset)
91
92 /**
93 * This property holds the blur radius for the text shadow.
94 * The default value for this property is 2.
95 *
96 * Access functions:
97 * @li void setShadowBlur(qreal radius)
98 * @li qreal shadowBlur() const
99 */
100 Q_PROPERTY(qreal shadowBlur READ shadowBlur WRITE setShadowBlur)
101
102 /**
103 * This property holds the maximum size that can be returned
104 * by KFileItemDelegate::sizeHint(). If the maximum size is empty,
105 * it will be ignored.
106 */
107 Q_PROPERTY(QSize maximumSize READ maximumSize WRITE setMaximumSize)
108
109 /**
110 * This property determines whether a tooltip will be shown by the delegate
111 * if the display role is elided. This tooltip will contain the full display
112 * role information. The tooltip will only be shown if the Qt::ToolTipRole differs
113 * from Qt::DisplayRole, or if they match, showToolTipWhenElided flag is set and
114 * the display role information is elided.
115 */
116 Q_PROPERTY(bool showToolTipWhenElided READ showToolTipWhenElided WRITE setShowToolTipWhenElided)
117
118 /**
119 * This property determines if there are KIO jobs on a destination URL visible, then
120 * they will have a small animation overlay displayed on them.
121 */
122 Q_PROPERTY(bool jobTransfersVisible READ jobTransfersVisible WRITE setJobTransfersVisible)
123
124public:
125 /**
126 * This enum defines the additional information that can be displayed below item
127 * labels in icon views.
128 *
129 * The information will only be shown for indexes for which the model provides
130 * a valid value for KDirModel::FileItemRole, and only when there's sufficient vertical
131 * space to display at least one line of the information, along with the display label.
132 *
133 * For the number of items to be shown for folders, the model must provide a valid
134 * value for KDirMode::ChildCountRole, in addition to KDirModel::FileItemRole.
135 *
136 * Note that KFileItemDelegate will not call KFileItem::determineMimeType() if
137 * KFileItem::isMimeTypeKnown() returns false, so if you want to display MIME types
138 * you should use a KMimeTypeResolver with the model and the view, to ensure that MIME
139 * types are resolved. If the MIME type isn't known, "Unknown" will be displayed until
140 * the MIME type has been successfully resolved.
141 *
142 * @see setShowInformation()
143 * @see showInformation()
144 * @see information
145 */
146 enum Information {
147 NoInformation, ///< No additional information will be shown for items.
148 Size, ///< The file size for files, and the number of items for folders.
149 Permissions, ///< A UNIX permissions string, e.g.\ -rwxr-xr-x.
150 OctalPermissions, ///< The permissions as an octal value, e.g.\ 0644.
151 Owner, ///< The user name of the file owner, e.g.\ root
152 OwnerAndGroup, ///< The user and group that owns the file, e.g.\ root:root
153 CreationTime, ///< The date and time the file/folder was created.
154 ModificationTime, ///< The date and time the file/folder was last modified.
155 AccessTime, ///< The date and time the file/folder was last accessed.
156 MimeType, ///< The MIME type for the item, e.g.\ text/html.
157 FriendlyMimeType, ///< The descriptive name for the MIME type, e.g.\ HTML Document.
158 LinkDest, ///< The destination of a symbolic link. @since 4.5
159 LocalPathOrUrl, ///< The local path to the file or the URL in case it is not a local file. @since 4.5
160 Comment, ///< A simple comment that can be displayed to the user as is. @since 4.6
161 };
162 Q_ENUM(Information)
163
164 typedef QList<Information> InformationList;
165
166 /**
167 * Constructs a new KFileItemDelegate.
168 *
169 * @param parent The parent object for the delegate.
170 */
171 explicit KFileItemDelegate(QObject *parent = nullptr);
172
173 /**
174 * Destroys the item delegate.
175 */
176 ~KFileItemDelegate() override;
177
178 /**
179 * Returns the nominal size for the item referred to by @p index, given the
180 * provided options.
181 *
182 * If the model provides a valid Qt::FontRole and/or Qt::TextAlignmentRole for the item,
183 * those will be used instead of the ones specified in the style options.
184 *
185 * This function is reimplemented from @ref QAbstractItemDelegate.
186 *
187 * @param option The style options that should be used when painting the item.
188 * @param index The index to the item for which to return the size hint.
189 */
190 QSize sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const override;
191
192 /**
193 * Paints the item indicated by @p index, using @p painter.
194 *
195 * The item will be drawn in the rectangle specified by option.rect.
196 * The correct size for that rectangle can be obtained by calling
197 * @ref sizeHint().
198 *
199 * This function will use the following data values if the model provides
200 * them for the item, in place of the values in @p option:
201 *
202 * @li Qt::FontRole The font that should be used for the display role.
203 * @li Qt::TextAlignmentRole The alignment of the display role.
204 * @li Qt::ForegroundRole The text color for the display role.
205 * @li Qt::BackgroundRole The background color for the item.
206 *
207 * This function is reimplemented from @ref QAbstractItemDelegate.
208 *
209 * @param painter The painter with which to draw the item.
210 * @param option The style options that should be used when painting the item.
211 * @param index The index to the item that should be painted.
212 */
213 void paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const override;
214
215 /**
216 * Reimplemented from @ref QAbstractItemDelegate.
217 */
218 QWidget *createEditor(QWidget *parent, const QStyleOptionViewItem &option, const QModelIndex &index) const override;
219
220 /**
221 * Reimplemented from @ref QAbstractItemDelegate.
222 */
223 bool editorEvent(QEvent *event, QAbstractItemModel *model, const QStyleOptionViewItem &option, const QModelIndex &index) override;
224
225 /**
226 * Reimplemented from @ref QAbstractItemDelegate.
227 */
228 void setEditorData(QWidget *editor, const QModelIndex &index) const override;
229
230 /**
231 * Reimplemented from @ref QAbstractItemDelegate.
232 */
233 void setModelData(QWidget *editor, QAbstractItemModel *model, const QModelIndex &index) const override;
234
235 /**
236 * Reimplemented from @ref QAbstractItemDelegate.
237 */
238 void updateEditorGeometry(QWidget *editor, const QStyleOptionViewItem &option, const QModelIndex &index) const override;
239
240 /**
241 * Sets the list of information lines that are shown below the icon label in list views.
242 *
243 * You will typically construct the list like this:
244 * @code
245 * KFileItemDelegate::InformationList list;
246 * list << KFileItemDelegate::FriendlyMimeType << KFileItemDelegate::Size;
247 * delegate->setShowInformation(list);
248 * @endcode
249 *
250 * The information lines will be displayed in the list order.
251 * The delegate will first draw the item label, and then as many information
252 * lines as will fit in the available space.
253 *
254 * @param list A list of information items that should be shown
255 */
256 void setShowInformation(const InformationList &list);
257
258 /**
259 * Sets a single information line that is shown below the icon label in list views.
260 *
261 * This is a convenience function for when you only want to show a single line
262 * of information.
263 *
264 * @param information The information that should be shown
265 */
266 void setShowInformation(Information information);
267
268 /**
269 * Returns the file item information that should be shown below item labels in list views.
270 */
271 InformationList showInformation() const;
272
273 /**
274 * Sets the color used for drawing the text shadow.
275 *
276 * To enable text shadows, set the shadow color to a non-transparent color.
277 * To disable text shadows, set the color to Qt::transparent.
278 *
279 * @see shadowColor()
280 */
281 void setShadowColor(const QColor &color);
282
283 /**
284 * Returns the color used for the text shadow.
285 *
286 * @see setShadowColor()
287 */
288 QColor shadowColor() const;
289
290 /**
291 * Sets the horizontal and vertical offset for the text shadow.
292 *
293 * @see shadowOffset()
294 */
295 void setShadowOffset(const QPointF &offset);
296
297 /**
298 * Returns the offset used for the text shadow.
299 *
300 * @see setShadowOffset()
301 */
302 QPointF shadowOffset() const;
303
304 /**
305 * Sets the blur radius for the text shadow.
306 *
307 * @see shadowBlur()
308 */
309 void setShadowBlur(qreal radius);
310
311 /**
312 * Returns the blur radius for the text shadow.
313 *
314 * @see setShadowBlur()
315 */
316 qreal shadowBlur() const;
317
318 /**
319 * Sets the maximum size for KFileItemDelegate::sizeHint().
320 *
321 * @see maximumSize()
322 */
323 void setMaximumSize(const QSize &size);
324
325 /**
326 * Returns the maximum size for KFileItemDelegate::sizeHint().
327 *
328 * @see setMaximumSize()
329 */
330 QSize maximumSize() const;
331
332 /**
333 * Sets whether a tooltip should be shown if the display role is
334 * elided containing the full display role information.
335 *
336 * @note The tooltip will only be shown if the Qt::ToolTipRole differs
337 * from Qt::DisplayRole, or if they match, showToolTipWhenElided
338 * flag is set and the display role information is elided.
339 * @see showToolTipWhenElided()
340 */
341 void setShowToolTipWhenElided(bool showToolTip);
342
343 /**
344 * Returns whether a tooltip should be shown if the display role
345 * is elided containing the full display role information.
346 *
347 * @note The tooltip will only be shown if the Qt::ToolTipRole differs
348 * from Qt::DisplayRole, or if they match, showToolTipWhenElided
349 * flag is set and the display role information is elided.
350 * @see setShowToolTipWhenElided()
351 */
352 bool showToolTipWhenElided() const;
353
354 /**
355 * Returns the rectangle of the icon that is aligned inside the decoration
356 * rectangle.
357 */
358 QRect iconRect(const QStyleOptionViewItem &option, const QModelIndex &index) const;
359
360 /**
361 * When the contents text needs to be wrapped, @p wrapMode strategy
362 * will be followed.
363 *
364 */
365 void setWrapMode(QTextOption::WrapMode wrapMode);
366
367 /**
368 * Returns the wrapping strategy followed to show text when it needs
369 * wrapping.
370 *
371 */
372 QTextOption::WrapMode wrapMode() const;
373
374 /**
375 * Enable/Disable the displaying of an animated overlay that is shown for any destination
376 * urls (in the view). When enabled, the animations (if any) will be drawn automatically.
377 *
378 * Only the files/folders that are visible and have jobs associated with them
379 * will display the animation.
380 * You would likely not want this enabled if you perform some kind of custom painting
381 * that takes up a whole item, and will just make this(and what you paint) look funky.
382 *
383 * Default is disabled.
384 *
385 * Note: The model (KDirModel) needs to have it's method called with the same
386 * value, when you make the call to this method.
387 */
388 void setJobTransfersVisible(bool jobTransfersVisible);
389
390 /**
391 * Returns whether or not the displaying of job transfers is enabled.
392 * @see setJobTransfersVisible()
393 */
394 bool jobTransfersVisible() const;
395
396 /**
397 * Reimplemented from @ref QAbstractItemDelegate.
398 */
399 bool eventFilter(QObject *object, QEvent *event) override;
400
401public Q_SLOTS:
402 /**
403 * Reimplemented from @ref QAbstractItemDelegate.
404 */
405 bool helpEvent(QHelpEvent *event, QAbstractItemView *view, const QStyleOptionViewItem &option, const QModelIndex &index) override;
406
407 /**
408 * Returns the shape of the item as a region.
409 * The returned region can be used for precise hit testing of the item.
410 */
411 QRegion shape(const QStyleOptionViewItem &option, const QModelIndex &index);
412
413private:
414 class Private;
415 std::unique_ptr<Private> const d; /// @internal
416 Q_DISABLE_COPY(KFileItemDelegate)
417};
418
419#endif // KFILEITEMDELEGATE_H
420

source code of kio/src/widgets/kfileitemdelegate.h