src/plugins/find/ifindfilter.cpp

   1 /**************************************************************************
   2 **
   3 ** This file is part of Qt Creator
   4 **
   5 ** Copyright (c) 2011 Nokia Corporation and/or its subsidiary(-ies).
   6 **
   7 ** Contact: Nokia Corporation (info@qt.nokia.com)
   8 **
   9 **
  10 ** GNU Lesser General Public License Usage
  11 **
  12 ** This file may be used under the terms of the GNU Lesser General Public
  13 ** License version 2.1 as published by the Free Software Foundation and
  14 ** appearing in the file LICENSE.LGPL included in the packaging of this file.
  15 ** Please review the following information to ensure the GNU Lesser General
  16 ** Public License version 2.1 requirements will be met:
  17 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  18 **
  19 ** In addition, as a special exception, Nokia gives you certain additional
  20 ** rights. These rights are described in the Nokia Qt LGPL Exception
  21 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  22 **
  23 ** Other Usage
  24 **
  25 ** Alternatively, this file may be used in accordance with the terms and
  26 ** conditions contained in a signed written agreement between you and Nokia.
  27 **
  28 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **************************************************************************/
  32
  33 #include "ifindfilter.h"
  34
  35 /*!
  36     \class Find::IFindFilter
  37     \brief The IFindFilter class is the base class for find implementations
  38     that are invoked via the \gui{Edit -> Find/Replace -> Advanced Find}
  39     dialog.
  40
  41     Implementations of this class add an additional "Scope" to the Advanced
  42     Find dialog. That can be any search that requires the user to provide
  43     a text based search term (potentially with find flags like
  44     searching case sensitively or using regular expressions). Existing
  45     scopes are e.g. "All Projects" (i.e. search in all files in all projects)
  46     and "Files on File System" where the user provides a directory and file
  47     patterns to search.
  48
  49     To make your find scope available to the user, you need to implement this
  50     class, and register an instance of your subclass in the plugin manager.
  51
  52     A common way to present the search results to the user, is to use the
  53     shared \gui{Search Results} panel.
  54
  55     If you want to implement a find filter that is doing a file based text
  56     search, you should use Find::BaseFileFind, which already implements all
  57     the details for this kind of search, only requiring you to provide an
  58     iterator over the file names of the files that should be searched.
  59
  60     If you want to implement a more specialized find filter, you'll need
  61     to
  62     \list
  63         \o Start your search in a separate thread
  64         \o Make this known to the Core::ProgressManager, for a progress bar
  65            and the ability to cancel the search
  66         \o Interface with the shared \gui{Search Results} panel, to show
  67            the search results, handle the event that the user click on one
  68            of the search result items, and possible handle a global replace
  69            of all or some of the search result items.
  70     \endlist
  71
  72     Luckily QtConcurrent and the search result panel provide the frameworks
  73     that make it relatively easy to implement,
  74     while ensuring a common way for the user.
  75
  76     The common pattern is roughly this:
  77
  78     Implement the actual search within a QtConcurrent based method, i.e.
  79     a method that takes a \c{QFutureInterface<MySearchResult> &future}
  80     as the first parameter and the other information needed for the search
  81     as additional parameters. It should set useful progress information
  82     on the QFutureInterface, regularly check for \c{future.isPaused()}
  83     and \c{future.isCanceled()}, and report the search results
  84     (possibly in chunks) via \c{future.reportResult}.
  85
  86     In the find filter's find/replaceAll method, get the shared
  87     \gui{Search Results} window, initiate a new search and connect the
  88     signals for handling selection of results and the replace action
  89     (see the Find::SearchResultWindow class for details).
  90     Start your search implementation via the corresponding QtConcurrent
  91     methods. Add the returned QFuture object to the Core::ProgressManager.
  92     Use a QFutureWatcher on the returned QFuture object to receive a signal
  93     when your search implementation reports search results, and add these
  94     to the shared \gui{Search Results} window.
  95 */
  96
  97 /*!
  98     \fn IFindFilter::~IFindFilter()
  99     \internal
 100 */
 101
 102 /*!
 103     \fn QString IFindFilter::id() const
 104     \brief Unique string identifier for this find filter.
 105
 106     Usually should be something like "MyPlugin.MyFindFilter".
 107 */
 108
 109 /*!
 110     \fn QString IFindFilter::displayName() const
 111     \brief The name of the find filter/scope as presented to the user.
 112
 113     This is the name that e.g. appears in the scope selection combo box.
 114     Always return a translatable string (i.e. use tr() for the return value).
 115 */
 116
 117 /*!
 118     \fn bool IFindFilter::isEnabled() const
 119     \brief Returns if the user should be able to select this find filter
 120     at the moment.
 121
 122     This is used e.g. for the "Current Projects" scope - if the user hasn't
 123     opened a project, the scope is disabled.
 124
 125     \sa changed()
 126 */
 127
 128 /*!
 129     \fn QKeySequence IFindFilter::defaultShortcut() const
 130     \brief Returns the shortcut that can be used to open the advanced find
 131     dialog with this filter/scope preselected.
 132
 133     Usually return an empty shortcut here, the user can still choose and
 134     assign a specific shortcut to this find scope via the preferences.
 135 */
 136
 137 /*!
 138     \fn bool IFindFilter::isReplaceSupported() const
 139     \brief Returns if the find filter supports search and replace.
 140
 141     The default value is false, override this method to return true, if
 142     your find filter supports global search and replace.
 143 */
 144
 145 /*!
 146     \fn void IFindFilter::findAll(const QString &txt, Find::FindFlags findFlags)
 147     \brief This method is called when the user selected this find scope and
 148     initiated a search.
 149
 150     You should start a thread which actually performs the search for \a txt
 151     using the given \a findFlags
 152     (add it to Core::ProgressManager for a progress bar!) and presents the
 153     search results to the user (using the \gui{Search Results} output pane).
 154     For more information see the descriptions of this class,
 155     Core::ProgressManager, and Find::SearchResultWindow.
 156
 157     \sa replaceAll()
 158     \sa Core::ProgressManager
 159     \sa Find::SearchResultWindow
 160 */
 161
 162 /*!
 163     \fn void IFindFilter::replaceAll(const QString &txt, Find::FindFlags findFlags)
 164     \brief Override this method if you want to support search and replace.
 165
 166     This method is called when the user selected this find scope and
 167     initiated a search and replace.
 168     The default implementation does nothing.
 169
 170     You should start a thread which actually performs the search for \a txt
 171     using the given \a findFlags
 172     (add it to Core::ProgressManager for a progress bar!) and presents the
 173     search results to the user (using the \gui{Search Results} output pane).
 174     For more information see the descriptions of this class,
 175     Core::ProgressManager, and Find::SearchResultWindow.
 176
 177     \sa findAll()
 178     \sa Core::ProgressManager
 179     \sa Find::SearchResultWindow
 180 */
 181
 182 /*!
 183     \fn QWidget *IFindFilter::createConfigWidget()
 184     \brief Return a widget that contains additional controls for options
 185     for this find filter.
 186
 187     The widget will be shown below the common options in the Advanced Find
 188     dialog. It will be reparented and deleted by the find plugin.
 189 */
 190
 191 /*!
 192     \fn void IFindFilter::writeSettings(QSettings *settings)
 193     \brief Called at shutdown to write the state of the additional options
 194     for this find filter to the \a settings.
 195 */
 196
 197 /*!
 198     \fn void IFindFilter::readSettings(QSettings *settings)
 199     \brief Called at startup to read the state of the additional options
 200     for this find filter from the \a settings.
 201 */
 202
 203 /*!
 204     \fn void IFindFilter::changed()
 205     \brief Signals that the enabled state of this find filter has changed.
 206 */
 207
 208 /*!
 209     \fn Find::FindFlags BaseTextFind::supportedFindFlags() const
 210     \brief Returns the find flags, like whole words or regular expressions,
 211     that this find filter supports.
 212
 213     Depending on the returned value, the default find option widgets are
 214     enabled or disabled.
 215     The default is Find::FindCaseSensitively, Find::FindRegularExpression
 216     and Find::FindWholeWords
 217 */
 218 Find::FindFlags Find::IFindFilter::supportedFindFlags() const
 219 {
 220     return Find::FindCaseSensitively
 221             | Find::FindRegularExpression | Find::FindWholeWords;
 222 }