1/* This file is part of the KDE project
2 Copyright (C) 2012 Dawit Alemayehu <adawit@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License as published by the Free Software Foundation; either
7 version 2 of the License, or (at your option) any later version.
8
9 This library is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 Library General Public License for more details.
13
14 You should have received a copy of the GNU Library General Public License
15 along with this library; see the file COPYING.LIB. If not, write to
16 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17 Boston, MA 02110-1301, USA.
18 */
19
20#ifndef KPARTS_LISTINGEXTENSION_H
21#define KPARTS_LISTINGEXTENSION_H
22
23#include <QtCore/QObject>
24
25#include <kparts/kparts_export.h>
26
27
28class KFileItemList;
29
30namespace KParts
31{
32
33class ReadOnlyPart;
34
35/**
36 * @short an extension for filtering listings.
37 *
38 * This extension is intended to be implemented by parts that provide listing
39 * services, e.g. file management parts and is intended to provide a generic
40 * API for filtering any listing through keywords, wildcard characters and/or
41 * content-type.
42 *
43 * Examples:
44 *
45 * To show items that only match the term "kde"
46 * \code
47 * KParts::ListingFilterExtension* ext = KParts::ListingFilterExtension::childObject(part);
48 * if (ext && (ext->supportedFilterModes() & KParts::ListingFilterExtension::SubString)) {
49 * ext->setFilter(KParts::ListingFilterExtension::SubString, QLatin1String("kde"));
50 * }
51 * \endcode
52 *
53 * To show items that only match "text/html"
54 * \code
55 * KParts::ListingFilterExtension* ext = KParts::ListingFilterExtension::childObject(part);
56 * if (ext && (ext->supportedFilterModes() & KParts::ListingFilterExtension::MimeType)) {
57 * ext->setFilter(KParts::ListingFilterExtension::MimeType, QLatin1String("text/html"));
58 * }
59 * \endcode
60 *
61 * To show items that only match the wildcard string "*.txt"
62 * \code
63 * KParts::ListingFilterExtension* ext = KParts::ListingFilterExtension::childObject(part);
64 * if (ext && (ext->supportedFilterModes() & KParts::ListingFilterExtension::WildCard)) {
65 * ext->setFilter(KParts::ListingFilterExtension::WildCard, QLatin1String("*.txt"));
66 * }
67 * \endcode
68 *
69 * To show items that match multiple mime types, e.g. text/html & application/xml:
70 *
71 * \code
72 * KParts::ListingFilterExtension* ext = KParts::ListingFilterExtension::childObject(part);
73 * if (ext &&
74 * (ext->supportedFilterModes() & KParts::ListingFilterExtension::MimeType) &&
75 * ext->supportsMultipleFilters(KParts::ListingFilterExtension::MimeType)) {
76 * QStringList mimeTypes = ext->filter(KParts::ListingFilterExtension::MimeType).toStringList();
77 * mimeTypes << QLatin1String("text/html") << QLatin1String("application/xml");
78 * ext->setFilter(KParts::ListingFilterExtension::MimeType, mimeTypes);
79 * }
80 * \endcode
81 *
82 * @since 4.9.2
83 */
84class KPARTS_EXPORT ListingFilterExtension : public QObject
85{
86 Q_OBJECT
87
88public:
89 /**
90 * Supported file filtering modes modes.
91 */
92 enum FilterMode {
93 None = 0x00,
94 MimeType = 0x01, /*!< Filter by mime type, e.g. "text/plain". */
95 SubString = 0x02, /*!< Filter by matching any part of a file or directory name, e.g. "Documents" */
96 WildCard = 0x04 /*!< Filter by using wildcard matches, e.g. "*.txt" */
97 };
98
99 Q_DECLARE_FLAGS(FilterModes, FilterMode)
100
101 /*! Constructor */
102 ListingFilterExtension(KParts::ReadOnlyPart* parent);
103
104 /*! Destructor */
105 virtual ~ListingFilterExtension();
106
107 /**
108 * Queries @p obj for a child object which inherits from this class.
109 */
110 static ListingFilterExtension *childObject(QObject* obj);
111
112 /**
113 * Returns the OR'ed value of the file filter modes supported by the part
114 * that implements this extension.
115 *
116 * By default this function returns None.
117 */
118 virtual FilterModes supportedFilterModes() const;
119
120 /**
121 * Returns true if the part that implements this extension allows
122 * the use of multiple filters for the given filtering @p mode.
123 *
124 * By default this function returns false.
125 */
126 virtual bool supportsMultipleFilters(FilterMode mode) const;
127
128 /**
129 * Returns the currently set filters for the given @p mode.
130 *
131 * @param mode the desired filter mode as specified in @ref FilterMode.
132 */
133 virtual QVariant filter(FilterMode mode) const = 0;
134
135 /**
136 * Sets the file @p filter that should be applied by the part that
137 * implements this extension for the given filtering @p mode.
138 *
139 * To remove a filter for a given filter mode, simply call this function with
140 * the desired mode and the @p filter parameter set to a NULL variant.
141 *
142 * The second parameter can be
143 *
144 * @param mode the desired filter mode as specified in @ref FilterMode.
145 * @param filters a list of filter texts based on the selected mode.
146 */
147 virtual void setFilter(FilterMode mode, const QVariant& filter) = 0;
148
149private:
150 class ListingFilterExtensionPrivate;
151 ListingFilterExtension* const d;
152};
153
154/**
155 * @short an extension for receiving listing change notification.
156 *
157 * This extension is intended for implementation by parts that provide listing
158 * services, e.g. file management and is intended to notify about changes to
159 * a given listing. For example, if file management part implemented this extension
160 * it would emit @ref itemsDeleted and @ref itemsAdded signal whenever new files
161 * or folders are deleted and added to a directory respectively.
162 *
163 * @since 4.9.2
164 */
165class KPARTS_EXPORT ListingNotificationExtension : public QObject
166{
167 Q_OBJECT
168
169public:
170 /**
171 * Supported notification event types.
172 */
173 enum NotificationEventType {
174 None = 0x00,
175 ItemsAdded = 0x01, /*!< New items added to the listing. */
176 ItemsDeleted = 0x02 /*!< Items deleted from the listing. */
177 };
178
179 Q_DECLARE_FLAGS(NotificationEventTypes, NotificationEventType)
180
181 /*! Constructor */
182 ListingNotificationExtension(KParts::ReadOnlyPart* parent);
183
184 /*! Destructor */
185 virtual ~ListingNotificationExtension();
186
187 /**
188 * Returns the OR'ed value of the notification types supported by the part
189 * that implements this extension.
190 *
191 * By default this function returns None.
192 */
193 virtual NotificationEventTypes supportedNotificationEventTypes() const;
194
195 /**
196 * Queries @p obj for a child object which inherits from this class.
197 */
198 static ListingNotificationExtension *childObject(QObject* obj);
199
200Q_SIGNALS:
201 /**
202 * This signal is emitted when one of the notification events listed
203 * in @ref NotificationEventType occur.
204 */
205 void listingEvent(KParts::ListingNotificationExtension::NotificationEventType, const KFileItemList&);
206
207private:
208 class ListingNotificationExtensionPrivate;
209 ListingNotificationExtension* const d;
210};
211
212}
213
214Q_DECLARE_OPERATORS_FOR_FLAGS(KParts::ListingFilterExtension::FilterModes)
215Q_DECLARE_OPERATORS_FOR_FLAGS(KParts::ListingNotificationExtension::NotificationEventTypes)
216
217#endif /* KPARTS_LISTINGEXTENSION_H */
218