diff --git a/doc/qtcreatordev/src/common-extension-tasks.qdoc b/doc/qtcreatordev/src/common-extension-tasks.qdoc index 1cf6c90c768..36f88967818 100644 --- a/doc/qtcreatordev/src/common-extension-tasks.qdoc +++ b/doc/qtcreatordev/src/common-extension-tasks.qdoc @@ -86,13 +86,13 @@ \row \li Add a find filter to the \uicontrol Find dialog. \li Implement any kind of search term based search. - \li \l{Find::IFindFilter}, \l{Core::SearchResultWindow} + \li \l{Core::IFindFilter}, \l{Core::SearchResultWindow} \row \li Add support for the find tool bar to a widget. \li The widget that has focus is asked whether it supports text search. You can add support for widgets under your control. - \li \l{Core::IFindSupport}, \l{Find::BaseTextFind} + \li \l{Core::IFindSupport}, \l{Core::BaseTextFind} \omit \row @@ -111,8 +111,7 @@ \li For a text typed in by the user you provide a list of things to show in the popup. When the user selects an entry you are requested to do whatever you want. - \li \l{Core::ILocatorFilter}, \l{Core::LocatorFilterEntry}, - \l{Locator::BaseFileFilter} + \li \l{Core::ILocatorFilter}, \l{Core::BaseFileFilter} \row \li Show a progress indicator for a concurrently running task. diff --git a/src/plugins/coreplugin/find/basetextfind.cpp b/src/plugins/coreplugin/find/basetextfind.cpp index ef7042bd5de..2d3cb7de0b5 100644 --- a/src/plugins/coreplugin/find/basetextfind.cpp +++ b/src/plugins/coreplugin/find/basetextfind.cpp @@ -81,17 +81,54 @@ BaseTextFindPrivate::BaseTextFindPrivate(QPlainTextEdit *editor) { } +/*! + \class Core::BaseTextFind + \inmodule QtCreator + + \brief The BaseTextFind class implements a find filter for QPlainTextEdit + and QTextEdit based widgets. + + \sa Core::IFindFilter +*/ + +/*! + \fn void BaseTextFind::findScopeChanged(const QTextCursor &start, + const QTextCursor &end, + int verticalBlockSelectionFirstColumn, + int verticalBlockSelectionLastColumn) + + This signal is emitted when the search + scope changes to \a start, \a end, + \a verticalBlockSelectionFirstColumn, and + \a verticalBlockSelectionLastColumn. +*/ + +/*! + \fn void BaseTextFind::highlightAllRequested(const QString &txt, Core::FindFlags findFlags) + + This signal is emitted when the search results for \a txt using the given + \a findFlags should be highlighted in the editor widget. +*/ + +/*! + \internal +*/ BaseTextFind::BaseTextFind(QTextEdit *editor) : d(new BaseTextFindPrivate(editor)) { } - +/*! + \internal +*/ BaseTextFind::BaseTextFind(QPlainTextEdit *editor) : d(new BaseTextFindPrivate(editor)) { } +/*! + \internal +*/ BaseTextFind::~BaseTextFind() { delete d; @@ -121,28 +158,43 @@ bool BaseTextFind::isReadOnly() const return d->m_editor ? d->m_editor->isReadOnly() : d->m_plaineditor->isReadOnly(); } +/*! + \reimp +*/ bool BaseTextFind::supportsReplace() const { return !isReadOnly(); } +/*! + \reimp +*/ FindFlags BaseTextFind::supportedFindFlags() const { return FindBackward | FindCaseSensitively | FindRegularExpression | FindWholeWords | FindPreserveCase; } +/*! + \reimp +*/ void BaseTextFind::resetIncrementalSearch() { d->m_incrementalStartPos = -1; d->m_incrementalWrappedState = false; } +/*! + \reimp +*/ void BaseTextFind::clearHighlights() { highlightAll(QString(), {}); } +/*! + \reimp +*/ QString BaseTextFind::currentFindString() const { QTextCursor cursor = textCursor(); @@ -168,6 +220,9 @@ QString BaseTextFind::currentFindString() const return QString(); } +/*! + \reimp +*/ QString BaseTextFind::completedFindString() const { QTextCursor cursor = textCursor(); @@ -176,6 +231,9 @@ QString BaseTextFind::completedFindString() const return cursor.selectedText(); } +/*! + \reimp +*/ IFindSupport::Result BaseTextFind::findIncremental(const QString &txt, FindFlags findFlags) { QTextCursor cursor = textCursor(); @@ -195,6 +253,9 @@ IFindSupport::Result BaseTextFind::findIncremental(const QString &txt, FindFlags return found ? Found : NotFound; } +/*! + \reimp +*/ IFindSupport::Result BaseTextFind::findStep(const QString &txt, FindFlags findFlags) { bool wrapped = false; @@ -208,6 +269,9 @@ IFindSupport::Result BaseTextFind::findStep(const QString &txt, FindFlags findFl return found ? Found : NotFound; } +/*! + \reimp +*/ void BaseTextFind::replace(const QString &before, const QString &after, FindFlags findFlags) { QTextCursor cursor = replaceInternal(before, after, findFlags); @@ -259,6 +323,9 @@ QTextCursor BaseTextFind::replaceInternal(const QString &before, const QString & return cursor; } +/*! + \reimp +*/ bool BaseTextFind::replaceStep(const QString &before, const QString &after, FindFlags findFlags) { QTextCursor cursor = replaceInternal(before, after, findFlags); @@ -269,6 +336,10 @@ bool BaseTextFind::replaceStep(const QString &before, const QString &after, Find return found; } +/*! + \reimp + Returns the number of search hits replaced. +*/ int BaseTextFind::replaceAll(const QString &before, const QString &after, FindFlags findFlags) { QTextCursor editCursor = textCursor(); @@ -408,6 +479,9 @@ bool BaseTextFind::inScope(int startPosition, int endPosition) const && d->m_findScopeEnd.position() >= endPosition); } +/*! + \reimp +*/ void BaseTextFind::defineFindScope() { QTextCursor cursor = textCursor(); @@ -436,6 +510,9 @@ void BaseTextFind::defineFindScope() } } +/*! + \reimp +*/ void BaseTextFind::clearFindScope() { d->m_findScopeStart = QTextCursor(); @@ -447,6 +524,10 @@ void BaseTextFind::clearFindScope() d->m_findScopeVerticalBlockSelectionLastColumn); } +/*! + \reimp + Emits highlightAllRequested(). +*/ void BaseTextFind::highlightAll(const QString &txt, FindFlags findFlags) { emit highlightAllRequested(txt, findFlags); diff --git a/src/plugins/coreplugin/find/findplugin.cpp b/src/plugins/coreplugin/find/findplugin.cpp index 04236779184..aa3165547c8 100644 --- a/src/plugins/coreplugin/find/findplugin.cpp +++ b/src/plugins/coreplugin/find/findplugin.cpp @@ -53,11 +53,13 @@ #include /*! - \namespace Core::Internal + \namespace Core::Internal::ItemDataRoles \internal */ + /*! - \namespace Core::Internal::ItemDataRoles + \class Core::Find + \inmodule QtCreator \internal */ diff --git a/src/plugins/coreplugin/find/highlightscrollbarcontroller.cpp b/src/plugins/coreplugin/find/highlightscrollbarcontroller.cpp index b9d07b70da4..f68739f1e22 100644 --- a/src/plugins/coreplugin/find/highlightscrollbarcontroller.cpp +++ b/src/plugins/coreplugin/find/highlightscrollbarcontroller.cpp @@ -36,6 +36,18 @@ using namespace Utils; namespace Core { +/*! + \class Core::Highlight + \inmodule QtCreator + \internal +*/ + +/*! + \class Core::HighlightScrollBarController + \inmodule QtCreator + \internal +*/ + class HighlightScrollBarOverlay : public QWidget { public: diff --git a/src/plugins/coreplugin/find/ifindfilter.cpp b/src/plugins/coreplugin/find/ifindfilter.cpp index c861d1e0df9..fef203a1f8c 100644 --- a/src/plugins/coreplugin/find/ifindfilter.cpp +++ b/src/plugins/coreplugin/find/ifindfilter.cpp @@ -33,27 +33,32 @@ #include /*! - \class Find::IFindFilter + \class Core::IFindFilter + \inmodule QtCreator \brief The IFindFilter class is the base class for find implementations - that are invoked by selecting \gui Edit > \gui {Find/Replace} > - \gui {Advanced Find}. + that are invoked by selecting \uicontrol Edit > \uicontrol {Find/Replace} > + \uicontrol {Advanced Find}. - Implementations of this class add an additional \gui Scope to the \gui {Advanced + Implementations of this class add an additional \uicontrol Scope to the \uicontrol {Advanced Find} dialog. That can be any search that requires the user to provide a text based search term (potentially with find flags like searching case sensitively or using regular expressions). Existing - scopes are \gui {All Projects} that searches from all files in all projects - and \gui {Files in File System} where the user provides a directory and file + scopes are \uicontrol {All Projects} that searches from all files in all projects + and \uicontrol {Files in File System} where the user provides a directory and file patterns to search. + \image qtcreator-search-filesystem.png + To make your find scope available to the user, you need to implement this class, and register an instance of your subclass in the plugin manager. A common way to present the search results to the user, is to use the - shared \gui{Search Results} panel. + shared \uicontrol{Search Results} pane. + + \image qtcreator-searchresults.png If you want to implement a find filter that is doing a file based text - search, you should use Find::BaseFileFind, which already implements all + search, you should use \l Core::BaseTextFind, which already implements all the details for this kind of search, only requiring you to provide an iterator over the file names of the files that should be searched. @@ -62,19 +67,18 @@ \li Start your search in a separate thread \li Make this known to the Core::ProgressManager, for a progress bar and the ability to cancel the search - \li Interface with the shared \gui{Search Results} panel, to show + \li Interface with the shared \uicontrol{Search Results} pane, to show the search results, handle the event that the user click on one of the search result items, and possible handle a global replace of all or some of the search result items. \endlist - Luckily QtConcurrent and the search result panel provide the frameworks + Luckily QtConcurrent and the search results pane provide the frameworks that make it relatively easy to implement, while ensuring a common way for the user. - The common pattern is roughly this: - - Implement the actual search within a QtConcurrent based function, that is + The common pattern is roughly to first implement the actual search + within a QtConcurrent based function. That is a function that takes a \c{QFutureInterface &future} as the first parameter and the other information needed for the search as additional parameters. It should set useful progress information @@ -82,21 +86,17 @@ and \c{future.isCanceled()}, and report the search results (possibly in chunks) via \c{future.reportResult}. - In the find filter's find/replaceAll function, get the shared - \gui{Search Results} window, initiate a new search and connect the + In the find filter's \c find() or \c replaceAll() function, get the shared + \uicontrol{Search Results} window, initiate a new search and connect the signals for handling selection of results and the replace action (see the Core::SearchResultWindow class for details). Start your search implementation via the corresponding QtConcurrent functions. Add the returned QFuture object to the Core::ProgressManager. Use a QFutureWatcher on the returned QFuture object to receive a signal when your search implementation reports search results, and add these - to the shared \gui{Search Results} window. + to the shared \uicontrol{Search Results} window. */ -/*! - \fn IFindFilter::~IFindFilter() - \internal -*/ /*! \fn QString IFindFilter::id() const @@ -110,7 +110,8 @@ Returns the name of the find filter or scope as presented to the user. This is the name that appears in the scope selection combo box, for example. - Always return a translatable string (that is, use tr() for the return value). + Always return a translatable string. That is, use \c tr() for the return + value. */ /*! @@ -118,20 +119,18 @@ Returns whether the user should be able to select this find filter at the moment. - This is used for the \gui {Current Projects} scope, for example. If the user + This is used for the \uicontrol {Current Projects} scope, for example. If the user has not opened a project, the scope is disabled. - \sa changed() + \sa enabledChanged() */ /*! - \fn QKeySequence IFindFilter::defaultShortcut() const - Returns the shortcut that can be used to open the advanced find - dialog with this filter or scope preselected. + \fn bool IFindFilter::isValid() const + Returns whether the find filter is valid. - Usually return an empty shortcut here, the user can still choose and - assign a specific shortcut to this find scope via the preferences. + \sa validChanged() */ /*! @@ -143,7 +142,7 @@ */ /*! - \fn bool showSearchTermInput() const + \fn bool IFindFilter::showSearchTermInput() const Returns whether the find filter wants to show the search term line edit. The default value is \c true, override this function to return \c false, if @@ -151,14 +150,14 @@ */ /*! - \fn void IFindFilter::findAll(const QString &txt, Core::FindFlags findFlags) + \fn void IFindFilter::findAll(const QString &txt, FindFlags findFlags) This function is called when the user selected this find scope and initiated a search. You should start a thread which actually performs the search for \a txt using the given \a findFlags - (add it to Core::ProgressManager for a progress bar!) and presents the - search results to the user (using the \gui{Search Results} output pane). + (add it to Core::ProgressManager for a progress bar) and presents the + search results to the user (using the \uicontrol{Search Results} output pane). For more information, see the descriptions of this class, Core::ProgressManager, and Core::SearchResultWindow. @@ -168,7 +167,7 @@ */ /*! - \fn void IFindFilter::replaceAll(const QString &txt, Core::FindFlags findFlags) + \fn void IFindFilter::replaceAll(const QString &txt, FindFlags findFlags) Override this function if you want to support search and replace. This function is called when the user selected this find scope and @@ -177,8 +176,8 @@ You should start a thread which actually performs the search for \a txt using the given \a findFlags - (add it to Core::ProgressManager for a progress bar!) and presents the - search results to the user (using the \gui{Search Results} output pane). + (add it to Core::ProgressManager for a progress bar) and presents the + search results to the user (using the \uicontrol{Search Results} output pane). For more information see the descriptions of this class, Core::ProgressManager, and Core::SearchResultWindow. @@ -192,7 +191,7 @@ Returns a widget that contains additional controls for options for this find filter. - The widget will be shown below the common options in the \gui {Advanced Find} + The widget will be shown below the common options in the \uicontrol {Advanced Find} dialog. It will be reparented and deleted by the find plugin. */ @@ -211,44 +210,71 @@ /*! \fn void IFindFilter::enabledChanged(bool enabled) - Signals that the enabled state of this find filter has changed. + This signal is emitted when the \a enabled state of this find filter + changes. */ /*! - \fn Core::FindFlags BaseTextFind::supportedFindFlags() const - Returns the find flags, like whole words or regular expressions, - that this find filter supports. + \fn void IFindFilter::validChanged(bool valid) - Depending on the returned value, the default find option widgets are - enabled or disabled. - The default is Find::FindCaseSensitively, Find::FindRegularExpression - and Find::FindWholeWords + This signal is emitted when the \a valid state of this find filter changes. +*/ + +/*! + \fn void IFindFilter::displayNameChanged() + + This signal is emitted when the display name of this find filter changes. */ namespace Core { static QList g_findFilters; +/*! + \internal +*/ IFindFilter::IFindFilter() { g_findFilters.append(this); } +/*! + \internal +*/ IFindFilter::~IFindFilter() { g_findFilters.removeOne(this); } +/*! + Returns a list of find filters. +*/ const QList IFindFilter::allFindFilters() { return g_findFilters; } +/*! + Returns the shortcut that can be used to open the advanced find + dialog with this filter or scope preselected. + + Usually return an empty shortcut here, the user can still choose and + assign a specific shortcut to this find scope via the preferences. +*/ QKeySequence IFindFilter::defaultShortcut() const { return QKeySequence(); } +/*! + Returns the find flags, like whole words or regular expressions, + that this find filter supports. + + Depending on the returned value, the default find option widgets are + enabled or disabled. + The default is Core::FindCaseSensitively, Core::FindRegularExpression + and Core::FindWholeWords. +*/ FindFlags IFindFilter::supportedFindFlags() const { return FindCaseSensitively @@ -256,6 +282,9 @@ FindFlags IFindFilter::supportedFindFlags() const | FindWholeWords; } +/*! + Returns icons for the find flags \a flags. +*/ QPixmap IFindFilter::pixmapForFindFlags(FindFlags flags) { static const QPixmap casesensitiveIcon = Icons::FIND_CASE_INSENSITIVELY.pixmap(); @@ -300,6 +329,9 @@ QPixmap IFindFilter::pixmapForFindFlags(FindFlags flags) return pixmap; } +/*! + Returns descriptive text labels for the find flags \a flags. +*/ QString IFindFilter::descriptionForFindFlags(FindFlags flags) { QStringList flagStrings; diff --git a/src/plugins/coreplugin/find/ifindsupport.cpp b/src/plugins/coreplugin/find/ifindsupport.cpp index da54c5b41ea..f36bea2146d 100644 --- a/src/plugins/coreplugin/find/ifindsupport.cpp +++ b/src/plugins/coreplugin/find/ifindsupport.cpp @@ -30,6 +30,106 @@ using namespace Core; +/*! + \class Core::IFindSupport + \inmodule QtCreator + \brief The IFindSupport class provides functions for searching in a document + or widget. + + \sa Core::BaseTextFind +*/ + +/*! + \enum IFindSupport::Result + This enum holds whether the search term was found within the search scope + using the find flags. + + \value Found The search term was found. + \value NotFound The search term was not found. + \value NotYetFound The search term has not been found yet. +*/ + +/*! + \fn IFindSupport::IFindSupport() + \internal +*/ + +/*! + \fn IFindSupport::~IFindSupport() + \internal +*/ + +/*! + \fn bool IFindSupport::supportsReplace() const + Returns whether the find filter supports search and replace. +*/ + +/*! + \fn FindFlags IFindSupport::supportedFindFlags() const + Returns the find flags, such as whole words or regular expressions, + that this find filter supports. + + Depending on the returned value, the default find option widgets are + enabled or disabled. + + The default is Core::FindBackward, Core::FindCaseSensitively, + Core::FindRegularExpression, Core::FindWholeWords, and + Core::FindPreserveCase. +*/ + +/*! + \fn void IFindSupport::resetIncrementalSearch() + Resets incremental search to start position. +*/ + +/*! + \fn void IFindSupport::clearHighlights() + Clears highlighting of search results in the searched widget. +*/ + +/*! + \fn QString IFindSupport::currentFindString() const + Returns the current search string. +*/ + +/*! + \fn QString IFindSupport::completedFindString() const + Returns the complete search string. +*/ + +/*! + \fn void IFindSupport::highlightAll(const QString &txt, FindFlags findFlags) + Highlights all search hits for \a txt when using \a findFlags. +*/ + +/*! + \fn Result IFindSupport::findIncremental(const QString &txt, FindFlags findFlags) + Performs an incremental search of the search term \a txt using \a findFlags. +*/ + +/*! + \fn Result IFindSupport::findStep(const QString &txt, FindFlags findFlags) + Searches for \a txt using \a findFlags. +*/ + +/*! + \fn void IFindSupport::defineFindScope() + Defines the find scope. +*/ + +/*! + \fn void IFindSupport::clearFindScope() + Clears the find scope. +*/ + +/*! + \fn void IFindSupport::changed() + This signal is emitted when the search changes. +*/ + +/*! + Replaces \a before with \a after as specified by \a findFlags. +*/ void IFindSupport::replace(const QString &before, const QString &after, FindFlags findFlags) { Q_UNUSED(before) @@ -37,6 +137,12 @@ void IFindSupport::replace(const QString &before, const QString &after, FindFlag Q_UNUSED(findFlags) } +/*! + Replaces \a before with \a after as specified by \a findFlags, and then + performs findStep(). + + Returns whether the find step found another match. +*/ bool IFindSupport::replaceStep(const QString &before, const QString &after, FindFlags findFlags) { Q_UNUSED(before) @@ -45,6 +151,10 @@ bool IFindSupport::replaceStep(const QString &before, const QString &after, Find return false; } +/*! + Finds and replaces all instances of \a before with \a after as specified by + \a findFlags. +*/ int IFindSupport::replaceAll(const QString &before, const QString &after, FindFlags findFlags) { Q_UNUSED(before) @@ -53,6 +163,9 @@ int IFindSupport::replaceAll(const QString &before, const QString &after, FindFl return 0; } +/*! + Shows \a parent overlayed with the wrap indicator. +*/ void IFindSupport::showWrapIndicator(QWidget *parent) { Utils::FadingIndicator::showPixmap(parent, Utils::StyleHelper::dpiSpecificImageFile( diff --git a/src/plugins/coreplugin/find/itemviewfind.cpp b/src/plugins/coreplugin/find/itemviewfind.cpp index 3f07dff596c..ae1103a165f 100644 --- a/src/plugins/coreplugin/find/itemviewfind.cpp +++ b/src/plugins/coreplugin/find/itemviewfind.cpp @@ -35,6 +35,12 @@ namespace Core { +/*! + \class Core::ItemViewFind + \inmodule QtCreator + \internal +*/ + class ItemModelFindPrivate { public: diff --git a/src/plugins/coreplugin/find/optionspopup.cpp b/src/plugins/coreplugin/find/optionspopup.cpp index d7274f87e0c..b766cee1624 100644 --- a/src/plugins/coreplugin/find/optionspopup.cpp +++ b/src/plugins/coreplugin/find/optionspopup.cpp @@ -37,6 +37,12 @@ namespace Core { +/*! + \class Core::OptionsPopup + \inmodule QtCreator + \internal +*/ + OptionsPopup::OptionsPopup(QWidget *parent, const QVector &commands) : QWidget(parent, Qt::Popup) { diff --git a/src/plugins/coreplugin/find/searchresultwindow.cpp b/src/plugins/coreplugin/find/searchresultwindow.cpp index ec723c89285..a9895f720c8 100644 --- a/src/plugins/coreplugin/find/searchresultwindow.cpp +++ b/src/plugins/coreplugin/find/searchresultwindow.cpp @@ -53,6 +53,30 @@ static const int MAX_SEARCH_HISTORY = 12; namespace Core { +/*! + \namespace Core::Search + \inmodule QtCreator + \internal +*/ + +/*! + \class Core::Search::TextPosition + \inmodule QtCreator + \internal +*/ + +/*! + \class Core::Search::TextRange + \inmodule QtCreator + \internal +*/ + +/*! + \class Core::SearchResultItem + \inmodule QtCreator + \internal +*/ + namespace Internal { class InternalScrollArea : public QScrollArea @@ -236,6 +260,7 @@ using namespace Core::Internal; /*! \class Core::SearchResult + \inmodule QtCreator \brief The SearchResult class reports user interaction, such as the activation of a search result item. @@ -251,46 +276,99 @@ using namespace Core::Internal; */ /*! - \fn void SearchResult::replaceButtonClicked(const QString &replaceText, const QList &checkedItems, bool preserveCase) + \fn void SearchResult::replaceButtonClicked(const QString &replaceText, + const QList &checkedItems, + bool preserveCase) + Indicates that the user initiated a text replace by selecting - \gui {Replace All}, for example. + \uicontrol {Replace All}, for example. The signal reports the text to use for replacement in \a replaceText, - and the list of search result items that were selected by the user - in \a checkedItems. + the list of search result items that were selected by the user + in \a checkedItems, and whether a search and replace should preserve the + case of the replaced strings in \a preserveCase. The handler of this signal should apply the replace only on the selected items. */ +/*! + \enum Core::SearchResult::AddMode + This enum type specifies whether the search results should be sorted or + ordered: + + \value AddSorted + The search results are sorted. + \value AddOrdered + The search results are ordered. +*/ + +/*! + \fn void SearchResult::cancelled() + This signal is emitted if the user cancels the search. +*/ + +/*! + \fn void SearchResult::countChanged(int count) + This signal is emitted when the number of search hits changes to \a count. +*/ + +/*! + \fn void SearchResult::paused(bool paused) + This signal is emitted when the search status is set to \a paused. +*/ + +/*! + \fn void SearchResult::requestEnabledCheck() + + This signal is emitted when the enabled status of search results is + requested. +*/ + +/*! + \fn void SearchResult::searchAgainRequested() + + This signal is emitted when the \uicontrol {Search Again} button is + selected. +*/ + +/*! + \fn void SearchResult::visibilityChanged(bool visible) + + This signal is emitted when the visibility of the search results changes + to \a visible. +*/ + /*! \class Core::SearchResultWindow + \inmodule QtCreator \brief The SearchResultWindow class is the implementation of a commonly - shared \gui{Search Results} output pane. Use it to show search results - to a user. + shared \uicontrol{Search Results} output pane. + + \image qtcreator-searchresults.png Whenever you want to show the user a list of search results, or want to present UI for a global search and replace, use the single instance of this class. - Except for being an implementation of a output pane, the - SearchResultWindow has a few functions and one enum that allows other + In addition to being an implementation of an output pane, the + SearchResultWindow has functions and enums that enable other plugins to show their search results and hook into the user actions for selecting an entry and performing a global replace. Whenever you start a search, call startNewSearch(SearchMode) to initialize - the \gui {Search Results} output pane. The parameter determines if the GUI for + the \uicontrol {Search Results} output pane. The parameter determines if the GUI for replacing should be shown. The function returns a SearchResult object that is your hook into the signals from user interaction for this search. - When you produce search results, call addResults or addResult to add them - to the \gui {Search Results} output pane. - After the search has finished call finishSearch to inform the - \gui {Search Results} output pane about it. + When you produce search results, call addResults() or addResult() to add them + to the \uicontrol {Search Results} output pane. + After the search has finished call finishSearch() to inform the + \uicontrol {Search Results} output pane about it. - You will get activated signals via your SearchResult instance when - the user selects a search result item, and, if you started the search - with the SearchAndReplace option, the replaceButtonClicked signal - when the user requests a replace. + You will get activated() signals via your SearchResult instance when + the user selects a search result item. If you started the search + with the SearchAndReplace option, the replaceButtonClicked() signal + is emitted when the user requests a replace. */ /*! @@ -298,6 +376,17 @@ using namespace Core::Internal; \internal */ +/*! + \enum SearchResultWindow::PreserveCaseMode + This enum type specifies whether a search and replace should preserve the + case of the replaced strings: + + \value PreserveCaseEnabled + The case is preserved when replacings strings. + \value PreserveCaseDisabled + The given case is used when replacing strings. +*/ + SearchResultWindow *SearchResultWindow::m_instance = nullptr; /*! @@ -322,7 +411,7 @@ SearchResultWindow::~SearchResultWindow() } /*! - Returns the single shared instance of the \gui {Search Results} output pane. + Returns the single shared instance of the \uicontrol {Search Results} output pane. */ SearchResultWindow *SearchResultWindow::instance() { @@ -356,24 +445,31 @@ QList SearchResultWindow::toolBarWidgets() const } /*! - Tells the \gui {Search Results} output pane to start a new search. + Tells the \uicontrol {Search Results} output pane to start a new search. The \a label should be a string that shortly describes the type of the search, that is, the search filter and possibly the most relevant search - option, followed by a colon ':'. For example: \c {Project 'myproject':} + option, followed by a colon (:). For example: \c {Project 'myproject':} The \a searchTerm is shown after the colon. - The \a toolTip should elaborate on the search parameters, like file patterns that are searched and - find flags. - If \a cfgGroup is not empty, it will be used for storing the "do not ask again" - setting of a "this change cannot be undone" warning (which is implicitly requested + + The \a toolTip should elaborate on the search parameters, like file patterns + that are searched and find flags. + + If \a cfgGroup is not empty, it will be used for storing the \e {do not ask again} + setting of a \e {this change cannot be undone} warning (which is implicitly requested by passing a non-empty group). + + The \a searchOrSearchAndReplace parameter holds whether the search + results pane should show a UI for a global search and replace action. + The \a preserveCaseMode parameter holds whether the case of the search + string should be preserved when replacing strings. + Returns a SearchResult object that is used for signaling user interaction with the results of this search. The search result window owns the returned SearchResult - and might delete it any time, even while the search is running - (for example, when the user clears the \gui {Search Results} pane, or when - the user opens so many other searches - that this search falls out of the history). + and might delete it any time, even while the search is running. + For example, when the user clears the \uicontrol {Search Results} pane, or when + the user opens so many other searches that this search falls out of the history. */ SearchResult *SearchResultWindow::startNewSearch(const QString &label, @@ -420,7 +516,7 @@ SearchResult *SearchResultWindow::startNewSearch(const QString &label, } /*! - Clears the current contents of the \gui {Search Results} output pane. + Clears the current contents of the \uicontrol {Search Results} output pane. */ void SearchResultWindow::clearContents() { @@ -495,13 +591,18 @@ void SearchResultWindow::setTextEditorFont(const QFont &font, widget->setTextEditorFont(font, color); } +/*! + Sets the \uicontrol {Search Results} tab width to \a tabWidth. +*/ void SearchResultWindow::setTabWidth(int tabWidth) { d->m_tabWidth = tabWidth; foreach (Internal::SearchResultWidget *widget, d->m_searchResultWidgets) widget->setTabWidth(tabWidth); } - +/*! + Opens a new search panel. +*/ void SearchResultWindow::openNewSearchPanel() { d->setCurrentIndexWithFocus(0); @@ -644,23 +745,32 @@ QString SearchResult::textToReplace() const return m_widget->textToReplace(); } +/*! + Returns the number of search hits. +*/ int SearchResult::count() const { return m_widget->count(); } +/*! + Sets whether the \uicontrol {Seach Again} button is enabled to \a supported. +*/ void SearchResult::setSearchAgainSupported(bool supported) { m_widget->setSearchAgainSupported(supported); } +/*! + Returns a UI for a global search and replace action. +*/ QWidget *SearchResult::additionalReplaceWidget() const { return m_widget->additionalReplaceWidget(); } /*! - Adds a single result line to the \gui {Search Results} output pane. + Adds a single result line to the \uicontrol {Search Results} output pane. \a fileName, \a lineNumber, and \a lineText are shown on the result line. \a searchTermStart and \a searchTermLength specify the region that @@ -683,6 +793,18 @@ void SearchResult::addResult(const QString &fileName, int lineNumber, const QStr m_widget->addResult(fileName, lineText, mainRange, userData); } +/*! + Adds a single result line to the \uicontrol {Search Results} output pane. + + \a mainRange specifies the region from the beginning of the search term + through its length that should be visually marked. + \a fileName and \a lineText are shown on the result line. + You can attach arbitrary \a userData to the search result, which can + be used, for example, when reacting to the signals of the search results + for your search. + + \sa addResults() +*/ void SearchResult::addResult(const QString &fileName, const QString &lineText, Search::TextRange mainRange, @@ -693,7 +815,8 @@ void SearchResult::addResult(const QString &fileName, } /*! - Adds the search result \a items to the \gui {Search Results} output pane. + Adds the search result \a items to the \uicontrol {Search Results} output + pane using \a mode. \sa addResult() */ @@ -704,8 +827,8 @@ void SearchResult::addResults(const QList &items, AddMode mode } /*! - Notifies the \gui {Search Results} output pane that the current search - has finished, and the UI should reflect that. + Notifies the \uicontrol {Search Results} output pane that the current search + has been \a canceled, and the UI should reflect that. */ void SearchResult::finishSearch(bool canceled) { @@ -729,13 +852,16 @@ void SearchResult::restart() m_widget->restart(); } +/*! + Sets whether the \uicontrol {Seach Again} button is enabled to \a enabled. +*/ void SearchResult::setSearchAgainEnabled(bool enabled) { m_widget->setSearchAgainEnabled(enabled); } /*! - * Opens the \gui {Search Results} output pane with this search. + * Opens the \uicontrol {Search Results} output pane with this search. */ void SearchResult::popup() { diff --git a/src/plugins/coreplugin/icore.cpp b/src/plugins/coreplugin/icore.cpp index 83b3f2e2e08..ead03010eb5 100644 --- a/src/plugins/coreplugin/icore.cpp +++ b/src/plugins/coreplugin/icore.cpp @@ -44,6 +44,22 @@ which constitute the basic functionality of \QC. */ +/*! + \enum Core::FindFlag + This enum holds the find flags. + + \value FindBackward + Searches backwards. + \value FindCaseSensitively + Considers case when searching. + \value FindWholeWords + Finds only whole words. + \value FindRegularExpression + Uses a regular epression as a search term. + \value FindPreserveCase + Preserves the case when replacing search terms. +*/ + /*! \namespace Core::Internal \internal @@ -51,6 +67,7 @@ /*! \class Core::ICore + \inmodule QtCreator \brief The ICore class allows access to the different parts that make up the basic functionality of \QC. @@ -58,7 +75,7 @@ instance is created by the Core plugin. You can access this instance from your plugin through \c{Core::instance()}. - \mainclass + \ingroup mainclasses */ /*! @@ -81,7 +98,7 @@ /*! \fn bool ICore::showOptionsDialog(Id group, Id page, QWidget *parent = 0); - Opens the application \gui Options (or \gui Preferences) dialog with preselected + Opens the application \uicontrol Options (or \uicontrol Preferences) dialog with preselected \a page in the specified \a group. The arguments refer to the string IDs of the corresponding IOptionsPage. @@ -230,7 +247,7 @@ \fn void ICore::openFiles(const QStringList &fileNames, OpenFilesFlags flags = None) Opens all files from a list of \a fileNames like it would be done if they were given to \QC on the command line, or - they were opened via \gui File > \gui Open. + they were opened via \uicontrol File > \uicontrol Open. */ /*! @@ -253,12 +270,12 @@ Signals that the user has requested that the global settings should be saved to disk. - At the moment that happens when the application is closed, and on \gui{Save All}. + At the moment that happens when the application is closed, and on \uicontrol{Save All}. */ /*! \fn void ICore::optionsDialogRequested() - Enables plugins to perform actions just before the \gui Tools > \gui Options + Enables plugins to perform actions just before the \uicontrol Tools > \uicontrol Options dialog is shown. */