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

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

    \ingroup creator-how-to-search

    \title Navigate with locator

    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.webp} {List of locator filters}

    \section1 Go to the locator

    To activate the locator:

    \list

        \li Select \key {Ctrl+K} (\key {Cmd+K} on \macos).

        \li Go to \uicontrol Tools, and then select \uicontrol Locate.

        \li Go to \uicontrol Edit, and then select \uicontrol {Go to Line}.

        \li Select the line and column indicator on the
            \l{Editing code}{editor toolbar}.

    \endlist

    By default, you can find the locator in the bottom left of the \QC window.
    To open it as a centered popup, select \inlineimage {icons/magnifier.png} {Locator menu},
    and then select \uicontrol {Open as Centered Popup}.

    \section1 Use locator filters

    The filters that are available depend on the current document and project.
    If the locator field is empty, a list of available filters is shown.
    A list of filters is also shown when selecting \inlineimage {icons/magnifier.png} {Locator menu}.
    For more information about what a particular locator filter does, see the
    tooltips that appear when you hover over a filter.

    To use a locator filter:

    \list
        \li Enter the locator filter prefix followed by \key Space. The prefix
            is usually short, from one to three characters. Then enter the search
            string (for example, a filename or class name) or the command to
            execute. Select \key {Tab} to complete the search string.

        \li Select a locator filter in the filter list to use it. Use
            the up and down arrow keys or select \key Ctrl+P and \key Ctrl+N
            to move up and down the list, and then select \key Enter to use the
            selected filter.
    \endlist

    As you enter a search string,
    the locator shows the occurrences of that string regardless of where in the
    name of an object it appears. Some locator filters, such as colon, \c m,
    and \c t, support \e fuzzy matching, which means that you can enter the
    uppercase letters to locate a symbol when using camel case or the letters
    after the underscore when using snake case.

    To turn off \key Tab completion, select \inlineimage {icons/magnifier.png}
    {Locator menu} and clear \uicontrol {Use Tab Completion}.

    \section2 Use wildcard characters in search strings

    To narrow down the search results, use the following wildcard characters:

    \list

        \li To match any number of any or no characters, enter \c{*}.

        \li To match a single instance of any character, enter \c{?}.

    \endlist

    \section1 Omit default filters

    By default, you can use the following preset locator filters without a
    prefix:

    \list

        \li Going to a line and column in the current file (\c {l}).

        \li Going to an open file (\c {o}).

        \li Going to a file in any open project (\c {a}).

    \endlist

    \section1 Locate lines and columns

    To move directly to a particular line and column in the document when you
    open the document, append the line and column number to the file name in
    the locator, separated by plus signs (+) or colons (:).

    For example, to open \c HelloWorld.qml to line
    41 and column 2, enter:

    \code
    HelloWorld.qml:41:2
    \endcode

    \section1 Search the web

    Use the \uicontrol {Web Search (r)} locator filter to perform web searches.

    URLs and search commands for Bing, Google, Yahoo! Search, cplusplus.com, and
    Wikipedia are configured by default. Add search commands for other web search
    engines in the locator preferences.

    \section1 Create files and directories from the locator

    To create a new file and open it in the editor:

    \list 1
        \li Enter \c f followed by \key Space, followed by path and file name
        \li Select \key Enter or select \uicontrol {Create and Open File}.
    \endlist

    To create a directory, select \uicontrol {Create Directory}.

    \sa {Search}{How to: Search}, {Manage sessions}, {Perform calculations},
    {Locator}

*/

