apps/konsole/src/IncrementalSearchBar.h

   1 /*
   2     Copyright 2006-2008 by Robert Knight <robertknight@gmail.com>
   3
   4     This program is free software; you can redistribute it and/or modify
   5     it under the terms of the GNU General Public License as published by
   6     the Free Software Foundation; either version 2 of the License, or
   7     (at your option) any later version.
   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, write to the Free Software
  16     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  17     02110-1301  USA.
  18 */
  19
  20 #ifndef INCREMENTALSEARCHBAR_H
  21 #define INCREMENTALSEARCHBAR_H
  22
  23 // Qt
  24 #include <QtGui/QWidget>
  25
  26 class QCheckBox;
  27 class QLabel;
  28 class QProgressBar;
  29 class QTimer;
  30 class KLineEdit;
  31
  32 namespace Konsole
  33 {
  34
  35 /**
  36  * A widget which allows users to search incrementally through a document for a
  37  * a text string or regular expression.
  38  *
  39  * The widget consists of a text box into which the user can enter their search text and
  40  * buttons to trigger a search for the next and previous matches for the search text.
  41  *
  42  * When the search text is changed, the searchChanged() signal is emitted.  A search through
  43  * the document for the new text should begin immediately and the active view of the document
  44  * should jump to display any matches if found.  setFoundMatch() should be called whenever the
  45  * search text changes to indicate whether a match for the text was found in the document.
  46  *
  47  * findNextClicked() and findPreviousClicked() signals are emitted when the user presses buttons
  48  * to find next and previous matches respectively.
  49  *
  50  * The search bar has a number of optional features which can be enabled or disabled by passing
  51  * a set of Features flags to the constructor.
  52  *
  53  * An optional checkbox can be displayed to indicate whether all matches in the document
  54  * for searchText() should be highlighted.
  55  * The highlightMatchesToggled() signal is emitted when this checkbox is toggled.
  56  *
  57  * The two further optional checkboxes allow the user to control the matching process.
  58  * The first indicates whether searches are case sensitive.
  59  * The matchCaseToggled() signal is emitted when this is changed.
  60  * The second indicates whether the search text should be treated as a plain string or
  61  * as a regular expression.
  62  * The matchRegExpToggled() signal is emitted when this is changed.
  63  */
  64 class IncrementalSearchBar : public QWidget
  65 {
  66 Q_OBJECT
  67
  68 public:
  69     enum Continue
  70     {
  71         /**
  72          * Indicates that the search has reached the bottom of the document and has been continued from
  73          * the top
  74          */
  75         ContinueFromTop,
  76         /**
  77          * Indicates that the search has reached the top of the document and has been continued from
  78          * the bottom
  79          */
  80         ContinueFromBottom,
  81
  82         /** Clears the Continue flag */
  83         ClearContinue
  84     };
  85
  86     /**
  87      * This enum defines the features which can be supported by an implementation of
  88      * an incremental search bar
  89      */
  90     enum Features
  91     {
  92         /** search facility supports highlighting of all matches */
  93         HighlightMatches = 1,
  94         /** search facility supports case-sensitive and case-insensitive search */
  95         MatchCase        = 2,
  96         /** search facility supports regular expressions */
  97         RegExp           = 4,
  98         /** search facility supports all features */
  99         AllFeatures      = HighlightMatches | MatchCase | RegExp
 100     };
 101
 102     /**
 103      * Constructs a new incremental search bar with the given parent widget
 104      * @p features specifies the features which should be made available to the user.
 105      */
 106     explicit IncrementalSearchBar(Features features , QWidget* parent = 0);
 107
 108     /**
 109      * Sets an indicator for the user as to whether or not a match for the
 110      * current search text was found in the document.
 111      *
 112      * The indicator will not be shown if the search text is empty ( because
 113      * the user has not yet entered a query ).
 114      *
 115      * @param match True if a match was found or false otherwise.  If true,
 116      * and the search text is non-empty, an indicator that no matches were
 117      * found will be shown.
 118      */
 119     void setFoundMatch( bool match );
 120
 121     /**
 122      * Sets a flag to indicate that the current search for matches has reached the top or bottom of
 123      * the document and has been continued again from the other end of the document.
 124      *
 125      * This flag will be cleared when the user presses the buttons to find a next or previous match.
 126      */
 127     void setContinueFlag( Continue flag );
 128
 129     /** Returns the current search text */
 130     QString searchText();
 131     /**
 132      * Returns whether matches for the current search text should be highlighted in the document.
 133      * Always returns true if the highlight matches checkbox is not visible.
 134      */
 135     bool highlightMatches();
 136     /**
 137      * Returns whether matching for the current search text should be case sensitive.
 138      * Always returns false if the match case checkbox is not visible.
 139      */
 140     bool matchCase();
 141     /**
 142      * Returns whether the current search text should be treated as plain text or a regular expression
 143      * Always returns false if the match regular expression checkbox is not visible.
 144      */
 145     bool matchRegExp();
 146
 147     // reimplemented
 148     virtual void setVisible( bool visible );
 149 signals:
 150     /** Emitted when the text entered in the search box is altered */
 151     void searchChanged( const QString& text );
 152     /** Emitted when the user clicks the button to find the next match */
 153     void findNextClicked();
 154     /** Emitted when the user clicks the button to find the previous match */
 155     void findPreviousClicked();
 156     /**
 157      * Emitted when the user toggles the checkbox to indicate whether
 158      * matches for the search text should be highlighted
 159      */
 160     void highlightMatchesToggled(bool);
 161     /**
 162      * Emitted when the user toggles the checkbox to indicate whether
 163      * matching for the search text should be case sensitive
 164      */
 165     void matchCaseToggled(bool);
 166     /**
 167      * Emitted when the user toggles the checkbox to indicate whether
 168      * the search text should be treated as a plain string or a regular expression
 169      */
 170     void matchRegExpToggled(bool);
 171     /** Emitted when the close button is clicked */
 172     void closeClicked();
 173
 174 protected:
 175     virtual bool eventFilter( QObject* watched , QEvent* event );
 176
 177 private slots:
 178     void notifySearchChanged();
 179     void clearLineEdit();
 180
 181 private:
 182     bool _foundMatch;
 183     QCheckBox* _matchCaseBox;
 184     QCheckBox* _matchRegExpBox;
 185     QCheckBox* _highlightBox;
 186
 187     KLineEdit* _searchEdit;
 188     QLabel* _continueLabel;
 189     QProgressBar* _progress;
 190
 191     QTimer* _searchTimer;
 192 };
 193
 194 }
 195 #endif // INCREMENTALSEARCHBAR_H