1/*
2 This file is part of the KDE project
3 SPDX-FileCopyrightText: 2012 Dawit Alemayehu <adawit@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KPARTS_LISTINGFILTEREXTENSION_H
9#define KPARTS_LISTINGFILTEREXTENSION_H
10
11#include <kparts/kparts_export.h>
12
13#include <QObject>
14#include <memory>
15
16class KFileItemList;
17
18namespace KParts
19{
20class ReadOnlyPart;
21class ListingFilterExtensionPrivate;
22
23/*!
24 * \class KParts::ListingFilterExtension
25 * \inheaderfile KParts/ListingFilterExtension
26 * \inmodule KParts
27 *
28 * \brief An extension for filtering listings.
29 *
30 * This extension is intended to be implemented by parts that provide listing
31 * services, e.g. file management parts and is intended to provide a generic
32 * API for filtering any listing through keywords, wildcard characters and/or
33 * content-type.
34 *
35 * Examples:
36 *
37 * To show items that only match the term "kde"
38 * \code
39 * KParts::ListingFilterExtension* ext = KParts::ListingFilterExtension::childObject(part);
40 * if (ext && (ext->supportedFilterModes() & KParts::ListingFilterExtension::SubString)) {
41 * ext->setFilter(KParts::ListingFilterExtension::SubString, QLatin1String("kde"));
42 * }
43 * \endcode
44 *
45 * To show items that only match "text/html"
46 * \code
47 * KParts::ListingFilterExtension* ext = KParts::ListingFilterExtension::childObject(part);
48 * if (ext && (ext->supportedFilterModes() & KParts::ListingFilterExtension::MimeType)) {
49 * ext->setFilter(KParts::ListingFilterExtension::MimeType, QLatin1String("text/html"));
50 * }
51 * \endcode
52 *
53 * To show items that only match the wildcard string "*.txt"
54 * \code
55 * KParts::ListingFilterExtension* ext = KParts::ListingFilterExtension::childObject(part);
56 * if (ext && (ext->supportedFilterModes() & KParts::ListingFilterExtension::WildCard)) {
57 * ext->setFilter(KParts::ListingFilterExtension::WildCard, QLatin1String("*.txt"));
58 * }
59 * \endcode
60 *
61 * To show items that match multiple mime types, e.g. text/html & application/xml:
62 *
63 * \code
64 * KParts::ListingFilterExtension* ext = KParts::ListingFilterExtension::childObject(part);
65 * if (ext &&
66 * (ext->supportedFilterModes() & KParts::ListingFilterExtension::MimeType) &&
67 * ext->supportsMultipleFilters(KParts::ListingFilterExtension::MimeType)) {
68 * QStringList mimeTypes = ext->filter(KParts::ListingFilterExtension::MimeType).toStringList();
69 * mimeTypes << QLatin1String("text/html") << QLatin1String("application/xml");
70 * ext->setFilter(KParts::ListingFilterExtension::MimeType, mimeTypes);
71 * }
72 * \endcode
73 *
74 * \since 4.9.2
75 */
76class KPARTS_EXPORT ListingFilterExtension : public QObject
77{
78 Q_OBJECT
79
80public:
81 /*!
82 * Supported file filtering modes modes.
83 *
84 * \value None
85 * \value MimeType Filter by mime type, e.g. "text/plain"
86 * \value SubString Filter by matching any part of a file or directory name, e.g. "Documents"
87 * \value WildCard Filter by using wildcard matches, e.g. "*.txt"
88 */
89 enum FilterMode {
90 None = 0x00,
91 MimeType = 0x01,
92 SubString = 0x02,
93 WildCard = 0x04,
94 };
95
96 Q_DECLARE_FLAGS(FilterModes, FilterMode)
97
98 /*! Constructor */
99 explicit ListingFilterExtension(KParts::ReadOnlyPart *parent);
100
101 ~ListingFilterExtension() override;
102
103 /*!
104 * Queries \a obj for a child object which inherits from this class.
105 */
106 static ListingFilterExtension *childObject(QObject *obj);
107
108 /*!
109 * Returns the OR'ed value of the file filter modes supported by the part
110 * that implements this extension.
111 *
112 * By default this function returns None.
113 */
114 virtual FilterModes supportedFilterModes() const;
115
116 /*!
117 * Returns true if the part that implements this extension allows
118 * the use of multiple filters for the given filtering \a mode.
119 *
120 * By default this function returns \c false.
121 */
122 virtual bool supportsMultipleFilters(FilterMode mode) const;
123
124 /*!
125 * Returns the currently set filters for the given \a mode.
126 *
127 * \a mode the desired filter mode as specified in FilterMode.
128 */
129 virtual QVariant filter(FilterMode mode) const = 0;
130
131 /*!
132 * Sets the file \a filter that should be applied by the part that
133 * implements this extension for the given filtering \a mode.
134 *
135 * To remove a filter for a given filter mode, simply call this function with
136 * the desired mode and the \a filter parameter set to a NULL variant.
137 *
138 * The second parameter can be
139 *
140 * \a mode the desired filter mode as specified in FilterMode.
141 *
142 * \a filter a list of filter texts based on the selected mode.
143 */
144 virtual void setFilter(FilterMode mode, const QVariant &filter) = 0;
145
146private:
147 std::unique_ptr<ListingFilterExtension> const d;
148};
149
150Q_DECLARE_OPERATORS_FOR_FLAGS(ListingFilterExtension::FilterModes)
151
152}
153
154#endif /* KPARTS_LISTINGFILTEREXTENSION_H */
155

source code of kparts/src/listingfilterextension.h