// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page creator-searching.html
    \previouspage creator-language-servers.html
    \nextpage creator-scxml.html

    \title Searching

    \quotation
    \l {Search}{How to: Search}
    \endquotation

    Open the \e {locator} to locate not only files, but any items defined by
    \e {locator filters}, as well as trigger global actions and perform other
    tasks, such as build projects or run external tools.

    \image {qtcreator-locator-open.webp} {List of found files in the locator}

    Use the incremental and advanced search to search in currently open projects
    or files on the file system.

    \image {qtcreator-find-from-current-file.webp} {Search hits highlighted in the editor}

    \sa {Search}{How to: Search}, {Search Results View}
*/

/*!
    \page creator-editor-finding.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-search

    \title Search in current file

    The incremental search highlights the matching strings in the editor while
    you type.

    To search through the currently open file:

    \list 1

        \li Select \key {Ctrl+F} or go to \uicontrol Edit >
            \uicontrol {Find/Replace} > \uicontrol {Find/Replace}.

        \li In \uicontrol Find, enter the text you are looking for.

            \image {qtcreator-find-from-current-file.webp} {Search hits highlighted in the editor}

            All occurrences of the text are highlighted in the editor as you
            type.

        \li To go to the next occurrence, select
            \inlineimage {icons/next.png} {Find Next} (\uicontrol {Find Next})
            or \key F3.

        \li To go to the previous occurrence, select
            \inlineimage {icons/prev.png} {Find Previous}
            (\uicontrol {Find Previous}) or \key {Shift+F3}.

        \li To select all found occurrences in a file, select
            \uicontrol {Select All}.

    \endlist

    \note Select text before selecting \uicontrol {Find/Replace} to search only
    from the selection.

    \section1 Set search criteria

    To restrict the search in the \uicontrol Find box, select
    \inlineimage {icons/qtcreator-new-search-icon.png} {New Search}
    (\uicontrol {New Search}) and set search criteria:

    \list

        \li To make your search case sensitive, select
            \uicontrol {Case Sensitive}.

        \li To search only whole words, select \uicontrol {Whole Words Only}.

        \li To search using \l{QRegularExpression}{regular expressions}, select
            \uicontrol {Use Regular Expressions}. Regular expressions used in \QC
            are modeled on Perl regular expressions

    \endlist

   \section1 Replace text

    To replace occurrences of the existing text, enter the new text in
    \uicontrol {Replace with}.

    \list
        \li To replace the selected occurrence, select \uicontrol {Replace}.
        \li To replace the selected occurrence and move to the next one,
            select \uicontrol {Replace & Find}.
        \li To replace all occurrences in the file, select
            \uicontrol {Replace All}.
    \endlist

    \section1 Preserve case when replacing

    To preserve the case of the original text when replacing, select
    \inlineimage {icons/qtcreator-new-search-icon.png} {New Search}
    (\uicontrol {New Search}) and then select
    \uicontrol {Preserve Case when Replacing}. You cannot use this option
    together with \uicontrol {Use Regular Expressions}.

    The case of the of the occurrence is preserved according to the following
    rules:

    \list

        \li All upper-case occurrences are replaced with the upper-case new
            text.
        \li All lower-case occurrences are replaced with the lower-case new
            text.

        \li Capitalized occurrences are replaced with the capitalized new text.

        \li Other occurrences are replaced with the new text as entered.

        \li If an occurrence and the new text have the same prefix or suffix,
            the case of the prefix and suffix are preserved, and the
            other rules are applied to the rest of the occurrence.

    \endlist

    \section1 Highlight search hits

    The locations of search hits, breakpoints, and bookmarks in your document
    are highlighted on the editor scroll bar. To turn highlighting off, select
    \preferences > \uicontrol {Text Editor} >
    \uicontrol Display > \uicontrol {Highlight search results on the scrollbar}.

    \image {qtcreator-preferences-text-editor-display.webp} {Display tab in Text Editor preferences}

    \section1 Search globally

    Select \uicontrol Advanced to open the \uicontrol {Search Results} view where
    you can search in currently open projects or files on the file system. Or,
    search for symbols to refactor code.

    \sa {Search}{How to: Search}, {Search Results View}

*/

