1 | /** |
2 | * This file is part of the KDE project |
3 | * Copyright (C) 2007-2008 Rafael Fernández López <ereslibre@kde.org> |
4 | * Copyright (C) 2008 Kevin Ottens <ervin@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 KWIDGETITEMDELEGATE_H |
23 | #define KWIDGETITEMDELEGATE_H |
24 | |
25 | #include <QtCore/QEvent> |
26 | #include <QtCore/QList> |
27 | #include <QtCore/QPersistentModelIndex> |
28 | #include <QtGui/QAbstractItemDelegate> |
29 | |
30 | #include <kdeui_export.h> |
31 | |
32 | class QObject; |
33 | class QPainter; |
34 | class QStyleOption; |
35 | class QStyleOptionViewItem; |
36 | class QAbstractItemView; |
37 | class QItemSelection; |
38 | |
39 | class KWidgetItemDelegatePrivate; |
40 | class KWidgetItemDelegatePool; |
41 | |
42 | /** |
43 | * This class allows to create item delegates embedding simple widgets to interact |
44 | * with items. For instance you can add push buttons, line edits, etc. to your delegate |
45 | * and use them to modify the state of your model. |
46 | * |
47 | * @since 4.1 |
48 | */ |
49 | class KDEUI_EXPORT KWidgetItemDelegate : public QAbstractItemDelegate |
50 | { |
51 | Q_OBJECT |
52 | |
53 | public: |
54 | /** |
55 | * Creates a new ItemDelegate to be used with a given itemview. |
56 | * |
57 | * @param itemView the item view the new delegate will monitor |
58 | * @param parent the parent of this delegate |
59 | */ |
60 | explicit KWidgetItemDelegate(QAbstractItemView *itemView, QObject *parent = 0); |
61 | |
62 | /** |
63 | * Destroys an ItemDelegate. |
64 | */ |
65 | virtual ~KWidgetItemDelegate(); |
66 | |
67 | /** |
68 | * Retrieves the item view this delegate is monitoring. |
69 | * |
70 | * @return the item view this delegate is monitoring |
71 | */ |
72 | QAbstractItemView *itemView() const; |
73 | |
74 | /** |
75 | * Retrieves the currently focused index. An invalid index if none is focused. |
76 | * |
77 | * @return the current focused index, or QPersistentModelIndex() if none is focused. |
78 | */ |
79 | QPersistentModelIndex focusedIndex() const; |
80 | |
81 | protected: |
82 | /** |
83 | * Creates the list of widgets needed for an item. |
84 | * |
85 | * @note No initialization of the widgets is supposed to happen here. |
86 | * The widgets will be initialized based on needs for a given item. |
87 | * |
88 | * @note If you want to connect some widget signals to any slot, you should |
89 | * do it here. |
90 | * |
91 | * @note If you want to know the index for which you are creating widgets, it is |
92 | * available as a QModelIndex Q_PROPERTY called "goya:creatingWidgetsForIndex". |
93 | * Ensure to add Q_DECLARE_METATYPE(QModelIndex) before your method definition |
94 | * to tell QVariant about QModelIndex. |
95 | * |
96 | * @return the list of newly created widgets which will be used to interact with an item. |
97 | * @see updateItemWidgets() |
98 | */ |
99 | virtual QList<QWidget*> createItemWidgets() const = 0; |
100 | |
101 | /** |
102 | * Updates a list of widgets for its use inside of the delegate (painting or |
103 | * event handling). |
104 | * |
105 | * @note All the positioning and sizing should be done in item coordinates. |
106 | * |
107 | * @warning Do not make widget connections in here, since this method will |
108 | * be called very regularly. |
109 | * |
110 | * @param widgets the widgets to update |
111 | * @param option the current set of style options for the view. |
112 | * @param index the model index of the item currently manipulated. |
113 | */ |
114 | virtual void updateItemWidgets(const QList<QWidget*> widgets, |
115 | const QStyleOptionViewItem &option, |
116 | const QPersistentModelIndex &index) const = 0; |
117 | |
118 | /** |
119 | * Paint the widgets of the item. This method is meant to be used in the paint() |
120 | * method of your item delegate implementation. |
121 | * |
122 | * @param painter the painter the widgets will be painted on. |
123 | * @param option the current set of style options for the view. |
124 | * @param index the model index of the item currently painted. |
125 | * |
126 | * @warning since 4.2 this method is not longer needed to be called. All widgets will kept |
127 | * updated without the need of calling paintWidgets() in your paint() event. For the |
128 | * widgets of a certain index to be updated your model has to emit dataChanged() on the |
129 | * indexes that want to be updated. |
130 | */ |
131 | #ifndef KDE_NO_DEPRECATED |
132 | KDE_DEPRECATED void paintWidgets(QPainter *painter, const QStyleOptionViewItem &option, |
133 | const QPersistentModelIndex &index) const; |
134 | #endif |
135 | |
136 | /** |
137 | * Sets the list of event @p types that a @p widget will block. |
138 | * |
139 | * Blocked events are not passed to the view. This way you can prevent an item |
140 | * from being selected when a button is clicked for instance. |
141 | * |
142 | * @param widget the widget which must block events |
143 | * @param types the list of event types the widget must block |
144 | */ |
145 | void setBlockedEventTypes(QWidget *widget, QList<QEvent::Type> types) const; |
146 | |
147 | /** |
148 | * Retrieves the list of blocked event types for the given widget. |
149 | * |
150 | * @param widget the specified widget. |
151 | * |
152 | * @return the list of blocked event types, can be empty if no events are blocked. |
153 | */ |
154 | QList<QEvent::Type> blockedEventTypes(QWidget *widget) const; |
155 | |
156 | private: |
157 | //@cond PRIVATE |
158 | friend class KWidgetItemDelegatePool; |
159 | friend class KWidgetItemDelegateEventListener; |
160 | KWidgetItemDelegatePrivate *const d; |
161 | Q_PRIVATE_SLOT(d, void _k_slotRowsInserted(const QModelIndex&,int,int)) |
162 | Q_PRIVATE_SLOT(d, void _k_slotRowsAboutToBeRemoved(const QModelIndex&,int,int)) |
163 | Q_PRIVATE_SLOT(d, void _k_slotRowsRemoved(const QModelIndex&,int,int)) |
164 | Q_PRIVATE_SLOT(d, void _k_slotDataChanged(const QModelIndex&,const QModelIndex&)) |
165 | Q_PRIVATE_SLOT(d, void _k_slotLayoutChanged()) |
166 | Q_PRIVATE_SLOT(d, void _k_slotModelReset()) |
167 | Q_PRIVATE_SLOT(d, void _k_slotSelectionChanged(const QItemSelection&,const QItemSelection&)) |
168 | //@endcond |
169 | }; |
170 | |
171 | #endif |
172 | |