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

source code of kparts/src/listingfilterextension.h