KParts

listingfilterextension.h
1 /*
2  This file is part of the KDE project
3  SPDX-FileCopyrightText: 2012 Dawit Alemayehu <[email protected]>
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 
16 class KFileItemList;
17 
18 namespace KParts
19 {
20 class ReadOnlyPart;
21 class 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  */
74 class KPARTS_EXPORT ListingFilterExtension : public QObject
75 {
76  Q_OBJECT
77 
78 public:
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 */
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 
143 private:
144  std::unique_ptr<ListingFilterExtension> const d;
145 };
146 
147 Q_DECLARE_OPERATORS_FOR_FLAGS(ListingFilterExtension::FilterModes)
148 
149 }
150 
151 #endif /* KPARTS_LISTINGFILTEREXTENSION_H */
FilterMode
Supported file filtering modes modes.
An extension for filtering listings.
Base class for any "viewer" part.
Definition: readonlypart.h:51
The KParts namespace,.
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Tue Aug 9 2022 03:51:33 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.