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 | |
28 | class KFileItemList; |
29 | |
30 | namespace KParts |
31 | { |
32 | |
33 | class 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 | */ |
84 | class KPARTS_EXPORT ListingFilterExtension : public QObject |
85 | { |
86 | Q_OBJECT |
87 | |
88 | public: |
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 | |
149 | private: |
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 | */ |
165 | class KPARTS_EXPORT ListingNotificationExtension : public QObject |
166 | { |
167 | Q_OBJECT |
168 | |
169 | public: |
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 | |
200 | Q_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 | |
207 | private: |
208 | class ListingNotificationExtensionPrivate; |
209 | ListingNotificationExtension* const d; |
210 | }; |
211 | |
212 | } |
213 | |
214 | Q_DECLARE_OPERATORS_FOR_FLAGS(KParts::ListingFilterExtension::FilterModes) |
215 | Q_DECLARE_OPERATORS_FOR_FLAGS(KParts::ListingNotificationExtension::NotificationEventTypes) |
216 | |
217 | #endif /* KPARTS_LISTINGEXTENSION_H */ |
218 | |