/*!
    \page creator-preferences-locator.html
    \previouspage creator-reference.html

    \ingroup creator-reference-editors

    \title Locator

    \brief Add and change locator filters.

    To set locator preferences, go to \preferences > \uicontrol Environment >
    \uicontrol Locator, or select
    \inlineimage {icons/magnifier.png} {Locator menu} > \uicontrol Configure in
    the locator field.

    \image {qtcreator-locator-customize.webp} {Locator tab in Environment preferences}

    \section1 Changing Locator Filters

    You can change the preset locator filters to match your use case. For
    example, change the filter prefix and restrict the search to
    items that match the filter.

    To configure a locator filter:

    \list 1

        \li Go to \preferences > \uicontrol Environment > \uicontrol Locator.

        \li Select a filter, and then select \uicontrol Edit.

        \li Specify the prefix string.

            \image {qtcreator-locator-filter-edit-ai.webp} {Filter Configuration dialog}

        \li To implicitly include the filter even when not typing a prefix as a
            part of the search string, select \uicontrol {Include by default}.

    \endlist

    \section1 Adding Web Search Engines

    By default, the \uicontrol {Web Search (r)} locator filter includes the URLs
    and search commands for Bing, Google, Yahoo! Search, cplusplus.com, and
    Wikipedia.

    To find out the format of the search command to use for your favorite
    web search engine, perform a search in your browser and copy the resulting
    URL to the locator filter configuration. Replace the search term with the
    variable \c {%1}.

    To add URLs and search commands to the list:

    \list 1

        \li Go to \preferences > \uicontrol Environment > \uicontrol Locator.

        \li Select \uicontrol {Web Search} > \uicontrol Edit.

        \li Select \uicontrol Add to add a URL filter to the list.

            \image {qtcreator-add-online-doc.webp} {List of URLs in Filter Configuration dialog}

        \li Double-click the new entry to specify a URL and a search command.
            For example, \c {http://www.google.com/search?q=%1}.

        \li Select \uicontrol OK.

    \endlist

    To add a new separate web search locator filter instead of updating the
    default filter, select \uicontrol Add > \uicontrol {URL Template}.

    \section1 Creating Locator Filters

    To quickly access files not directly mentioned in your project,
    create your own directory filters. That way you can locate files in a
    directory structure you have defined.

    To create custom locator filters:

    \list 1

        \li Go to \preferences > \uicontrol Environment > \uicontrol Locator.

        \li Select \uicontrol Add > \uicontrol {Files in Directories} to add
            a directory filter.

            \image {qtcreator-locator-generic-directory-filter.png} {Filter Configuration dialog}

        \li In \uicontrol Name, enter a name for your filter.

        \li Select \uicontrol Add to add directories to \uicontrol Directories.
            The locator searches directories recursively.

        \li In \uicontrol {File pattern}, specify file patterns to
            restrict the search to files that match the pattern.
            Separate the patterns with commas. For example, to search for all
            \c {.qml} and \c {.ui.qml} files, enter \c{*.qml,*.ui.qml}

        \li In \uicontrol {Exclusion pattern}, specify file
            patterns to omit files from the search.

        \li In \uicontrol Prefix, specify the prefix string.

            To implicitly include the filter even when not typing a prefix
            as a part of the search string, select
            \uicontrol {Include by default}.

        \li Select \uicontrol OK.

    \endlist

    \section1 Configuring Locator Cache

    The locator searches the files matching your file pattern in the directories
    you have selected and caches that information. \QC updates the cache for all
    preset filters as you write code. By default, \QC updates your custom
    filters once an hour.

    To update the cached information manually, select
    \inlineimage {icons/magnifier.png} {Locator menu} > \uicontrol Refresh in the
    locator.

    To set a new cache update time:

    \list 1

        \li Go to \preferences > \uicontrol Environment > \uicontrol Locator.

        \li In \uicontrol {Refresh interval}, set a new time in minutes.

    \endlist

    \section1 Hiding Long Paths

    To hide the common part of absolute paths in the locator:

    \list 1
        \li Go to \preferences > \uicontrol Environment > \uicontrol Locator.
        \li Select \uicontrol {Show Paths in Relation to Active Project} to
            show relative paths.
    \endlist

    \sa {Navigate with locator}, {Search}{How to: Search}, {Perform calculations}
*/
