1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2022 Nicolas Fella <nicolas.fella@gmx.de>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KFILEFILTER_H
9#define KFILEFILTER_H
10
11#include "kiocore_export.h"
12
13#include <QSharedDataPointer>
14#include <QString>
15#include <QStringList>
16
17class KFileFilterPrivate;
18
19/*!
20 * \class KFileFilter
21 * \inmodule KIOCore
22 *
23 * Encapsulates rules to filter a list of files.
24 * Files can be filtered based on name patterns (e.g. *.cpp), MIME types, or both.
25 * Filters also optionally have a user-facing label.
26 *
27 * \since 5.101
28 */
29class KIOCORE_EXPORT KFileFilter
30{
31public:
32 /*!
33 * Creates an empty filter.
34 */
35 explicit KFileFilter();
36
37 /*!
38 * Creates a filter with a given label, name patterns, and MIME types.
39 *
40 * \a label The user-facing label for this filter.
41 *
42 * \a filePatterns A list of file name patterns that should be included, e.g. ("*.cpp", "*.cxx").
43 *
44 * \a mimePatterns A list of MIME types that should be included, e.g. ("text/plain", "image/png").
45 *
46 */
47 explicit KFileFilter(const QString &label, const QStringList &filePatterns, const QStringList &mimePatterns);
48
49 KFileFilter(const KFileFilter &other);
50 KFileFilter &operator=(const KFileFilter &other);
51 ~KFileFilter();
52
53 /*!
54 * Checks whether two filters are equal.
55 *
56 * Filters are considered equal if their file and name patters match.
57 * The label is ignored here.
58 */
59 bool operator==(const KFileFilter &other) const;
60
61 /*!
62 * The user-facing label for this filter.
63 *
64 * If no label is passed on creation one is created based on the patterns.
65 */
66 QString label() const;
67
68 /*!
69 * List of file name patterns that are included by this filter.
70 */
71 QStringList filePatterns() const;
72
73 /*!
74 * List of MIME types that are included by this filter;
75 */
76 QStringList mimePatterns() const;
77
78 /*!
79 * Converts this filter to a string representation
80 */
81 QString toFilterString() const;
82
83 /*!
84 * Whether the filer is empty, i.e.\ matches all files.
85 */
86 bool isEmpty() const;
87
88 /*!
89 * Whether the filter is valid.
90 *
91 * Creating a filter from an invalid/unkown MIME type will result in an invalid filter.
92 *
93 * \since 6.0
94 */
95 bool isValid() const;
96
97 /*!
98 * Creates a filter for one MIME type.
99 * The user-facing label is automatically determined from the MIME type.
100 */
101 static KFileFilter fromMimeType(const QString &mimeType);
102
103 /*!
104 * Creates filters from a list of MIME types.
105 * The user-facing label is automatically determined from the MIME type.
106 *
107 * \since 6.0
108 */
109 static QList<KFileFilter> fromMimeTypes(const QStringList &mimeTypes);
110
111private:
112 /*!
113 * Convert a filter string understood by KFileWidget to a list of KFileFilters.
114 * \internal
115 */
116 static QList<KFileFilter> fromFilterString(const QString &filterString);
117 friend class KFileFilterCombo;
118 friend class KFileFilterTest;
119 friend class KFileFilterComboPrivate;
120 friend class KFileWidgetTest;
121 friend class KFileFilterComboTest;
122 friend class KDEPlatformFileDialog;
123 friend class KDEPlatformFileDialogHelper;
124 friend class KEncodingFileDialog;
125
126 QSharedDataPointer<KFileFilterPrivate> d;
127};
128
129KIOCORE_EXPORT QDebug operator<<(QDebug dbg, const KFileFilter &filter);
130
131#endif
132

source code of kio/src/core/kfilefilter.h