1/**
2 * This file is part of the KDE project
3 * Copyright (C) 2007, 2009 Rafael Fernández López <ereslibre@kde.org>
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 KCATEGORYDRAWER_H
22#define KCATEGORYDRAWER_H
23
24#include <kdeui_export.h>
25
26#include <QtCore/QObject>
27#include <QtGui/QMouseEvent>
28
29class QPainter;
30class QModelIndex;
31class QStyleOption;
32
33class KCategorizedView;
34
35/**
36 * @deprecated
37 *
38 * The category drawing is performed by this class. It also gives information about the category
39 * height and margins.
40 *
41 * @warning Please use KCategoryDrawerV3 instead
42 */
43class KDEUI_EXPORT KCategoryDrawer
44{
45public:
46 KDE_DEPRECATED KCategoryDrawer();
47
48 virtual ~KCategoryDrawer();
49
50 /**
51 * This method purpose is to draw a category represented by the given
52 * @param index with the given @param sortRole sorting role
53 *
54 * @note This method will be called one time per category, always with the
55 * first element in that category
56 */
57 virtual void drawCategory(const QModelIndex &index,
58 int sortRole,
59 const QStyleOption &option,
60 QPainter *painter) const;
61
62 /**
63 * @return The category height for the category representated by index @p index with
64 * style options @p option.
65 */
66 virtual int categoryHeight(const QModelIndex &index, const QStyleOption &option) const;
67
68 //TODO KDE5: make virtual as leftMargin
69 /**
70 * @note 0 by default
71 *
72 * @since 4.4
73 */
74 int leftMargin() const;
75
76 /**
77 * @note call to this method on the KCategoryDrawer constructor to set the left margin
78 *
79 * @since 4.4
80 */
81 void setLeftMargin(int leftMargin);
82
83 //TODO KDE5: make virtual as rightMargin
84 /**
85 * @note 0 by default
86 *
87 * @since 4.4
88 */
89 int rightMargin() const;
90
91 /**
92 * @note call to this method on the KCategoryDrawer constructor to set the right margin
93 *
94 * @since 4.4
95 */
96 void setRightMargin(int rightMargin);
97
98 KCategoryDrawer &operator=(const KCategoryDrawer &cd);
99
100private:
101 class Private;
102 Private *const d;
103};
104
105
106/**
107 * @deprecated
108 *
109 * @since 4.4
110 *
111 * @warning Please use KCategoryDrawerV3 instead
112 */
113class KDEUI_EXPORT KCategoryDrawerV2
114 : public QObject
115 , public KCategoryDrawer
116{
117 Q_OBJECT
118
119public:
120 KDE_DEPRECATED KCategoryDrawerV2(QObject *parent = 0);
121 virtual ~KCategoryDrawerV2();
122
123 KDE_DEPRECATED virtual void mouseButtonPressed(const QModelIndex &index, QMouseEvent *event);
124
125 KDE_DEPRECATED virtual void mouseButtonReleased(const QModelIndex &index, QMouseEvent *event);
126
127 KDE_DEPRECATED virtual void mouseButtonMoved(const QModelIndex &index, QMouseEvent *event);
128
129 KDE_DEPRECATED virtual void mouseButtonDoubleClicked(const QModelIndex &index, QMouseEvent *event);
130
131Q_SIGNALS:
132 /**
133 * This signal becomes emitted when collapse or expand has been clicked.
134 */
135 void collapseOrExpandClicked(const QModelIndex &index);
136
137 /**
138 * Emit this signal on your subclass implementation to notify that something happened. Usually
139 * this will be triggered when you have received an event, and its position matched some "hot spot".
140 *
141 * You give this action the integer you want, and having connected this signal to your code,
142 * the connected slot can perform the needed changes (view, model, selection model, delegate...)
143 */
144 void actionRequested(int action, const QModelIndex &index);
145};
146
147/**
148 * @since 4.5
149 */
150class KDEUI_EXPORT KCategoryDrawerV3
151 : public KCategoryDrawerV2
152{
153 friend class KCategorizedView;
154
155public:
156 KCategoryDrawerV3(KCategorizedView *view);
157 virtual ~KCategoryDrawerV3();
158
159 /**
160 * @return The view this category drawer is associated with.
161 */
162 KCategorizedView *view() const;
163
164 using KCategoryDrawerV2::mouseButtonPressed;
165 using KCategoryDrawerV2::mouseButtonReleased;
166 using KCategoryDrawerV2::mouseButtonDoubleClicked;
167
168protected:
169 /**
170 * Method called when the mouse button has been pressed.
171 *
172 * @param index The representative index of the block of items.
173 * @param blockRect The rect occupied by the block of items.
174 * @param event The mouse event.
175 *
176 * @warning You explicitly have to determine whether the event has been accepted or not. You
177 * have to call event->accept() or event->ignore() at all possible case branches in
178 * your code.
179 */
180 virtual void mouseButtonPressed(const QModelIndex &index, const QRect &blockRect, QMouseEvent *event);
181
182 /**
183 * Method called when the mouse button has been released.
184 *
185 * @param index The representative index of the block of items.
186 * @param blockRect The rect occupied by the block of items.
187 * @param event The mouse event.
188 *
189 * @warning You explicitly have to determine whether the event has been accepted or not. You
190 * have to call event->accept() or event->ignore() at all possible case branches in
191 * your code.
192 */
193 virtual void mouseButtonReleased(const QModelIndex &index, const QRect &blockRect, QMouseEvent *event);
194
195 /**
196 * Method called when the mouse has been moved.
197 *
198 * @param index The representative index of the block of items.
199 * @param blockRect The rect occupied by the block of items.
200 * @param event The mouse event.
201 */
202 virtual void mouseMoved(const QModelIndex &index, const QRect &blockRect, QMouseEvent *event);
203
204 /**
205 * Method called when the mouse button has been double clicked.
206 *
207 * @param index The representative index of the block of items.
208 * @param blockRect The rect occupied by the block of items.
209 * @param event The mouse event.
210 *
211 * @warning You explicitly have to determine whether the event has been accepted or not. You
212 * have to call event->accept() or event->ignore() at all possible case branches in
213 * your code.
214 */
215 virtual void mouseButtonDoubleClicked(const QModelIndex &index, const QRect &blockRect, QMouseEvent *event);
216
217 /**
218 * Method called when the mouse button has left this block.
219 *
220 * @param index The representative index of the block of items.
221 * @param blockRect The rect occupied by the block of items.
222 */
223 virtual void mouseLeft(const QModelIndex &index, const QRect &blockRect);
224
225private:
226 class Private;
227 Private *const d;
228};
229
230#endif // KCATEGORYDRAWER_H
231