1/*
2 Copyright 2007 Robert Knight <robertknight@gmail.com>
3 Copyright 2008 Marco Martin <notmart@gmail.com>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
19*/
20
21#ifndef PLASMA_DELEGATE_H
22#define PLASMA_DELEGATE_H
23
24// Qt
25#include <QtGui/QAbstractItemDelegate>
26
27// Plasma
28#include <plasma/plasma_export.h>
29
30namespace Plasma
31{
32
33class DelegatePrivate;
34
35/**
36 * @class Delegate plasma/delegate.h <Plasma/Delegate>
37 *
38 * Item delegate for rendering items in Plasma menus implemented with item views.
39 *
40 * The delegate makes use of its own data roles that are:
41 * SubTitleRole: the text of the subtitle
42 * SubTitleMandatoryRole: if the subtitle is to always be displayed
43 * (as default the subtitle is displayed only on mouse over)
44 * NOTE: if model doesn't return a valid data for SubTitleMandatoryRole (i.e. if it returns QVaraint())
45 * then subtitles will be shown for adjasent items with the same content and not shown
46 * otherwise.
47 *
48 * ColumnTypeRole: if the column is a main column (with title and subtitle)
49 * or a secondary action column (only a little icon that appears on mouse
50 * over is displayed)
51 */
52class PLASMA_EXPORT Delegate : public QAbstractItemDelegate
53{
54 Q_OBJECT
55public:
56
57 enum SpecificRoles {
58 SubTitleRole = Qt::UserRole + 1,
59 SubTitleMandatoryRole = Qt::UserRole + 2,
60 ColumnTypeRole = Qt::UserRole + 3
61 };
62
63 enum ColumnType {
64 MainColumn = 1,
65 SecondaryActionColumn = 2
66 };
67
68 Delegate(QObject *parent = 0);
69 ~Delegate();
70
71 /**
72 * Maps an arbitrary role to a role belonging to SpecificRoles.
73 * Using this function you can use any model with this delegate.
74 *
75 * @param role a role belonging to SpecificRoles
76 * @param actual an arbitrary role of the model we are using
77 */
78 void setRoleMapping(SpecificRoles role, int actual);
79
80 int roleMapping(SpecificRoles role) const;
81
82 //Reimplemented
83 virtual void paint(QPainter *painter, const QStyleOptionViewItem &option,
84 const QModelIndex &index) const;
85
86 /**
87 * @return true if a tooltip should be shown
88 */
89 bool showToolTip() const;
90
91protected:
92 /**
93 * Returns the empty area after the title.
94 * The height is the height of the subtitle.
95 * It can be used by subclasses that wants to paint additional data after
96 * calling the paint function of the superclass.
97 *
98 * @param option options for the title text
99 * @param index model index that we want to compute the free area
100 */
101 QRect rectAfterTitle(const QStyleOptionViewItem &option, const QModelIndex &index) const;
102
103 /**
104 * Returns the empty area after the subtitle.
105 * The height is the height of the subtitle.
106 * It can be used by subclasses, that wants to paint additional data.
107 *
108 * @param option options for the subtitle text
109 * @param index model index that we want to compute the free area
110 */
111 QRect rectAfterSubTitle(const QStyleOptionViewItem &option, const QModelIndex &index) const;
112
113 /**
114 * Returns the empty area after both the title and the subtitle.
115 * The height is the height of the item.
116 * It can be used by subclasses that wants to paint additional data
117 *
118 * @param option options for the title and subtitle text
119 * @param index model index that we want to compute the free area
120 */
121 QRect emptyRect(const QStyleOptionViewItem &option, const QModelIndex &index) const;
122
123 virtual QSize sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const;
124
125private:
126 DelegatePrivate *const d;
127};
128
129}
130
131#endif // PLASMA_DELEGATE_H
132