/*!
    \page creator-how-to-advanced-search.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-search

    \title Search in projects or file systems

    To search in projects or file systems in the \uicontrol {Search Results}
    view:

    \list
        \li Select \key {Ctrl+Shift+F}
        \li Go to \uicontrol Edit > \uicontrol {Find/Replace} >
            \uicontrol {Advanced Find}, and select
            \uicontrol {Open Advanced Find}.
        \li Go to the \uicontrol {Search Results} view.
    \endlist

    The search scope and search criteria determine where \QC looks for the search
    string, how it matches the string with text, and which results it shows.

    \section1 Search in a single project

    \list 1
        \li In \uicontrol Scope, select \uicontrol {Single Project}.
            \image {qtcreator-search-single-projects.webp} {Single Project option in the Search Results view}
        \li In \uicontrol {Search for}, enter the string you are looking for.
        \li Select options to make the search case sensitive, search only whole
            words, use regular expressions, or ignore binary or generated files.
        \li In \uicontrol Project, select an open project to search in.
            Select \uicontrol Current to search in the project that the currently
            active file belongs to.
        \li In \uicontrol {File pattern}, specify file patterns to
            restrict the search to files that match the pattern. For example, to
            search for a string only in \c {.cpp} and \c {.h} files, enter
            \c {*.cpp,*.h}.
        \li In \uicontrol {Exclusion pattern}, specify file patterns
            to omit files from the search.
        \li Select \uicontrol Search.
    \endlist

    If you cannot find some files, see \l{Specify project contents} for
    how to declare them as a part of the project.

    \section1 Search in all projects

    \list 1
        \li In \uicontrol Scope, select \uicontrol {All Projects}.
            \image {qtcreator-search-all-projects.webp} {All Projects option in the Search Results view}
        \li Set search criteria.
        \li Select \uicontrol Search.
    \endlist

    \section1 Search in the file system

    In addition to the options available for searching from all projects, you can
    select the search engine to use and the directory to search in.

    \list 1
        \li In \uicontrol Scope, select \uicontrol {Files in File System}.
            \image {qtcreator-search-file-system.webp} {Files in File System option in the Search Results view}
        \li In \uicontrol {Search for}, enter the string you are looking for.
        \li In \uicontrol {Search engine}, select the search engine to use:
            \list
                \li Select \uicontrol Internal to use the \QC search
                    engine.
                \li Select \uicontrol {Git Grep} to use Git to only
                    search tracked files in the Git work tree. To
                    restrict the search to the HEAD, a tag, a local or
                    remote branch, or a commit hash, enter a reference.
                    Leave the field empty to search through the file
                    system.
                \li Select \uicontrol {Silver Searcher} to use the
                    experimental Silver Searcher plugin.
            \endlist
        \li In \uicontrol Directory, select the directory to search in.
            Select \uicontrol Browse to locate the directory or
            \uicontrol Current to search in the directory where the currently
            active file is.
        \li Select \uicontrol Search.
    \endlist

    \section1 Search and replace

    To replace occurrences of the existing text:

    \list 1
        \li Select \uicontrol {Search & Replace}.
        \image {qtcreator-search-results-reg-exp.webp} {Search results when searching and replacing}
        \li Enter the new text in \uicontrol {Replace with}.
        \li Select \uicontrol Replace.
    \endlist

    To preserve the case of the original text when replacing,
    select \uicontrol {Preserve case}. The rules listed in
    \l {Preserve case when replacing} apply here as well.

    \sa {Search}{How to: Search}, {Find symbols}, {Search in current file},
    {Turn on Silver Searcher}, {Search Results View}
*/
