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