File indexing completed on 2024-04-14 11:09:25

0001 /*
0002     This file is part of the KDE libraries
0003     SPDX-FileCopyrightText: 2003 Scott Wheeler <wheeler@kde.org>
0004     SPDX-FileCopyrightText: 2004 Gustavo Sverzut Barbieri <gsbarbieri@users.sourceforge.net>
0005 
0006     SPDX-License-Identifier: LGPL-2.0-or-later
0007 */
0008 
0009 #ifndef KLISTWIDGETSEARCHLINE_H
0010 #define KLISTWIDGETSEARCHLINE_H
0011 
0012 #include <QLineEdit>
0013 #include <memory>
0014 
0015 #include <kitemviews_export.h>
0016 
0017 class QListWidget;
0018 class QListWidgetItem;
0019 class QModelIndex;
0020 
0021 /**
0022  * @class KListWidgetSearchLine klistwidgetsearchline.h KListWidgetSearchLine
0023  *
0024  * This class makes it easy to add a search line for filtering the items in a
0025  * listwidget based on a simple text search.
0026  *
0027  * No changes to the application other than instantiating this class with an
0028  * appropriate QListWidget should be needed.
0029  */
0030 class KITEMVIEWS_EXPORT KListWidgetSearchLine : public QLineEdit
0031 {
0032     Q_OBJECT
0033 #if KITEMVIEWS_BUILD_DEPRECATED_SINCE(5, 0)
0034     Q_PROPERTY(QString clickMessage READ clickMessage WRITE setClickMessage)
0035 #endif
0036 
0037 public:
0038     /**
0039      * Constructs a KListWidgetSearchLine with \a listWidget being the QListWidget to
0040      * be filtered.
0041      *
0042      * If \a listWidget is null then the widget will be disabled until a listWidget
0043      * is set with setListWidget().
0044      */
0045     explicit KListWidgetSearchLine(QWidget *parent = nullptr, QListWidget *listWidget = nullptr);
0046 
0047     /**
0048      * Destroys the KListWidgetSearchLine.
0049      */
0050     ~KListWidgetSearchLine() override;
0051 
0052     /**
0053      * Returns if the search is case sensitive.  This defaults to Qt::CaseInsensitive.
0054      *
0055      * @see setCaseSensitive()
0056      */
0057     Qt::CaseSensitivity caseSensitive() const;
0058 
0059     /**
0060      * Returns the listWidget that is currently filtered by the search.
0061      *
0062      * @see setListWidget()
0063      */
0064     QListWidget *listWidget() const;
0065 
0066 #if KITEMVIEWS_ENABLE_DEPRECATED_SINCE(5, 0)
0067     /**
0068      * @return the message set with setClickMessage
0069      * @deprecated since 5.0, use QLineEdit::placeholderText() instead.
0070      **/
0071     KITEMVIEWS_DEPRECATED_VERSION(5, 0, "Use QLineEdit::placeholderText()")
0072     QString clickMessage() const
0073     {
0074         return placeholderText();
0075     }
0076 #endif
0077 
0078 #if KITEMVIEWS_ENABLE_DEPRECATED_SINCE(5, 0)
0079     /**
0080      * This makes the line edit display a grayed-out hinting text as long as
0081      * the user didn't enter any text. It is often used as indication about
0082      * the purpose of the line edit.
0083      * @deprecated since 5.0, use QLineEdit::setPlaceholderText() instead.
0084      */
0085     KITEMVIEWS_DEPRECATED_VERSION(5, 0, "Use QLineEdit::setPlaceholderText(const QString&)")
0086     void setClickMessage(const QString &msg)
0087     {
0088         setPlaceholderText(msg);
0089     }
0090 #endif
0091 
0092 public Q_SLOTS:
0093     /**
0094      * Updates search to only make visible the items that match \a s.  If
0095      * \a s is null then the line edit's text will be used.
0096      */
0097     virtual void updateSearch(const QString &s = QString());
0098 
0099     /**
0100      * Make the search case sensitive or case insensitive.
0101      *
0102      * @see caseSenstive()
0103      */
0104     void setCaseSensitivity(Qt::CaseSensitivity cs);
0105 
0106     /**
0107      * Sets the QListWidget that is filtered by this search line.  If \a lv is null
0108      * then the widget will be disabled.
0109      *
0110      * @see listWidget()
0111      */
0112     void setListWidget(QListWidget *lv);
0113 
0114     /**
0115      * Clear line edit and empty hiddenItems, returning elements to listWidget.
0116      */
0117     void clear();
0118 
0119 protected:
0120     /**
0121      * Returns true if \a item matches the search \a s.  This will be evaluated
0122      * based on the value of caseSensitive().  This can be overridden in
0123      * subclasses to implement more complicated matching schemes.
0124      */
0125     virtual bool itemMatches(const QListWidgetItem *item, const QString &s) const;
0126     /**
0127      * Re-implemented for internal reasons.  API not affected.
0128      */
0129     bool event(QEvent *event) override;
0130 
0131 private:
0132     friend class KListWidgetSearchLinePrivate;
0133     std::unique_ptr<class KListWidgetSearchLinePrivate> const d;
0134 
0135     Q_PRIVATE_SLOT(d, void _k_listWidgetDeleted())
0136     Q_PRIVATE_SLOT(d, void _k_queueSearch(const QString &))
0137     Q_PRIVATE_SLOT(d, void _k_activateSearch())
0138     Q_PRIVATE_SLOT(d, void _k_rowsInserted(const QModelIndex &, int, int))
0139     Q_PRIVATE_SLOT(d, void _k_dataChanged(const QModelIndex &, const QModelIndex &))
0140 };
0141 
0142 #endif /* KLISTWIDGETSEARCHLINE_H */