apps/keditbookmarks/kebsearchline.h

   1 /* This file is part of the KDE project
   2    Copyright (C) 2005 Daniel Teske <teske@squorn.de>
   3
   4    This program is free software; you can redistribute it and/or
   5    modify it under the terms of the GNU General Public License as
   6    published by the Free Software Foundation; either version 2 of
   7    the License, or (at your option) version 3.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program.  If not, see <http://www.gnu.org/licenses/>
  16 */
  17
  18 #ifndef __kebsearchline_h
  19 #define __kebsearchline_h
  20
  21 #include <k3listviewsearchline.h>
  22 #include <kglobal.h>
  23 #include <klocale.h>
  24 #include <ktoolbar.h>
  25 #include <kiconloader.h>
  26 #include <kdebug.h>
  27
  28 #include <QtCore/QTimer>
  29 #include <QtGui/QAbstractItemView>
  30 #include <QtGui/QListView>
  31 #include <QtGui/QTreeView>
  32 #include <QtGui/QMenu>
  33 #include <QtGui/QAction>
  34 #include <QtGui/QToolButton>
  35 #include <QtGui/QApplication>
  36 #include <QtGui/QLabel>
  37 #include <QtCore/QLinkedList>
  38
  39
  40
  41 class KViewSearchLinePrivate;
  42 /**
  43  * This class makes it easy to add a search line for filtering the items in a
  44  * QListView/QTreeView based on a simple text search.
  45  *
  46  * No changes to the application other than instantiating this class with an
  47  * appropriate QListView/QTreeView should be needed.
  48  *
  49  * This class automatically responds to the dataChanged(), rowsInserted(),
  50  * rowsRemoved() and similar signals.
  51  * This means that the view needs to be bound to a model().
  52  *
  53  * Note: Don't call setModel() on the view while a KViewSearchLine filters
  54  * the view. (Instead call setView(0) before and setView(view) after calling
  55  * setModel()
  56  *
  57  *
  58  * Note: You need to call updateSearch() if you called QListView::setModelColumn()
  59  */
  60
  61 //FIXME delete KViewSearchLine if there is a replacement in kdelibs
  62 class KViewSearchLine : public KLineEdit
  63 {
  64     Q_OBJECT
  65
  66 public:
  67     /**
  68      * Constructs a KViewSearchLine with \a view being the QTreeView/QListView
  69      * to be filtered.
  70      *
  71      * If \a view is null then the widget will be disabled until a listview
  72      * is set with setListView().
  73      */
  74     explicit KViewSearchLine(QWidget *parent = 0, QAbstractItemView *view = 0);
  75
  76     /**
  77      * Constructs a KViewSearchLine without any QListView/QTreeView to filter. The
  78      * QListView/QTreeView object has to be set later with setListView().
  79      */
  80     KViewSearchLine(QWidget *parent);
  81
  82     /**
  83      * Destroys the KViewSearchLine.
  84      */
  85     virtual ~KViewSearchLine();
  86
  87     /**
  88      * Returns true if the search is case sensitive.  This defaults to false.
  89      *
  90      * @see setCaseSensitive()
  91      */
  92     bool caseSensitive() const;
  93
  94     /**
  95      * Returns the current list of columns that will be searched.  If the
  96      * returned list is empty all visible columns will be searched.
  97      *
  98      * @see setSearchColumns
  99      */
 100     QLinkedList<int> searchColumns() const;
 101
 102     /**
 103      * If this is true (the default) then the parents of matched items will also
 104      * be shown.
 105      *
 106      * @see setKeepParentsVisible()
 107      */
 108     bool keepParentsVisible() const;
 109
 110     /**
 111      * Returns the view that is currently filtered by the search.
 112      *
 113      * @see setView()
 114      */
 115     QAbstractItemView *view() const;
 116
 117 public Q_SLOTS:
 118     /**
 119      * Updates search to only make visible the items that match \a s.  If
 120      * \a s is null then the line edit's text will be used.
 121      */
 122     virtual void updateSearch(const QString &s = QString());
 123
 124     /**
 125      * Make the search case sensitive or case insensitive.
 126      *
 127      * @see caseSenstive()
 128      */
 129     void setCaseSensitive(bool cs);
 130
 131     /**
 132      * When a search is active on a list that's organized into a tree view if
 133      * a parent or ancesestor of an item is does not match the search then it
 134      * will be hidden and as such so too will any children that match.
 135      *
 136      * If this is set to true (the default) then the parents of matching items
 137      * will be shown.
 138      *
 139      * This applys only to QTreeViews.
 140      *
 141      * @see keepParentsVisible
 142      */
 143     void setKeepParentsVisible(bool v);
 144
 145     /**
 146      * Sets the list of columns to be searched.  The default is to search all,
 147      * visible columns which can be restored by passing \a columns as an empty
 148      * list.
 149      * This has no effect if the view is a QListView.
 150      *
 151      * @see searchColumns
 152      */
 153     void setSearchColumns(const QLinkedList<int> &columns);
 154
 155     /**
 156      * Sets the view that is filtered by this search line.
 157      * If \a v is null then the widget will be disabled.
 158      * v must be either a QListView or a QTreeView
 159      * (That includes QListWidget and QTreeWidget)
 160      * @see view()
 161      */
 162     void setView(QAbstractItemView *v);
 163
 164 protected:
 165
 166     /**
 167      * Returns true if the row including \a item matches the search \a s.
 168      * This will be evaluated based on the value of caseSensitive() and
 169      * searchColumns().  This can be overridden in subclasses to implement
 170      * more complicated matching schemes.
 171      */
 172     virtual bool itemMatches(const QModelIndex & item, const QString &s) const;
 173
 174     /**
 175     * Re-implemented for internal reasons.  API not affected.
 176     */
 177     virtual void contextMenuEvent( QContextMenuEvent*e );
 178
 179 protected Q_SLOTS:
 180     /**
 181      * When keys are pressed a new search string is created and a timer is
 182      * activated.  The most recent search is activated when this timer runs out
 183      * if another key has not yet been pressed.
 184      *
 185      * This method makes @param search the most recent search and starts the
 186      * timer.
 187      *
 188      * Together with activateSearch() this makes it such that searches are not
 189      * started until there is a short break in the users typing.
 190      *
 191      * @see activateSearch()
 192      */
 193     void queueSearch(const QString &search);
 194
 195     /**
 196      * When the timer started with queueSearch() expires this slot is called.
 197      * If there has been another timer started then this slot does nothing.
 198      * However if there are no other pending searches this starts the list view
 199      * search.
 200      *
 201      * @see queueSearch()
 202      */
 203     void activateSearch();
 204
 205 private:
 206     /**
 207      * QListView's and QTreeView's setRowHidden are slightly different.
 208      */
 209     void setVisible(QModelIndex index, bool v);
 210
 211     /**
 212      * This is used in case parent items of matching items shouldn't be
 213      * visible.  It hides all items that don't match the search string.
 214      */
 215     void checkItemParentsNotVisible();
 216
 217     /**
 218      * This is used in case parent items of matching items should be visible.
 219      * It makes a recursive call to all children.  It returns true if at least
 220      * one item in the subtree with the given root item is visible.
 221      */
 222     bool checkItemParentsVisible(QModelIndex index);
 223
 224     /**
 225      * returns whether any row between first and last is visible
 226      */
 227     bool anyVisible(const QModelIndex & first, const QModelIndex & last);
 228
 229     /**
 230      * rechecks indecies first-last after a dataChanged() signal
 231      * sets their visibility and returns true if any item should be
 232      * visible
 233      */
 234     bool recheck(const QModelIndex & first, const QModelIndex & last);
 235
 236     /**
 237      * Hide QListView/QTreeView's different isRowHidden
 238      */
 239     bool isVisible(const QModelIndex & index);
 240
 241     /**
 242      * returns the model() of the view()
 243      */
 244     QAbstractItemModel * model() const;
 245
 246     /**
 247      * returns the index exactly one row below \p index
 248      */
 249     QModelIndex nextRow(const QModelIndex & index);
 250
 251 private Q_SLOTS:
 252     void listViewDeleted();
 253     void slotDataChanged(const QModelIndex &topLeft, const QModelIndex &bottomRight);
 254     void slotRowsInserted(const QModelIndex &parent, int first, int last);
 255     void slotRowsRemoved(const QModelIndex &parent, int first, int last);
 256     void slotColumnsInserted(const QModelIndex &parent, int first, int last);
 257     void slotColumnsRemoved(const QModelIndex &parent, int first, int last);
 258     void slotModelReset();
 259     void searchColumnsMenuActivated(QAction * act);
 260
 261 private:
 262     class KViewSearchLinePrivate;
 263     KViewSearchLinePrivate *d;
 264         QVector<QAction *> actions;
 265 };
 266
 267 /**
 268  * Creates a widget featuring a KViewSearchLine, a label with the text
 269  * "Search" and a button to clear the search.
 270  */
 271 class KViewSearchLineWidget : public QWidget
 272 {
 273     Q_OBJECT
 274
 275 public:
 276     /**
 277      * Creates a KListViewSearchLineWidget for \a view with \a parent as the
 278      * parent
 279      */
 280     explicit KViewSearchLineWidget(QAbstractItemView *view = 0, QWidget *parent = 0);
 281
 282     /**
 283      * Destroys the KListViewSearchLineWidget
 284      */
 285     ~KViewSearchLineWidget();
 286
 287     /**
 288      * Creates the search line.  This can be useful to reimplement in cases where
 289      * a K3ListViewSearchLine subclass is used.
 290      */
 291     virtual KViewSearchLine *createSearchLine(QAbstractItemView *view);
 292
 293     /**
 294      * Returns a pointer to the search line.
 295      */
 296     KViewSearchLine *searchLine() const;
 297
 298 protected Q_SLOTS:
 299     /**
 300      * Creates the widgets inside of the widget.  This is called from the
 301      * constructor via a single shot timer so that it it guaranteed to run
 302      * after construction is complete.  This makes it suitable for overriding in
 303      * subclasses.
 304      */
 305     virtual void createWidgets();
 306
 307 private:
 308     class KViewSearchLineWidgetPrivate;
 309     KViewSearchLineWidgetPrivate *d;
 310 };
 311
 312
 313 #endif