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
32class QObject;
33class QPainter;
34class QStyleOption;
35class QStyleOptionViewItem;
36class QAbstractItemView;
37class QItemSelection;
38
39class KWidgetItemDelegatePrivate;
40class 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 */
49class KDEUI_EXPORT KWidgetItemDelegate : public QAbstractItemDelegate
50{
51 Q_OBJECT
52
53public:
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
81protected:
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
156private:
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