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 | |
30 | class QAbstractItemModel; |
31 | class QAbstractItemView; |
32 | class QHelpEvent; |
33 | class QModelIndex; |
34 | class 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 | */ |
67 | class 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 | ///< 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 | |