File indexing completed on 2024-07-21 03:41:06

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2022 Nicolas Fella <nicolas.fella@gmx.de>
0004 
0005     SPDX-License-Identifier: LGPL-2.0-or-later
0006 */
0007 
0008 #ifndef KFILEFILTER_H
0009 #define KFILEFILTER_H
0010 
0011 #include "kiocore_export.h"
0012 
0013 #include <QSharedDataPointer>
0014 #include <QString>
0015 #include <QStringList>
0016 
0017 class KFileFilterPrivate;
0018 
0019 /**
0020  * Encapsulates rules to filter a list of files.
0021  * Files can be filtered based on name patterns (e.g. *.cpp), MIME types, or both.
0022  * Filters also optionally have a user-facing label.
0023  *
0024  * @since 5.101
0025  */
0026 class KIOCORE_EXPORT KFileFilter
0027 {
0028 public:
0029     /**
0030      * Creates an empty filter.
0031      */
0032     explicit KFileFilter();
0033 
0034     /**
0035      * Creates a filter with a given label, name patterns, and MIME types.
0036      *
0037      * @param label The user-facing label for this filter.
0038      * @param filePatterns A list of file name patterns that should be included, e.g. ("*.cpp", "*.cxx").
0039      * @param mimePatterns A list of MIME types that should be included, e.g. ("text/plain", "image/png").
0040      *
0041      */
0042     explicit KFileFilter(const QString &label, const QStringList &filePatterns, const QStringList &mimePatterns);
0043 
0044     KFileFilter(const KFileFilter &other);
0045     KFileFilter &operator=(const KFileFilter &other);
0046     ~KFileFilter();
0047     bool operator==(const KFileFilter &other) const;
0048 
0049     /**
0050      * The user-facing label for this filter.
0051      *
0052      * If no label is passed on creation one is created based on the patterns.
0053      */
0054     QString label() const;
0055 
0056     /**
0057      * List of file name patterns that are included by this filter.
0058      */
0059     QStringList filePatterns() const;
0060 
0061     /**
0062      * List of MIME types that are included by this filter;
0063      */
0064     QStringList mimePatterns() const;
0065 
0066     /**
0067      * Converts this filter to a string representation understood by KFileWidget.
0068      */
0069     QString toFilterString() const;
0070 
0071     /**
0072      * Whether the filer is empty, i.e. matches all files.
0073      */
0074     bool isEmpty() const;
0075 
0076     /**
0077      * Whether the filter is valid.
0078      *
0079      * Creating a filter from an invalid/unkown MIME type will result in an invalid filter.
0080      *
0081      * @since 6.0
0082      */
0083     bool isValid() const;
0084 
0085     /*
0086      * Creates a filter for one MIME type.
0087      * The user-facing label is automatically determined from the MIME type.
0088      */
0089     static KFileFilter fromMimeType(const QString &mimeType);
0090 
0091     /**
0092      * Creates filters from a list of MIME types.
0093      * The user-facing label is automatically determined from the MIME type.
0094      *
0095      * @since 6.0
0096      */
0097     static QList<KFileFilter> fromMimeTypes(const QStringList &mimeTypes);
0098 
0099 private:
0100     /**
0101      * Convert a filter string understood by KFileWidget to a list of KFileFilters.
0102      */
0103     static QList<KFileFilter> fromFilterString(const QString &filterString);
0104     friend class KFileFilterCombo;
0105     friend class KFileFilterTest;
0106     friend class KFileFilterComboPrivate;
0107     friend class KFileWidgetTest;
0108     friend class KFileFilterComboTest;
0109     friend class KDEPlatformFileDialog;
0110     friend class KDEPlatformFileDialogHelper;
0111     friend class KEncodingFileDialog;
0112 
0113     QSharedDataPointer<KFileFilterPrivate> d;
0114 };
0115 
0116 KIOCORE_EXPORT QDebug operator<<(QDebug dbg, const KFileFilter &filter);
0117 
0118 #endif